Harness 레이어 구조
"누가 읽는가" 기준으로 나눈 5개 레이어
| 레이어 | 파일 | 질문 | 누가 쓰나 | 언제 |
|---|---|---|---|---|
| Goal | feature_list.json | 무엇을? | initializer agent | 프로젝트 시작 |
| Knowledge | ADR, skill, AGENTS.md | 왜? 어떻게? | 인간 (+ GC agent) | 결정할 때마다 |
| Execution | tool calls | 실제 행동 | coding agent | 매 세션 |
| Environment | init.sh | 어디서? | initializer agent | 프로젝트 시작 |
| State | claude-progress.txt, git log | 지금까지? | coding agent (인간 관찰) | 매 세션 끝 |
핵심 원칙
Knowledge layer만 인간이 직접 쓰는 레이어다. 나머지는 agent가 쓰거나 실행한다. → 인간이 집중해야 할 곳 = ADR + Skill 설계
"코드 주석 → ADR 링크"의 실제 흐름
코드 주석에 ADR 링크를 다는 것은 세 레이어에 걸친 행위다:
Skill (knowledge layer)에 규칙을 써둔다
"라이브러리를 선택할 때 ADR을 작성하고,
해당 코드에 # ADR-0003 참고 주석을 달아라"
↓
coding agent가 코드를 작성할 때 (execution layer)
이 규칙을 따라 주석을 자동으로 삽입한다
↓
코드 파일 안에 ADR 링크가 존재한다
인간이 직접 주석을 다는 게 아니다. Skill에 한 번 써두면 agent가 매번 알아서 지킨다.
레이어 간 관계
- Goal layer가 coding agent에게 무엇을 할지 지시
- Knowledge layer가 coding agent에게 어떻게, 왜 를 알려줌
- Execution layer가 실제 코드와 파일을 만들어냄
- Environment layer가 execution이 가능한 환경을 보장
- State layer가 다음 세션 agent와 인간에게 지금까지를 전달
관련 개념
- initializer-coding-agent-pattern — 각 레이어가 어떻게 초기화되는가
- context-history-documentation — Knowledge layer 설계 방법 (ADR)
-