Dev Workflow

기능 개발 워크플로

모든 개발은 기획/설계 → 상세계획 → 구현/테스트 → 최종리뷰 순서로 진행한다.

단계별 스킬·모델 규칙

• SDD 진행 중 태스크별 리뷰는 구현 단계에 속하므로 Sonnet 5로 진행한다.
• 최종리뷰는 전체 브랜치를 1회만 리뷰한다. 추가 리뷰 라운드나 재검증 패스를 스스로 만들지 마라.
• 리뷰에서는 발견한 이슈를 심각도와 무관하게 모두 보고하라.
• 최종리뷰에는 산출물이 「원 요청」 인용문에 답하는지를 계획 준수 여부와 독립된 별도 항목으로 포함하라. 예/아니오 체크가 아니라 어떻게 답하는지를 서술한 뒤 판정하라.
• 실행 시 현재 기본 모델과 다를 시: 상세개발계획·최종리뷰는 해당 모델의 서브에이전트로 위임하고, 기획/설계(대화형)는 사용자에게 /model 전환을 요청한다.
• 위 단계에 정의된 것 외의 서브에이전트는 만들지 마라.

단계 전환 규칙

• 기획/설계와 상세계획 단계가 끝나면 산출물(설계 문서, 계획 문서)을 요약해 보고하고 사용자 컨펌을 받은 뒤에만 다음 단계로 진행하라. 컨펌 없이 다음 단계를 시작하지 마라. 수정 요청이 있으면 반영 후 다시 컨펌을 받아라.
• 컨펌 보고에는 「원 요청」 인용과, 산출물이 그 요청에 어떻게 답하는지를 함께 제시하라. 사용자가 승인하는 대상은 산출물 자체가 아니라 "원 요청에 대한 이 답"이다.
• 구현/테스트가 끝나면 컨펌 없이 바로 최종리뷰로 진행하라.
• 최종리뷰가 끝나면 구현 결과와 리뷰에서 발견된 이슈를 함께 보고하고 사용자 컨펌을 받아라. 이 컨펌이 머지·이슈 수정 여부의 결정이다.

경량 경로

아래 두 조건을 모두 만족하면 4단계 대신 경량 경로를 쓴다.

• 설계 결정이 없다 — 어떻게 고칠지가 자명하고 선택지가 하나뿐이다.
• 변경이 한 관심사에 국한된다 — 새 모듈·새 의존성·인터페이스 변경이 없다.

경량 경로:

1. 무엇을 왜 어떻게 고칠지 2~3줄로 보고하고 컨펌을 받아라.
2. 구현하라. 버그면 재현 테스트를 먼저 쓴다(TDD는 그대로 유지한다).
3. 변경 요약을 보고하라. 설계·계획 문서와 최종리뷰는 생략한다.

• 판단이 애매하면 전체 경로를 써라. 경량 경로는 예외이지 기본값이 아니다.
• 구현 중에 설계 결정이 필요해지면 즉시 멈추고 전체 경로로 전환하라.
• 브랜치·커밋 규칙은 경량 경로에도 그대로 적용된다.

브랜치·커밋 규칙

• 새 기획 시작 시 {feature-name} 기반으로 브랜치를 만들고 시작하라.
• 작업 단계별로 git에 커밋하여 이력을 저장하라.
• 커밋 메시지 형식: <type>: #<일감번호> <제목 (한글 가능)> + 본문(선택)
  • type 예시: feat, fix, refactor, chore, docs
  • #<일감번호>: DevOps, Zira 등 형상관리 도구에 사용하는 번호가 있을 경우, 없으면 생략
• Co-Authored-By 문구 사용 금지 — 커밋 메시지에 포함하지 않음

문서 규칙

• 기획/계획 작성 시 반드시 markdown 파일로 저장하라.
  • 설계: docs/feature/yyyy-mm/yyyy-mm-dd-{day-sequence}-{feature-name}-design.md
  • 계획: docs/feature/yyyy-mm/yyyy-mm-dd-{day-sequence}-{feature-name}-plan.md
  • {day-sequence}는 그날 순번 2자리, 01부터. 계획은 해당 설계와 동일한 순번을 쓴다.
• 설계·계획 문서 맨 위에 「원 요청」 섹션을 두고 사용자의 요청을 원문 그대로 인용하라(요약·의역 금지). 계획 문서는 설계 문서의 인용을 그대로 옮긴다.
• 설계 문서에는 해당 기능의 주요 엔티티·모듈 네이밍 항목을 포함하라. 구현은 이 네이밍을 따른다. (코드 네이밍 상세 규칙은 .claude/rules/의 언어별 규칙을 따르라.)
• 문서는 결정 사항과 그 근거 중심으로 필요한 내용만 담아라. 상투적 요약, 채우기 섹션, 중복 설명으로 분량을 늘리지 마라.
• 모든 문서는 한국어로 작성하라.