diff --git a/plugins/atelier/README.md b/plugins/atelier/README.md index 38e789aa..3a4f196a 100644 --- a/plugins/atelier/README.md +++ b/plugins/atelier/README.md @@ -14,7 +14,7 @@ spec 설계 → 리뷰 → 구현 → PR 머지까지의 전체 흐름을 하나 |---|---|---| | `git-utils` | 2.4.2 | `skills/git/`(+references), `cli/` (Rust 포팅) | | `github-autopilot` | 0.30.1 | `commands/autopilot/*`, `agents/autopilot/*`, `skills/issue-label/`, `skills/autopilot/`(+resilience·branch-sync·draft-branch→references), `cli/` | -| `spec-kit` | 0.7.1 | `agents/spec/*`, `skills/spec/`(+issue-report·spec-criteria→references), `templates/spec/` | +| `spec-kit` | 0.7.1 | `agents/spec/*`, `skills/spec-write/`·`skills/spec-review/`(+issue-report·spec-criteria→references), `templates/spec/` | | `workflow-guide` | 0.6.0 | `agents/workflow/*`, `skills/{workflow,agent-design-principles}/`, `rules/` | | `coding-style` | 0.3.0 | `skills/coding-style/`, `templates/claude-md/` | | `orchestrator` | 0.2.0 | `skills/orchestrator/` | @@ -73,7 +73,7 @@ atelier setup > **현재 상태**: Epic 1 (consolidation) + Epic 2 (skill extraction) 완료. > 단일 `atelier` 바이너리가 `atelier autopilot <...>` / `atelier git <...>` 를 제공하고(582 tests green), -> Fat Controller 14개가 관심사 skill(`spec`/`autopilot`/`git`) + `references/` 로 해체되었습니다. +> Fat Controller 14개가 관심사 skill(`spec-write`/`spec-review`/`autopilot`/`git`) + `references/` 로 해체되었습니다. > 슬래시 표면은 capability 35개 → 관심사 단위로 수렴, 흡수 6개 plugin 은 snapshot freeze 보존. > > ⚠️ `gh` CLI 의존 git 명령(pr create, reviews, guard pr)은 mock 단위 테스트만 완료 — diff --git a/plugins/atelier/agents/spec/file-pair-observer.md b/plugins/atelier/agents/spec/file-pair-observer.md index 4ee5aecc..50c6c43d 100644 --- a/plugins/atelier/agents/spec/file-pair-observer.md +++ b/plugins/atelier/agents/spec/file-pair-observer.md @@ -1,5 +1,5 @@ --- -description: (내부용) spec skill 이 호출하는 per-file 관찰 에이전트. spec 파일 1개와 관련 code 영역을 직접 읽고 사실만 나열한다. +description: (내부용) spec-review skill 이 호출하는 per-file 관찰 에이전트. spec 파일 1개와 관련 code 영역을 직접 읽고 사실만 나열한다. model: haiku tools: ["Read", "Glob", "Grep"] --- diff --git a/plugins/atelier/agents/spec/gap-aggregator.md b/plugins/atelier/agents/spec/gap-aggregator.md index 33e5a7fe..04fb9c01 100644 --- a/plugins/atelier/agents/spec/gap-aggregator.md +++ b/plugins/atelier/agents/spec/gap-aggregator.md @@ -1,5 +1,5 @@ --- -description: (내부용) spec skill 이 호출하는 종합 분석 에이전트. file-pair-observer (L1) 리포트들을 입력받아 code↔spec 갭과 spec↔spec 갭을 식별한다. +description: (내부용) spec-review skill 이 호출하는 종합 분석 에이전트. file-pair-observer (L1) 리포트들을 입력받아 code↔spec 갭과 spec↔spec 갭을 식별한다. model: sonnet tools: [] --- diff --git a/plugins/atelier/agents/spec/gap-auditor.md b/plugins/atelier/agents/spec/gap-auditor.md index d8c90ccb..5df39592 100644 --- a/plugins/atelier/agents/spec/gap-auditor.md +++ b/plugins/atelier/agents/spec/gap-auditor.md @@ -1,5 +1,5 @@ --- -description: (내부용) spec skill 이 호출하는 통합 감사 에이전트. L2 finding 의 인용 정확성 + 의미 적합성을 단일 게이트로 검증한다. +description: (내부용) spec-review skill 이 호출하는 통합 감사 에이전트. L2 finding 의 인용 정확성 + 의미 적합성을 단일 게이트로 검증한다. model: sonnet tools: [] --- @@ -251,7 +251,7 @@ autopilot 의 Spec Quality Gate (autopilot skill `references/startup.md` §"Spec # Spec Quality Grading Request ## 평가 기준 -{spec skill references/quality-criteria.md 본문 — 4관점 체크리스트 + 점수·등급 기준} +{spec-review skill references/quality-criteria.md 본문 — 4관점 체크리스트 + 점수·등급 기준} ## Spec Files diff --git a/plugins/atelier/agents/spec/spec-annotator.md b/plugins/atelier/agents/spec/spec-annotator.md index 42a2f5a7..4bc04746 100644 --- a/plugins/atelier/agents/spec/spec-annotator.md +++ b/plugins/atelier/agents/spec/spec-annotator.md @@ -1,5 +1,5 @@ --- -description: (내부용) spec skill 의 annotation reference 가 호출하는 1차 분석 에이전트. spec 본문에서 식별자/경로 패턴을 추출하고 프로젝트 디렉터리와 매칭하여 related_paths 후보를 추정한다. +description: (내부용) spec-review skill 의 annotation reference 가 호출하는 1차 분석 에이전트. spec 본문에서 식별자/경로 패턴을 추출하고 프로젝트 디렉터리와 매칭하여 related_paths 후보를 추정한다. model: haiku tools: ["Read", "Glob", "Grep"] --- diff --git a/plugins/atelier/skills/autopilot/references/startup.md b/plugins/atelier/skills/autopilot/references/startup.md index 3ec548b9..60f9a292 100644 --- a/plugins/atelier/skills/autopilot/references/startup.md +++ b/plugins/atelier/skills/autopilot/references/startup.md @@ -45,7 +45,7 @@ autopilot preflight --autopilot-md github-autopilot.local.md --repo-root . `spec_paths`에 스펙 파일이 있으면, `gap-auditor` 에이전트를 **Spec Quality Grading 모드**로 호출하여 스펙 품질을 평가한다 (gap-auditor 는 `tools: []` 이므로 기준과 파일 내용을 프롬프트로 전달): 전달 정보: -- 평가 기준: `spec` skill 의 `references/quality-criteria.md` 본문 (4관점 체크리스트 + 등급 기준) +- 평가 기준: `spec-review` skill 의 `references/quality-criteria.md` 본문 (4관점 체크리스트 + 등급 기준) - spec_files: `spec_paths`에서 `**/*.md`로 수집한 파일들의 경로 + 본문 - spec_quality_threshold: 설정값 (기본: `"C"`) diff --git a/plugins/atelier/skills/interview/SKILL.md b/plugins/atelier/skills/interview/SKILL.md new file mode 100644 index 00000000..702fbce1 --- /dev/null +++ b/plugins/atelier/skills/interview/SKILL.md @@ -0,0 +1,41 @@ +--- +name: interview +description: 작업 착수 전 계획·설계를 사람과 대화로 다지는 인터뷰 메타스킬. "grill me / 이 계획 심문해줘 / 스트레스 테스트해줘", "같이 brainstorm 하자 / 설계 같이 잡자 / 막연한데 방향 잡아줘" 같은 요청에 사용합니다. 슬래시로 직접 호출하거나 모델이 모호한 요청을 감지하면 사용을 제안합니다. 기본은 기존 계획을 심문(grill)하고, 무에서 설계를 시작할 땐 brainstorm 으로 전환합니다. +version: 1.0.0 +--- + +# interview + +코드를 건드리기 전에 계획·설계를 사람과 대화로 다진다. 두 모드가 있다. + +| 의도 | 모드 | 동작 | +|---|---|---| +| 이미 계획/설계/접근안이 있고 빈틈을 찾고 싶다 (기본) | grill | 아래 인라인 지시 | +| 아직 구체안이 없어 무에서 설계를 시작한다 | brainstorm | `references/brainstorm.md` 로드 | + +요청이 "막연한 아이디어 → 설계"면 brainstorm, "이 계획 검증/심문"이면 grill 이다. 헷갈리면 사용자에게 한 번 확인한다. + +## grill (기본) + +이 계획의 모든 측면에 대해 **공유된 이해에 도달할 때까지 집요하게 인터뷰하라**. 설계 트리의 각 가지를 내려가며, 결정 사이의 의존성을 하나씩 해소하라. 각 질문마다 추천 답을 함께 제시하라. + +질문은 한 번에 하나씩만 하라. + +질문이 코드베이스 탐색으로 답해질 수 있다면, 묻지 말고 코드베이스를 탐색하라. + +### 종료와 핸드오프 + +모든 가지가 해소되면(또는 사용자가 충분하다고 하면) 합의된 결정 목록을 요약한다. 코드 변경이 필요하면 Plan Mode 로, 합의된 설계를 스펙 문서로 남겨야 하면 `spec-write` 로 핸드오프한다. 합의 전에는 구현을 시작하지 않는다. + +## 책임 경계 + +| 대상 | 차이 | 핸드오프 | +|---|---|---| +| `spec-write` | **대화 ≠ 문서**. interview 는 설계를 *대화로 합의*(brainstorm: 무에서 / grill: 기존 계획 도전)하고, `spec-write` 는 *합의된 설계를 스펙 문서로 형식화*(DESIGN/concerns/flows)한다 | 합의된 설계를 장기 스펙 문서로 남길 땐 `spec-write`, 단일 작업 구현은 Plan Mode 로 | +| `spec-review` | 작성된 스펙을 *코드와 대조 분석*(L1/L2/audit)·품질 평가하는 단계. interview 의 설계 도전(grill)과 다른 활동 | 스펙 작성 후 코드 정합 확인이 필요하면 `spec-review` 로 | +| Plan Mode | interview 는 *무엇을/왜*(의도·설계 합의), Plan Mode 는 *어떻게*(코드 변경 단계) | 의도가 확정되고 코드 변경이 필요하면 Plan Mode 로 넘긴다 | +| `autopilot` | 자율 루프와 무관, 사람↔에이전트 대화 전용 | 해당 없음 | + +## 출처 + +`grill`·`brainstorm` 은 [obra/superpowers](https://github.com/obra/superpowers) (MIT License, © 2025 Jesse Vincent) 의 `grill-me`·`brainstorming` 스킬이 원본입니다. grill 은 원본 지시문을 보존했고, brainstorm 은 생태계 바인딩 4곳(writing-plans→Plan Mode, browser visual companion→AskUserQuestion·markdown 다이어그램, 체크리스트→TaskCreate, 문서 위치→프로젝트 spec 컨벤션)만 치환한 충실 포팅입니다. MIT 고지는 `references/brainstorm.md` 머리에 명시되어 있습니다. diff --git a/plugins/atelier/skills/interview/references/brainstorm.md b/plugins/atelier/skills/interview/references/brainstorm.md new file mode 100644 index 00000000..675fd48c --- /dev/null +++ b/plugins/atelier/skills/interview/references/brainstorm.md @@ -0,0 +1,153 @@ +# interview — brainstorm 모드 + +> Adapted from [obra/superpowers](https://github.com/obra/superpowers) `brainstorming` skill — MIT License, © 2025 Jesse Vincent. +> 생태계 바인딩 4곳만 atelier 로 치환: writing-plans → Plan Mode / browser visual companion → AskUserQuestion·markdown 다이어그램 / 체크리스트 → TaskCreate / 문서 위치 → 프로젝트 spec 컨벤션. + +아이디어를 자연스러운 협업 대화를 통해 완전한 설계와 스펙으로 발전시킨다. 현재 프로젝트 컨텍스트를 이해하는 데서 출발해, 질문을 한 번에 하나씩 던져 아이디어를 다듬는다. 무엇을 만드는지 이해되면 설계를 제시하고 사용자 승인을 받는다. + + +설계를 제시하고 사용자가 승인하기 전까지는 어떤 구현 스킬도 호출하지 말고, 코드를 쓰지 말고, 프로젝트를 스캐폴딩하지 말고, 어떤 구현 행동도 하지 마라. 체감 난이도와 무관하게 모든 프로젝트에 적용된다. + + +## 안티패턴: "이건 너무 단순해서 설계가 필요 없다" + +모든 프로젝트가 이 프로세스를 거친다. todo 리스트, 함수 하나짜리 유틸, 설정 변경 — 전부 다. **"단순한" 프로젝트야말로 미검증 가정이 가장 큰 낭비를 만드는 곳이다.** 설계는 짧아도 된다(정말 단순하면 몇 문장이면 충분하다). 하지만 반드시 제시하고 승인을 받아야 한다. + +## 체크리스트 + +아래 각 항목을 **TaskCreate 로 task 로 만들고 순서대로 완료**한다: + +1. **프로젝트 컨텍스트 탐색** — 파일, 문서, 최근 커밋 확인 +2. **시각 자료 제안** (시각 질문이 예상될 때) — 다른 내용과 결합하지 않은 별도 메시지로. 아래 "시각 자료" 섹션 참조 +3. **명확화 질문** — 한 번에 하나씩, 목적/제약/성공 기준 이해 +4. **2–3개 접근법 제안** — trade-off 와 추천안 포함 +5. **설계 제시** — 복잡도에 비례한 섹션 단위, 섹션마다 사용자 검증 +6. **설계 문서 작성** (장기 스펙이 필요할 때만) — `spec-write` 컨벤션을 따라 작성·커밋 +7. **스펙 self-review** — placeholder·모순·모호함·스코프 인라인 점검 +8. **사용자의 스펙 리뷰** — 작성된 문서를 사용자가 검토한 뒤 진행 +9. **구현 전환** — Plan Mode 로 진입해 구현 계획 수립 + +## Process Flow + +```dot +digraph brainstorming { + "프로젝트 컨텍스트 탐색" [shape=box]; + "시각 질문 예상?" [shape=diamond]; + "시각 자료 제안\n(별도 메시지, 다른 내용 금지)" [shape=box]; + "명확화 질문 (하나씩)" [shape=box]; + "2-3 접근법 제안" [shape=box]; + "설계 섹션별 제시" [shape=box]; + "사용자 설계 승인?" [shape=diamond]; + "설계 문서 작성" [shape=box]; + "스펙 self-review\n(인라인 수정)" [shape=box]; + "사용자 스펙 리뷰?" [shape=diamond]; + "Plan Mode 진입" [shape=doublecircle]; + + "프로젝트 컨텍스트 탐색" -> "시각 질문 예상?"; + "시각 질문 예상?" -> "시각 자료 제안\n(별도 메시지, 다른 내용 금지)" [label="yes"]; + "시각 질문 예상?" -> "명확화 질문 (하나씩)" [label="no"]; + "시각 자료 제안\n(별도 메시지, 다른 내용 금지)" -> "명확화 질문 (하나씩)"; + "명확화 질문 (하나씩)" -> "2-3 접근법 제안"; + "2-3 접근법 제안" -> "설계 섹션별 제시"; + "설계 섹션별 제시" -> "사용자 설계 승인?"; + "사용자 설계 승인?" -> "설계 섹션별 제시" [label="no, 수정"]; + "사용자 설계 승인?" -> "설계 문서 작성" [label="yes"]; + "설계 문서 작성" -> "스펙 self-review\n(인라인 수정)"; + "스펙 self-review\n(인라인 수정)" -> "사용자 스펙 리뷰?"; + "사용자 스펙 리뷰?" -> "설계 문서 작성" [label="수정 요청"]; + "사용자 스펙 리뷰?" -> "Plan Mode 진입" [label="승인"]; +} +``` + +**종착 상태는 Plan Mode 진입이다.** 다른 어떤 구현 스킬도 호출하지 않는다. brainstorm 이후의 유일한 다음 단계는 Plan Mode 다. + +## 프로세스 + +**아이디어 이해:** + +- 현재 프로젝트 상태(파일, 문서, 최근 커밋)를 먼저 확인한다 +- 상세 질문 전에 **스코프를 판정**한다: 요청이 여러 독립 서브시스템을 담고 있으면(예: "채팅 + 파일 저장 + 빌링 + 분석이 있는 플랫폼") 즉시 플래그한다. **분해가 먼저 필요한 프로젝트의 디테일을 다듬는 데 질문을 낭비하지 마라.** +- 단일 스펙에 담기엔 큰 프로젝트면 사용자와 함께 서브프로젝트로 분해한다: 독립적인 조각은 무엇인가, 서로 어떻게 연결되나, 어떤 순서로 만들어야 하나. 그 다음 첫 서브프로젝트를 정상 설계 플로우로 brainstorm 한다. 각 서브프로젝트는 자기만의 스펙 → 계획 → 구현 사이클을 가진다 +- 적절한 스코프의 프로젝트는 질문을 한 번에 하나씩 던져 아이디어를 다듬는다 +- 가능하면 객관식을 선호한다 (AskUserQuestion 활용) — 주관식도 괜찮다 +- 메시지당 질문 하나 — 주제에 더 깊은 탐색이 필요하면 여러 질문으로 쪼갠다 +- 이해의 초점: 목적, 제약, 성공 기준 + +**접근법 탐색:** + +- 서로 다른 접근법 2–3개를 trade-off 와 함께 제안한다 +- 대화체로 제시하되 추천안과 그 이유를 명시한다 +- 추천안을 먼저 제시하고 왜인지 설명한다 + +**설계 제시:** + +- 무엇을 만드는지 이해됐다고 믿으면 설계를 제시한다 +- 각 섹션을 복잡도에 비례해 조절한다: 단순하면 몇 문장, 미묘하면 200–300단어까지 +- 각 섹션 후 여기까지 맞는지 확인한다 +- 다룰 것: 아키텍처, 컴포넌트, 데이터 흐름, 에러 처리, 테스트 +- 뭔가 말이 안 되면 되돌아가 명확히 할 준비를 한다 + +**격리와 명료함을 위한 설계:** + +- 시스템을 작은 단위로 쪼갠다. 각 단위는 하나의 명확한 목적을 갖고, 잘 정의된 인터페이스로 통신하며, 독립적으로 이해·테스트 가능해야 한다 +- 각 단위에 대해 답할 수 있어야 한다: 무엇을 하는가, 어떻게 쓰는가, 무엇에 의존하는가 +- 내부를 읽지 않고 단위가 뭘 하는지 이해할 수 있는가? 내부를 바꿔도 소비자가 깨지지 않는가? 아니라면 경계를 다시 잡아야 한다 +- 작고 경계가 분명한 단위는 에이전트 자신에게도 유리하다 — 한 번에 컨텍스트에 담을 수 있는 코드를 더 잘 추론하고, 파일이 집중되어 있을수록 편집이 더 신뢰할 만하다. 파일이 커지고 있다면 너무 많은 일을 하고 있다는 신호인 경우가 많다 +- 이 지향은 atelier 의 SOLID 원칙(`coding-style` skill)과 동일하다 — 설계 단계에서 SRP/ISP/DIP 를 미리 적용하는 것 + +**기존 코드베이스에서 작업:** + +- 변경을 제안하기 전에 현재 구조를 탐색한다. 기존 패턴을 따른다 +- 기존 코드의 문제가 이번 작업에 영향을 주는 경우(너무 커진 파일, 불분명한 경계, 얽힌 책임)에는 targeted improvement 를 설계에 포함한다 — 좋은 개발자가 자기가 작업하는 코드를 개선하는 방식으로 +- 무관한 리팩터링은 제안하지 않는다. 현재 목표에 복무하는 것에 집중한다 + +## 설계 이후 + +**문서화:** (장기 스펙 문서가 필요할 때만) + +- 문서 작성은 **`spec-write` 스킬의 컨벤션**(`spec-write/references/authoring.md`)을 따른다 — 깊이 기준·출력 구조(DESIGN/concerns/flows)·`related_paths`·저장 경로 규약이 거기에 있다. brainstorm 은 합의된 설계를 그 컨벤션으로 형식화한다 (문서 형식을 자체 정의하지 않는다) +- 단순 작업이라 장기 스펙이 불필요하면 이 단계를 건너뛰고 바로 구현 전환으로 간다 — 설계는 Plan Mode 의 plan 파일이 담는다 + +**스펙 self-review:** +스펙 문서를 쓴 뒤 새로운 눈으로 본다: + +1. **Placeholder 스캔**: "TBD", "TODO", 미완성 섹션, 모호한 요구사항이 있는가? 고친다 +2. **내부 일관성**: 섹션끼리 모순되는가? 아키텍처가 기능 설명과 일치하는가? +3. **스코프 점검**: 단일 구현 계획에 담길 만큼 집중되어 있는가, 분해가 필요한가? +4. **모호함 점검**: 두 가지로 해석될 수 있는 요구사항이 있는가? 있으면 하나를 골라 명시한다 + +발견한 문제는 인라인으로 고친다. 재리뷰는 불필요 — 고치고 넘어간다. + +**사용자 리뷰 게이트:** +self-review 가 끝나면 진행 전에 사용자에게 작성된 스펙 리뷰를 요청한다: + +> "스펙을 `<경로>` 에 작성하고 커밋했습니다. 구현 계획을 잡기 전에 검토하시고 수정할 부분이 있으면 알려주세요." + +사용자의 응답을 기다린다. 수정 요청이 오면 반영하고 self-review 를 다시 돈다. 사용자가 승인한 뒤에만 진행한다. + +**구현 전환:** + +- **Plan Mode 로 진입**해 상세 구현 계획을 수립한다 +- 다른 스킬을 호출하지 않는다. Plan Mode 가 다음 단계다. 합의된 설계를 장기 스펙 문서로 남겨야 하면 `spec-write` 로 형식화한다 + +## 핵심 원칙 + +- **질문은 한 번에 하나** — 여러 질문으로 압도하지 않는다 +- **객관식 선호** — 가능하면 주관식보다 답하기 쉽다 (AskUserQuestion) +- **가차없는 YAGNI** — 모든 설계에서 불필요한 기능을 제거한다 +- **대안 탐색** — 정하기 전에 항상 2–3개 접근법을 제안한다 +- **점진적 검증** — 설계를 제시하고 승인받은 뒤 다음으로 간다 +- **유연하게** — 말이 안 되면 되돌아가 명확히 한다 + +## 시각 자료 + +brainstorm 중 목업·다이어그램·시각적 대안을 보여주는 도구다. **도구이지 모드가 아니다** — 사용자가 동의해도 모든 질문이 시각 자료를 거치는 게 아니라, 시각적 처리가 도움이 되는 질문에만 쓸 수 있게 되는 것이다. + +**제안하기:** 앞으로의 질문에 시각 콘텐츠(목업, 레이아웃, 다이어그램)가 필요할 것 같으면 동의를 한 번 구한다. **이 제안은 반드시 별도 메시지여야 한다** — 명확화 질문, 컨텍스트 요약, 다른 어떤 내용과도 결합하지 않는다. 거절하면 텍스트로만 진행한다. + +**질문별 판단:** 동의를 받았어도 **질문마다** 시각이냐 텍스트냐를 따로 결정한다. 기준: **읽는 것보다 보는 것이 이해에 더 나은가?** + +- **시각으로**: 내용 자체가 시각적인 것 — 목업, 레이아웃 비교, 모듈 구조·의존성·흐름 다이어그램 → markdown 표 / ASCII / mermaid. 대안 2–3개를 나란히 비교시킬 땐 AskUserQuestion 의 preview +- **텍스트로**: 내용이 텍스트인 것 — 요구사항 질문, 개념 선택, trade-off 목록, 스코프 결정 + +UI 주제에 대한 질문이라고 자동으로 시각 질문인 건 아니다. "이 맥락에서 personality 가 무슨 뜻인가요?"는 개념 질문이라 텍스트로, "어느 wizard 레이아웃이 나은가요?"는 시각 질문이라 다이어그램으로 간다. diff --git a/plugins/atelier/skills/spec/SKILL.md b/plugins/atelier/skills/spec-review/SKILL.md similarity index 75% rename from plugins/atelier/skills/spec/SKILL.md rename to plugins/atelier/skills/spec-review/SKILL.md index 68bbb82f..ef463991 100644 --- a/plugins/atelier/skills/spec/SKILL.md +++ b/plugins/atelier/skills/spec-review/SKILL.md @@ -1,22 +1,23 @@ --- -name: spec -description: 스펙 설계·리뷰·갭 분석의 단일 진입점. "스펙 리뷰해줘", "spec↔code 갭 봐줘", "설계하자/큰그림 잡자", "컴포넌트 상세 설계", "외부 spec 에 related_paths 주석" 같은 요청에 사용합니다. 슬래시로 직접 호출하거나 맥락에서 모델이 자동 호출합니다. L1(관찰)→L2(종합)→audit(감사) 레이어로 file:line 인용 기반 분석. +name: spec-review +description: 작성된 스펙 문서를 코드와 대조 분석하고 품질을 평가하는 스킬. "스펙 리뷰해줘", "spec↔code 갭 봐줘", "이 spec 들 검증", "스펙 품질 평가", "외부 spec 에 related_paths 주석" 같은 요청에 사용합니다. 슬래시로 직접 호출하거나 맥락에서 모델이 자동 호출합니다. 스펙 문서 작성은 `spec-write`, 설계 대화는 `interview` 스킬이 담당합니다. L1(관찰)→L2(종합)→audit(감사) 레이어로 file:line 인용 기반 분석. --- -# spec +# spec-review -스펙 문서를 다루는 모든 워크플로우(리뷰·갭 분석·설계·주석)의 **관심사 단위 진입점이자 공통 도메인 지식**입니다. 사용자가 spec 슬래시로 진입하거나 모델이 맥락에서 자동 호출하며, 의도에 따라 아래 `references/` 로 디스패치합니다. +작성된 스펙 문서를 **코드와 대조 분석·평가·주석**하는 스킬입니다. 사용자가 spec-review 슬래시로 진입하거나 모델이 맥락에서 자동 호출하며, 의도에 따라 아래 `references/` 로 디스패치합니다. + +> 스펙 문서를 **작성**하려면 `spec-write`, 설계를 **대화로 합의**하려면 `interview` 를 씁니다. spec-review 는 이미 존재하는 스펙을 분석하는 단계입니다. ## 진입 라우팅 (의도 → reference) -spec 슬래시 또는 모델 자동 호출로 진입하면, 사용자의 자연어 의도를 분류해 해당 흐름을 수행합니다. +spec-review 슬래시 또는 모델 자동 호출로 진입하면, 사용자의 자연어 의도를 분류해 해당 흐름을 수행합니다. | 사용자 의도 (예) | 흐름 | 로드할 references | |---|---|---| | "스펙 리뷰", "이 spec 들 검증", 다중 spec 대조 | spec-review (다중 spec, L1 병렬) | file-observation → gap-audit-loop → report-format(spec-review) | | "갭 봐줘", "spec 과 code 차이", 단일 spec | gap-detect (단일 spec, code↔spec 우선) | file-observation → gap-audit-loop → report-format(gap-detect) | -| "설계하자", "큰그림", "아키텍처 잡자" | design (Big Picture 핑퐁) | design-protocol | -| "컴포넌트 상세", "이 흐름 설계", concerns/flows | design-detail | design-protocol | +| "스펙 품질 평가", "이 스펙 등급" | quality (4관점 등급 산정) | quality-criteria | | "related_paths 채워줘", 외부 spec 주석 | annotate | annotation | 입력 인자(spec 파일 경로 등)가 함께 오면 그대로 사용하고, 없으면 AskUserQuestion 으로 확인합니다. 결정적 동작은 없으며(전부 판단/분석), 모든 분석은 sub-agent 에 위임합니다. @@ -50,7 +51,6 @@ spec 슬래시 또는 모델 자동 호출로 진입하면, 사용자의 자연 | `references/file-observation.md` | L1 spawn + 인용 검증 + 피드백 루프 수행 시 | file-pair-observer 입력 프롬프트, 인용 검증 절차, 피드백 루프 알고리즘/종료 조건, drop 로그 | | `references/gap-audit-loop.md` | L2 종합 + audit 감사 수행 시 | gap-aggregator 입력, gap-auditor 단일 게이트, audit 루프 정책, fix request 형식, 실패 모드 | | `references/report-format.md` | 최종 리포트 출력 시 | spec-review / gap-detect 출력 구조, 검증 통계 footer, Output Examples | -| `references/design-protocol.md` | 대화형 설계(`design`/`design-detail`) 시 | 핑퐁 루프, 6개 관점, 수렴 판단, 출력 구조 | | `references/annotation.md` | 외부 spec frontmatter 주석(`annotate-spec`) 시 | spec-annotator 호출, 신뢰도별 confirm, frontmatter 갱신 모드 | | `references/quality-criteria.md` | 스펙 품질 평가·등급 산정 시 (autopilot Spec Quality Gate 포함) | Big Picture/Detail/Verification/Consistency 4관점 체크리스트, 점수·등급 기준 | | `references/issue-report.md` | 분석 결과를 심각도 기반 이슈 리포트로 보고할 때 | severity 기준, 이슈 항목 구조, 마크다운 출력 형식 | diff --git a/plugins/atelier/skills/spec/references/annotation.md b/plugins/atelier/skills/spec-review/references/annotation.md similarity index 100% rename from plugins/atelier/skills/spec/references/annotation.md rename to plugins/atelier/skills/spec-review/references/annotation.md diff --git a/plugins/atelier/skills/spec/references/file-observation.md b/plugins/atelier/skills/spec-review/references/file-observation.md similarity index 100% rename from plugins/atelier/skills/spec/references/file-observation.md rename to plugins/atelier/skills/spec-review/references/file-observation.md diff --git a/plugins/atelier/skills/spec/references/gap-audit-loop.md b/plugins/atelier/skills/spec-review/references/gap-audit-loop.md similarity index 100% rename from plugins/atelier/skills/spec/references/gap-audit-loop.md rename to plugins/atelier/skills/spec-review/references/gap-audit-loop.md diff --git a/plugins/atelier/skills/spec/references/issue-report.md b/plugins/atelier/skills/spec-review/references/issue-report.md similarity index 100% rename from plugins/atelier/skills/spec/references/issue-report.md rename to plugins/atelier/skills/spec-review/references/issue-report.md diff --git a/plugins/atelier/skills/spec/references/quality-criteria.md b/plugins/atelier/skills/spec-review/references/quality-criteria.md similarity index 100% rename from plugins/atelier/skills/spec/references/quality-criteria.md rename to plugins/atelier/skills/spec-review/references/quality-criteria.md diff --git a/plugins/atelier/skills/spec/references/report-format.md b/plugins/atelier/skills/spec-review/references/report-format.md similarity index 100% rename from plugins/atelier/skills/spec/references/report-format.md rename to plugins/atelier/skills/spec-review/references/report-format.md diff --git a/plugins/atelier/skills/spec-write/SKILL.md b/plugins/atelier/skills/spec-write/SKILL.md new file mode 100644 index 00000000..d7ec9c3d --- /dev/null +++ b/plugins/atelier/skills/spec-write/SKILL.md @@ -0,0 +1,35 @@ +--- +name: spec-write +description: 합의된 설계를 스펙 문서 계층으로 작성하는 스킬. "이 설계를 스펙 문서로 적어줘", "DESIGN.md 작성", "큰그림 스펙 적어줘", "컴포넌트 스펙 작성", "이 흐름 문서화" 같은 요청에 사용합니다. 설계를 대화로 합의하는 단계는 `interview` 스킬, 작성된 스펙을 코드와 대조 분석하는 단계는 `spec-review` 스킬이 담당합니다. 여기서는 합의된 설계를 정해진 구조(DESIGN→concerns→flows)로 형식화합니다. +version: 1.0.0 +--- + +# spec-write + +합의된 설계를 **스펙 문서 계층으로 적는** 스킬입니다. 설계를 *생각하고 도전하는 대화*는 `interview`(brainstorm/grill)에서 끝내고, 여기서는 그 결과를 정해진 구조와 깊이로 형식화합니다. 메인 에이전트가 직접 문서를 작성합니다(sub-agent 분석 아님). + +## 진입 라우팅 (의도 → 흐름) + +| 사용자 의도 (예) | 흐름 | 산출물 | +|---|---|---| +| "이 설계 스펙 문서로", "DESIGN.md 작성", "큰그림 스펙 적어줘" | write (Big Picture) | `spec/DESIGN.md` | +| "컴포넌트 스펙 작성", "이 흐름 문서화", concerns/flows | write-detail (상세) | `spec/concerns/*.md`, `spec/flows/*.md` | + +> **설계를 아직 합의하지 않았다면** (막연한 아이디어, 큰그림 잡기, 기존 계획 도전) `interview` 스킬을 먼저 씁니다. spec-write 는 **합의된 설계를 문서로 형식화**하는 단계입니다. +> +> **작성한 스펙이 실제 코드와 맞는지 확인**하려면 `spec-review` 스킬(spec↔code 갭 분석)을 씁니다. + +입력 인자(설계 내용, 저장 경로 등)가 함께 오면 그대로 사용하고, 없으면 AskUserQuestion 으로 확인합니다. + +## 작성 절차·형식 + +스펙 문서의 진입 전 맥락, 깊이 기준, 작성 원칙, 출력 구조(DESIGN/concerns/flows 템플릿), `related_paths` 규약은 `references/authoring.md` 에서 progressive disclosure 로 로드합니다. + +| reference | 언제 로드 | 내용 | +|---|---|---| +| `references/authoring.md` | `write`/`write-detail` 수행 시 | 진입 전 맥락, 깊이 기준, 작성 원칙, 출력 구조(DESIGN/concerns/flows), related_paths | + +## 공통 원칙 + +- **합의 후 형식화** — 설계 결정은 interview 에서 합의한다. spec-write 는 합의된 내용을 구조화할 뿐, 새 설계 결정을 임의로 내리지 않는다. +- 작성 원칙(승인 전 저장 금지·`related_paths`·깊이 분리)과 출력 구조는 `references/authoring.md` 가 canonical 이다. diff --git a/plugins/atelier/skills/spec-write/references/authoring.md b/plugins/atelier/skills/spec-write/references/authoring.md new file mode 100644 index 00000000..aea22f1e --- /dev/null +++ b/plugins/atelier/skills/spec-write/references/authoring.md @@ -0,0 +1,133 @@ +# 스펙 문서 작성 컨벤션 + +합의된 설계를 스펙 문서로 적는 절차와 형식. **설계를 생각하고 도전하며 합의에 이르는 대화는 `interview`(brainstorm: 무에서 설계 / grill: 기존 계획 심문)에서 끝낸다.** 여기서는 그 결과를 정해진 구조로 형식화한다 — `write`(Big Picture DESIGN.md)와 `write-detail`(컴포넌트/플로우 상세)이 이 컨벤션을 공유한다. + +## 진입 전 맥락 파악 (write-detail) + +`write-detail` 은 Big Picture 를 전제하므로 `spec/DESIGN.md`(또는 `**/DESIGN*.md`)를 Glob 으로 찾아 Read 한다. 없으면 AskUserQuestion 으로 `write` 를 먼저 만들거나 기존 경로를 확인하고, 기존 `spec/concerns/`·`spec/flows/` 및 관련 코드도 파악한다. + +## 깊이 기준 + +- **write (Big Picture) → DESIGN.md** — 포함: 목표, 설계 철학(의견), 컴포넌트 목록과 책임, 컴포넌트 간 데이터 흐름, 확장 가능 지점. 제외: trait/인터페이스 시그니처, 의사코드, 상태 전이 다이어그램, DB 스키마, API 상세 (→ write-detail 영역). +- **write-detail** — "구현자가 코드 구조를 잡을 수 있지만, 구현 방법은 선택할 수 있는 수준". DESIGN.md 의 철학·원칙을 존중하며 세부 구체화. ❌ DESIGN.md 큰그림 중복 기술, ❌ 구현 코드 작성(의사코드까지만). + +## 작성 원칙 + +- 저장 경로는 AskUserQuestion 으로 확인한다 (기본값은 아래 각 출력 구조 참조). +- **최종 승인 전까지 파일을 저장하지 않는다.** 내용을 제시하고 동의받은 뒤 Write. +- 기존 코드를 참조하되, 스펙이 기존 구조에 종속되지 않도록 한다. +- frontmatter `related_paths` 를 채운다 — 후속 `spec-review`·`gap-detect` 가 이 필드를 코드 영역 매핑 Hint 로 사용하므로 분석 정확도가 크게 오른다. 본문에서 언급된 모듈/디렉터리/식별자를 프로젝트 구조와 매칭하되, **확실한 경로만** 적는다(추정에 자신 없으면 비움). 신규 설계라 코드가 아직 없으면 비워둔다. + +## 출력 구조 + +### write → DESIGN.md + +저장 경로 기본: `spec/DESIGN.md` (AskUserQuestion 확인 후 Write). + +```markdown +--- +related_paths: + - {추정 코드 경로} +--- + +# DESIGN + +> **Date**: {오늘 날짜} +> **Status**: Draft + +## 목표 +{1-3문장: 이 시스템이 해결하는 문제, 설계 목표로 서술} + +## 설계 철학 +{번호 매긴 원칙들. 각 1-2문장. 서술이 아닌 의견/결정.} + +### 1. {원칙 이름} +{설명} + +## 전체 구조 +{ASCII 다이어그램: 컴포넌트 배치와 데이터 흐름} + +## 관심사 분리 +| 레이어 | 책임 | 비고 | +|--------|------|------| + +## OCP 확장점 +{새 타입/시스템 추가 시 코어 변경 없이 확장 가능한 지점} + +## 미결정 사항 +{확정되지 않은 항목. write-detail 에서 구체화할 후보} + +## 상세 문서 +| 문서 | 설명 | +|------|------| +| [concerns/...](...) | ... | +| [flows/...](...) | ... | +``` + +### write-detail → concerns/{name}.md (컴포넌트) + +저장 경로 기본: `spec/concerns/{component-name}.md` (AskUserQuestion 확인 후 Write). 저장 후 DESIGN.md 에 상세 문서 링크 추가를 제안한다. + +```markdown +--- +related_paths: + - {추정 코드 경로} +--- + +# {컴포넌트 이름} + +> {한 문장: 이 컴포넌트가 하는 것과 하지 않는 것} + +## 역할 +{핵심 책임} + +## 인터페이스/Trait +{합의된 시그니처} + +## 핵심 로직 +{의사코드 — 합의된 수준} + +## 에러 처리 +{실패 시나리오와 대응 정책} + +## 제약 조건 +{불변 조건, 한계, 성능 제약} + +## 관련 문서 +| 문서 | 관계 | +|------|------| +| [DESIGN.md](../DESIGN.md) | 전체 구조에서의 위치 | +``` + +### write-detail → flows/{nn-scenario}.md (플로우) + +저장 경로 기본: `spec/flows/{nn-scenario-name}.md`. + +```markdown +--- +related_paths: + - {추정 코드 경로} +--- + +# Flow {번호}: {시나리오 이름} + +> {한 문장 요약} + +## 흐름 다이어그램 +{ASCII 다이어그램} + +## 단계별 설명 +{각 단계: 트리거 → 컴포넌트 → 데이터 → 결과} + +## 실패 경로 +{각 단계에서 실패 시} + +## 엣지 케이스 +{비정상적이지만 유효한 시나리오} + +## 관련 문서 +| 문서 | 관계 | +|------|------| +| [DESIGN.md](../DESIGN.md) | 전체 구조 | +| [관련 concern](./concerns/xxx.md) | 관련 컴포넌트 상세 | +``` diff --git a/plugins/atelier/skills/spec/references/design-protocol.md b/plugins/atelier/skills/spec/references/design-protocol.md deleted file mode 100644 index a8815d52..00000000 --- a/plugins/atelier/skills/spec/references/design-protocol.md +++ /dev/null @@ -1,236 +0,0 @@ -# 대화형 설계 핑퐁 프로토콜 - -`design` (Big Picture) 와 `design-detail` (컴포넌트/플로우 상세) 이 공유하는 대화형 설계 절차. AI가 먼저 채워진 초안을 제안하고, 사용자가 피드백/의사코드로 방향을 잡고, AI가 반영 후 다른 관점에서 도전하는 **핑퐁 세션**. - -## 핑퐁 루프 프로토콜 - -세션 시작 이후 수렴할 때까지 반복: - -``` -1. AI가 설계의 한 측면을 구체적으로 제안한다 (빈 칸이 아닌 채워진 초안) -2. 사용자가 응답한다: - - 동의 → 이 측면은 합의됨, 다음 측면으로 - - 방향 수정 → AI가 수정 반영 - - 의사코드/구조 제시 → AI가 설계 언어로 흡수 (단순 에코 아님) - - 새 관심사 제기 → AI가 해당 관심사를 탐색 -3. AI가 반영한 뒤, 다른 관점에서 하나의 구체적 도전을 제시한다 -4. AskUserQuestion으로 피드백을 요청한다 -``` - -## 6개 관점 - -대화 중 아래 관점들을 내부적으로 추적한다. **사용자에게 관점 이름이나 전환을 노출하지 않는다.** - -| 코드 | 관점 | 핵심 질문 | -|------|------|----------| -| S | 단순성 | 더 줄일 수 있나? 불필요한 추상화는 없나? | -| O | OCP | 새 타입/시스템 추가 시 기존 코드 변경 없이 가능한가? | -| F | 실패/복구 | 여기서 터지면? 재시도? 사람 개입? | -| B | 경계 | 이 컴포넌트가 알아야 할 것 vs 몰라야 할 것 | -| C | 동시성 | 동시 접근 시 어떻게 되나? | -| M | 운영 | 상태 확인, 디버깅이 가능한가? | - -### 관점 전환 규칙 - -- 사용자의 응답이 자연스럽게 특정 관점을 열면 → 그 흐름을 따라간다 -- 3회 이상 교환 동안 미탐색 관점이 있으면 → 구체적 시나리오로 자연스럽게 도입한다 -- 관점 전환을 선언하지 않고, 항상 구체적 시나리오로 질문한다 - -``` -좋은 예: - "두 사용자가 동시에 아이템을 제출하면 어떻게 되나요? 지금 구조는 순차 처리라 - 두 번째 사용자가 대기하게 됩니다. 이게 괜찮은 건가요, 아니면 큐가 필요할까요?" - - "여기에 trait를 세 종류가 구현하는데, 실제로 1-2개만 있을 수 있다면 - 추상화가 오히려 간접 참조만 추가합니다. 더 구현체가 생길 예정인가요?" - -나쁜 예: - "동시성에 대해 생각해보셨나요?" - "이 추상화가 정말 필요한가요?" -``` - -## 사용자 의사코드 처리 - -사용자가 의사코드나 구조적 피드백을 제시하면: - -1. **설계 언어로 반영한다** — 의사코드를 에코하지 않고 설계 문서의 일부로 흡수한다 -2. **의사코드의 한 측면을 도전한다** — 관련 관점에서 구체적 시나리오를 제시한다 - -``` -사용자: "loop { collect(); process(); done(); }" - -AI 반영: "수집 → 처리 → 완료 반영의 단순 루프로 정리했습니다. - Daemon은 이 루프만 돌리고, 무엇을 수집하고 어떻게 처리할지는 - 외부에서 정의하는 구조네요." - -AI 도전: "한 가지 — process()가 LLM 호출이라 30초~수분이 걸릴 텐데, - 이 루프가 한 번에 하나만 처리하면 처리량이 제한됩니다. - 동시에 여러 아이템을 process()할 수 있어야 하나요?" -``` - -## 수렴 판단 (모드별 임계값) - -수렴 조건은 design(Big Picture)과 design-detail(컴포넌트/플로우)이 다르다. - -**design (Big Picture)** — 다음 충족 시 수렴: -- 6개 관점 중 **4개 이상**이 의미 있게 다뤄졌다 -- 핵심 아키텍처 (컴포넌트 목록 + 각각의 책임)에 사용자가 동의했다 -- 사용자가 **2-3회 연속** 새 관심사 없이 확인/동의만 했다 - -**design-detail (컴포넌트/플로우)** — 단위가 좁으므로 기준이 낮다: -- 6개 관점 중 **3개 이상** 다룸 (design 의 4개보다 낮음) -- 컴포넌트: 인터페이스/역할 합의 + 핵심 로직 방향 결정 + 주요 에러 케이스 / 플로우: 주요 흐름(happy path) 합의 + 핵심 분기점 -- 사용자가 **2-3회 연속** 확인만 했다 - -수렴 시 AskUserQuestion 으로 정리(파일 저장) 의사를 묻는다. - -## 안티패턴 - -- ❌ 한 번에 여러 질문 나열 / 번호 매긴 설문지 -- ❌ 단계 선언 ("Phase 2로 넘어가겠습니다") / 관점 전환 선언 -- ❌ 빈 칸 채우기 ("목표가 뭐예요?", "액터가 누구예요?") -- ❌ 사용자 의사코드를 그대로 에코 -- ✅ 한 번에 **하나의 구체적 제안** + **하나의 구체적 도전** + AskUserQuestion - -## frontmatter `related_paths` 권고 (설계 출력 공통) - -설계 산출물(spec) 상단에 YAML frontmatter 로 `related_paths` 를 채우는 것을 권장한다. 후속 `spec-review`·`gap-detect` 가 이 필드를 코드 영역 매핑 Hint 로 사용하므로, 채워두면 분석 정확도가 크게 오른다. - -- 본문에서 명시적으로 언급된 모듈/디렉터리/식별자를 프로젝트 디렉터리 구조와 매칭한다. -- **확실한 경로만** 적는다. 추정에 자신 없으면 비워라 — 잘못된 Hint 는 자율 보강 fallback 보다 해롭다. -- 신규 설계라 코드가 아직 없으면 비워둔다. - -## 공통 주의사항 - -- 사용자가 이전 논의를 번복해도 자연스럽게 수용한다 -- 기존 코드를 참조하되 설계가 기존 구조에 종속되지 않도록 한다 -- 최종 승인 전까지 파일 저장 안 함 - ---- - -## design-detail 세션 준비 - -design-detail(컴포넌트/플로우 상세)는 design 이후 단계이므로 진입 전 맥락 파악이 필요하다. - -1. **맥락 파악**: `spec/DESIGN.md` 또는 `**/DESIGN*.md` 를 Glob 으로 찾아 Read. 없으면 AskUserQuestion: "Big Picture 스펙(DESIGN.md)을 찾을 수 없습니다. design 으로 먼저 만들거나, 기존 스펙 경로를 알려주세요." 기존 `spec/concerns/`·`spec/flows/` 및 관련 코드도 파악. -2. **세션 타입 결정**: `flow` 키워드 → 플로우 세션, 그 외 → 컴포넌트 세션. 인자 없으면 DESIGN.md 의 컴포넌트/시나리오 목록 제시 후 선택. -3. **초안 제안**: 해당 컴포넌트/시나리오 정보 + 기존 코드 구조 반영해 구체적 초안 먼저 제안 → 핑퐁 루프. - -## 깊이 기준 - -- **design (Big Picture)** — 포함: 목표, 설계 철학(의견), 컴포넌트 목록과 책임, 컴포넌트 간 데이터 흐름, 확장 가능 지점. 제외: trait/인터페이스 시그니처, 의사코드, 상태 전이 다이어그램, DB 스키마, API 상세 (→ design-detail 영역). -- **design-detail** — "구현자가 코드 구조를 잡을 수 있지만, 구현 방법은 선택할 수 있는 수준". DESIGN.md 의 철학·원칙을 존중하며 세부 구체화. ❌ DESIGN.md 큰그림 중복 기술, ❌ 구현 코드 작성(의사코드까지만). - -## 출력 구조 - -### design → DESIGN.md - -저장 경로는 AskUserQuestion 으로 확인 (기본: `spec/DESIGN.md`) 후 Write. - -```markdown ---- -related_paths: - - {추정 코드 경로} ---- - -# DESIGN - -> **Date**: {오늘 날짜} -> **Status**: Draft - -## 목표 -{1-3문장: 이 시스템이 해결하는 문제, 설계 목표로 서술} - -## 설계 철학 -{번호 매긴 원칙들. 각 1-2문장. 서술이 아닌 의견/결정.} - -### 1. {원칙 이름} -{설명} - -## 전체 구조 -{ASCII 다이어그램: 컴포넌트 배치와 데이터 흐름} - -## 관심사 분리 -| 레이어 | 책임 | 비고 | -|--------|------|------| - -## OCP 확장점 -{새 타입/시스템 추가 시 코어 변경 없이 확장 가능한 지점} - -## 미결정 사항 -{확정되지 않은 항목. design-detail 에서 구체화할 후보} - -## 상세 문서 -| 문서 | 설명 | -|------|------| -| [concerns/...](...) | ... | -| [flows/...](...) | ... | -``` - -### design-detail → concerns/{name}.md (컴포넌트) - -저장 경로 기본: `spec/concerns/{component-name}.md` (AskUserQuestion 확인 후 Write). 저장 후 DESIGN.md 에 상세 문서 링크 추가 제안. - -```markdown ---- -related_paths: - - {추정 코드 경로} ---- - -# {컴포넌트 이름} - -> {한 문장: 이 컴포넌트가 하는 것과 하지 않는 것} - -## 역할 -{핵심 책임} - -## 인터페이스/Trait -{합의된 시그니처} - -## 핵심 로직 -{의사코드 — 합의된 수준} - -## 에러 처리 -{실패 시나리오와 대응 정책} - -## 제약 조건 -{불변 조건, 한계, 성능 제약} - -## 관련 문서 -| 문서 | 관계 | -|------|------| -| [DESIGN.md](../DESIGN.md) | 전체 구조에서의 위치 | -``` - -### design-detail → flows/{nn-scenario}.md (플로우) - -저장 경로 기본: `spec/flows/{nn-scenario-name}.md`. - -```markdown ---- -related_paths: - - {추정 코드 경로} ---- - -# Flow {번호}: {시나리오 이름} - -> {한 문장 요약} - -## 흐름 다이어그램 -{ASCII 다이어그램} - -## 단계별 설명 -{각 단계: 트리거 → 컴포넌트 → 데이터 → 결과} - -## 실패 경로 -{각 단계에서 실패 시} - -## 엣지 케이스 -{비정상적이지만 유효한 시나리오} - -## 관련 문서 -| 문서 | 관계 | -|------|------| -| [DESIGN.md](../DESIGN.md) | 전체 구조 | -| [관련 concern](./concerns/xxx.md) | 관련 컴포넌트 상세 | -``` diff --git a/tools/validate/extraction-invariants.json b/tools/validate/extraction-invariants.json index ea7e77a8..e8dc0a45 100644 --- a/tools/validate/extraction-invariants.json +++ b/tools/validate/extraction-invariants.json @@ -5,14 +5,13 @@ "plugins/atelier/commands" ], "invariants": [ - {"domain": "spec/design", "token": "## OCP 확장점", "reason": "design DESIGN.md 출력 구조 섹션"}, - {"domain": "spec/design", "token": "## 미결정 사항", "reason": "design DESIGN.md 출력 구조 섹션"}, - {"domain": "spec/design", "token": "## 관심사 분리", "reason": "design DESIGN.md 출력 구조 섹션"}, - {"domain": "spec/design-detail", "token": "## 핵심 로직", "reason": "design-detail concerns 출력 구조"}, - {"domain": "spec/design-detail", "token": "## 흐름 다이어그램", "reason": "design-detail flows 출력 구조"}, - {"domain": "spec/design-detail", "token": "3개 이상", "reason": "design-detail 수렴 임계값 (design 4개와 구분)"}, - {"domain": "spec/design-detail", "token": "spec/concerns/", "reason": "design-detail 컴포넌트 저장 경로"}, - {"domain": "spec/design-detail", "token": "spec/flows/", "reason": "design-detail 플로우 저장 경로"}, + {"domain": "spec-write/write", "token": "## OCP 확장점", "reason": "write DESIGN.md 출력 구조 섹션"}, + {"domain": "spec-write/write", "token": "## 미결정 사항", "reason": "write DESIGN.md 출력 구조 섹션"}, + {"domain": "spec-write/write", "token": "## 관심사 분리", "reason": "write DESIGN.md 출력 구조 섹션"}, + {"domain": "spec-write/write-detail", "token": "## 핵심 로직", "reason": "write-detail concerns 출력 구조"}, + {"domain": "spec-write/write-detail", "token": "## 흐름 다이어그램", "reason": "write-detail flows 출력 구조"}, + {"domain": "spec-write/write-detail", "token": "spec/concerns/", "reason": "write-detail 컴포넌트 저장 경로"}, + {"domain": "spec-write/write-detail", "token": "spec/flows/", "reason": "write-detail 플로우 저장 경로"}, {"domain": "spec/review", "token": "excerpt mismatch", "reason": "L1 인용 검증 실패 사유"}, {"domain": "spec/review", "token": "gap-auditor", "reason": "audit 단일 게이트 에이전트"}, {"domain": "spec/annotate", "token": "## 에러 처리", "reason": "annotate 에러 처리 (매칭 0건/retry)"},