하네스의 세 문서 — SPEC.md · PLAN.md · DONE_CRITERIA.md
에이전트 하네스는 세 개의 문서로 선다
에이전트에게 일을 맡길 때 무너지는 지점은 늘 세 곳이다 — 무엇을 만들지 모호하고, 어떻게 진행할지 즉흥적이고, 다 됐는지 판단 기준이 없다. 이 셋을 문서로 고정하는 것이 하네스의 뼈대다:
| 문서 | 답하는 질문 | 성격 | 대응(Ouroboros) |
|---|---|---|---|
| SPEC.md | 무엇을 만드나 | 불변(frozen) | Seed |
| PLAN.md | 어떻게 진행하나 | 가변(적응) | Interview → Double Diamond |
| DONE_CRITERIA.md | 됐는지 어떻게 아나 | 증거 | 3단계 평가 게이트 |
세 문서는 Ouroboros가 22만 줄로 강제한 구조를 개인 워크플로 수준으로 옮긴 것이다 — 의도는 불변, 경로는 가변, 완료는 증거.
1. SPEC.md — 무엇을 (불변의 의도)
SPEC는 “이 작업이 무엇인가”를 검사 가능한 형태로 못 박는다. 승인 뒤에는 불변 — 바꾸려면 명시적 재합의가 필요하다. 이 불변성이 계약 표류(contract drift)를 구조적으로 막는다.
# SPEC: <기능/작업>
## 목표 (불변) — 사용자에게 보이는 결과 하나
## 제약 (불변) — 건드리면 안 되는 것, 지켜야 할 것
## 수용 기준 (3~7개, 각각 검증 가능한 결과)
1. ... 2. ... 3. ...
## 비목표 (Non-goals) — 이번 범위 밖
## 가정 (사용자 확인 필요) — [가정] ... → 확인됨 YYYY-MM-DD
핵심 규칙: 수용 기준은 결과의 목록이지 구현 단계가 아니다(3~7개). 그리고 비목표를 반드시 적는다 — 과잉 구현과 표류를 동시에 막는 가장 싼 장치다.
2. PLAN.md — 어떻게 (먼저 명료화, 그다음 분해)
여기가 이 글의 핵심이다. 계획은 “단계 나열”로 시작하지 않는다. 좋은 계획은 먼저 모호함을 걷어내는 것에서 시작한다. 곧바로 스텝을 쓰면, 아직 추측 중인 것을 계획으로 굳혀버린다.
2-1. 계획 전 명료화 — 10차원 체크리스트
계획을 쓰기 전에 아래 10가지를 물어 답을 확정한다. 답이 안 나오는 칸이 곧 다음에 확인할 지점이다.
| 항목 | 의미 | 예시 질문 |
|---|---|---|
| 명시 요청 | 사용자가 직접 말한 작업 | “산출물은 보고서 초안인가요, 요약본인가요?” |
| 최종 목적 | 작업으로 이루려는 목표 | “이 결과물은 설득/의사결정/학습/실행 중 어디에?” |
| 대상 독자 | 결과물을 볼 사람 | “읽는 사람은 임원/실무자/고객/투자자 중 누구?” |
| 성공 기준 | 잘 끝났다고 판단할 조건 | “어떤 상태가 되면 성공인가요?” |
| 제약 조건 | 시간·형식·톤·분량·도구·정책 | “지켜야 할 형식이나 제외할 내용이 있나요?” |
| 가정 | 사용자가 말 안 했지만 모델이 추정한 것 | “내부 보고용으로 이해했는데 맞나요?” |
| 우선순위 | 품질·속도·정확성·창의성·비용의 순서 | “빠른 초안 vs 완성도, 뭐가 우선?” |
| 리스크 | 잘못 이해하면 큰 문제인 부분 | “이건 법무/재무/고객 커뮤니케이션에 영향?” |
| 열린 질문 | 아직 확인 안 된 불확실성 | “결정 전 확인 필요: 대상 독자, 데이터 출처” |
| 결정 기록 | 사용자가 확정한 사항 | “임원 보고용 1페이지 요약을 원함” |
이 10차원이 왜 중요한가 — 에이전트는 모호함을 되묻기보다 그냥 추측으로 메우고 실행하기 때문이다. 그 추측이 어긋나면 safe-but-wrong이 나온다. 10차원은 그 추측을 실행 전에 드러내 확정한다.
특히 마지막 두 칸이 계획의 품질을 가른다:
- 열린 질문 = “아직 모르는 것을 안다”는 정직함. 모호도가 남았다는 신호이자, 계획이 아직 이르다는 경고다.
- 결정 기록 = 확정된 것을 문장으로 남겨, 세션이 길어지거나 컨텍스트가 압축돼도 되돌아갈 앵커.
Ouroboros가 “인터뷰는 당신이 준비됐다고 느낄 때가 아니라 수학이 준비됐다고 말할 때 끝난다”고 한 것과 같다 — 모호도(Goal/Constraint/Success/Context Clarity)가 임계값 아래로 떨어지기 전에는 계획을 쓰지 않는다. 위 10차원이 바로 그 모호도를 채우는 질문들이다.
2-2. 그다음에야 분해
10차원이 채워지면, 계획은 결과(수용 기준) 단위로 스텝을 나눈다 — 구현 단계로 잘게 쪼개는 건 실행 시점의 몫이다.
# PLAN: <기능>
## 명료화 결과 (위 10차원 요약)
- 최종 목적: ... / 대상 독자: ... / 우선순위: ... / 리스크: ...
## 열린 질문 (착수 전 해소 필요)
- [ ] ...
## 결정 기록
- YYYY-MM-DD: <확정 사항>
## 단계 (수용 기준 단위, 병렬 가능 표시)
1. AC-1 ... (검증: `<명령>`)
2. AC-2 ... (병렬 가능)
계획은 SPEC와 달리 가변이다 — 진행하며 배운 것을 반영해 적응한다. 단, 바뀔 때마다 왜 바뀌었는지 결정 기록에 남긴다.
3. DONE_CRITERIA.md — 됐는지 어떻게 아나 (증거)
가장 자주 생략되고, 가장 중요하다. 에이전트의 “완료했습니다”는 그 자체로 증거가 아니다 — 완료는 승인이 아니다. 완료를 증거로 닫는다.
# DONE_CRITERIA: <기능>
## 수용 기준별 검증 (SPEC의 AC와 1:1)
- [ ] AC-1 — 검증 명령 `<cmd>` → 실제 출력: <원문 인용>
- [ ] AC-2 — 검증 명령 `<cmd>` → 미실행이면 "미실행"으로 명시
## 변경 파일
- <diff 범위>
## 남은 위험 / 알려진 한계
- ...
## 게이팅 (통과 못 하면 미완)
- lint/typecheck/test 전부 green, 새 오류 0
핵심은 세 가지: ① 각 기준을 검증 명령 + 출력 원문으로 증명(요약 금지), ② 미실행 검증은 “미실행”으로 정직히, ③ 남은 위험 최소 한 줄. 이 형식이라야 “Done” 한 마디에 숨는 미완/오류가 걸러진다.
세 문서의 생애 — 하나의 루프
SPEC.md (무엇/불변) ──freeze──▶ PLAN.md (어떻게/가변)
▲ │ 10차원 명료화 → 분해 → 실행
│ ▼
└──재합의 필요시만── DONE_CRITERIA.md (증거로 검증)
- SPEC 없이 PLAN = 표류의 씨앗(무엇을 만드는지 안 굳힘)
- 명료화 없이 PLAN = 추측을 계획으로 굳힘(safe-but-wrong)
- DONE_CRITERIA 없이 완료 = 거짓 확신(검증 없는 “Done”)
세 문서는 서로를 참조한다 — DONE_CRITERIA의 체크는 SPEC의 수용 기준과 1:1이고, PLAN의 결정 기록은 SPEC의 가정을 확정한 이력이다. Claude Code라면 이 셋을 프로젝트에 두고, 착수 규칙·완료 보고 형식은 CLAUDE.md 운영 규칙으로, 위험 게이팅은 훅으로 강제하면 된다.
한 줄 결론
하네스의 힘은 똑똑한 에이전트가 아니라 세 개의 문서에서 나온다 — 의도를 SPEC로 얼리고, 계획을 PLAN에서 먼저 명료화한 뒤 분해하고, 완료를 DONE_CRITERIA로 증거로 닫는다. 그중 계획의 절반은 스텝이 아니라 위 10가지 질문에 답하는 일이다.
출처 · 관련 글
- 첨부 이미지: 사용자 제공(계획 전 명료화 10차원 체크리스트).
- 불변 명세·인터뷰·3단계 평가의 근거: Ouroboros 3부작 정리 (원 저장소 Q00/ouroboros 실측 분석).
- 계획·투명성 대원칙(공식): Anthropic, Building Effective Agents.
- 관련 본인 정리글: AI 작업 운영 규칙 · AI가 틀렸을 때 질문 5패턴 · Explorer/Implementer/Verifier
참고: 세 문서 스캐폴드와 10차원 체크리스트는 규범적 제안이며, 프로젝트 규모에 맞춰 취사선택하라. 빠른 일회성 작업엔 SPEC 최소형(산출물 종류 + 성공 기준 한 줄)만으로 충분하다.