RaamPrashathT/spec-it

spec-it은(는) 무엇을 하나요?

$ARGUMENTS를 후속 질문 없이 코딩 에이전트가 구축할 수 있는 명세와 모든 요구사항 및 엣지 케이스를 보여주는 목업으로 변환합니다.

아이디어 → 1. 컨텍스트 (질문 없음) → 2. 제품 질문 → 3. 기술 질문
     → 4. REQUIREMENTS.md → 5. 목업 → 6. 확인

references/…와 같은 경로는 ${CLAUDE_SKILL_DIR}에 상대적입니다. 출력은 spec-it/<kebab-name>/ 디렉토리에 저장됩니다:

spec-it/<name>/
├── REQUIREMENTS.md      핵심 결과물: 의도, 결정, 단계, 기능 요구사항, 엣지 케이스, 가정
└── mockups/             index.html + 화면, 또는 api.html + openapi.yaml, 또는 cli.html + transcripts.md
    └── assets/          theme.css, fixtures.js, app.js

규칙

1. 사실은 당신의 것, 결정은 그들의 것. 레포지토리, 첨부 파일, 웹 또는 표준이 답할 수 있는 것을 절대 묻지 마세요. 개발자를 대신해 범위, 우선순위 또는 트레이드오프를 결정하지 마세요.
2. 모든 질문은 그 자리를 증명해야 합니다. 각 질문 전에 references/questions.md의 질문 게이트를 실행하세요. 방어 가능한 표준 기본값이 있는 세부 사항은 질문이 아니라 가정(A-n)입니다.
3. 할당량 없음. 최소 질문 수는 없습니다. 일반적인 실행은 5~12개의 질문을 합니다. 개발자의 다음 답변을 예측할 수 있으면 중단하세요.
4. 피커를 통해 질문하세요 (AskUserQuestion, 피커 없이 일반 번호 텍스트). 호출당 최대 3개의 독립적인 질문, 다른 질문에 의존하는 옵션이 있는 질문은 절대 함께 묶지 마세요.
5. 각 질문은 한 번만 표시되며, 메시지의 마지막 항목이어야 합니다. 이후에 요약하지 마세요.
6. 상태를 디스크에 기록하세요. 컨텍스트 단계 후에 REQUIREMENTS.md를 작업 파일로 유지하세요: §1–2를 초기에 초안 작성하고, 결정이 확정될 때 채워 넣으세요. 컨텍스트 압축 후에는 작업 전에 다시 읽으세요.
7. 목업은 오프라인에서 작동합니다. CDN, 네트워크 또는 웹 폰트를 사용하지 마세요.
8. 확인 스크립트가 완료를 제어합니다: node ${CLAUDE_SKILL_DIR}/scripts/check.mjs spec-it/<name>이 0으로 종료되어야 합니다.

ID: FR-n 요구사항, EC-n 엣지 케이스, D-n 결정, A-n 가정. 모듈이 있는 경우 FR/EC/A는 모듈 접두사를 사용합니다(BOOK-FR-3). ID는 영구적입니다: 번호를 다시 매기지 말고, 제거 시 "(removed)"를 표시하세요.

1. 컨텍스트 (아직 질문 없음)

무엇이든 묻기 전에 이것을 먼저 하세요. 두 조회를 병렬로 실행하고, 가능한 경우 새 컨텍스트 서브에이전트를 사용하세요.

• 코드베이스 스캔 (폴더가 비어 있으면 건너뜀): 스택, 아이디어와 겹치는 기존 기능, 데이터 모델, 인증, UI 키트 및 디자인 토큰, API 및 CLI 규칙, 반쯤 완성된 것. 최대 25줄.
• 선행 사례 스캔 (웹 검색, 2–4회): 2–3개의 기존 제품이나 표준이 이 문제를 해결하는 방법; 이 도메인의 알려진 어려운 문제 (실제 사용에서 잘못될 수 있는 것); 표준 기능 세트; 관련 명세 (RFC, clig.dev, WCAG, 결제 또는 개인정보 보호 규칙). 최대 25줄, 출처 링크 포함.

그런 다음 개발자에게 컨텍스트 브리핑을 보여주세요 (최대 15줄):

발견한 내용
- 레포: <이 아이디어가 건드리거나 재사용하는 기존 것>
- 다른 사람들의 방식: <제품 A는 X를, 제품 B는 Y를 함>
- 이 도메인의 어려운 문제: <2–4개, 예: 노쇼로 방이 비어 있음; 반복 예약>
- 제 해석: <원하는 것과 그 이유에 대한 한 문장 가설> · 신뢰도 <n>%

유형(UI, API, CLI, 혼합)을 분류하고 assets/requirements-template.md에서 REQUIREMENTS.md를 생성하여 §1과 컨텍스트 섹션을 채우세요. 발견한 어려운 문제는 최상의 질문을 위한 원자재입니다.

2. 제품 질문

references/questions.md를 읽으세요. 가장 위험한 미지의 것부터 아래로 작업하세요: 이것이 올바른 문제인가, 누구를 위한 것인가, 무엇이 먼저 출시되는가, 무엇이 제외되는가, 그 다음 도메인의 어려운 문제를 구체적인 시나리오로 다루세요. 각 답변을 §결정에 D-n으로 기록하세요.

다음 세 가지가 모두 충족되면 기술 질문으로 전환하세요:

• 재진술(결과, 사용자, 이유, 성공, 범위 밖)을 개발자 자신의 말로 작성할 수 있을 때;
• 1단계 범위와 비목표가 합의되었을 때;
• 남은 것이 어떻게에 관한 것이지, 무엇, 누구, 왜가 아닐 때.

예외: 범위를 변경하는 하드 제약 조건("오프라인에서 실행되어야 함", "기존 Auth0 테넌트 재사용", "데이터를 EU에 유지")은 표면화되는 즉시 질문해야 합니다. 이는 제품 질문을 재구성하기 때문입니다.

3. 기술 질문

분기점에서만: 레포지토리와 표준이 해결하지 못하고, 답변이 데이터 모델, 계약 또는 사용자에게 보이는 동작을 변경하는 지점. 목록은 references/questions.md § 기술에 있습니다. 많은 실행에서 0–4개가 필요합니다. 레포지토리가 이미 고정한 호스팅, CI, 프레임워크 또는 벤더 선택에 대해 묻지 마세요.

확인 게이트. 한 메시지: 재진술(6줄), 그 다음 당신이 취한 모든 가정(A-n, 각각 한 줄, 기본값 포함). 질문: 확인하거나 변경할 것을 지정하세요. 변경 사항을 반영하세요. 명시적인 '예' 후에만 사양의 상태 줄에 Status: Confirmed를 작성하세요.

단계와 모듈

단계 (항상 고려). "무엇이 먼저 출시되는가" 제품 질문이 이를 결정합니다. 1단계는 사용자가 핵심 작업을 처음부터 끝까지 완료할 수 있는 가장 얇은 조각(워킹 스켈레톤)입니다. 개발자가 한 번에 모든 것을 원한다면 하나의 단계만 있습니다. 모든 FR은 Phase: n을 갖습니다. 1단계는 완전히 명세화되고, 이후 단계는 §배포 계획에서 기능당 한 글머리 기호로 표시되며, --next-phase가 세부 사항을 추가할 때까지 기다립니다.

모듈 (신호가 있을 때만). 다음 중 두 가지 이상을 충족할 때만 영역을 모듈로 취급하세요: 다른 사람이나 용어; 자체 데이터 소유; 단독으로 출시해도 유용함; 자체 10개 이상의 질문이 필요함. 2개 이상의 적격 영역이 있는 경우 한 번 질문하세요: 모듈 섹션이 있는 하나의 명세 (권장), 또는 가장 중요한 모듈을 지금 명세화하고 나머지는 개요만 제공. 아이디어가 얼마나 커 보이는지로 모듈을 추론하지 마세요. 모듈은 동일한 REQUIREMENTS.md에 §기능 요구사항 아래 ## 섹션으로 남아 있으며 ID 접두사를 사용합니다.

크기 제한. 1단계가 약 25개의 필수 FR 또는 12개의 목업 아티팩트를 초과하면 무엇을 2단계로 이동할지 질문하세요.

4. REQUIREMENTS.md 작성

템플릿을 채우세요. 모든 FR은 ID, 우선순위, 단계, Given/When/Then 및 Source: 결정 ID를 가지며, 제기된 모든 엣지 케이스는 구체적인 픽스처 값과 함께 EC-n이 됩니다. FR은 사용자가 관찰하는 것을 말하며, 기술은 §기술 결정에 들어갑니다. 그런 다음 이 목록에 대해 한 번 자체 검토하고 실패한 항목을 수정하세요:

• 동시에 유지될 수 없는 두 진술; 두 번 명시된 하나의 규칙.
• 개발자가 두 가지 다른 방식으로 구축할 수 있는 FR (누락된 제한, 단위, 역할 또는 실패 동작).
• 관찰로 통과 또는 실패할 수 없는 기준, 또는 숫자가 없는 모호한 단어.
• FR이 없는 역할, 엔티티 또는 흐름; 아무것도 인용하지 않은 결정.
• 용어집과 반대되는 단어 사용.

5. 목업

아티팩트(화면, 엔드포인트 그룹 또는 명령 그룹)를 최대 12개까지 나열하고, 각각의 상태와 모든 EC가 상태에 매핑되도록 합니다. 목록을 한 메시지로 보여주고 개발자가 반대하지 않으면 진행하세요. 그런 다음 references/screens.md (UI) 또는 references/api-cli.md (API, CLI)를 읽고 빌드하세요:

1. 먼저 mockups/assets/fixtures.js를 작성하세요: 모든 아티팩트가 표시하는 모든 이름, ID, 금액 및 날짜.
2. UI: 디자인 방향을 §디자인 방향에 작성하세요. 레포지토리에 디자인 시스템이나 토큰이 있으면 따르고 디자인 질문을 건너뛰세요; 그렇지 않으면 옵션 미리보기에 ASCII 스케치와 함께 하나의 디자인 방향 질문을 하세요.
3. ${CLAUDE_SKILL_DIR}/assets/theme.css와 app.js를 mockups/assets/로 복사하고 토큰을 설정한 후, 대비 검사가 통과할 때까지 확인 스크립트를 실행하세요.
4. references/renderer.md에서 각 아티팩트를 빌드하세요: 아티팩트가 4개 이상이고 서브에이전트 도구가 있으면 각 아티팩트에 대해 병렬로 하나의 서브에이전트를 사용하고, 그렇지 않으면 여기서 한 번에 하나씩 빌드하세요. CLI: mockups/transcripts.md를 작성한 후, node ${CLAUDE_SKILL_DIR}/scripts/cli-render.mjs spec-it/<name>을 실행하세요.
5. ${CLAUDE_SKILL_DIR}/assets/index.html에서 mockups/index.html을 채우세요.
6. 브라우저 도구가 있는 UI: 선택적으로 references/critic.md를 실행하고 상위 수정 사항을 한 번 적용하세요.

6. 확인 및 보고

확인 스크립트가 0으로 종료될 때까지 실행하세요; 모호성 경고는 다듬어야 할 표현으로 취급하세요. 최대 10줄로 보고하세요: 경로, 카운트(질문한 수, FR, EC, 가정, 아티팩트), 확인 요약 줄, 목업 보는 방법(mockups/index.html 열기, 또는 node ${CLAUDE_SKILL_DIR}/scripts/serve.mjs spec-it/<name>), 그리고 다음 단계가 있다면 그것을 포함하세요. node ${CLAUDE_SKILL_DIR}/scripts/export.mjs spec-it/<name>은 공유를 위한 단일 파일 복사본을 요청 시 작성합니다.

이후 실행

• --next-phase: 명세를 읽고, 다음 단계의 글머리 기호를 가져온 후, 해당 단계에 대해서만 2~6단계를 실행하세요 (질문은 1단계가 열어둔 것부터 시작합니다). 새 FR은 번호를 계속하고, 이전 ID는 절대 변경되지 않습니다.
• --revise (또는 변경 요청): 새 결정을 기록하고, 영향을 받는 FR과 EC를 업데이트하고, 영향을 받은 아티팩트만 다시 렌더링한 후 확인 스크립트를 다시 실행하세요.

합리화

생각	현실
"모든 영역을 다뤄야 하므로, 통합에 대해 물어봐야지."	답변이 명세를 변경하는 경우에만 물어보세요. "v1에는 없음"은 가정입니다.
"어떤 시간 단계를 원하는지 물어볼게."	표준 기본값이 존재합니다. A-n을 기록하고, 확인 게이트가 표시합니다.
"아이디어가 명확하니 컨텍스트 단계는 건너뛰자."	컨텍스트 단계는 좋은 질문이 나오는 곳입니다. 항상 실행하세요.
"아이디어가 커 보이니 모듈을 사용하자."	모듈은 신호가 필요하고, 그 다음 개발자의 선택이 필요합니다.
"모든 권장 사항을 수락했군요, 좋아요."	권장 사항이 너무 안전할 수 있습니다. 다음 질문은 개발자가 동의하지 않을 만한 것이어야 합니다.