명세 기반 기능 개발
개요
이 스킬은 계획-선-코드 게이팅 프로토콜을 강제합니다. 자율 코딩 에이전트는 종종 바로 파일 수정에 뛰어들어 컨텍스트 드리프트, 환각 API, 시행착오 디버깅에 토큰을 낭비하는 실패를 겪습니다.
이 스킬이 활성화되면, 공식 사양(SPEC.md 또는 .specs/<feature-slug>.md)이 작성되고, 저장소 제약 조건에 대해 검증되며, 승인될 때까지 애플리케이션 코드를 수정할 수 없습니다.
1단계: 컨텍스트 및 제약 조건 탐색
사양을 작성하기 전에:
- 기존 컨벤션, 데이터 모델 및 API 유틸리티를 프로젝트에서 식별합니다.
- 타입 정의 또는 스키마 파일(예:
schema.prisma,drizzle/schema.ts, Zod 스키마, OpenAPI 사양)을 찾습니다. - 필요하지 않으면 전체 파일을 읽지 말고, 내보내기, 인터페이스 헤더 및 타입을 검사합니다.
2단계: SPEC.md 초안 작성
./references/spec_template.md를 읽고 다음 정확한 구조를 따라 .specs/<feature-slug>.md(또는 요청된 경우 저장소 루트에 SPEC.md)를 생성합니다:
- 목표, 성공 기준 및 명시적 비목표: 명확한 2문장 문제 설명, 결정론적 통과 기준 및 명시적 범위 밖 경계.
- 데이터 계약 및 시그니처: 정확한 TypeScript 인터페이스, 데이터베이스 컬럼 타입 또는 API 스키마.
- 파일 수정 경계 행렬: 명시적인
생성,수정(대상 함수/라인 포함) 및금지경로. - 구현 체크리스트 및 검증 프로토콜: 정확한 테스트 명령, 린터 검사 및 엣지 케이스.
3단계: 게이팅 체크포인트 (필수)
사양이 생성되면:
- 대화형 모드 (사용자 세션): 사양 파일에 대한 링크와 함께 간결한 요약을 제시하고, 아키텍처 트레이드오프(여러 유효한 접근 방식이 있는 경우
ask_question사용)를 표면화한 후, 코드 작성을 진행하기 전에 확인을 요청합니다:"
SPEC.md에 사양을 초안 작성했습니다. 제안된 데이터 계약 및 파일 경계 행렬을 검토해 주세요. 구현을 진행할까요?" - 자율 하위 에이전트 모드: 상위 리드 오케스트레이터(예:
code-audit-orchestrator)에 의해 호출되어 이미 승인된 수정 계획이 제공된 경우, 파일 경계 행렬이금지경로와 충돌이 없는지 확인하고 4단계로 진행합니다. - HARD STOP: 대화형 세션에서는 승인 또는 피드백을 기다립니다. 허가를 받을 때까지 소스 파일을 건드리지 마십시오.
4단계: 단계적 실행 및 중간 수정 프로토콜
승인 후:
- 선택적 샌드박스 격리: 다중 파일 변경의 경우 또는 기본 작업 트리에 관련 없는 변경 사항이 있는 경우, 파일을 수정하기 전에
git-worktree-isolator를 통해 격리된 작업 트리를 준비합니다. - 개별적인 원자적 이정표(예: 스키마 $¥to$ 코어 로직 $¥to$ API 핸들러 $¥to$ UI/통합)로 기능을 구현합니다.
- 이정표가 완료됨에 따라 사양 파일에서 진행 체크박스를 표시합니다.
- Git 커밋을 개별 이정표로 범위를 지정합니다.
탈출구: 중간 사양 수정
구현 중 예상치 못한 제약 조건(예: 금지 파일을 반드시 수정해야 함, 업스트림 SDK 타입이 초안 작성된 계약과 일치하지 않음, 또는 사용자가 중간에 요구 사항을 수정)이 발견되면:
- 영향을 받는 이정표에 대한 편집을 즉시 중단합니다.
- 사양 파일의
## 6. 사양 수정 사항 (델타 로그)에 다음을 문서화하는 항목을 추가합니다:- 트리거 / 차단 요인: 원래 계약을 유지할 수 없는 이유.
- 수정된 섹션 및 델타: 데이터 계약 또는 파일 수정 경계 행렬의 정확한 변경 사항.
- 델타가 이전에
금지된 파일을 건드리거나 공개 API/스키마 계약을 변경하는 경우, 일시 중지하고 재개하기 전에 사용자에게 빠른 확인을 요청합니다. 델타가 순수하게 내부적(예: 내부 헬퍼 파일 추출)인 경우, 델타를 사양에 기록하고 계속 진행합니다.
5단계: 검증 및 보관
- 2단계에서 지정된 결정론적 테스트 스위트를 실행합니다.
- 모든 타입 검사와 린터가 깨끗하게 통과하는지 확인합니다.
- 사양 상태를
완료로 업데이트하고.specs/completed/YYYY-MM-DD-<feature-name>.md로 보관합니다(또는 저장소가.specs/를 추적하지 않는 경우 임시 사양 파일을 제거합니다).