Write Spec

1. 스펙의 기술 영역 키워드를 추출한다 (예: Python, 테스트, DDD, GitHub Actions, 프론트엔드 등)
2. 현재 로드된 스킬 목록에서 키워드와 관련된 컨벤션 스킬을 선별한다
   • 대상: 코딩 표준, 아키텍처 패턴, 테스트 설계 등 품질/컨벤션을 정의하는 스킬
   • 제외: 워크플로우 스킬 (commit, deploy, release, submit-pr 등), 도구 스킬 (agent-browser 등)
3. 선별된 스킬의 SKILL.md 파일을 읽는다
   • ~/.claude/skills/{스킬명}/SKILL.md
   • 없으면 ~/.claude/plugins/ 하위에서 Glob으로 탐색
4. 읽은 컨벤션을 이후 단계(인터뷰, 코드베이스 확인, 작성)에 반영한다. 스펙이 컨벤션을 위반하거나 컨벤션이 다루는 사항을 누락하지 않도록 한다
5. 관련 스킬이 없으면 이 단계를 건너뛴다

3. 인터뷰

확인되지 않은 사항을 AskUserQuestion으로 질문한다.

인터뷰 영역:

• 기술적 결정: 아키텍처, 의존성, 트레이드오프 중 미확정 항목
• 경계 설정: 항상 해야 할 것, 먼저 물어볼 것, 절대 하지 말 것
• 소비자 고려: 기존 인터페이스를 변경하는 경우, 예상 소비자와 마이그레이션 전략
• 검증 방법: 테스트, 수동 검증 등

참조 스펙 기반 신규 모드에서 추가로 확인:

• 작업 단위 범위: 참조 스펙 중 이번 스펙이 다루는 부분과 제외되는 부분
• 상속 결정: 참조 스펙의 기술적 결정 중 그대로 따르는 것과 이번 단위에서 재검토하는 것
• 선행/후행 관계: 참조 스펙의 다른 작업 단위와의 의존 순서

규칙:

• 질문 전에 코드베이스에서 답을 찾을 수 있는지 먼저 확인한다
• 뻔한 질문은 하지 않는다
• 한 번에 1~2개의 깊이 있는 질문만 한다
• 대화/문서에서 이미 결정된 사항은 다시 묻지 않는다
• 선택지를 제안할 때는 각 선택지의 장단점과 프로젝트에 미치는 영향을 함께 제시한다
• 유저와 같은 언어로 질문한다
• 모든 미결정 사항이 해소될 때까지 반복한다

4. 코드베이스 확인 (필요 시)

스펙 작성에 필요한 기존 코드 구조, 인터페이스, 테스트 패턴을 확인한다.

스펙이 public 함수/클래스 시그니처를 정의하거나 기존 인터페이스를 변경하는 경우, 추가로 확인:

• 인터페이스 설계 품질: 파라미터가 적절한 레이어(생성자 vs 메서드)에 있는지, 호출자 관점에서 불필요한 인자가 없는지, 반환 타입이 소비자에게 유용한지
• 도메인 네이밍 일관성: 새로 도입하는 이름이 코드베이스(소비자 포함)의 기존 용어와 일관되는지. 동일 개념에 다른 용어가 사용되고 있지 않은지
• 기존 패턴 정합성: 코드베이스에 유사한 구조가 있다면 그 아키텍처/접근 방식과 일관되는지

5. 스펙 문서 작성

새 스펙 (인자 없음, 또는 --ref): docs/specs/ 하위에 작성한다. 파일명: {YYYY-MM-DD}-{kebab-case-영문}.md (예: 2026-04-03-user-auth-flow.md) 기존 스펙: 원본 파일을 수정한다.

--ref 모드일 때 추가로:

• 본문 상단에 참조 스펙 경로를 링크로 명시한다 (예: > 참조: [원본 스펙 제목](상대경로.md))
• 참조 스펙에 이미 기술된 내용을 복붙하지 않는다. 신규 스펙은 이번 작업 단위에 한정된 결정과 경계만 담는다
• 참조 스펙과 다르게 정한 사항이 있다면 "상세"에 명시한다

다음 구조로 작성한다:

# [기능명]

## 목표
[한 문장으로 무엇을 왜 만드는지]

## 상세
[구현 세부사항, 기술적 결정]

## 경계
- 항상: ...
- 먼저: ...
- 절대: ...

## 검증
[테스트 방법, 확인 절차]

5.1 검증 섹션 작성 원칙

검증은 섹션을 채우기 위한 항목이 아니라, 스펙이 의도한 변경이 실제로 반영되었는지 확인할 수단. 다음 원칙을 따른다.

• 실패 시 드러날 버그가 구체적이어야 한다: 각 항목은 "이 검증이 실패하면 어떤 버그가 드러나는가?"에 구체적 답이 있어야 한다. 답이 "두 곳에 같은 상수를 서로 다르게 입력했다" 수준이면 타당한 검증이 아니다
• 진실의 원천과의 정합성을 확인해야 한다: 테스트가 기대값을 원본에서 복제해 자기 자신과 비교하는 구조(tautology)는 금지. 요구사항/명세와의 일치를 확인하는 경로여야 한다
• 이미 보장된 것은 중복 검증하지 않는다: 타입체커, 컴파일러, 기존 테스트가 이미 보장하는 범위는 검증 항목에서 제외한다. 무엇이 이미 보장되는지 먼저 식별한다
• 의미 있는 검증이 없으면 비워둔다: 자동화 가치가 없거나 다른 수단으로 보장되는 경우 억지로 항목을 만들지 않는다. 쓰지 않는 이유를 명시한다

수동 검증은 자동화가 비용 대비 가치가 없거나 관측 대상이 감각적(오디오, UI, 렌더 결과)인 경우에만 구체적 조건으로 기술

본 섹션은 무엇을 검증할지를 정한다. 어떻게 테스트를 쓸지는 test-design 스킬을 따른다

규칙

• 대화에서 확인된 사실만 스펙에 반영한다. 추측하지 않는다
• 불확실한 부분은 인터뷰로 확정한 뒤 작성한다
• 스펙은 구현자가 바로 작업할 수 있을 만큼 구체적이어야 한다
• 한국어로 작성한다
• 2단계에서 참조한 컨벤션 스킬의 규칙을 위반하지 않도록 작성한다