구현 계획 수립 스킬
목적
implement-commit 스킬을 구동하는 TOML 구현 계획을 생성합니다.
계획은 기계가 파싱 가능해야 합니다—오케스트레이터가 기계적으로 읽습니다.
사용 시기
- 기능 설계 문서가 존재하고 승인됨
- 구현을 시작할 준비가 됨
- 작업을 조정하거나 진행 상황을 추적해야 함
전제 조건
- 기능 설계가
docs/features/NNNN-기능명/design.md에 존재 - 테스트 계획이
docs/features/NNNN-기능명/test-plan.md에 존재
출력 형식
docs/features/NNNN-기능명/implementation-plan.toml 생성:
[meta]
feature = "기능명"
feature_dir = "docs/features/NNNN-기능명"
workspace = "./작업공간/경로"
[dependencies]
1 = []
2 = []
3 = [1, 2]
[[commits]]
id = 1
title = "간단한 설명"
message = "feat(범위): 관례적인 커밋 메시지"
files = ["경로/대상/파일.rs"] # 작업공간 기준 상대 경로
acceptance = ["CC 테이블의 기준 (CC-N)"]
anti_patterns = ["하지 말아야 할 것"]
tests = ["테스트_계획의_테스트_이름"] # 필수: test-plan.md에 매핑
절차
1. 설계 문서 연구
design.md를 철저히 읽고 다음을 기록:
- 모듈 구조 및 영향받는 파일
- 컴포넌트 간 의존성
- 중요 제약 조건 표 (CC-1, CC-2 등)
2. 테스트 계획 연구 (중요)
test-plan.md를 읽고 매핑 생성:
- 요구사항 커버리지 표의 모든 테스트 이름 나열
- 각 테스트는 반드시 정확히 하나의 커밋에 할당
- 테스트는 허용 기준의 진실 공급원
3. 기능 경계 식별
코드 아티팩트 경계가 아닌 기능 경계를 찾으세요.
좋은 경계:
- 새로운 모듈과 그 타입, 구현, 테스트가 함께
- 사용자에게 보이는 기능 (예: 새 CLI 명령어)
- 요구사항이 종단 간 충족됨
안티 패턴: 아티팩트별로 분할 (타입은 한 커밋, 구현은 다른 커밋, 테스트는 세 번째 커밋).
4. 의존성 그래프 구축
각 커밋에 대해 먼저 완료되어야 하는 커밋을 나열합니다.
[dependencies] 테이블로 인코딩하며, 키는 커밋 ID, 값은 의존성 ID 목록입니다.
오케스트레이터는 이를 사용하여 병렬 실행을 결정합니다.
5. 커밋에 테스트 매핑
각 커밋에 대해 test-plan.md에서 해당 커밋을 검증하는 특정 테스트 이름을 나열합니다:
tests = [
"test_protocol_encode_acquire_request",
"test_protocol_decode_roundtrip",
]
test-plan.md의 모든 테스트는 정확히 하나의 커밋 tests 배열에 나타나야 합니다.
이것은 감사 가능한 추적성을 생성합니다: test-plan.md → implementation-plan.toml → 코드.
6. 중요 제약 조건 추출
각 커밋에 대해 설계의 중요 제약 조건 표에서 관련 항목을 복사:
acceptance= 반드시 충족되어야 하는 기준 (CC-N 및 테스트 이름 참조)anti_patterns= 검토자가 거부해야 할 것
7. 커밋 항목 작성
각 커밋에 대해:
[[commits]]
id = N # 순차 정수
title = "..." # 이 커밋이 달성하는 것
message = "..." # 전체 관례적인 커밋 메시지
files = ["..."] # 작업공간 기준 상대 경로
acceptance = ["..."] # CC 표 + 테스트 설명에서
anti_patterns = ["..."] # CC 표에서, 또는 빈 []
tests = ["..."] # test-plan.md의 테스트 이름 (필수)
8. 독립 에이전트로 검증
계획 초안을 작성한 후, 검증 에이전트를 생성:
result = spawn(
prompt=draft_spawn_prompt(SkillDefined(
"구현 계획이 test-plan.md의 모든 테스트를 포함하는지 검증"
)),
context_files=[
f"{skill_dir}/agents/verifier.md",
f"{feature_dir}/test-plan.md",
f"{feature_dir}/implementation-plan.toml",
],
response_model=VerificationResult,
read_only=True,
)
if not result.parsed.valid:
# 계속 진행 전에 누락 수정
agent_feedback(f"계획 불완전: {result.parsed.gaps}")
검증기는 다음을 확인:
- test-plan.md의 모든 테스트가 커밋에 할당됨
- 어떤 테스트도 여러 커밋에 할당되지 않음
- 허용 기준이 특정 테스트를 참조함
9. TOML 유효성 검사
# TOML 파싱 확인
python3 -c "import tomllib; tomllib.load(open('implementation-plan.toml', 'rb'))"
커밋 크기 가이드라인
목표: 커밋당 200-400줄 변경
너무 작음:
- 구현 없는 타입
- 적어도 하나의 구현이 없는 트레이트
- 테스트 없는 구현
너무 큼:
- 관련 없는 여러 기능
- 500줄 초과
- 5-6개 이상의 파일 수정
적당함:
- 타입, 구현, 테스트를 포함한 모듈 (~200-400줄)
- 핸들러와 테스트를 포함한 CLI 명령어 (~150-350줄)
- 테스트를 포함한 완전한 어댑터 (~200-400줄)
검증 모델
from pydantic import BaseModel
class VerificationResult(BaseModel):
valid: bool
total_tests_in_plan: int
tests_assigned: int
gaps: list[str] # 어떤 커밋에도 할당되지 않은 테스트
duplicates: list[str] # 여러 커밋에 할당된 테스트
예시
전체 예시는 docs/features/0000-템플릿/implementation-plan.toml을 참조하세요.
다음 단계
계획을 생성하고 검증한 후:
- 실현 가능성과 크기 검토
implement-commit스킬을 실행하여 구현