[하네스 엔지니어링 입문] 3. 구성 요소 및 구축

1. 구성 요소

구성 요소	역할	핵심 기능
지시 문서	Agent에게 어떻게 행동해야 하는지 알려줌	방향 제시
아키텍처 제약	잘못된 구조나 코드를 자동으로 차단	잘못된 방향 차단
피드백 루프	작업 결과가 올바른지 빠르게 확인	결과 검증 및 교정
지식 저장소	프로젝트의 결정과 맥락을 지속적으로 제공	결정의 이유와 배경 제공

 

2. 작성 방법

구성 요소	주요 내용	예시
지시 문서	프로젝트 구조, 코드 규칙, 금지 사항, 작업 절차, 테스트·PR 규칙	AGENTS.md, CLAUDE.md
아키텍처 제약	Lint, Type Check, 모듈·레이어 의존성, 금지 Import	ESLint, Ruff, ArchUnit, pre-commit
피드백 루프	Test, Lint, Build, CI, 구체적인 오류 메시지	Unit Test, Integration Test, GitHub Actions
지식 저장소	기술 결정, 실패 기록, Convention, 도메인 지식, 운영 지식	docs/, ADR, Runbook

 

작성 원칙) 지시 문서

작성 원칙	설명
구조화	프로젝트 개요, 구조, 규칙, 테스트 등 섹션별로 구분
구체적으로 작성	"좋은 코드를 작성"보다 실제 행동 기준을 명시
금지 사항 명시	수정 금지 파일, 금지 패턴 등을 명확하게 작성
실행 방법 제공	Build, Test, Lint 등의 실행 명령 제공
간결하게 유지	상세한 설명은 별도 docs/로 분리

 

AGENTS.md

프로젝트 구조
- domain: 비즈니스 로직
- application: UseCase
- infrastructure: 외부 시스템 연동

금지 사항
- Domain → Infrastructure 직접 참조 금지
- 기존 구현 확인 없이 새로운 Utils 생성 금지

작업 완료 조건
- 관련 테스트 작성
- 테스트 통과
- Architecture Test 통과

 

작성 원칙) 아키텍처 제약

적용 대상	구축 방법
코드 스타일	Formatter / Linter
잘못된 코드 패턴	정적 분석
타입 오류	Type Check
모듈·레이어 의존성	Architecture Test / Import Rule
Commit 전 검사	pre-commit Hook

• ✅ 자동으로 검증 가능한 중요한 규칙은 문서로 알려주는 것에 그치지 않고 도구로 검사하도록 구성함

 

작성 원칙) 피드백 루프

구분	역할	예시
Guide	처음부터 올바른 방향으로 작업하도록 안내	지시 문서, 기존 코드, 예제, 테스트 케이스
Sensor	작업 결과에서 잘못된 부분을 감지	Test, Lint, Build, CI

• 피드백은 가능한 한 빠르고 구체적으로 제공
• ➡️ Agent가 잘못된 방향으로 많은 작업을 수행하기 전에 문제를 발견할 수 있도록 구성하기

 

작성 원칙) 지식 저장소

저장 대상	내용	예시
기술 결정	어떤 기술·구조를 선택한 이유	ADR
실패 기록	시도했지만 사용하지 않기로 한 방법과 이유	docs/failures/
개발 규칙	상세 Convention 및 개발 방법	docs/conventions/
도메인 지식	비즈니스 용어와 규칙	Glossary, Workflow
운영 지식	장애 대응 및 운영 방법	Runbook, Troubleshooting

• ➡️ 지시 문서에 어떤 상황에 어떤 문서를 참고해야 하는지 안내하기

 

출처

• Wiki Docs - 하네스 엔지니어링 입문