Grill, then 명세 주도 개발

두 워크플로우가 연속으로 실행되며, 한 번의 핸드오프가 있습니다:

Grill (Matt Pocock, grill-me → to-spec): 사용자를 디자인 트리 형태로 인터뷰하여, 라운드별로 모든 것이 명시적으로 합의될 때까지 진행합니다. 그런 다음 합의된 이해를 바탕으로 새로운 질문 없이 명세를 종합합니다.
Build (DeepLearning.AI + JetBrains, Spec-Driven Development with Coding Agents): 명세는 날짜가 포함된 디렉토리 아래 요구사항.md, 계획.md 및 검증.md로 저장소에 저장되고, 자체 브랜치에서 작업 그룹별로 구현되고, 검증.md에 대해 검증되며, 변경 로그에 기록되고, 병합된 후 로드맵이 재계획됩니다.

Grill은 SDD 과정의 고정된 세 가지 질문 인터뷰(범위/결정/컨텍스트)를 전체 디자인 트리 인터뷰로 대체합니다. SDD 과정은 to-spec의 "이슈 트래커에 게시" 방식을 코드와 함께 존재하고 변경되는 명세 파일로 대체합니다.

개요

사용 시점: 변경 사항이 충분히 커서 먼저 문서화하는 것이 재작업보다 저렴한 경우: 새 기능, 로드맵 단계, MVP 스프린트 또는 레거시 코드베이스에 SDD 추가. 한 줄 수정이나 순수 버그 추적에는 건너뛰세요 (근본 원인 분석은 pstack-engineering 사용).

트리거 구문: "grill me then spec it", "grill to spec", "spec-driven", "SDD", "feature spec", "work on the next phase", "start the next feature".

하드 게이트 (절대 건너뛰지 않음):

사용자가 Grill이 공유된 이해에 도달했음을 확인할 때까지 명세 파일을 작성하지 않습니다 (게이트 A).
사용자가 명세 파일을 승인할 때까지 코드를 작성하지 않습니다 (게이트 B).
검증.md의 모든 항목이 통과할 때까지 병합하지 않습니다 (게이트 C).

실행 지침

시작 시 SPECS=${SDD_SPECS_DIR:-specs} 및 BASE=${SDD_BASE_BRANCH:-<저장소 기본 브랜치>}를 해석합니다. 아래 경로는 프로젝트 루트 기준입니다.

0단계 — 사전 파악 (사실 확인이 당신의 임무입니다)

프로젝트의 AGENTS.md / CLAUDE.md, README.md 및 용어집이나 ADR을 읽습니다. 저장소 자체의 git 규칙(래퍼, 브랜치 명명, 강제 푸시 금지)을 따릅니다.
헌법 확인: $SPECS/mission.md, $SPECS/tech-stack.md, $SPECS/roadmap.md.
- 모두 존재 → 다음 기능에 대해 1단계로 이동합니다.
- 누락, 새 프로젝트 → 첫 번째 Grill은 헌법 자체에 관한 것입니다 (미션, 대상 사용자, 기술 스택 차이점). 그 결과물은 세 파일이며, roadmap.md는 매우 작은 단계로 나뉘고, 각각 독립적으로 출시 가능해야 합니다.
- 누락, 기존 코드베이스(레거시) → 먼저 코드를 탐색하고 실제로 있는 내용(스택, 규칙, 출시된 기능은 완료된 단계로)을 기반으로 헌법 초안을 작성한 다음, 차이점과 향후 로드맵에 대해서만 Grill을 진행합니다.
사용자가 기능 이름을 지정하지 않은 경우, 대상은 다음 단계입니다: 로드맵에서 항목이 모두 체크되지 않은([ ]) 첫 번째 섹션.
기능이 다룰 코드를 탐색합니다. 저장소, 도구 또는 문서가 답할 수 있는 질문을 사용자에게 절대 묻지 않습니다. 광범위한 탐색이 필요한 경우, 환경에 새 하위 에이전트가 있다면 위임하고 관련 없는 질문을 차단하지 않습니다.

1단계 — Grill (디자인 트리 인터뷰)

공유된 이해가 확립될 때까지 집중적으로 사용자를 인터뷰합니다. 계획을 디자인 트리로 취급합니다: 모든 결정은 그에 의존하는 결정들로 분기됩니다.

라운드로 작업합니다. 프런티어는 모든 전제 조건이 이미 해결된 열린 결정입니다. 한 라운드에서 전체 프런티어를 질문한 다음 기다립니다.
각 질문에 번호를 매기고 권장 답변을 제시합니다. "예"가 권장 사항을 수락하도록 단어를 선택합니다.
같은 라운드에서 여전히 열려 있는 다른 질문에 의존하는 질문은 이후 라운드에 속합니다.
라운드 전체에서 최소한 SDD 축을 다룹니다: 범위(수집, 노출, 수행하는 것; 데이터 형태), 결정(저장소, 가시성, 검증, UX 패턴, 아키텍처), 컨텍스트(톤, 제약 조건, 스택 한계, 열린 질문) 및 테스트 지점: 기능이 테스트될 위치. 기존 지점과 가능한 가장 높은 지점을 선호합니다. 이상적인 것은 하나입니다.
새 종속성, 스키마 변경 및 공개 API 변경은 항상 명시적 질문이며 가정하지 않습니다 (tech-stack.md가 권위자입니다).

라운드 형식:

❓ **Q1** - **<제목>**: <질문, 옵션(있는 경우)>

➡️ <권장 답변>

---

❓ **Q2** - ...

환경에 구조화된 질문 도구(Claude Code AskUserQuestion)가 있는 경우 최대 4개의 객관식 질문으로 이루어진 라운드에 사용할 수 있습니다. 그렇지 않으면 위의 텍스트 형식을 사용합니다.

Grill은 프런티어가 비어 있을 때 종료됩니다. 합의된 결정을 짧은 목록으로 요약하고 사용자에게 확인을 요청합니다.

게이트 A: 사용자가 요약을 확인할 때까지 계속하지 마십시오.

2단계 — 명세 작성 (종합, 새로운 질문 없음)

대화를 명세로 전환합니다. 다시 인터뷰하지 않습니다. 실제 공백이 나타나면 Grill이 분기를 놓쳤음을 의미합니다. 해당 질문 하나만 묻고 계속합니다.

$BASE에서 브랜치를 생성합니다: 로드맵 단계의 경우 phase-<N>-<케밥-이름>, 그 외에는 feature/<케밥-이름> (또는 저장소의 자체 규칙 사용).
$SPECS/mission.md 및 $SPECS/tech-stack.md, 그리고 기존 기능 명세의 스타일을 다시 읽습니다.
오늘 날짜로 $SPECS/YYYY-MM-DD-<기능-이름>/을 생성하고 references/spec-templates.md의 세 파일을 작성합니다:
- 요구사항.md — to-spec 내용(문제, 솔루션, 광범위한 번호가 매겨진 사용자 스토리 목록, 구현 결정, 테스트 결정, 범위 외) 및 SDD 범위/결정/컨텍스트 섹션. 파일 경로나 코드 스니펫은 없습니다. 단, 결정을 산문보다 더 정확하게 고정하는 축약된 프로토타입 스니펫은 예외입니다.
- 계획.md — 번호가 매겨진 작업 그룹, 각각 독립적으로 구현 및 테스트 가능하며, 번호가 매겨진 하위 작업이 있습니다.
- 검증.md — 자동화된 검사(정확한 명령어), 수동 워크스루, 엣지 케이스, 사용자 대면 복사본에 대한 톤 확인, 그리고 완료 정의.
선택 사항, 사용자가 요청하거나 저장소가 이슈에서 작업을 추적하는 경우: 요구 사항을 이슈로 게시하고(gh issue create) 요구사항.md에서 링크합니다.
사용자에게 세 파일(경로 및 짧은 요약)을 보여줍니다.

게이트 B: 승인을 기다립니다. 피드백("X에 대한 작업 그룹 추가", "컴포넌트는 자체 파일에")은 명세에 먼저 적용되며 모든 파일은 동기화 상태를 유지합니다.

3단계 — 구현

작업 그룹을 순서대로 구현합니다. 각 그룹 후: 프로젝트 테스트 및 타입 검사를 실행하고, 그룹 이름을 메시지로 커밋하고, 계획.md에서 해당 상자를 체크합니다.
구현 결과 명세가 잘못되었거나 불완전한 것으로 드러나면, 명세를 코드와 동일한 커밋에서 업데이트합니다. 명세와 코드는 절대 분리되지 않습니다.
서로에 대한 종속성이 없는 그룹은 병렬 하위 에이전트(각각 자체 작업 트리에서, 호스트의 작업 트리 규칙을 따름)로 넘어갈 수 있으며, 사용자가 병합합니다.
사용자의 승인 없이 새 종속성을 추가하지 않습니다. 그룹이 "필요"하더라도 마찬가지입니다.

4단계 — 검증

검증.md의 모든 자동화된 검사를 실행하고 실제 출력을 붙여넣습니다.
수동 검사를 수행합니다(UI의 경우 실제로 구동: 브라우저 자동화 또는 스크린샷, "작동해야 함"이 아닌).
선택적 심층 검토: 브랜치 차이에 대해 세 가지 관점(정확성, 명세 적합성, 유지보수성)에서 리뷰어를 생성하고, 문제가 되는 부분을 수정합니다.
사용자에게 구축된 내용에 비추어 명세를 명확히 할 필요가 있는지 질문합니다.

게이트 C: 모든 완료 정의 항목이 통과하거나 사용자가 명시적으로 하나를 면제합니다 (면제는 검증.md에 기록).

5단계 — 종료

$SPECS/roadmap.md에서 단계를 완료로 표시합니다([x]).
CHANGELOG.md를 업데이트합니다(# Changelog, ## YYYY-MM-DD 헤딩은 최신순, 마지막 기록 날짜 이후의 의미 있는 변경 사항당 한 개의 글머리 기호). 프로젝트 changelog 스킬이 있으면 사용합니다.
커밋하고, $BASE로 전환하고, 브랜치를 병합하고, 삭제하고, 저장소 규칙에 따라 푸시합니다.
재계획: 배운 내용이 mission.md, tech-stack.md 또는 로드맵을 변경하는지 질문합니다 (단계 병합, 분할 또는 재정렬). 교차 결정(예: "Vitest 사용", "반응형 UI")은 tech-stack.md / mission.md에 들어가고 기존 명세에 역포팅됩니다.
다음 단계를 제안합니다: 1단계부터 다시 시작합니다.

환경 변수

변수	기본값	설명
`SDD_SPECS_DIR`	`specs`	헌법 및 기능 명세 디렉토리, 프로젝트 루트 기준
`SDD_BASE_BRANCH`	저장소 기본 브랜치	기능이 생성되고 병합되는 브랜치

확인 체크리스트

알려진 함정

영원히 Grill하기. 프런티어가 비어 있으면 Grill이 종료됩니다. 호기심이 다할 때가 아닙니다. 이미 결정된 사항을 다시 묻지 마세요. 코드 리뷰에 속하는 세부 사항을 묻지 마세요.
명세 작성 단계에서 인터뷰하기. 2단계는 종합합니다. 새로운 질문이 있다면 Grill이 불완전했다는 의미입니다. 누락된 질문 하나를 묻고 두 번째 인터뷰는 하지 마세요.
게이트 A/B 전에 작성하기. SDD 과정은 명확합니다: 인터뷰가 응답될 때까지 아무것도 디스크에 기록하지 않습니다. 명세 승인 전 코드는 방법을 무효화합니다.
너무 큰 단계. 한 번에 검토할 수 없는 단계는 명세 작성 전에 로드맵에서 분할해야 합니다.
명세 표류. 구현 중간에 요청된 변경 사항은 명세에 먼저 적용된 다음 코드에 적용됩니다. 코드와 더 이상 일치하지 않는 명세는 없는 것보다 나쁩니다.
요구사항의 파일 경로. 빨리 썩습니다. 대신 모듈과 인터페이스를 설명하세요 (경로는 최대 계획.md 하위 작업에만 속합니다).
저장소 규칙이 우선합니다. 저장소의 AGENTS.md에 있는 브랜치 이름, 푸시 래퍼, 작업 트리 위치 및 기여 규칙은 여기의 기본값을 재정의합니다.

파일 템플릿은 references/spec-templates.md를, 각 부분의 출처는 references/sources.md를 참조하세요.

Grill → 명세 주도 개발