1단계 — 의도 정의 (Intent)
무엇을, 왜 만드는지를 검증 가능한 문장으로 못 박는다.
이 단계의 목적
이 단계의 산출물은 코드가 아니라 문서지만, 이후 모든 단계의 상한선을 정하는 것은 이 문서다. 의도가 모호하면 에이전트는 빈틈을 추측으로 채우고, 그 추측은 리뷰 단계에서 재작업으로 되돌아온다. 목표는 "무엇을 만들지"에 대한 합의를 사람들 사이에서 먼저 끝내고, 그 합의를 에이전트가 행간 없이 읽을 수 있는 문서로 남기는 것이다.
실행 순서
- 문제/기회를 한 문단으로 서술한다. 지금 무엇이 고통스럽고, 왜 지금 해결해야 하는지를 데이터나 구체 사례로 뒷받침한다. "더 좋으면 좋겠다" 수준의 서술은 반려한다.
- PR-FAQ로 완성된 모습을 역산한다. 출시 발표문과 예상 FAQ를 먼저 써서, 사용자 관점에서 "이게 성공하면 무엇이 달라지는가"를 구체적으로 그린다.
- 6-pager 축약형으로 배경·제약·트레이드오프를 서술한다. 고려했다가 버린 대안과 그 이유를 반드시 남긴다. 버린 것을 적지 않으면 나중에 같은 대안이 재검토 없이 반복 제안된다.
- 검증 가능한 성공 기준을 명시한다. "사용성이 좋아진다"가 아니라 "온보딩 소요 시간이 30분 이내면 성공"처럼 참/거짓을 판정할 수 있는 문장으로 쓴다.
- 이해관계자 합의를 받는다. 리뷰 코멘트나 승인 기록을 문서에 남겨, 나중에 "그런 얘기 없었다"는 되짚기를 차단한다.
산출물
두 문서는 리포에 커밋해 다음 단계(컨텍스트 설계)와 이후 사이클의 입력으로 남긴다.
완료 기준 체크리스트
- [ ] 성공 기준이 "~하면 성공"처럼 검증 가능한 문장으로 쓰여 있다
- [ ] 트레이드오프에서 의도적으로 버린 대안과 그 이유가 명시돼 있다
- [ ] 에이전트가 행간을 추측하지 않고 읽을 수 있을 만큼 배경과 제약이 구체적이다
- [ ] 이해관계자 전원의 합의(리뷰 코멘트·승인 기록)가 문서에 남아 있다
- [ ] 문서가 리포에 커밋되어 다음 세션에서 그대로 참조 가능하다
흔한 실수
- 기능 나열식 요구사항. "A 화면, B 버튼, C API"만 나열하고 왜 필요한지가 없으면 에이전트는 목적 없이 표면만 구현한다.
- 성공 기준 없는 의도. "빠르고 안정적으로"처럼 측정 불가능한 형용사만 있으면 검증 단계에서 합격선을 정할 수 없다.
- 한 번 쓰고 버리는 문서. 합의 직후 방치되고 세션마다 구두로 다시 설명하면, 문서는 죽은 기록이 되고 컨텍스트 자산으로 이어지지 않는다.
Claude Code로 하면
TIP
의도 문서를 specs/ 또는 docs/에 커밋하고, 프로젝트 CLAUDE.md에 "세션 시작 시 최신 의도 문서를 먼저 읽는다"는 규칙을 명시한다. 그러면 매 세션이 같은 출발선에서 시작된다.
의도 문서가 준비되면 plan mode로 넘어간다. 문서 경로를 프롬프트에 지정해 "이 의도 문서를 기준으로 구현 계획을 세워줘"라고 요청하면, 에이전트가 의도를 작업 단위로 분해한 계획을 제안한다. 이 계획을 승인하는 것이 3단계(공동 구현)로 넘어가는 관문이다. 의도 문서 자체를 승인 없이 계획으로 건너뛰지 않는다 — 문서화되지 않은 의도는 다음 세션에서 휘발된다.