출력 스타일 (평범한 단어, 대시 없음, 하이픈 없음)
이 스킬이 생성하는 모든 것(파일과 메시지 모두)을 평범하고 간단한 언어로 작성합니다. 독자를 당신으로 부르며 동료처럼 따뜻하고 직접적으로 말하고, 모든 단계를 명령이 아닌 실행하거나 건너뛸 수 있는 추천으로 제시합니다. 실제 의미를 지닌 기술 용어는 유지하고, 각각을 평범한 단어로 설명합니다. 문장 부호로 대시나 하이픈을 절대 사용하지 않습니다: em 대시, en 대시, 하이픈으로 연결된 복합어도 사용하지 않습니다. read-only 대신 read only라고 씁니다. 간단한 단어로 말하거나 문장을 다시 작성합니다. 코드, 파일 경로, 명령 플래그, 다른 스킬이 일치시키는 값은 하이픈을 유지합니다. 짧은 문장, 쉼표, 또는 괄호를 사용합니다. 명확함이 영리함보다 중요합니다.
이 스킬이 하는 일
구조화된 발견(discovery)을 실행하고, 옵션을 평가하며, docs/specs/에 빌드 명세서를 작성하거나 업데이트합니다. 메인 스레드는 쓰기를 담당하며, 코드베이스 읽기나 웹 가져오기와 같은 작업은 저렴한 서브 에이전트에게만 위임합니다(서브 에이전트 참조). 네 가지 모드:
| 모드 | 사용 시기 | 설계 동작 |
|---|---|---|
FEATURE | 기존 코드 유무와 관계없이 새로운 기능을 처음부터 설계할 때 | 원칙 기반 설계, 모범 사례, 최소한의 코드 읽기 |
ARCHITECTURE | 새 프로젝트의 기술 스택이나 기반 아키텍처를 선택할 때 | 포괄적인 스택 평가, 업계 패턴, 읽을 코드 없음 |
ENHANCEMENT | 이미 존재하는 것을 개선, 교체, 또는 확장할 때 | 기존 코드 + 명세서 읽기, 집중된 옵션 비교 |
CROSS-CUTTING | 오류 처리, 로깅, 인증, 네이밍 등 코드베이스 전체에 걸쳐 패턴을 표준화할 때 | 현재 상태 샘플링, 표준 정확히 정의, 적용 권장 |
- 생성: 새로운 결정 →
Proposed상태의 새 명세서 - 업데이트: 기존 결정을 발전시킴 → 기존 명세서를 그 자리에서 편집
- 대체: 과거 결정을 교체함 → 새 명세서 + 기존 명세서의 상태 줄 업데이트
- 비준: 엔지니어가 결정하기 전에 빌드하기로 선택했을 때
/develop이 기록한Assumed명세서를 심의함 → 아래 비준(Assumed) 결정 비준하기 참조
명세서 상태는 빌드 가능한 범위 기능이 명세서를 연결하는지 여부(docs/scope/ 행의 spec 셀이 명세서를 가리키는지)에 따라 두 가지 방식 중 하나로 동작합니다:
- 기능 연결 명세서 (일반적인 FEATURE/ENHANCEMENT, 또는 범위 행이 있는 ARCHITECTURE 기반): 상태는 기능 수명 주기를 반영합니다. /architect는
Proposed로 생성하고 내용을 소유하지만 상태를 절대 진행시키지 않습니다; /develop은 기능이 진행 중일 때 상태를In Progress로 진행시키고, 빌드되어 검증되면(범위done)Accepted로 진행시킵니다. 엔지니어의 확인은 내용만 비준합니다;Accepted는 출시됨을 의미합니다. - 독립적인 결정 명세서 (기반/스택 또는 교차 설계 표준, 범위 행이 연결되지 않음): 결정 상태. 작성 시
Proposed, 엔지니어가 확인 시 비준하면Accepted(결정이 발효됨). /develop은 이것을 진행시키지 않습니다.
이미 출시된 작업을 문서화하는 명세서("이미 빌드됨" 경로, 또는 이미 existing인 연결된 기능)는 Accepted 상태로 태어납니다.
Assumed 상태. /develop은 엔지니어가 부하가 걸린 결정이 심의되기 전에 빌드하기로 선택했을 때 Assumed 상태의 명세서를 생성할 수 있습니다. 이는 심의된 결정이 아니라 빌드에 사용된 가정을 기록합니다. 기능은 여전히 done으로 표시될 수 있습니다; Assumed 명세서는 비준이 필요함을 표시하지만 이를 차단하지는 않습니다. 오직 /architect만이 비준(아래 참조)을 통해 Assumed 상태를 해제합니다. /architect는 Assumed 명세서를 절대 생성하지 않으며, 이미 존재하는 것만 심의합니다.
코드를 작성하지 않습니다. AGENTS.md/CLAUDE.md를 절대 업데이트하지 않습니다(/sync가 소유함).
서브 에이전트 (메인 스레드가 쓰고, 서브 에이전트는 읽기, 가져오기, 또는 교차 확인만 함)
메인 스레드는 대화를 진행하고 명세서를 작성합니다; 쓰기나 수정 작업을 서브 에이전트에게 절대 넘기지 않습니다. 생성하는 모든 서브 에이전트는 읽기 전용이며 세션 모델을 상속받지 않습니다:
- 코드베이스 읽기 (가장 저렴한 모델, Claude Code
haiku): 리포지토리가 클 때(ENHANCEMENT/CROSS-CUTTING) 기존 코드를 읽기 전용으로 스캔합니다. Claude Code:scout유형. 파일 덤프가 아닌 간결한 맵을 반환합니다. - 웹에서 가져오기 (가장 저렴한 모델, Claude Code
haiku): 설계 대화 중(Stage c) 현재 도구 환경 확인과 Agent Skill / MCP 발견을 수행하며, 결정에 최신 사실이 필요할 때 사용합니다. Claude Code:researcher유형. 원시 페이지가 아닌 간결한 요약을 반환합니다. - 초안 명세서 교차 확인 (주요 임무는 결정 완전성: 작업이 생성해야 하는 값의 출처가 명세서에 명명되지 않은 것과 빌더가 그렇지 않으면 발명할 결정을 찾는 것): 완성된 명세서를 읽고 비판을 반환하는 읽기 전용 패스이며, 아무것도 작성하지 않습니다.
/architect는 항상 실행 여부를 묻고(엔지니어를 대신하여 실행하거나 건너뛰지 않음),GA/Beta(이러한 버그가 사는 계층)에서는 강력하게Another model을 추천하고,Alpha에서는 제공하며,Prototype에서는Skip을 추천합니다; 발견된 모든 격차는 자동 해결되지 않고 엔지니어에게 권장 수정 사항과 함께 제시되어 결정하도록 합니다. 명세서 작성 후 참조.
웹 가져오기는 결정에 필요할 때 한 번 수행됩니다(Stage (c) 환경 및 도구 발견 확인). 반환된 링크는 사람이 따라갈 수 있도록 명세서의 참조(References)에 들어갑니다; AI는 다시 가져오지 않습니다(교차 확인, /develop, 또는 /audit에서도).
묻기 vs 행동하기
명세서를 작성하기 전(그리고 읽기/가져오기 도우미를 생성하기 전)에 목표 지향적인 질문을 하고, 예산을 내용에 사용합니다. 모든 질문을 분류합니다:
- INFER(추론): 프롬프트나 코드베이스가 드러내는 모든 것(기능 vs 아키텍처, 스택, UI 범위, 이미 선택된 공급자). 유도하고, 묻지 않습니다.
- ASK(묻기): 엔지니어만 아는 것(요구사항, 선호도, 비즈니스 규칙, 규정 준수 범위).
- RECOMMEND(추천): 전문성이 결정하는 모든 것(어떤 공급자/라이브러리/패턴이 적합한지). 선택 사항, 한 줄 이유, 그리고 차점을 명시합니다; 엔지니어가 무시할 수 있습니다. 절대 중립적인 메뉴나 조용한 결정을 내리지 않습니다.
완전한 데이터 모델, 전체 스택, 또는 기성 수락 기준 세트를 하나의 수락 또는 변경 패널에 번들로 묶지 않으며, 도구, 공급자, 또는 설정 선택을 조용히 결정하지 않습니다.
추천은 사용 중인 스택에 맞춥니다(BaaS에서는 새로운 외부 도구보다 자체 인증/저장소를 선호하고, 재사용이 확산보다 우선). 웹이나 모바일 모두: 플랫폼을 추론하고, 웹이라고 가정하지 않습니다.
이것은 의도이지 절차가 아닙니다. 질문을 실행하는 방법은 internal/design-conversation.md에 있으며, 아래의 실행(Execution)은 단일 설계 질문을 하기 전에 이 파일을 전체 읽도록 합니다.
아티팩트 소유권
이 스킬에 의해서만 생성되거나 업데이트되는 docs/specs/의 명세서 파일과, 그 외의 지원 증거(인벤토리, 감사)는 명세서의 rationale.md(디렉토리 명세서) 또는 인라인(단일 파일 명세서)에 위치하며, 범위 폴더(docs/scope/는 /scope가 소유함)에는 절대 위치하지 않습니다.
두 가지 독립적인 선택, 위치(리포지토리 형태)와 형태(결정 크기):
-
위치 = 리포지토리 형태. 단일 리포지토리 →
docs/specs/. 모노리포지토리 → 워크스페이스 결정의 경우docs/specs/<workspace>/, 리포지토리 전체 결정의 경우docs/specs/_root/(범위를 미러링). 번호 매기기는 위치별로 수행됩니다(해당 디렉토리에서 다음NNNN을 스캔). 해결된 위치를$SPEC_DIR이라고 부릅니다. -
형태 = 결정 크기, 모든 리포지토리 형태에서 동일합니다. 간단한 결정: 하나의 파일
$SPEC_DIR/NNNN-title.md(모든 것이 인라인으로 간결하게 작성됨). 관련 하위 결정이 있는 우산(umbrella), 무겁거나 기초적인 결정, 또는verify.md가 필요한 결정은 디렉토리 형태를 사용합니다:$SPEC_DIR/NNNN-title/및 최상위 파일index.md와 그 옆에rationale.md(우산의 경우 하위 명세서NNNN-<child>.md). 이름을 두 번 사용하지 않습니다(NNNN-title/NNNN-title.md); 디렉토리가 번호를 전달하고 최상위 파일은index.md입니다. 기본값은 단일 파일입니다.디렉토리 명세서는 항상 정확히 두 개의 핵심 파일(옵션으로
verify.md와 하위 명세서 포함)을 가집니다:index.md:/develop이 읽는 빌드 명세서:## Summary,## Requirements,## Decision, 디자인/명세 섹션,## Build plan,## Consequences,## Follow-up, 그리고 한 줄## Rationale포인터를 통해rationale.md를 참조합니다. 우산의 경우## Structure매니페스트로 시작하여 모든 하위 명세서를 나열하고 연결하며(한 줄: 무엇인지와 지원하는 결정), 교차 하위 계약을 포함합니다.rationale.md:/develop이 건너뛰는 결정 기록:## Context,## Options considered,## Rationale,## References섹션, 그리고 모든 방대한 증거(인벤토리, 감사)를 자체 부제목 아래에 포함합니다.research/폴더는 없습니다; 모든 증거는 여기에 있습니다.- 하위 명세서(우산만 해당)는 평평한
NNNN-<child>.md파일이며, 각각 자체적으로 빌드할 수 있을 만큼 완전하고 짧은 인라인 근거(자체rationale.md없음)를 포함합니다; 무거워질 때만 하위 명세서를 자체 디렉토리로 승격시킵니다. 교차 하위 계약은 우산index.md에 있습니다.
-
범위로의 한 가지 좁은 예외: 명세서가 확인된 후, 일치하는 기능을 빌드 준비된 형태로 업데이트합니다(정확한 편집은 명세서 작성 후 3단계 참조). 원자적 작업 목록을 범위에 덤프하지 않습니다. 일치하는 기능이 없는 경우: 등록을 제안합니다(작업 유도 단계 참조).
아티팩트 베이스. 명세서는 기본적으로 docs/ 아래에 있습니다. docs/가 게시된 문서 사이트(docusaurus.config.*, .vitepress/, mkdocs.yml, Astro Starlight, 또는 Nextra 감지)인 경우 대신 .workflow/를 사용합니다(.workflow/specs/). 이미 존재하는 베이스가 무엇이든 항상 따릅니다(여기서 경로는 docs/를 가정).
이식성 (모든 OS, 모든 에이전트)
- 명령어:
git은 모든 OS에서 동일한 유일한 필수 CLI입니다. 다른 셸 스니펫(mkdir -p,date,find,ls,cat,wc)은 POSIX 참조이며 리터럴 스크립트가 아닙니다; 에이전트의 크로스 플랫폼 파일 도구(읽기, 검색/글로브, 쓰기, 디렉토리 생성)와 오늘 날짜에 대한 지식을 사용하세요.mkdir대신 쓰기 도구로docs/specs/를 생성하세요. - 번들 파일:
agent-prompt.md,agent-modes/*.md,spec-template.md는 이 스킬의 폴더에 상대적인 경로에 있습니다. 메인 스레드는 명세서를 작성하기 직전에 직접 읽습니다(명세서 작성 참조):agent-prompt.md(페르소나, 규칙, 보고서 형식), 일치하는 하나의agent-modes/<mode>.md, 그리고spec-template.md(섹션 구조). 인터뷰 내내 컨텍스트에 있지 않도록 사전 점검 중이 아닌 쓰기 시간에만 읽으세요. - 대화형 질문 지원 없음? 에이전트가 제공하는 모든 것(옵션 선택기)을 사용하고 누락된 경우에만 대체하세요: 동일한 옵션으로 일반 텍스트로 질문 라운드를 묻습니다.
실행
단계 0: 주제 확인 (사전 점검 전)
설계 주제가 제공되지 않은 경우(/architect에 인수나 빈 설명이 있음), 다른 작업을 하기 전에 중단하고 물어보세요:
"어떤 설계 결정을 작업하고 싶으신가요? 설계해야 할 기능, 시스템, 또는 선택 사항을 한두 문장으로 설명해주세요."
답변을 기다리고, 사전 점검 전에 이를 설계 주제로 사용하세요.
사전 점검 (메인 모델)
다음 단계를 실행하세요(git 명령어는 리터럴이며, 다른 모든 것은 에이전트의 파일 도구를 사용):
- 최신 상태 확인 (팀):
git fetch를 조용히 실행하고, 기본 브랜치를 선택합니다(git rev-parse --verify main이 성공하면main, 그렇지 않으면master).git rev-list --count HEAD..origin/<base>로 뒤처진 커밋 수를 셉니다. >0이면 결정하기 전에 "먼저 풀(pull)하세요"라고 경고합니다(팀원이 명세서를 추가했거나 이 기능을 변경했을 수 있음). - 명세서 위치 해결 (
SPEC_DIR) =docs/specs/에 미러링된 범위 워크스페이스: 단일 리포지토리 →docs/specs/; 모노리포지토리 워크스페이스 →docs/specs/<workspace>/; 리포지토리 전체 →docs/specs/_root/.<workspace>는 범위가 결정하는 방식으로 결정합니다(주제/경로/범위 행). 디렉토리가 없으면 생성합니다. - 오늘 날짜: 오늘 날짜를 사용합니다(명세서에 삽입).
- 이 위치의 기존 명세서 나열:
NNNN-*.md파일과$SPEC_DIR의index.md파일, 번호 매기기(위치별) 및 관련 결정 감지를 위해. - 소스 파일 수 계산 (예:
.ts,.tsx,.js,.py,.go,.rs,.java),node_modules/,.git/,dist/제외. 읽을 코드의 양과 해당 읽기를scout서브 에이전트에 오프로드할지 여부를 알려줍니다. - 프로젝트 컨텍스트 읽기, 스택 및 커뮤니티 스킬의 진실 공급원: 루트
AGENTS.md(CLAUDE.md로 대체, 없으면 MISSING), 이 기능 영역에 대한 중첩된<area>/AGENTS.md(예: 인증 기능의 경우src/auth/AGENTS.md). - 이 기능의 빌드 접근 방식 읽기: 명세서의
## Build plan이 정렬되고 분할되는 방식을 결정하는 전달 전략. 우선 순위: 선언된 경우 이 기능의 범위 행Approach재정의, 그렇지 않으면 프로젝트 기본값(루트AGENTS.md먼저, 그 다음docs/scope/의 범위 헤더). 자체 접근 방식이 있는 기능은 해당 접근 방식으로 빌드됩니다; 다른 기능은 프로젝트 기본값을 사용합니다. 네 가지는 동일한 순서를 다른 이름으로 바꾼 것이 아니라 재료적으로 다른## Build plan순서를 의미합니다: Tracer Bullet는 먼저 모든 계층을 통과하는 얇은 종단 간 스레드를 구축한 다음 두껍게 만듭니다; Skateboard는 먼저 사용 가능한 가장 얇은 전체를 구축한 다음 성장시킵니다; Facade는 플레이스홀더 데이터가 있는 UI 셸로 시작하여 마이그레이션을 연기합니다(프로토타입 경로); Journey는 다음으로 넘어가기 전에 한 사용자 경로의 작업을 완전히 완료합니다. 프로젝트별 변형이 가능합니다. 둘 다 기록하지 않은 경우 가정을 기록하고 스태프/프린시플 판단으로 기본값을 설정합니다(프로덕션 작업의 경우 종단 간 Tracer Bullet 조각 선호). 기록된 접근 방식이 순서에 눈에 띄게 영향을 미치도록 하세요. - 연결된 범위 기능 찾기(있는 경우):
docs/scope/파일 이름/제목(워크스페이스 하위 디렉토리 포함)을 저렴하게 스캔하여 이 주제와 일치하는 기능을 찾습니다. 포함하는 단일 범위 파일(scope.md또는 분할된 경우 일치하는<epic>.md)만 엽니다. 발견되면 해당 행의 의도와 수락 기준 시드(Stage (a) 시드)를 읽고, 작업 유도 및 연결 단계를 위해 파일/행을 기억합니다; 이것은 또한 기능 연결 vs 독립형 상태를 결정합니다. 일치하는 행이 없으면,
...
(번역을 위해 잘림)