donghyeon.kang/company-haness
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
f668d6a158dd3847cdd51af732afaa8d509771d5
company-haness/docs/superpowers/specs/2026-07-13-p3-prompt-skill-separation-design.md
T

30 KiB
Raw Blame History

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 스키마

# 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 엔트리에서 생성:

---
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 문장목록 → 실행 계약):

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 강화가 실제 품질을 올렸나"를 독립적으로 판정.

Reference in New Issue View Git Blame Copy Permalink