설계 후 구축하기
에이전트는 구현은 빠르지만 설계가 붕괴되고 있다는 사실을 알아채지 못합니다. 해결책은 코드가 존재하기 전에 결정 사항에 동의하는 것입니다. 그러면 각 PR이 이미 승인된 내용과 일치하므로 리뷰가 빠릅니다. 각 단계를 초안으로 작성하고, 사용자가 검토 및 승인합니다.
1. 작업 규모 산정 및 단계 선택
| 작업 | 단계 |
|---|---|
| 중간 기능, 국소적 리팩터링 | 프로그램 설계 → 슬라이스 |
| 큰 기능, 전반적 리팩터링 | 아키텍처 → 프로그램 설계 → 슬라이스 |
| 새 프로젝트, 멀티 레포, 또는 불명확한 문제 | 제품 → 아키텍처 → 프로그램 설계 → 슬라이스 |
선택한 규모와 이유를 한 줄로 말씀해 주세요. 사용자는 단계를 추가하거나 생략할 수 있습니다.
2. 먼저 컨텍스트 수집하기
초안을 작성하기 전에: docs/README.md와 그 문서가 가리키는 살아있는 문서, docs/designs/에 있는 열린 설계 문서, 해당 영역의 관련 코드와 git 히스토리를 읽으세요. 도구나 접근 방식 중에서 선택해야 할 경우 (문서, 벤치마크, 알려진 이슈를) 조사하고 구체적인 옵션과 출처를 제시하세요. 가정에 기반하여 설계하지 마세요.
3. 각 단계 실행하기
template.md에서 docs/designs/YYYY-MM-DD-<slug>.md 설계 파일을 생성합니다 (레포에 해당 레이아웃이 없다면 먼저 글로벌 규칙에 따라 docs/ 레이아웃을 설정하세요). 각 단계에 대해, 이 스킬의 폴더에 있는 해당 단계 파일을 읽고, 설계 파일의 해당 섹션을 초안으로 작성한 후 멈춥니다:
product.md: 문제, 사용자, 동작, 범위 밖architecture.md: 컴포넌트, 계약, 데이터 모델, 제약 조건program-design.md: 타입, 시그니처, 파일 레이아웃, 호출 흐름slices.md: 빌드 순서, 레포, PR, 각 슬라이스의 체크 항목
멈출 때 사용자에게 다음을 보여줍니다:
- 도움이 되는 다이어그램과 짧은 요약 (전체 문서를 채팅에 붙여넣지 않음)
- 내린 결정과 열린 질문들을 번호를 매겨 사용자가 "2: 네"라고 답할 수 있도록 함
사용자가 이 단계를 승인할 때까지 다음 단계를 시작하지 마세요. 사용자가 무언가를 변경하면 채팅뿐만 아니라 설계 파일도 업데이트하세요.
4. 슬라이스별로 구축하기
슬라이스 계획이 승인된 후:
- 한 번에 하나의 슬라이스를 구축합니다. 각 슬라이스는 합의된 체크 항목이 통과되고 그 증거가 보여진 상태로 종료됩니다.
- 슬라이스당 하나의 PR(또는 사용자가 PR을 사용하지 않으면 커밋)을 작성하며, 글로벌 규칙에 따라 설명합니다.
- 구현 중 설계가 잘못되었음을 알게 되면, 조용히 설계에서 벗어나지 말고 중단하고 설계 변경을 제안합니다. 변경이 합의되면 설계 파일을 업데이트합니다.
- 설계 파일에서 슬라이스가 적용될 때마다 체크 표시를 하여, 이후 세션이 그 지점부터 이어갈 수 있게 합니다.
5. 완료하기
마지막 슬라이스가 적용되면, 살아있는 문서가 진실의 원천으로 유지되도록 결과를 반영합니다:
- 레포의
docs/product.md,docs/architecture.md및 주제별 문서(이 스킬의 단계 파일이 아님)를 현재 시스템 상태에 맞게 업데이트하고, 글로벌 규칙의 문서 작성 규칙을 따릅니다. - 새롭거나 프로젝트 특화된 어려운 용어를
docs/glossary.md에 추가합니다. - 각 중요한 결정 사항을
docs/decisions/NNNN-<slug>.md노트로 만듭니다. - 설계 파일을 완료로 표시하고
docs/README.md에 추가합니다. 이후에는 다시 작성하지 마세요. - 살아있는 문서에서 무엇이 변경되었는지 사용자에게 보여줍니다.