jaysnote

05. 어떤 문서를 만들어야 하나

#agentic-engineering #문서화

문서는 “관료적 절차”가 아니라 사람의 의도를 agent가 실행할 수 있게 고정하는 인터페이스다. 각 문서는 04. 경계에서 사람이 책임지는 “무엇을·왜”를 담는다.

문서 지도

헌법(Constitution)   ─ 프로젝트 전체에 영원히 적용되는 불변 원칙
   │
PRD (제품 요구사항)   ─ 무엇을·왜·누구를 위해 (비즈니스 의도)
   │
명세 (Spec)          ─ 기능 단위 요구사항·사용자 스토리·수용 기준
   │
아키텍처 (Architecture) ─ 어떻게(시스템 구조, 컴포넌트, 데이터 흐름)
   │
ADR (결정 기록)       ─ 중요한 결정 하나하나의 "왜"
   │
계획 (Plan) → 작업 (Tasks) ─ 실행 단위로 분해

문서별 가이드

1. 헌법 (Constitution) — 가장 먼저, 가장 오래

  • 무엇: 협상 불가능한 원칙. “테스트 없이 머지 금지”, “모든 외부 호출에 타임아웃”, “공개 API 하위 호환 유지”.
  • 왜: agent가 plan을 세울 때 반드시 따라야 하는 하드 가드레일. → SpecKit constitution, 경계의 가드레일.
  • 언제: 프로젝트 시작 시 1회 작성, 드물게 갱신.
  • 누가: 🧑 사람이 결정(가치 판단). agent는 초안 제안.
  • 템플릿: 00-constitution.md

2. PRD (Product Requirements Document)

  • 무엇: 제품/기능이 왜 필요한지, 누구를 위한 건지, 성공을 어떻게 측정하는지. 솔루션이 아니라 문제를 적는다.
  • 포함: 배경/문제, 목표와 비목표(non-goals), 대상 사용자, 성공 지표, 범위, 제약.
  • 왜: agent와 사람이 “무엇을 만드는가”에 대해 같은 그림을 공유. 모호함을 제거.
  • 누가: 🧑 사람 주도, 🤖 초안·누락 질문.
  • 주의: 비목표(만들지 않을 것)를 명시하라. agent의 과잉 구현을 막는 가장 강력한 한 줄.
  • 템플릿: 01-prd.md

3. 명세 (Spec)

  • 무엇: 기능 단위의 구체적 요구사항. 사용자 스토리 + 측정 가능한 수용 기준.
  • 핵심: 수용 기준은 테스트로 옮길 수 있게 써라. “빨라야 함”(❌) → “p95 응답 300ms 이하”(✅). 이게 TDD와 SDD를 잇는 다리다.
  • 누가: 🧑 주도, 🤖 초안. 모호하면 agent가 질문(SpecKit의 /clarify).
  • 주의: 기술 용어 없이 무엇을·왜만. “어떻게”는 아키텍처/계획으로 미룬다.

4. 아키텍처 문서 (Architecture)

  • 무엇: 시스템 구조 — 주요 컴포넌트, 책임, 경계, 데이터 흐름, 외부 의존성, 핵심 기술 선택.
  • 왜: “어떻게”의 큰 그림. 되돌리기 어려운 결정이 모이는 곳 → 사람이 반드시 검토.
  • 누가: 🧑 결정, 🤖 옵션·트레이드오프 제시.
  • 분량: 처음엔 한 페이지 + 다이어그램 하나로 충분. 코드와 함께 갱신.
  • 템플릿: 02-architecture.md

5. ADR (Architecture Decision Record)

  • 무엇: 중요한 결정 하나에 대한 짧은 기록. 맥락 → 결정 → 결과/트레이드오프.
  • 왜: “왜 PostgreSQL을 골랐나”, “왜 모놀리스인가” 같은 질문에 6개월 뒤 답하기 위해. agent에게도 결정의 이유를 주어 일관성 유지.
  • 누가: 🧑 결정 기록, 🤖 초안 작성.
  • 언제: 되돌리기 어렵거나 논쟁적인 결정마다 1개. 파일명 예: adr/0001-use-postgres.md.
  • 템플릿: 03-adr.md

6. 계획(Plan) & 작업(Tasks)

  • 무엇: spec+아키텍처를 실행 단위로 분해. Plan은 접근법, Tasks는 의존성 순서가 반영된 체크리스트.
  • 누가: 🤖 agent 주도(기계적), 🧑 검토. → SpecKit /plan, /tasks.
  • 템플릿: 04-tasks.md

7. CLAUDE.md — agent를 위한 상시 메모리

  • 무엇: Claude Code가 매 세션 자동으로 읽는 프로젝트 컨텍스트. 빌드/테스트 명령, 규칙, 함정, 디렉터리 의미.
  • 왜: 위 문서들이 “이번에 무엇을”이라면, CLAUDE.md는 “이 저장소에서 항상 통하는 방식”. → 06. 워크플로.
  • 이 저장소의 CLAUDE.md가 그 예시.

얼마나 만들어야 하나 — 과하지 않게

문서는 비용이다. 규모에 맞춰라:

상황최소 문서 세트
일회성 스크립트·프로토타입없음 (vibe coding)
개인 작은 기능spec(수용 기준 포함) 한 장
유지보수할 제품 기능PRD + spec + 아키텍처 한 장 + tasks
팀/규제/대규모헌법 + PRD + spec + 아키텍처 + ADR + tasks 전부

규칙: 문서를 만드는 비용 < 그 문서가 막아줄 잘못된 구현의 비용 일 때만 만든다. 의심되면 더 적게 시작하고, 모호함이 드러나면 그때 문서를 늘려라.

문서 ↔ SDD 단계 매핑

문서SDD / SpecKit 단계
헌법/speckit.constitution
PRD + Spec/speckit.specify (+ /clarify)
아키텍처 + ADR/speckit.plan
계획·작업/speckit.plan, /speckit.tasks
CLAUDE.md(SpecKit 외부) Claude Code 상시 컨텍스트

다음: 이 전부를 Claude Code로 실행하는 06. 실전 워크플로.

← 목록으로