334 lines
30 KiB
Markdown
334 lines
30 KiB
Markdown
# P3-A 설계 — 프롬프트/skill 분리 **구조 인프라** (3층 모델: 정체성 / 절차 / 문맥)
|
||
|
||
> 리뷰 로드맵 P3, **P3-A(구조 인프라)** 범위. 선행: P1(venture-bootstrap)·P2(design-direction) 완료·master 머지.
|
||
> 관련 SoT: `org-os/00-role-registry/role-working-methods.yaml`, `.claude/hooks/gen_agents.py`, `.claude/skills/`.
|
||
> **P3-A 완료 ≠ method 품질 완료.** P3-A는 "절차가 누락 없이 정확한 역할에게 도달하는 구조"만 보장한다. 절차 자체를 전문가급 업무 계약으로 만드는 것은 **P3-B(Role Method Contract Hardening, §17)** 소관이며 별도 사이클로 이어진다. 이 분리는 P4 벤치마크가 "구조 이동"과 "방법론 강화"의 품질 효과를 구분해 측정하게 한다.
|
||
|
||
## 1. 문제와 목표 (BLUF)
|
||
|
||
**bottom-line:** 에이전트 카드(`.claude/agents/*.md`)가 **정체성(Who am I)**과 **실무 절차(How I work)**를 한 파일에 뒤섞어 담고, 절차가 카드마다 **중복 삽입**된다. 이를 3층으로 분리한다 — **agent=정체성·경계**, **skill=절차**, **context-package=현재 과제**. 절차는 `role-working-methods.yaml`(유일 편집 SoT)에서 **역할별 method-skill로 생성**하고, 카드는 얇은 spine + skill 참조만 남긴다. **범위는 구조 이동으로 한정**(P3-A) — 절차 문장을 재작성·심화하지 않는다(그건 P3-B).
|
||
|
||
**decision-needed:** 사용자 spec 승인 → 구현 계획(writing-plans) → SDD. **approver: 사용자(theorose49).**
|
||
|
||
**confidence:** High(E3) — 중복은 실측됨: 72/72 카드에 `## 일하는 방식` 인라인 embed, 총 5044줄. 한 역할 method가 워커 카드 + family router 카드에 각각 박히고(fan-out), collapse family는 멤버 전원 method를 1카드에 인라인. design 역할은 method embed + craft-block + design-craft SKILL.md = 3중 중복.
|
||
|
||
**risks:** (a) subagent가 `skills:` frontmatter를 auto-load 못 하면 절차 유실 → 카드 spine hedge + Phase 0 실측으로 방어. (b) 절차 내용이 바뀌면 P4 벤치마크에서 품질 회귀로 잡힘 — P3는 **내용 불변 구조 이동**(품질 중립)으로 스코프 고정. (c) skill 참조 무결성 게이트가 현재 **전무** → 새 게이트로 채움.
|
||
|
||
**evidence:** `gen_agents.py:87-106`(wm_block), `des-prod.md:30-46`(3중 중복 실물), `lint_refs.py`·`doctor.py` grep(skill 검사 0건), 75 agent-bound 역할 == 75 working-method(1:1, 누락/고아 0).
|
||
|
||
**핵심 목표(측정 가능):**
|
||
1. 절차의 **인라인 중복 제거**: router·collapse·워커에서 full method embed 삭제. 카드 = 정체성 + 얇은 spine + skill 참조.
|
||
2. **SoT 단일화**: `role-working-methods.yaml` 1곳만 사람이 편집. method-skill은 생성물(gen).
|
||
3. **무결성 강제 신설**: 모든 `skills:` 참조 실존 + 고아 skill 0 + 생성물 drift 0 (doctor/lint 게이트).
|
||
4. **품질 중립**: 같은 절차 내용이 skill로 에이전트에 도달. 에이전트 개수(72)·역할(75)·상태머신·validator 계약 불변.
|
||
|
||
## 2. 3층 모델
|
||
|
||
| 층 | 무엇 | 어디 | 안정성 | P3 변화 |
|
||
|---|---|---|---|---|
|
||
| **정체성 (Who am I)** | 관점·시야·책임·evidence-basis·경계(exclusions)·협업역할·**하네스 출력계약(불변식)** | `.claude/agents/*.md` (생성물) | 역할당 안정 | 카드에 유지(정체성은 작다). 절차 embed 제거, spine로 축약 |
|
||
| **절차 (How I work)** | 단계별 실무 절차·프레임워크·체크리스트·입출력·도구순서·실패패턴·자기검증·handoff | `.claude/skills/generated/<role>-method/SKILL.md` (생성물) + 공용 `.claude/skills/<craft>/`(수제) | 방법론 진화 시 갱신 | **신설** — YAML서 생성 |
|
||
| **문맥 (What now)** | mode/tier/lens/objective/must-read/task-boundaries/design-brief | `context_package.py`가 spawn마다 컴파일 (`context-package-spec.yaml`) | 과제당 | 변화 없음(이미 존재) |
|
||
|
||
**불변 원칙:** 정체성은 카드에 눈앞에 둔다(경계·출력계약은 절대 숨기지 않는다). 절차는 skill로 재사용·버전관리한다. 문맥은 런타임에 주입한다.
|
||
|
||
## 3. SoT & 생성 파이프라인
|
||
|
||
```
|
||
role-working-methods.yaml ← 유일 편집 SoT (사람이 고치는 유일 파일, 75역할)
|
||
│ gen_method_skills.py (신설, gen_agents 자매)
|
||
▼
|
||
.claude/skills/generated/<role>-method/SKILL.md ← 생성물 75개 (편집 금지, 헤더 경고 + drift 게이트)
|
||
│
|
||
method-skill-registry.yaml ← role→method-skill(+capability-skills), family→policy 매핑 (신설, 수제 SoT)
|
||
│ gen_agents.py (개정: wm_block embed → spine + skills: frontmatter)
|
||
▼
|
||
.claude/agents/*.md ← 생성물 72개 (정체성 + 얇은 spine + skills 참조)
|
||
```
|
||
|
||
- **`role-working-methods.yaml`**: 기존 필드(working-method/key-frameworks/evidence-they-use/sources) 불변 + **optional `self-check` 필드 additive 신설**(역할 고유 검증 문항, 하위호환 — 없으면 skill에 self-check 섹션 생략). 유일하게 사람이 편집하는 절차 원천.
|
||
- **`gen_method_skills.py`(신설)**: 각 agent-bound 역할(75) → 1 method-skill SKILL.md 생성. `--check`로 drift 검증(파일 안 씀). `gen_agents.py`와 동일한 생성물 패턴(수기편집 금지).
|
||
- **`method-skill-registry.yaml`(신설, 수제)**: 어느 역할이 어느 method-skill + 공용 capability-skill을 쓰는지, family별 협업정책. 기존 `gen_agents.py`에 하드코딩된 `CRAFT`/`SKILLS_FM`/`IMPL_FAMILIES` dict를 이 registry로 **흡수·단일화**.
|
||
- **`gen_agents.py`(개정)**: `wm_block`(full embed) 제거 → `method_spine`(얇은 유도 블록) + registry 기반 `skills:` frontmatter 방출.
|
||
|
||
**생성물 편집 금지 강제:** 생성 skill·에이전트 상단에 `<!-- GENERATED — edit role-working-methods.yaml / role-profiles.yaml, then rerun gen_*. Do not edit. -->` 헤더. doctor가 `--check`로 drift(수기 편집)를 실패 처리.
|
||
|
||
## 4. `method-skill-registry.yaml` 스키마
|
||
|
||
```yaml
|
||
# method-skill-registry — role→skill 배선의 단일 정본(SoT).
|
||
# gen_method_skills 가 method-skill 을 생성하고, gen_agents 가 이 파일로 skills: frontmatter 를 방출한다.
|
||
method-skill-registry:
|
||
version: 1
|
||
generated-dir: .claude/skills/generated # 생성 method-skill 위치 규약(Phase 0 확정)
|
||
method-skill-suffix: -method # <role-lower><suffix> = skill name
|
||
|
||
# ── 역할별: 생성 method-skill(고유 절차) + 공용 capability-skill(수제 전문기법) ──
|
||
roles:
|
||
DES-PROD: { method-skill: des-prod-method, capability-skills: [design-craft] }
|
||
DES-PLATFORM: { method-skill: des-platform-method, capability-skills: [design-craft] }
|
||
DES-INTERNAL: { method-skill: des-internal-method, capability-skills: [design-craft] }
|
||
DES-VISUAL: { method-skill: des-visual-method, capability-skills: [design-craft] }
|
||
DOC-VISUAL: { method-skill: doc-visual-method, capability-skills: [design-craft, diagram-craft] }
|
||
ARCH-TECH: { method-skill: arch-tech-method, capability-skills: [] }
|
||
# … 75역할 전부 (method-skill 은 관례상 <role-lower>-method 이지만 명시로 둔다 = 오타 조기검출)
|
||
|
||
# ── family별: 협업정책 + family 수준 공용 skill (멤버 method-skill 은 member-role-ids 에서 파생) ──
|
||
families:
|
||
FAM-DESIGN: { policy: fan-out, lead: DES-DIRECTOR, capability-skills: [] }
|
||
FAM-ENG-BACKEND: { policy: collapse, capability-skills: [build-loop] }
|
||
FAM-ENG-FRONTEND: { policy: collapse, capability-skills: [build-loop] }
|
||
FAM-ENG-SPECIAL: { policy: collapse, capability-skills: [build-loop] }
|
||
FAM-PLATFORM-INFRA: { policy: collapse, capability-skills: [build-loop] }
|
||
FAM-QA: { policy: collapse, capability-skills: [] }
|
||
FAM-OPS-DELIVERY: { policy: collapse, capability-skills: [] }
|
||
FAM-ORCH: { policy: n/a, capability-skills: [] }
|
||
# fan-out-split(router+워커)·단일멤버 fan-out 도 명시(정책 대조용)
|
||
```
|
||
|
||
**설계 결정:**
|
||
- `capability-skills`(design-craft/build-loop/diagram-craft)는 registry의 SoT가 된다 — `gen_agents.py`의 `CRAFT`/`SKILLS_FM`/`IMPL_FAMILIES` 하드코딩 dict를 대체. 한 곳에서만 배선(#10 tools-matrix와 같은 철학).
|
||
- family의 **멤버 method-skill은 파생**(`member-role-ids` → 각 `roles[rid].method-skill`) — registry에 재나열 안 함(DRY).
|
||
- registry 키(role-id·family-id)는 실존 검증(오타로 정본이 조용히 무시되는 것 방지 — `gen_agents.py:60-63`와 동일 패턴).
|
||
|
||
## 5. 생성 method-skill(SKILL.md) 구조
|
||
|
||
`gen_method_skills.py`가 역할 `R`의 `role-working-methods.yaml` 엔트리에서 생성:
|
||
|
||
```markdown
|
||
---
|
||
name: des-prod-method
|
||
description: "Use when working AS the 프로덕트 디자이너 (DES-PROD) role — the step-by-step working method, frameworks, evidence types, and self-check for this role. Auto-loaded via the des-prod agent's skills: frontmatter."
|
||
generated-from: role-working-methods.yaml#DES-PROD
|
||
---
|
||
<!-- GENERATED from role-working-methods.yaml — do not edit. Rerun: python3 .claude/hooks/gen_method_skills.py -->
|
||
|
||
# DES-PROD 실무 절차 (일하는 방식)
|
||
|
||
## 절차 (working-method)
|
||
- 먼저 design-brief를 세운다(design-brief-spec): …
|
||
- Double Diamond로 진행한다: …
|
||
- …
|
||
|
||
## 주요 프레임워크
|
||
- design-brief (제약>묘사) …
|
||
- Double Diamond …
|
||
|
||
## 판단 근거 자료 (evidence)
|
||
- user research · 행동 데이터 …
|
||
|
||
## 참고 출처
|
||
- https://…
|
||
|
||
## 자기검증 (self-check) — 역할 고유 검증만 (선택·optional)
|
||
- 사용자 행동 근거 없이 시각 취향으로 결정하지 않았나?
|
||
- 핵심 흐름과 예외 상태를 모두 설계했나?
|
||
- generic한 "modern/clean" 표현으로 방향을 대체하지 않았나?
|
||
```
|
||
|
||
- **본문 = `role-working-methods.yaml`의 working-method/key-frameworks/evidence/sources를 그대로 옮긴 것**(내용 불변 — §14 비목표). 즉 `wm_block`이 카드에 넣던 텍스트가 skill로 이동.
|
||
- `description`은 **skill 자동선택 신호**(Claude Code가 skill 매칭에 사용) — 역할명 + "working AS this role"로 생성. 사람이 쓰는 게 아니라 **파생**(role-profiles의 role-name + perspective 첫 문장).
|
||
- **self-check는 역할 고유 검증만 담는다 — 공통 하네스 불변식(고유관점/비종합/근거+반증/실물≠요약)을 재복제하지 않는다.** 이유: (a) 공통 불변식은 카드의 전용 계약 섹션(§7)에 이미 가시이므로 skill에 넣으면 재중복. (b) skill이 auto-load 실패하면 skill 내부 self-check도 함께 사라지므로, skill에 공통 불변식을 넣는 건 "auto-load 실패 hedge"가 되지도 않는다(가시 hedge는 카드 계약 섹션이 담당).
|
||
- self-check는 **optional `self-check` 필드**(role-working-methods.yaml에 additive 신설, §3)에서 렌더. 필드 없는 역할은 self-check 섹션 생략(P3는 75개를 backfill하지 않음 — 내용 중립, §14). design 역할 등 exemplar만 우선 작성 가능.
|
||
|
||
## 6. 에이전트 카드 변화 — 협업역할별 3정책 (Decision C)
|
||
|
||
기존 4개 생성 경로가 정책에 1:1 대응한다.
|
||
|
||
### 6.1 워커 (`build_role_agent`, 43개) — 자기 method-skill
|
||
- frontmatter: `skills: [<자기 method-skill>, <capability-skills…>]` (registry `roles[rid]`).
|
||
- 본문: 기존 `## 일하는 방식` full embed **삭제** → `## 핵심 작업 방법`(§7 spine) 삽입. 나머지(관점·시야·책임·evidence-basis·Fan-out 워커 계약·When invoked·Output contract) **유지**.
|
||
- design 워커의 `craft_block`(design-craft 인라인 리마인더)은 **capability-skill 참조로 대체**(design-craft가 이미 skills:에 있음 → 본문 리마인더는 spine 1줄로 축약, 중복 제거).
|
||
|
||
### 6.2 synthesis lead (`build_lead_agent`, 3개: CONSULT-EM·DOC-LEAD·DES-DIRECTOR) — 자기 수렴 method만
|
||
- frontmatter: `skills: [<lead 자기 method-skill>, <capability-skills…>]`. **멤버 method-skill 없음**.
|
||
- 본문: lead 자신의 관점·수렴 method spine + Synthesis-lead 계약(FRAME/SYNTHESIZE, storyline) **유지**. 멤버 절차는 담지 않음(멤버는 각자 skill 로드). "멤버 보고서 원본 필독·평균 금지·dissent 보존"은 계약에 유지.
|
||
|
||
### 6.3 router (`build_router_agent`, 10개) — 멤버 method 전부 제거, pointer만
|
||
- frontmatter: `skills: [<family capability-skills…>]`만. **멤버 method-skill·자기 method 없음**(router는 일을 직접 안 함).
|
||
- 본문: 기존 멤버 전원 `## 일하는 방식` embed **삭제** → **member→method-skill pointer table**로 대체:
|
||
```
|
||
## fan-out 멤버 → method-skill
|
||
- DES-PROD (agent: des-prod, skill: des-prod-method)
|
||
- DES-PLATFORM (agent: des-platform, skill: des-platform-method)
|
||
- …
|
||
```
|
||
Router 계약(정상경로 fan-out / 단독경로 role-by-role / conflicts 보존)은 **유지**. 단독경로는 "각 멤버 skill을 이름으로 로드해 역할별 분석"으로 문구 갱신.
|
||
- 멤버 관점·시야·책임(`## 대표 역할별 관점·시야·책임`)은 **유지**(라우팅 판단 근거 = 정체성이지 절차 아님). 삭제되는 건 절차(method)뿐.
|
||
|
||
### 6.4 family agent (`build_agent`, 16개: 6 collapse + 9 단일멤버 fan-out + FAM-ORCH) — 실제 수행자, method 유지
|
||
- 이 경로는 **실제 작업 수행자**(collapse는 멤버 전원 일을 1 에이전트가, 단일멤버 fan-out은 그 1명 일을). 멤버 method를 완전히 제거하면 수행 능력이 사라진다(사용자 Decision C 명시).
|
||
- frontmatter: `skills: [<멤버 method-skill union>, <family capability-skills…>]`. 멤버 method-skill을 `member-role-ids`에서 파생해 전부 로드.
|
||
- 본문: 기존 멤버 전원 full embed **삭제** → §7 spine(멤버 프레임워크 요지 + "전체 절차는 각 멤버 method-skill") + collapse 계약(설계 Accepted 확인) 유지. 멤버 관점·시야·책임 유지.
|
||
- FAM-ORCH(policy n/a)는 자기 1멤버(OPS-ORCH) method-skill 로드.
|
||
|
||
**요약 표:**
|
||
|
||
| 경로 | 개수 | 자기 method | 멤버 method | frontmatter skills |
|
||
|---|---|---|---|---|
|
||
| 워커 | 43 | ✅ spine+skill | — | 자기 method-skill + capability |
|
||
| lead | 3 | ✅ spine+skill | ❌ | 자기 method-skill + capability |
|
||
| router | 10 | ❌(수행 안 함) | ❌ pointer만 | family capability만 |
|
||
| family agent | 16 | ✅(=멤버) | ✅ union 로드 | 멤버 method-skill union + capability |
|
||
|
||
## 7. 카드 method-spine (파생 규칙) + 유지되는 하네스 불변식
|
||
|
||
**spine = 카드에 남는 얇은 절차 잔여 — 역할-파생만(신규 중복 금지).** `role-working-methods.yaml`에서 **파생**(사람이 75역할 spine을 손으로 안 씀 — YAGNI·DRY):
|
||
|
||
```
|
||
## 핵심 작업 방법 (전체 절차는 skill)
|
||
- 핵심 접근: <working-method[0] — 첫 절차 문장(essence)>
|
||
- 주요 프레임워크: <key-frameworks[:3] 이름만 — 정의·단계 없음>
|
||
- **전체 실무 절차·체크리스트·자기검증·handoff는 `<method-skill>` skill을 따른다. skill 미적재 시 작업 시작 금지.**
|
||
```
|
||
|
||
- spine은 **역할 파생 3줄만**(essence 1줄 + top3 프레임워크 **이름만** + skill pointer/load-guard). 카드가 역할별로 구별되고 라우팅·선택에 도움.
|
||
- **프레임워크는 이름만**(예: `Double Diamond, JTBD, Design Brief`) — 정의·단계·사용법은 skill 본문에서만. spine에 설명을 넣으면 skill과 재중복.
|
||
- **공통 불변식(고유 관점만/비종합/근거+반증/실물≠요약)은 spine에 재나열하지 않는다** — 이미 카드의 전용 섹션(`## When invoked`·`## Fan-out 워커 계약`·`## Output contract`)에 가시로 유지되므로(§6서 유지 명시), spine이 다시 나열하면 P3의 dedup 목표와 모순된다. 사용자 Decision B("하네스 불변식은 카드에 계속 가시")는 **기존 전용 섹션 유지로 충족**된다 — 새 중복을 만들지 않고.
|
||
- **auto-load 실패 hedge = 카드의 전용 계약 섹션(항상 가시) + spine load-guard("skill 미적재 시 시작 금지")** 2중. skill 내부 self-check는 hedge가 아니다(skill이 안 실리면 그 self-check도 사라짐) — 그래서 skill self-check에는 공통 불변식을 넣지 않는다(§5).
|
||
- 분량: spine ~3줄(현 embed ~25줄 대비 ~88% 축소). router/family는 멤버 수만큼 pointer 줄이 늘지만 여전히 full embed보다 작다.
|
||
|
||
**카드에 계속 가시로 남는 하네스 불변식(절대 skill로 숨기지 않음):**
|
||
- `## Output contract (hook이 강제)`: report-header(BLUF) 필수, evidence 없는 confidence:High 금지, E4/E5 실존 아티팩트, **primary-artifacts 분리(#9)**, MD 손수 금지, external side-effect 기본 금지. → **전부 유지**(이건 절차가 아니라 하네스 계약).
|
||
- `## When invoked` 진입 규약(context-package 확인, must-read/forbidden-context). → 유지.
|
||
- 이유: 이들은 validator(`validate_report`)·guard(`guard_tools`)가 강제하는 계약이므로 에이전트 눈앞에 항상 있어야 한다.
|
||
|
||
## 8. `gen_agents.py` 변경
|
||
|
||
1. **로드**: `load_method_registry()` 신설 — `method-skill-registry.yaml` 읽어 `roles`/`families` 맵. 키 실존 검증(오타 조기검출).
|
||
2. **`wm_block` 제거** → `method_spine(rid_or_members, ...)` 신설: §7 규칙으로 spine 텍스트 생성(essence 1줄 + top3 프레임워크 **이름만** + skill pointer/load-guard). **공통 불변식 재나열 안 함**.
|
||
3. **`skills_fm_line` 개정**: 기존 하드코딩(`SKILLS_FM`/`IMPL_FAMILIES`) 제거 → registry에서 파생.
|
||
- 워커/lead: `[roles[rid].method-skill] + roles[rid].capability-skills`.
|
||
- router: `families[fid].capability-skills`만.
|
||
- family agent: `dedup(멤버들 method-skill) + families[fid].capability-skills`.
|
||
4. **`craft_block` 축소**: design 역할 인라인 리마인더 → spine 1줄 + capability-skill 참조(design-craft가 skills:에 이미 있음). D2-우선 등 핵심 self-check 1줄만 잔류(중복 제거).
|
||
5. **router 본문**: 멤버 method embed → member→method-skill pointer table.
|
||
6. **검증(assert) 개정**: `## 일하는 방식` 존재 assert(605-606) → `## 핵심 작업 방법`(spine) + `skills:` frontmatter 존재 assert. 개수 계약(72/43/3/16/10) 불변.
|
||
|
||
## 9. 무결성 강제 (신설 게이트 — 현재 전무)
|
||
|
||
**`doctor.py` `check_method_skill_wiring()` 신설:**
|
||
1. **완전성**: agent-bound 역할(75) 전부 registry `roles`에 있고 각자 `method-skill` 지정.
|
||
2. **실존**: registry가 가리키는 모든 method-skill이 `generated-dir`에 SKILL.md로 실존. 모든 capability-skill이 수제 skill로 실존.
|
||
3. **참조 해소**: 모든 `.claude/agents/*.md`의 `skills:` frontmatter 항목이 실존 SKILL.md로 해소.
|
||
4. **고아 0**: `generated-dir`의 모든 SKILL.md가 registry role에 매핑(1:1). 남는 생성물 없음(75==75==75).
|
||
5. **drift 0**: `gen_method_skills.py --check` 통과(생성물이 현 YAML과 일치 — 수기 편집·stale 검출). `gen_agents.py --check`도 동일.
|
||
6. **키 정합**: registry `roles`/`families` 키 ⊆ roles.yaml / capability-families.yaml.
|
||
|
||
**`lint_refs.py` 확장:** 에이전트 `skills:` 참조 → SKILL.md 해소 무결성(참조 그래프 린트에 편입). 커맨드→agent 참조와 동형.
|
||
|
||
**Phase 0 실측(§10)** 후 배선. `run_all.py`(CI 진입점)에 자동 편입.
|
||
|
||
## 10. skill 발견·auto-load 리스크 & Phase 0
|
||
|
||
**load-bearing 가정:** subagent가 `.claude/skills/generated/<role>-method/SKILL.md`(중첩 디렉터리)를 `skills:` frontmatter로 auto-load한다.
|
||
|
||
- **근거(부분):** 플러그인 skill이 `.../skills/<name>/SKILL.md` 중첩으로 발견됨(현재 사용 중). 기존 프로젝트 skill 3종은 flat `.claude/skills/<name>/`.
|
||
- **Phase 0(구현 첫 태스크, 게이트):** 생성 skill 1개를 `.claude/skills/generated/probe-method/`에 두고 throwaway 에이전트 `skills:[probe-method]`로 **실제 subagent 로드 확인**.
|
||
- 발견되면: `generated/` 중첩 레이아웃 확정(사용자 선호).
|
||
- 발견 안 되면: flat `.claude/skills/<role>-method/`로 폴백(검증된 패턴, 이름 규약 `*-method`로 그룹화). registry `generated-dir` 한 줄만 바꾸면 전 파이프라인 대응.
|
||
- **hedge:** 발견 여부와 무관하게 카드 spine + skill self-check에 공통 불변식이 중복 가시 → auto-load 실패해도 역할이 빈 껍데기가 되지 않음(사용자 Decision B). 이건 belt-and-suspenders이지 회귀가 아니다.
|
||
|
||
## 11. 하위호환·마이그레이션
|
||
|
||
- **기존 skill 3종 유지**: design-craft·diagram-craft·build-loop는 수제 capability-skill로 그대로. registry가 이들을 참조(하드코딩 dict 흡수).
|
||
- **기존 테스트 갱신**(회귀 아님, 계약 이동):
|
||
- `test_enforcement.py:605-606`, `909-915`: `## 일하는 방식` embed assert → spine + `skills:` 참조 assert. `skills:[design-craft]` 유지 확인(capability-skill로).
|
||
- `test_p1_build.py`: build-loop skill 존재·참조 — 유지(registry 경유로 변경만).
|
||
- `gen_agents.py` 내부 assert(§8.6).
|
||
- **커맨드·hook 무영향**: state_engine·validate_report·context_package·render_report 등은 카드 본문 텍스트에 의존하지 않음(계약은 `.report.yaml`·SoT yaml). 카드 재구성은 이들과 독립.
|
||
- **역순 안전**: gen_method_skills → gen_agents 순으로만 생성(skill이 먼저 실존해야 카드가 참조). doctor가 순서 위반(참조는 있는데 skill 없음)을 실패 처리.
|
||
|
||
## 12. 하네스 정합성 (불변 유지)
|
||
|
||
- 에이전트 개수 **72 불변**(43 워커 + 3 lead + 16 family + 10 router). 역할 **75 불변**.
|
||
- 상태머신·전이·condition-catalog·validator·guard·evidence-ledger·token-ledger·kpi 전부 **무영향**.
|
||
- 신규 산출물: `gen_method_skills.py`, `method-skill-registry.yaml`, `.claude/skills/generated/*/SKILL.md`(75), doctor/lint 게이트, 테스트.
|
||
- gen 재생성 흐름에 편입: `role-profiles`/`capability-families` 변경 후 `gen_agents` 재실행 → 이제 `gen_method_skills`도 함께(문서·CLAUDE.md 검증 섹션 갱신).
|
||
|
||
## 13. 테스트 계획 (`test_p3_*.py`, ~standalone check() 컨벤션)
|
||
|
||
1. **gen_method_skills 완전성**: 75 역할 → 75 SKILL.md, 각 frontmatter(name/description/generated-from) 유효.
|
||
2. **내용 불변(품질중립)**: 생성 skill 본문이 YAML의 working-method/frameworks/evidence를 손실 없이 포함(핵심 문장 부분일치).
|
||
3. **--check drift**: 생성 후 재-check 통과. 수기 1글자 변조 → --check 실패(감지).
|
||
4. **registry 완전성·키 정합**: 75 역할 전부 매핑, 키 ⊆ roles/families, 오타 키 → assert.
|
||
5. **gen_agents 방출**: 워커 카드에 `skills:[<method>]` + `## 핵심 작업 방법` 있고 `## 일하는 방식` full embed 없음.
|
||
6. **spine 얇음·중복금지**: spine에 공통 불변식 문장(고유관점/비종합/근거+반증/실물≠요약) 재나열 **없음**. 프레임워크는 이름만(정의 문장 없음). essence 1줄만.
|
||
7. **skill self-check 정책**: 생성 skill의 self-check 섹션에 공통 불변식 문장 **없음**(역할 고유 검증만). `self-check` YAML 필드 없는 역할은 self-check 섹션 생략.
|
||
8. **router 정책**: router 카드에 멤버 method embed 없음, member→method-skill pointer table 있음, `skills:`에 멤버 method 없음.
|
||
9. **lead 정책**: lead 카드에 멤버 method 없음, 자기 method-skill만.
|
||
10. **collapse/family 정책**: family agent `skills:`에 멤버 method-skill union 있음(수행능력 보존).
|
||
11. **capability-skill 흡수**: des-prod `skills:`에 design-craft, IMPL family에 build-loop — registry 경유로 유지.
|
||
12. **하네스 불변식 잔류**: 모든 카드에 Output contract(primary-artifacts·report-header)·When invoked·협업 계약 유지(공통 불변식의 유일 가시 지점).
|
||
13. **doctor 게이트**: 정상 → OK. method-skill 삭제 → FAIL(실존). registry에서 역할 제거 → FAIL(완전성). 고아 skill 추가 → FAIL. skills: 깨진 참조 → FAIL.
|
||
14. **lint_refs**: 깨진 skills: 참조 검출.
|
||
15. **개수 계약**: 72 agents·75 skills 회귀 검출.
|
||
16. **run_all 통합**: 전체 green.
|
||
|
||
## 14. 비목표 (스코프 고정)
|
||
|
||
- **절차 내용 변경 금지**: working-method 문장을 다시 쓰거나 개선하지 않는다 — **위치만 이동**(카드 embed → skill). 품질 변화는 P4 벤치마크가 별도 검증. P3-A는 구조적·품질중립.
|
||
- **method 품질 강화는 P3-B**: 절차 완전성 검사·decision-rules·alternatives-policy·output-artifacts·handoff-contract·prohibited-shortcuts·execution-trace는 P3-A 범위 밖 — §17 후속.
|
||
- **self-check 75개 backfill 금지**: `self-check`는 optional 필드. P3-A는 전 역할에 self-check를 채워 넣지 않는다(내용 생성 = 중립성 위반). 필드가 있는 역할만 렌더, exemplar(design 역할 등)만 우선 작성 가능.
|
||
- **상태머신/validator/guard 계약 변경 금지**.
|
||
- **수제 클러스터 skill 금지**: 역할별 생성(사용자 Decision A) — 유사역할 평균화 방지.
|
||
- **에이전트 개수·역할 수 변경 금지**.
|
||
- **P4(벤치마크)·설계외 리팩터 금지**: skill 발견 폴백(§10) 외 런타임 동작 변경 없음.
|
||
|
||
## 15. 열린 결정 (사용자 리뷰서 확정됨)
|
||
|
||
1. **카드 spine 구성**: ✅ **확정** — 역할별 `working-method[0]`(essence) + 프레임워크 **이름 최대 3개** + method-skill pointer/load-guard로만. 공통 하네스 불변식은 기존 When invoked·협업 계약·Output contract 섹션에 유지, spine·생성 skill에 재복제 안 함(§7).
|
||
2. **skill self-check**: ✅ **확정** — 역할 고유 검증만. optional `self-check` YAML 필드에서 렌더, 없으면 생략. 공통 불변식 재복제 금지(§5).
|
||
3. **method-skill `name` 규약**: `<role-lower>-method`(예 `des-prod-method`). role-id에 특수문자 없으므로 안전. registry에 명시(파생 아님 — 오타 검출).
|
||
4. **generated-dir 레이아웃**: `.claude/skills/generated/`(사용자 선호) vs flat 폴백 — **Phase 0가 실측 후 확정**(§10).
|
||
5. **collapse family skill 폭증 우려**: FAM-ENG-BACKEND(6멤버)는 6 method-skill + build-loop = 7 skill auto-load. 기존엔 6멤버 method가 다 인라인이었으므로 **로드량 중립 이상**(on-demand). 문제되면 family-공통 method-skill로 합치는 건 향후(P3 범위 밖).
|
||
|
||
## 16. 구현 체크리스트 (writing-plans가 TDD 태스크로 분해)
|
||
|
||
- [ ] **Phase 0**: skill 발견·auto-load 실측 → generated-dir 레이아웃 확정(§10).
|
||
- [ ] `role-working-methods.yaml`에 optional `self-check` 필드 스키마 추가(additive) + design exemplar 몇 개(§3,§5).
|
||
- [ ] `method-skill-registry.yaml` 작성(75 역할 + family 정책, capability-skill 흡수)(§4).
|
||
- [ ] `gen_method_skills.py`(생성 + --check drift, self-check optional 렌더)(§3,§5).
|
||
- [ ] 75 method-skill 생성·커밋(생성물)(§5).
|
||
- [ ] `gen_agents.py` 개정: wm_block→method_spine(공통불변식 재나열 안 함·프레임워크 이름만), skills: registry 파생, router pointer, craft_block 축소, assert 갱신(§6,§7,§8).
|
||
- [ ] 72 에이전트 재생성(§6).
|
||
- [ ] `doctor.py check_method_skill_wiring` + `lint_refs.py` skill 참조(§9).
|
||
- [ ] `test_p3_*.py` 16종(§13).
|
||
- [ ] 기존 테스트 갱신(§11).
|
||
- [ ] CLAUDE.md·검증 섹션·gen 흐름 문서 갱신(§12).
|
||
- [ ] `run_all.py` green + doctor OK 재확인.
|
||
|
||
## 17. 후속 로드맵 — P3-B(Role Method Contract Hardening) + P4 구분
|
||
|
||
P3-A는 **기반 공사**다. 단독으로 끝나면 "기존의 평균적 절차를 더 깔끔하게 배포하는 시스템"에 머문다. 사용자가 원하는 강한 결과(디자인 등)를 위해선 절차 자체를 실행·검증 가능한 **업무 계약**으로 만드는 P3-B가 이어져야 한다. 여기 스코프만 캡처(설계는 별도 brainstorm→spec→plan 사이클).
|
||
|
||
**핵심 원리 — 공통 품질과 역할별 사고의 분리(평균화 방지):**
|
||
- **공통 품질 = validator/report-schema가 강제**(75역할에 복제 금지): 근거 없는 결론 금지, 대안 비교 필수, 반대논거·dissent 필수, required-artifact 누락 차단, handoff 대상·입력 명시, 생략 단계+사유 기록.
|
||
- **역할별 사고 = method-skill이 제공**: 무엇을 어떤 순서로 분석하나, 어떤 자료를 근거로, 어떤 판단규칙, 어떤 전문 산출물, 다음 역할에 무엇을 넘기나, 이 역할의 흔한 오류.
|
||
|
||
**P3-B ①: `role-working-methods.yaml` 스키마 확장** (flat 문장목록 → 실행 계약):
|
||
```yaml
|
||
role-working-methods:
|
||
DES-PROD:
|
||
purpose: ; triggers: ; non-goals:
|
||
required-inputs: [product-decision, direction-input-brief, user-research, constraints]
|
||
workflow:
|
||
- id: brief
|
||
objective: ; actions: []; required-output: ; completion-gate: []
|
||
- id: references # …단계별
|
||
decision-rules: []; evidence-policy: {}; alternatives-policy: {}
|
||
output-artifacts: []; handoff-contract: {}; prohibited-shortcuts: []
|
||
escalation-conditions: []; self-check: []
|
||
```
|
||
gen_method_skills가 이 계약을 skill 본문(입력→단계→단계별 산출물→완료게이트→판단규칙→근거→대안·반증→금지→handoff→자기검증)으로 렌더.
|
||
|
||
**P3-B ②: 역할별 차별화(디자인 예시 — design-craft 수준):** 같은 디자인군도 평균화 금지.
|
||
- DES-PROD: brief→reference(3–6 named+anti-reference)→constraint-matrix→token-semantics→decision-record, prohibited-shortcuts(brief 없이 토큰부터/색값만 바꾼 대안/MVP 이유로 상태설계 생략).
|
||
- DES-PLATFORM: token 계층·component boundary·state model·variant explosion·composition·governance·migration·deprecation.
|
||
- DES-VISUAL: visual thesis·form language·typographic character·signature element·material·motion grammar·anti-reference·generic-risk.
|
||
- DES-DIRECTOR: 발산 프레이밍·독립안 비교·수렴기준·평균금지·locked-invariant·dissent·critique 종합.
|
||
|
||
**P3-B ③: 실행 강제(존재≠수행):** standard/heavy 보고서에 `method-execution` trace(skill-id·sha256·completed-phases·skipped-phases+사유·decisions[alternatives-considered]·handoff artifacts). validator: required phase 누락→Hard Fail, 생략+사유없음→Hard Fail, 대안 필요한데 1개→Hard Fail, 근거참조 없음→Hard Fail/confidence cap, handoff artifact 누락→다음 stage 진입 차단. **light tier는 경량 적용**, standard/heavy만 full trace(과도 비용 회피).
|
||
|
||
**P4 벤치마크 3단 비교(반드시 분리):** Baseline vs **P3-A(구조 이동)** vs **P3-B(방법론 강화)**. 그래야 "skill 분리 자체가 품질을 떨어뜨렸나"와 "method 강화가 실제 품질을 올렸나"를 독립적으로 판정.
|