PreviewDD → SpecDD → TestDD

§0TL;DR — 30초 안에 잡아야 할 것

§1제품 비전

1.0 방법론 정체성 — 3-DD Cycles

TDD는 코드를 테스트로 주도했다.
SpecDD는 코드를 스펙으로 주도했다.
우리는 그 앞에 PreviewDD를 놓는다.

본 프로젝트는 PreviewDD → SpecDD → TestDD 3개 cycle이 스테이지 게이트로 연쇄되는 방법론을 구현합니다. 각 DD는 병렬 발산(다양성) → 집계(결정) → 잠금(산출물 해시) 3단계를 따르며, 인간은 cycle 사이 H1/H2 두 gate에만 개입합니다.

1.1 한 문장 정의

"Claude Code 사용자가 한 줄을 입력하면, 본인은 디자인 OK / 배포 OK 두 번만 누르고 production-ready 풀스택 앱이 freeze된 상태로 손에 떨어지는 도구."

1.2 해결하는 통증

• "GPT/Claude로 앱 만들기" 영상 99%는 첫 아이디어를 그대로 짠다 → 진짜 더 좋은 4번 카드를 못 봄
• 스펙 없이 코드부터 짜면 drift가 누적 → "왜 안 되지?" 디버그 무한 루프
• 풀스택은 의사결정 100개 — 매번 "어떤 DB?", "어떤 인증?", "어떤 배포?" 묻는 게 사람 진을 뺌
• 테스트는 "나중에" 미루다 결국 안 만들어짐
• 결과: AI 코딩의 99%는 데모로 끝나고 freeze되지 않는다

1.3 두 해카톤 문제 테마와의 매핑

조준 테마: Build For What's Next (1순위) — "an interface that doesn't have a name yet. A workflow from a few years out."

사람이 의사결정에서 빠지고 다양성·검증·자기수정만 강제하는 파이프라인은 아직 이름이 없는 워크플로우입니다. 보조 테마는 Build From What You Know — 우리 자신(개발자)이 매일 쓰는 "AI한테 앱 시켜보기"의 통증을 정확히 알기 때문.

§2Marketplace 저장소 구조 + Plugin 배포

배포 표준은 OpenAI의 openai/codex-plugin-cc 레이아웃을 따릅니다 — 저장소 루트는 marketplace, plugins/ 하위가 실제 plugin. 하나의 repo가 marketplace 역할을 겸하여 사용자는 /plugin marketplace add <owner>/<repo> 한 줄로 접근 가능합니다.

2.1 저장소 최상위 구조

Two-Weeks-Team/PreviewForgeForClaudeCode/
├── .claude-plugin/
│   └── marketplace.json           ← marketplace 매니페스트
├── plugins/
│   └── preview-forge/             ← 실제 plugin (다음 §2.3 참조)
├── scripts/
│   ├── install-check.sh           ← 설치 전 환경 점검
│   └── release.sh                 ← 버전 태깅 + changelog 자동화
├── tests/
│   ├── plugin-manifest.test.ts    ← 매니페스트 schema 검증
│   ├── hooks.test.ts              ← hooks.json round-trip
│   └── smoke/                     ← e2e smoke test (mock API)
├── docs/
│   ├── plugin-demo.webm           ← README에 임베드할 데모 영상
│   ├── architecture.svg           ← 143-agent 조직도 그림
│   └── screenshots/               ← 대시보드 스크린샷
├── .github/
│   ├── workflows/
│   │   ├── ci.yml                 ← lint + test + manifest 검증
│   │   ├── release.yml            ← 태그 push → GitHub Release
│   │   └── marketplace-validate.yml
│   └── ISSUE_TEMPLATE/
├── .gitignore
├── LICENSE                        ← Apache-2.0
├── NOTICE                         ← 라이선스 고지
├── CHANGELOG.md
├── README.md                      ← codex-plugin-cc 스타일
└── package.json                   ← monorepo 루트 (tests/scripts용)

2.2 Marketplace manifest — .claude-plugin/marketplace.json

{
  "name": "two-weeks-team",
  "owner": {
    "name": "Two-Weeks-Team"
  },
  "metadata": {
    "description": "Preview Forge: 143-agent engineering swarm that builds frozen full-stack apps from a single idea.",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "preview-forge",
      "description": "한 줄 아이디어 → OpenAPI 잠금 → 풀스택 freeze. Claude Code에서 /pf:new 한 줄로 실행.",
      "version": "1.0.0",
      "author": {
        "name": "Two-Weeks-Team"
      },
      "source": "./plugins/preview-forge"
    }
  ]
}

2.3 Plugin 내부 구조 — plugins/preview-forge/

plugins/preview-forge/
├── .claude-plugin/
│   └── plugin.json                ← plugin 매니페스트 (§2.4)
├── agents/                        ← 143 Subagent 정의
│   ├── meta/{run-supervisor,cost-monitor,chief-engineer-pm}.md
│   ├── ideation/
│   │   ├── {ideation-lead,idea-clarifier,diversity-validator}.md
│   │   └── advocates/P01-P26.md
│   ├── panels/
│   │   ├── {tp,bp,up,rp}/{lead,01-10}.md   # 4 패널 × 11명 = 44
│   │   └── mitigation-designer.md
│   ├── spec/{lead,author,sc1-sc7}.md
│   ├── engineering/
│   │   ├── backend/{lead,controller,dto,service,repository,auth}.md
│   │   ├── frontend/{lead,app-router,component,state,tailwind,a11y}.md
│   │   ├── database/{lead,schema,migration,seed,query-opt}.md
│   │   ├── devops/{lead,docker,caddy,cicd,env}.md
│   │   └── sdk/{lead,nestia-gen,ts-client}.md
│   ├── qa/
│   │   ├── functional/{lead,unit,e2e,property,holdout}.md
│   │   ├── security/{lead,sast,secret-scan}.md
│   │   ├── performance/{lead,bundle,load}.md
│   │   └── a11y/{lead,axe,color-sr}.md
│   ├── scc/{lead,backend,frontend,type,dep}.md
│   ├── judges/{j1-j5}.md
│   ├── auditors/{au1-au5}.md
│   └── docs/{readme,changelog,demo-script}.md
├── skills/                        ← model-invoked
│   ├── run-bootstrap/SKILL.md
│   ├── scaffold/SKILL.md
│   └── mitigation-design/SKILL.md
├── commands/                      ← user-invoked slash commands (14개)
│   ├── pf:new.md · pf:status.md · pf:replay.md · pf:lessons.md
│   ├── pf:panel.md · pf:freeze.md · pf:gallery.md · pf:export.md
│   ├── pf:budget.md · pf:retry.md · pf:seed.md · pf:bootstrap.md
│   ├── pf:design.md               ← Gate H1 내장 Design Studio 오픈
│   └── pf:help.md
├── design-studio/                 ← Gate H1 내장 리뷰 UI (Next.js route)
│   ├── index.tsx                  ← 26 mockup grid + chosen tweak panel
│   ├── tweak-controls.tsx         ← 슬라이더/컬러픽커/density/wireframe toggle
│   └── live-preview.tsx           ← postMessage 기반 iframe 실시간 렌더
├── hooks/
│   ├── hooks.json
│   ├── askuser-enforcement.py     ← AskUserQuestion 강제 훅
│   ├── factory-policy.py          ← destructive bash 차단 (Layer-0)
│   └── auto-retro-trigger.py      ← run 종료 시 LESSON 자동 추출
├── bin/
│   └── pf                         ← 헤드리스 CLI
├── methodology/
│   └── global.md                  ← Layer-0 7개 비협상 규칙
├── assets/
│   ├── docker-compose.template.yml
│   ├── Caddyfile.template
│   ├── install.sh.template
│   └── nestia.config.ts.template
├── memory/                        ← 초기 seed (plugin install 후 ~/.claude로 복사됨)
│   ├── CLAUDE.md                  ← 세션 시작 룰
│   ├── PROGRESS.md                ← run 인덱스 (빈 상태)
│   └── LESSONS.md                 ← 실패 카탈로그 (빈 상태)
├── schemas/
│   ├── preview-card.schema.json   ← 5-tuple validation
│   ├── panel-vote.schema.json
│   └── score-report.schema.json
├── seed-ideas/
│   ├── 01-craft-studio-pos.md
│   ├── 02-infant-sleep-tracker.md
│   ├── 03-community-code-review.md
│   └── 04-10-*.md                 ← 총 10개 사전 검증 idea
├── monitors/
│   └── monitors.json              ← cost + run-supervisor 이벤트 모니터
├── settings.json                  ← plugin 활성화 시 기본값
├── CHANGELOG.md
├── LICENSE
├── NOTICE
└── README.md                      ← plugin 로컬 README (선택)

2.4 Plugin manifest — plugins/preview-forge/.claude-plugin/plugin.json

{
  "name": "preview-forge",
  "description": "한 줄 아이디어 → 143명 가상 엔지니어링 조직이 OpenAPI-first로 풀스택 앱을 freeze까지. 내장 Design Studio로 외부 디자인 서비스 의존 제거. Built with Opus 4.7.",
  "version": "1.0.0",
  "author": {
    "name": "Two-Weeks-Team",
    "email": "app.2weeks@gmail.com"
  },
  "homepage": "https://github.com/Two-Weeks-Team/PreviewForgeForClaudeCode",
  "repository": "https://github.com/Two-Weeks-Team/PreviewForgeForClaudeCode",
  "license": "Apache-2.0",
  "keywords": ["opus-4-7", "multi-agent", "spec-first", "openapi", "nestia", "design-studio", "self-contained", "hackathon"]
}

2.4.1 "외부 의존" 정의 — 제3자 서비스만 의존으로 간주

본 plugin의 의존성 원칙:

• 제3자 회사 서비스 = 제거 — Figma, Vercel API (build만 사용, 배포는 optional), 기타 비-Anthropic SaaS 의존 없음
• Anthropic-native 기능 = 허용 — Claude Code (Pro/Max), Claude Design, Managed Agents, Memory Tool, Batch API, Files API 등은 모두 Pro/Max 구독에 포함되므로 외부 의존이 아닌 플랫폼 기본 기능으로 간주
• 플러그인 내부 자원 = 자체완결 — 26 mockup은 inline-only HTML (CDN/외부 폰트/외부 이미지 0), 내장 Design Studio는 native HTML5만 사용

Gate H1 디자인 승인은 Claude Design 메인 · 내장 Studio fallback 2-tier:

1. 메인: /pf:design → chosen_preview를 Claude Design prompt로 패키징 → 사용자가 claude.ai/design에서 tweaks · edit · wireframe↔high-fi 토글 → "Send to Claude Code" → runs/<id>/design-bundle/에 수신
2. Fallback: Claude Design 응답 실패·offline 또는 사용자 명시적 선택 시 → 내장 Design Studio(plugins/preview-forge/design-studio/) Next.js route 오픈 → 26 mockup iframe grid + native HTML5 tweak controls로 동등 UX 제공. 두 경로 모두 design-approved.json을 생성하여 Stage 5가 consume

2.5 README 구조 (codex-plugin-cc 스타일)

저장소 루트 README.md는 다음 7개 섹션으로 구성:

1. Title + 한 줄 설명 + 데모 영상 (docs/plugin-demo.webm 임베드)
2. What You Get — 13 slash commands 리스트
3. Requirements — Claude Code 최신 + Pro/Max 구독 (팀/엔터프라이즈 포함), Node.js 20, Docker (optional)
4. Install — marketplace add → install → bootstrap 3 step
5. Usage — 각 슬래시 명령 예시 + 옵션
6. Typical Flows — 한 줄 idea → freeze까지의 표준 시나리오
7. FAQ — 비용, 실패 복구, 데이터 위치, 오프라인 가능 여부

2.6 설치 절차 (사용자 관점)

## 1) Marketplace 등록
/plugin marketplace add Two-Weeks-Team/PreviewForgeForClaudeCode

## 2) Plugin 설치
/plugin install preview-forge@two-weeks-team

## 3) 세션 리로드
/reload-plugins

## 4) 메모리 초기화 (LESSONS/PROGRESS/CLAUDE.md 복사)
/pf:bootstrap

## 5) 실행
/pf:new "한 줄 아이디어"

## 확인
## → /agents 에 143 agents 등록 확인
## → /help 에 /pf:* 13개 명령 확인
## → Next.js 대시보드 자동 기동 (http://localhost:3000)

2.7 외부 의존

2.8 배포 파이프라인

• CI: PR마다 marketplace.json·plugin.json schema 검증, hooks round-trip 테스트, smoke e2e (mock API)
• Release: main에 semver 태그 push 시 GitHub Actions가 GitHub Release 생성 + CHANGELOG 자동 추가 + marketplace.json version 자동 bump
• 버전 정책: SemVer. 1.x는 하위호환 API 유지, 2.x는 breaking change
• 제출: 해카톤 제출 후 Anthropic 공식 마켓플레이스(claude.ai/settings/plugins/submit)에 등록 신청

§3아키텍처 개요

Anthropic Managed Agents의 brain/hands/session 분리 철학을 차용한 3-layer 구조.

┌──────────────────────────────────────────────────────────────────┐
│  Layer A — Brain (의사결정)                                       │
│  Claude Opus 4.7 via Agent SDK                                   │
│  · 26-Preview Generator                                           │
│  · 10-Persona Panel (decision-panel)                              │
│  · Spec Locker (OpenAPI 작성자/비평가)                            │
│  · Score Judge (500점 채점관)                                     │
│  · Self-Correction Critic (evaluator-optimizer 패턴)              │
└──────────────────────────────────────────────────────────────────┘
                             ↕ execute(name, input) → string
┌──────────────────────────────────────────────────────────────────┐
│  Layer B — Hands (실행)                                           │
│  Claude Managed Agents 세션 (long-running, hours-OK)              │
│  · Bash + File ops in cloud container                             │
│  · pnpm install / nestia sdk / nestia swagger / vitest 실행       │
│  · 자기수정 루프(반복 빌드·테스트)                                  │
└──────────────────────────────────────────────────────────────────┘
                             ↕ events (SSE)
┌──────────────────────────────────────────────────────────────────┐
│  Layer C — Session/UI (사람 인터페이스)                            │
│  Next.js 14 (App Router) 대시보드                                 │
│  · 한 줄 입력 폼                                                  │
│  · 26-카드 매트릭스 + 26 advocate 동시 표시                        │
│  · 4-패널(40인) 동시 투표 + meta-tally 실시간 차트                 │
│  · 5 Engineering Team 칸반 (각 팀 진행률)                          │
│  · OpenAPI Swagger UI 임베드 + 🔒 lock 뱃지                       │
│  · 500점 스코어 게이지(5 카테고리 미니게이지 포함)                  │
│  · "디자인 승인" / "배포 승인" 두 버튼만                           │
└──────────────────────────────────────────────────────────────────┘

3.2 핵심 디자인 원칙 (이 5개로 모든 트레이드오프 결정)

1. 사람의 클릭은 2번 — 디자인 승인 + 배포 승인. 그 외 모든 묻기는 안티패턴
2. 모드 붕괴 방지 — 1개 답이 아니라 26개 카드부터 + 4개 다른 시각의 패널. 다양성은 비싸도 산다 (Anthropic multi-agent 연구: +90.2% 성능, ~15× 토큰)
3. 스펙이 source of truth — 코드 → 스펙이 아니라 스펙 → 코드. nestia/typia로 타입이 곧 스펙
4. 책임 분리(SoR) + 위계 보고선 — 143명이 무작위로 움직이는 게 아니라 모든 agent는 lead가 있고, 모든 lead는 개발총괄 PM(M3)이 있고, M3 위에는 Run Supervisor(M1) + Cost Monitor(M2) — 인간 조직처럼 작동
5. 499/500 = freeze — 자기수정은 무한이 아니라 점수가 멈출 때까지. 점수가 안 오르면 사람에게 에스컬레이션
6. 모든 destructive 행위는 Layer 0이 차단 — software-factory의 7개 비협상 규칙 그대로

3.3 엔지니어링 조직도 — 143 agents · 6-tier 위계

"Specialty Team → Team Lead → 개발총괄 PM(M3) → Run Supervisor(M1)" 보고선이 모든 agent에 적용됩니다.

                                  ┌─────────────────────────┐
                                  │  M1 · Run Supervisor    │  ← 모든 watcher의 watcher
                                  │  (kill switch, escalation)│    pause/resume/abort 권한
                                  └────────────┬────────────┘
                       ┌───────────────────────┼───────────────────────┐
                       │                       │                       │
                       ▼                       ▼                       ▼
              ┌──────────────────┐  ┌──────────────────┐    ┌──────────────────┐
              │  M2 · Cost       │  │  M3 · Chief      │    │ Software-Factory │
              │  Monitor         │  │  Engineer / Dev PM│    │  Layer-0 Hooks   │
              │  (track only,    │  │  (모든 lead 보고선│    │  (PreToolUse 차단)│
              │  no block)       │  │  + cross-team조정)│    │                  │
              └──────────────────┘  └────────┬─────────┘    └──────────────────┘
                                              │
        ┌─────────────────┬─────────────────┬─┴─────────────────┬─────────────────────┐
        │                 │                 │                   │                     │
        ▼                 ▼                 ▼                   ▼                     ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Ideation Dept │ │ 4 Decision    │ │ Spec Dept     │ │ 5 Engineering   │ │ QA Dept         │
│  (29)         │ │ Panels (40+5) │ │  (9)          │ │ Teams (25)      │ │ + SCC + Judges  │
│               │ │ + Mitigation  │ │               │ │                 │ │ + Auditors+Docs │
│ I_LEAD        │ │ Designer (1)  │ │ SPEC_LEAD     │ │ BE_LEAD (6)     │ │ (32)            │
│ ├ I1 Clarifier│ │               │ │ ├ SPEC_AUTHOR │ │ FE_LEAD (6)     │ │                 │
│ ├ I2 Diversity│ │ TP_LEAD (10)  │ │ ├ SC1 Security│ │ DB_LEAD (5)     │ │ QA_LEAD (5)     │
│ └ P01..P26    │ │ BP_LEAD (10)  │ │ ├ SC2 Perf    │ │ DO_LEAD (5)     │ │ SECQA_LEAD (3)  │
│   26 Preview  │ │ UP_LEAD (10)  │ │ ├ SC3 A11y    │ │ SDK_LEAD (3)    │ │ PERFQA_LEAD (3) │
│   Advocates   │ │ RP_LEAD (10)  │ │ ├ SC4 i18n    │ │                 │ │ A11YQA_LEAD (3) │
│   각자 다른   │ │               │ │ ├ SC5 Idemp   │ │ 각 lead가       │ │ SCC_LEAD (5)    │
│   페르소나로  │ │ MD · Mitigation│ │ ├ SC6 ErrModel│ │ M3에 일일       │ │ J1..J5 Judges   │
│   1장씩 작성  │ │   Designer    │ │ └ SC7 APIDsgn │ │ 진행률 보고     │ │ AU1..AU5 Audit  │
│               │ │   (panel      │ │               │ │                 │ │ DOC1..DOC3 Docs │
└───────────────┘ │   dissent →   │ └───────────────┘ └─────────────────┘ └─────────────────┘
                  │   action items)│
                  └───────────────┘

각 Department의 상세 멤버 + 페르소나는 §5 에이전트 카탈로그 참조.

§43-DD Cycles + H1/H2 Gates

파이프라인은 8개 stage가 아니라 3개의 Driven-Development 사이클 + 2개의 Human Gate로 설계됩니다. 각 DD 사이클은 이전 사이클의 산출물을 "잠금"으로 받아 다음 사이클에 인도하는 스테이지 게이트 구조.

① PreviewDD Cycle

Stage 1: 한 줄 아이디어 입력

• 입력: 자연어 1줄 (예: "공방 운영자가 수업·재고·정산을 한 곳에서")
• 옵션(모두 옵셔널): 도메인 힌트, 예산 천장, 타깃 데모 시간(기본 3분)
• 출력: idea.json
• 실패 모드: idea가 너무 짧으면(<10자) brainstorming 모드로 다시 돌려보냄

Stage 2: 26 Preview Advocate 생성 + 시각 mockup

26명의 독립 Preview Advocate(P01~P26)가 각자 다른 페르소나로 1장씩 작성. I_LEAD가 dispatch하고 I2(Diversity Validator)가 사후 Jaccard 검증.

26 페르소나 라이브러리(요약): P01 The Contrarian · P02 Operations Veteran · P03 Speed-Obsessed · P04 Cost-Conscious · P05 Design-Forward · P06 Spreadsheet Jockey(B2B power user) · P07 Mobile-First · P08 Slack-Native · P09 CLI Devotee · P10 Dreamer(5년 후) · P11 Pragmatist(오늘 출시) · P12 Privacy Hawk(E2E) · P13 Data Nerd(분석우선) · P14 Educator · P15 Community Builder · P16 Solo Founder · P17 Enterprise Buyer(SSO/감사) · P18 Designer(visual storytelling) · P19 Embedded(SDK only) · P20 OSS Maintainer · P21 Indie Hacker · P22 Researcher(학술) · P23 Game Designer · P24 Reluctant Adopter(회의적) · P25 AI-Native(LLM 워크플로 중심) · P26 Anti-AI(LLM 노출 0).

각 advocate의 산출물(1 idea → 6 fields):

• framing · target_persona · primary_surface · opus_4_7_capability · mvp_scope — 기존 5-튜플
• mockup.html — 완전 자체완결 단일 HTML 파일: inline <style>만 사용(CDN·외부 fonts·외부 이미지 금지), SVG 아이콘·플레이스홀더 인라인. Opus 4.7의 강화된 vision + HTML/CSS 생성 능력 활용

Mockup 생성 프롬프트 지시: "Your advocate persona shapes the mockup. Mobile-First → phone frame; CLI Devotee → terminal screen; Designer → visual hero; Spreadsheet Jockey → dense data grid. Single self-contained HTML file, inline <style> only, no external CSS/fonts/images/CDN. Use system font stack. SVG placeholders for imagery. Max 500 lines. Must render identically offline."

다양성 vs 일관성: 26개 mockup은 페르소나별로 시각적으로 다르되, 전역 design-token palette(같은 chosen_preview idea 기반)는 공유 → I_LEAD가 OKLCH 기본 팔레트를 prompt에 포함.

다양성 보장: I2가 (target_persona × primary_surface) Jaccard ≥ 0.7 검출 시 해당 advocate에게 재작성 요청. 3회 실패 시 그 advocate skip 보고. Mockup은 추가로 구조 유사도(DOM tree hash) 검증.
비용: 26 advocate × (3K input + 600 pitch + ~3K mockup output) ≈ 170K tokens, Opus 4.7 약 $2.5 (Batch API로 실행 시 $1.25)
데모 비주얼: 26 노드가 동시에 깜빡이며 카드를 발사 → 각 카드가 실시간으로 mockup을 렌더 (Tailwind CDN으로 즉시 visual) → I2가 빨간 X로 중복 표시 → 26 카드 visual grid 완성

Stage 3: 4-패널(40명) + Mitigation Designer — PreviewDD 잠금

v2 변경: 단일 10인 패널 → 4개 전문 패널 동시 운영 + Strategist 4명이 meta-tally. Mitigation Designer(MD)가 dissent를 action item으로 변환.

3-단계 결정 절차:

1. 3a. 사전 컬링: 4개 패널 각자 26→5 추림. 4×10×5 = 200 mentions → 빈도 합산 top-7 본선 진출
2. 3b. 패널별 본선 투표: 4 패널 동시 vote (tally.py 4번 병렬). 패널마다 1개 winner
3. 3c. Meta-tally: 4 winner가 같으면 즉시 채택. 다르면 4 chair(TP/BP/UP/RP_LEAD) + M3 Dev PM 5명이 meta-vote → 다수결. 동률 시 M3가 결정권 (Strategist 역할)

Mitigation Designer (MD): 4 패널의 모든 dissent + Devil's Advocate 의견을 입력으로 → 다음 단계(Spec/Implementation)에 반영할 action item 목록 생성. 예: "RP의 Auth Specialist가 'OAuth 2.1 PKCE 누락' 지적 → SC1 Security Critic의 spec checklist에 추가" → 단순 보고가 아니라 실제 변경으로 이어짐.

출력: chosen_preview.json + panel_meta_tally.md + mitigations.json
비용: 컬링 200K + 본선 80K + meta 30K + MD 20K ≈ 330K, Opus 혼합 ≈ $5
데모 비주얼: 4개 동심원에 10인 아바타 배치 → 각 패널이 동시에 막대 그래프 채움 → 가운데 5명 chair가 합의 → MD가 dissent 카드를 action item 카드로 변환하는 애니메이션

Stage 4: OpenAPI/Swagger 우선 스펙 잠금

출력: specs/openapi.yaml (OpenAPI 3.1) + specs/data-model.prisma + specs/SPEC.md

1. Spec Author 에이전트가 OpenAPI 초안 작성 (Opus 4.7, JSON mode)
2. Spec Critic 에이전트가 정합성 체크 (URL 충돌, 누락 필드, 인증/인가, idempotency, error model)
3. 양쪽 합의될 때까지 evaluator-optimizer 루프 (max 3 iter)
4. 합의된 스펙을 저장 + SHA-256 해시를 specs/.lock에 기록

Lock 의미: 이후 단계에서 spec 변경 시 hash mismatch → 빌드 자동 중단 + 사용자 재승인 요구.
데모 비주얼: Swagger UI가 코드 생성처럼 한 줄씩 차오름 → 마지막에 🔒 Lock 아이콘

🔒 Gate H1 — PreviewDD → SpecDD 전환 (디자인 승인)

상세 플로우는 하단 Gate H1 참조. 여기서 사용자가 mockup을 Claude Design으로 tweak 후 승인 → design-approved.json이 생성되면 SpecDD 사이클 시작.

② SpecDD Cycle

Stage 4: 1 Spec Lead + 1 Author + 7 Specialist Critics

v2 변경: 1 critic → 7 specialist critics 병렬. SPEC_LEAD가 작성/비평 워크플로 조율.

Stage 5: 5 Engineering Teams 풀스택 scaffold — SpecDD 잠금

v2 변경: scaffold-builder 1명 → 5 분야별 팀(Backend/Frontend/Database/DevOps/SDK)이 각자 책임 영역을 병렬로 구현. 각 팀은 lead + 멤버 구조, lead가 M3에 진행률 보고.

generated/<project_id>/
├── apps/api/         ← BE팀 (6명)
├── apps/web/         ← FE팀 (6명)
├── packages/sdk/     ← SDK팀 (3명)
├── specs/            ← Spec Dept 출력 (잠금됨)
├── deploy/           ← DO팀 (5명)
├── prisma/           ← DB팀 (5명)
└── tests/            ← QA Dept 출력 (Stage 6)

팀 간 동기화: M3 Dev PM이 각 팀 lead로부터 standup 형식의 진행률 수집 → 의존성 충돌 발견 시 우선순위 조정 (예: BE2 DTO가 SDK1 generation을 block).
빌드 검증: pnpm install && pnpm -r build && pnpm --filter api exec nestia swagger → openapi-diff. 불일치 시 SPEC_LEAD에게 escalate 또는 SCC_LEAD 자기수정 루프 진입.

③ TestDD Cycle

Stage 6: QA Dept 4팀 + Self-Correction Squad

v2 변경: test-runner 1명 → 4개 QA 팀(Functional/Security/Performance/Accessibility) + 5명 Self-Correction Squad.

Self-Correction Squad (5명):

• SCC_LEAD — 실패 분류 + 디스패치 (spec_violation은 escalate, code_bug는 도메인별 fixer에 라우팅)
• SCC_BE — 백엔드 코드 버그 fixer
• SCC_FE — 프론트엔드 코드 버그 fixer
• SCC_TYPE — TypeScript strict / typia 검증 실패 fixer
• SCC_DEP — 의존성/import/lockfile 충돌 fixer

자기수정 루프 (evaluator-optimizer):

while score < 499 and iter < MAX_ITER (=10):
    run all visible tests + lint + typecheck + nestia-staleness gate
    score = compute_score()
    if score >= 499: break
    diff = critic_agent.analyze(failures, spec, code)
    if diff.requires_spec_change: ESCALATE_TO_HUMAN
    apply_diff_via_managed_agent_bash()
# holdout으로 최종 검증
holdout_score = run_holdout_tests()
if holdout_score < visible_score - 50: FLAG_OVERFIT

Stage 7: 500점 Judge Council + Specialist Auditors — TestDD 잠금 (freeze)

v2 변경: score-judge 1명 → 5인 Judge Council(카테고리당 1명) + 5인 Specialist Auditor(독립 감사). Judge가 점수 매기고, Auditor가 그 점수를 다시 검증.

합격 규칙: ≥499 (Judge 합산) AND 5명 Auditor 모두 PASS = freeze. Judge는 통과해도 Auditor 1명이라도 FAIL이면 재수정. 이 이중 게이트가 "self-judge 편향"을 막음.

freeze 후: Documentation Squad(DOC1 README + DOC2 Changelog + DOC3 Demo Script) 3명이 병렬로 README, CHANGELOG.md, 데모 영상 스크립트 자동 작성.

🔒🚀 Gate H1 + H2 — 사이클 사이 인간 승인 (단 2번)

§5에이전트 카탈로그 (전문가 에이전트 구조)

5.1 143개 에이전트 — 부서별 카탈로그

모든 agent는 (이름) · (모델) · (보고선) · (allowed_scope) 4-튜플을 가집니다. 143개 전부 Claude Opus 4.7 (claude-opus-4-7) 전용 — Built with Opus 4.7 해카톤 부상 카테고리 정합. 비용은 prompt caching 1h TTL + Batch API + context editing(context-management-2025-06-27)로 최적화.

Tier 1 · Meta (3 agents)

Tier 2 · Ideation Department (29 agents)

Tier 3 · 4-Panel Decision Department (44 agents) + Mitigation Designer (1)

각 패널은 lead 1 + 멤버 10. 모든 lead는 M3에 보고. decision-panel 스킬의 페르소나 라이브러리를 4개 도메인에 매핑.

Tier 4 · Spec Department (9 agents)

Tier 5 · 5 Engineering Teams (25 agents)

Implementation Team들은 모두 Layer B (Managed Agents) 세션 내부에서 실행. 빌드·테스트가 hours 단위 long-running이어도 OK.

Tier 5 · QA Department (14 agents)

Tier 5 · Self-Correction Squad (5 agents)

Tier 5 · Judge Council (5 agents) + Specialist Auditors (5 agents)

Tier 5 · Documentation Squad (3 agents)

5.2 핵심 에이전트 컨트랙트 (대표 5개 발췌)

아래 5개는 대표 컨트랙트. 나머지 138개는 동일 schema(name/inputs/outputs/preconditions/postconditions/allowed_scope/forbidden/fail_modes)로 정의되며 Day 1–2에 YAML 파일로 일괄 commit 예정.

A1 · preview-generator

name: preview-generator
inputs:
  - idea (string, 10-280 chars)
  - domain_hint (optional)
  - budget_cap_usd (optional)
outputs:
  - previews.json (array of 26 PreviewCard objects)
  - cost_report.json
preconditions:
  - idea.length >= 10
postconditions:
  - len(previews) == 26
  - no duplicate (target_persona, primary_surface) pairs
  - each card has all 5 tuple fields non-empty
fail_modes:
  - dedup retry (1회) → 그래도 중복 → user_escalate
  - JSON parse fail → 1회 재시도, 실패 시 abort
allowed_scope:
  - read: idea.json
  - write: previews.json, cost_report.json
forbidden:
  - any network call to non-anthropic endpoints
  - file writes outside generated/<project_id>/

A12 · spec-author

name: spec-author
inputs:
  - chosen_preview.json
  - panel_report.md (mitigations 추출용)
outputs:
  - specs/openapi.yaml (OpenAPI 3.1)
  - specs/data-model.prisma
  - specs/SPEC.md
constraints:
  - 모든 write endpoint는 Idempotency-Key 헤더 + 4xx 정의 포함
  - 통화 필드는 BIGINT (KRW/USD-cents)
  - 인증은 chosen_preview.target_persona에 맞춰 (B2B → API key, B2C → OAuth)
  - 에러 응답은 RFC 7807 problem+json
postconditions:
  - openapi.yaml은 spectral default ruleset 통과
  - prisma schema는 prisma format 통과
fail_modes:
  - critic이 3회 reject → ESCALATE_TO_HUMAN

A14 · scaffold-builder

name: scaffold-builder
runs_in: Managed Agents session (long-running, ~10-20min)
inputs:
  - specs/openapi.yaml
  - specs/data-model.prisma
  - nestia-solo-fullstack assets/* templates
outputs:
  - generated/<project_id>/{apps,packages,deploy,prisma,tests}
  - build_log.txt
allowed_scope:
  - read/write: generated/<project_id>/**
  - bash: pnpm, node, docker (build only — never push, never deploy)
forbidden:
  - any bash matching software-factory pre-bash-irreversible-check.sh patterns
  - any edit to ~/.claude/, /etc/, $HOME outside cwd
checkpoints:
  - after pnpm install: smoke check (pnpm -v)
  - after nestia sdk: hash specs/swagger.json, compare with openapi.yaml
  - after build: dump bundle sizes
on_failure:
  - retry once with verbose log
  - if still fail: hand off to self-correction-critic with full log

A16 · self-correction-critic

name: self-correction-critic
loop:
  while score < 499 and iter < 10:
    1. fetch latest test/lint/build/typecheck failures
    2. classify failure type:
       - spec_violation → STOP (cannot fix code without changing spec)
       - test_flake → quarantine + log
       - code_bug → propose minimal diff
       - dep_missing → propose pnpm add command
    3. apply diff via Managed Agents bash/edit tools
    4. re-run score-judge
forbidden:
  - cannot modify specs/openapi.yaml (locked)
  - cannot modify tests/.holdout/* (overfit prevention)
  - cannot delete tests to make build pass (anti-pattern, hard-blocked)
escalation:
  - score plateau (3 iter no improvement) → human
  - any spec_violation → human
  - iter >= 10 → human with full trace

A17 · score-judge

category_1_spec_conformance:
  - openapi-diff specs/openapi.yaml apps/api/specs/swagger.json
  - score = 100 - (delta_count * 5), floor 0
category_2_tests_types:
  - vitest run --reporter=json (visible)
  - vitest run tests/.holdout --reporter=json
  - tsc --noEmit
  - score = (visible_pass + holdout_pass + tsc_clean ? 100 : 0)
category_3_security:
  - npm audit --audit-level=critical
  - secretlint .
  - software-factory blocked_actions audit (no violation in build_log)
category_4_build_bundle:
  - pnpm -r build
  - next bundle analyzer JSON
  - docker build --no-cache size check
category_5_demo_readiness:
  - docker compose up -d, wait 60s
  - curl /health == 200
  - playwright capture screenshot of seeded /
outputs:
  - score/report.json (per-category breakdown)
  - score/total.txt (single number)
  - score/badges.svg (for README)

5.3 통신 프로토콜 — Hierarchical + Blackboard Hybrid

v2는 순수 위계. v3는 보고선은 위계로, 정보 공유는 Blackboard로 hybrid. arxiv 2510.01285 — "blackboard가 AutoGen·Data Interpreter보다 적은 토큰으로 더 높은 성능".

• Hierarchical 보고선: Layer A 내부 병렬 subagent invocation (예: 4 패널 × 11명 = 44 동시 호출), lead가 tally.py로 집계 → M3에 보고
• Blackboard (SQLite): runs/<id>/blackboard.db — 모든 agent가 read/write 가능한 공유 테이블. schema: (ts, agent_id, key, value, tier, dept). 예: BE팀이 key="orm.adapter" value="prisma" 기록 → DB팀이 바로 보고 schema.prisma 대응
• Layer A → Layer B: Managed Agents events.send → SSE. 단 Blackboard 이벤트도 SSE로 브로드캐스트
• Layer B → Layer C: MA 이벤트 + Blackboard tail을 WebSocket으로 UI에 fan-out
• Layer C → Layer A: 사용자 AskUserQuestion 응답 → REST POST → M1/M3가 해당 agent에 전달

5.4 Memory Architecture — Full 4-layer (실수반복 방지)

social-seeding-platform 패턴 차용 + Anthropic Memory Tool + Reflexion을 결합한 4-layer 메모리. 새 run 시작 전 M1 Run Supervisor가 반드시 참조하여 모든 lead에게 프리로드.

새 run 시작 시퀀스 (M1 Run Supervisor가 enforce):

1. /pf:new "아이디어" 호출
2. M1이 memory/CLAUDE.md 읽음 → session rules 적재
3. M1이 memory/PROGRESS.md 읽음 → 직전 run 상태 확인 (resume 가능 여부)
4. M1이 memory/LESSONS.md 읽음 → 모든 dept lead에게 "이번 run에서 절대 피할 것" 프리로드
5. M1이 Memory Tool view /memories/agents → 과거 agent episodic 검색, 관련된 것만 해당 agent에 주입
6. Ideation Dept 활성화, 본격 실행 시작

Auto-retro (run 종료 시): M3 Dev PM이 자동으로 Reflexion critic에 다음 3개 질문:

1. "이 run에서 작동한 패턴 중 재사용할 것?" → CLAUDE.md의 "작동 패턴" 섹션 append
2. "이 run에서 실패한 패턴 중 다시 겪지 말아야 할 것?" → LESSONS.md append (문제 → 원인 → 해결)
3. "이 run에서 발견된 새 규칙?" → CLAUDE.md의 "절대 규칙" 섹션 append

각 answer는 M3가 검토 후 memory/에 commit. 사람 개입 없이 자가학습 루프 완성 — Anthropic 자체 보고(+39% on multi-step tasks with Memory Tool + context editing).

5.5 AskUserQuestion Layer-0 Enforcement

plugin의 hooks/hooks.json에 PreToolUse 훅을 등록하여 사용자 질문을 통제합니다.

hook 예시 (hooks/hooks.json):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/factory-policy.py" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Agent",
        "hooks": [{ "type": "command", "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/askuser-enforcement.py" }]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/auto-retro-trigger.py" }]
      }
    ]
  }
}

5.6 Deterministic Replay — trace.jsonl

모든 agent 호출·응답·Blackboard write·Memory read/write가 runs/<id>/trace.jsonl에 append. schema: {ts, agent_id, event_type, input_hash, output_hash, tokens, duration_ms, error?}. 전체 run을 오프라인에서 재생 가능 → (a) 버그 재현 (b) 데모 영상에서 "왔었던 그 순간" 재생 (c) LESSON 생성 시 증거로 첨부.

5.7 Adaptive Thinking + Task Budgets + Effort

Claude Opus 4.7의 thinking 모드는 Adaptive만 지원 (extended thinking budgets 제거됨). 기본 off, 의사결정 agent에서 thinking: {type: "adaptive", display: "summarized"} 명시 활성화. Effort는 에이전트 역할별로 차등:

Task Budgets beta(task-budgets-2026-03-13): agentic loop 전체(thinking + tool + output)에 advisory cap 제공. 모델이 countdown을 보며 graceful finish. max_tokens는 128K(하드캡), task_budget은 역할별 advisory.

5.8 Opus 4.7 + 컨텍스트 엔지니어링 통합 매트릭스

Claude Opus 4.7 + 2025-09 ~ 2026-04 출시된 모든 컨텍스트 기능을 본 시스템에서 어떻게 활용하는지 전수 매핑. Anthropic 내부 벤치마크: memory + context editing 결합 시 복잡한 multi-step task에서 +39% 성능.

5.9 M1 Run Supervisor의 컨텍스트 관리 프로토콜

M1은 단일 세션으로 run 전체(수 시간)를 운영. 아래 스택을 조합:

context_management = {
  "edits": [
    { "type": "clear_tool_uses_20250919",
      "trigger": {"type": "input_tokens", "value": 30000},
      "keep": {"type": "tool_uses", "value": 6},
      "clear_at_least": {"type": "input_tokens", "value": 10000},
      "exclude_tools": ["memory"] },
    { "type": "clear_thinking_20251015",
      "trigger": {"type": "input_tokens", "value": 80000} },
    { "type": "compact_20260112",
      "trigger": {"type": "input_tokens", "value": 600000},
      "instructions": "Preserve exactly: chosen_preview.5-tuple, specs/openapi.yaml SHA-256, panel_meta_tally winner, current freeze score, any LESSON appended this run." }
  ]
}

tools = [
  {"type": "memory_20250818", "name": "memory"},  # /memories 핸들러
  {"type": "web_search_20250305", "name": "web_search"},  # optional
  # Agent SDK Task tool로 143 subagent 호출
]

betas = [
  "context-management-2025-06-27",
  "compact-2026-01-12",
  "task-budgets-2026-03-13",
  "managed-agents-2026-04-01"
]

# System prompt · CLAUDE.md · LESSONS.md · methodology/global.md
# 전부 cache_control ttl="1h"로 캐싱
system = [
  {"type": "text", "text": LAYER_0_RULES,
   "cache_control": {"type": "ephemeral", "ttl": "1h"}},
  {"type": "text", "text": CLAUDE_MD + LESSONS_MD,
   "cache_control": {"type": "ephemeral", "ttl": "1h"}},
]

이 한 세션이 run 종료까지 이어지며, Blackboard·Memory Tool·Context Editing·Compaction이 협력하여 1M context window 안에서 무한 가까운 작업이 가능.

§6기술 스택 + Opus 4.7 사용 매트릭스

6.1 핵심 의존성 (모두 OSS-safe)

6.2 Opus 4.7 사용 매트릭스 (Most Creative 부상 조준)

데모 영상 메시지: "Opus 4.7을 143명의 인격으로 동시에 돌리고, 다섯 명이 채점하고, 다섯 명이 그 채점을 다시 감사하고, 사람한테는 두 번만 묻는다."

6.3 비용 추정 (e2e 1회당, soft cap)

참고: 143 agent 전부 Opus 4.7. Prompt caching 1h TTL("cache_control": {"type": "ephemeral", "ttl": "1h"}) 적용으로 cache read는 base의 10%, write는 100% 추가. 143 agent system prompt·LESSONS.md·CLAUDE.md 모두 caching 대상이므로 실 지출은 표의 50–70% 수준. Batch API(DOC squad, LESSONS 추출 등 비실시간)로 추가 50% 절감.

§7로컬 빌드 + 데모 워크플로우

7.1 디렉토리 구조 (저장소 루트)

PreviewForgeForClaudeCode/
├── README.md                       # 설치·사용·라이선스
├── LICENSE                         # Apache-2.0
├── package.json                    # workspace root
├── pnpm-workspace.yaml
├── apps/
│   ├── orchestrator/               # Layer A
│   │   ├── src/
│   │   │   ├── cli.ts              # `pnpx preview-forge "<idea>"`
│   │   │   ├── server.ts           # Next.js API (UI ↔ orchestrator)
│   │   │   ├── stages/             # stage-1.ts ~ stage-8.ts
│   │   │   ├── agents/             # A1~A17 정의
│   │   │   └── managed/            # Managed Agents 세션 관리
│   │   └── package.json
│   └── dashboard/                  # Layer C (Next.js 14)
│       ├── app/
│       │   ├── page.tsx            # 한 줄 입력
│       │   ├── run/[id]/page.tsx   # 26 카드 + 패널 + 점수
│       │   └── api/
│       └── package.json
├── packages/
│   ├── core/                       # 공유 타입
│   ├── score-judge/                # Stage 7 채점 라이브러리
│   └── spec-locker/                # Stage 4 OpenAPI 도구
├── runs/                           # 실행 결과물
│   └── <run_id>/
│       ├── idea.json
│       ├── previews.json
│       ├── panel_report.md
│       ├── chosen_preview.json
│       ├── specs/
│       ├── generated/              # 생성된 풀스택 앱
│       ├── score/
│       └── trace.jsonl
├── claudedocs/                     # 본 제안서, 의사결정 기록
└── scripts/
    ├── demo-record.sh
    └── seed-demo-idea.sh

7.2 사용자가 칠 명령 — Plugin 설치

## ─── 1회 설치 (3줄) ───
/plugin marketplace add Two-Weeks-Team/PreviewForgeForClaudeCode
/plugin install preview-forge
/pf:bootstrap   ## memory/CLAUDE.md + LESSONS.md + PROGRESS.md 초기화

## ─── 환경 ───
## Claude Code의 Pro/Max 인증을 그대로 사용 (별도 API 키·.env 불필요)

## ─── 실행 ───
## 대화형 (권장, 데모 영상용)
/pf:new "공방 운영자가 수업·재고·정산을 한 곳에서"
## → 브라우저가 http://localhost:3000/run/<id> 로 자동 열림
## → 143 agent live 시각화
## → 2개 AskUserQuestion (디자인, 배포)에만 답하면 됨

## CLI (헤드리스 배치)
pf "한 줄 아이디어"
## → runs/<id>/ 산출물 + 콘솔 진행률

## ─── 관리 ───
/pf:status              ## 현재 run 상태
/pf:replay <run_id>     ## trace.jsonl 재생
/pf:lessons             ## 쌓인 LESSONS 확인·편집
/pf:budget              ## 토큰 소비 현황
/pf:gallery             ## 과거 run 목록 + fork
/pf:export <run_id>     ## freeze된 앱을 tarball 또는 별도 plugin으로 export

## 4) 산출물 확인
ls runs/<id>/generated/
cd runs/<id>/generated && docker compose up -d
curl http://localhost:18080/health

7.3 3분 데모 영상 스토리보드

§84일 실행 일정 (4/22 PM ~ 4/26 20:00 EST)

현재 시각 기준 가용 ~115h, 수면·식사·세션 제외 실가용 ~50–60h.

Day 1 — 4/22(수) PM (KST) / AM-PM (EST)

• 🎯 12:00 EST Thariq Shihipar AMA 참석 (Claude Code 베스트프랙티스)
• 🛠 저장소 초기화: marketplace repo 스캐폴드(.claude-plugin/marketplace.json + plugins/preview-forge/) + Apache-2.0 LICENSE + NOTICE
• 🛠 Plugin manifest + memory/{CLAUDE,PROGRESS,LESSONS}.md seed
• 🛠 M1/M2/M3 Meta Layer 3 agents + hooks/askuser-enforcement.py + hooks/factory-policy.py
• 🛠 Ideation Department(29 agents) + /pf:new slash command — 26 카드 JSON 생성까지

Day 2 — 4/23(목)

• 🎯 11:00 EST Michael Cohen — Managed Agents 세션 필참 (부상 카테고리 핵심)
• 🛠 Stage 3: decision-panel 통합 + 26→5 컬링 + 본선 다수결
• 🛠 Stage 4: spec-author + spec-critic evaluator-optimizer 루프
• 🛠 Layer C: Next.js 대시보드 골격 + 한 줄 입력 + 26 카드 (frontend-design 활용)

Day 3 — 4/24(금)

• 🎯 12:00 EST Mike Brown(전년 1위) 세션 — 데모 영상 팁
• 🛠 Stage 5: Managed Agents 통합 + nestia-solo-fullstack assets로 scaffold-builder
• 🛠 Stage 6: test-runner + self-correction-critic + holdout 분리
• 🛠 Stage 7: score-judge 5개 카테고리 측정 스크립트
• 🧪 첫 e2e smoke run: "todo app" 한 줄로 freeze까지

Day 4 — 4/25(토)

• 🛠 Stage 8: 두 게이트 UI + 승인 후 자동 다음 단계
• 🛠 Layer C 폴리싱: 패널 투표 애니메이션, 점수 게이지, Swagger UI 임베드, Framer Motion
• 🧪 두 번째 e2e: 데모용 진짜 아이디어로
• 🛠 software-factory 훅 통합 검증

Day 5 — 4/26(일)

• AM (KST): 최종 e2e 3회 — 전부 freeze 도달해야 함
• PM (KST) / AM (EST): 데모 영상 녹화 (OBS, 5–10 take)
• 영상 편집 + YouTube unlisted 업로드
• README 마무리 + 100–200자 written summary
• 20:00 EST 제출 폼 입력

§9심사 루브릭 매핑 (자기 평가)

9.1 부상 카테고리 정렬

• Best Managed Agents ($5k): Stage 5–6의 long-running build/test/correct가 정확히 hours-OK async task. 강한 후보
• Most Creative Opus 4.7 ($5k): 11개 페르소나 + evaluator-optimizer + 자기 채점은 "표현 매체로서의 Opus" 정의에 부합. 강한 후보
• Keep Thinking ($5k): PreviewDD 신설 자체가 pitch — "SpecDD와 TDD만으로는 under-specified idea 문제 해결 불가, 그 앞에 다양성 cycle 추가 필요"라는 방법론적 주장. Anthropic 심사위원이 "아무도 여기 Claude를 가리키지 않았다"고 인정할 수 있는 지점. 강한 후보

§10리스크 및 미티게이션

§11베스트 프랙티스 적용 체크리스트 (조사 결과)

11.1 Anthropic 공식 패턴 — Building Effective Agents

• ✅ Parallelization (sectioning): 10 패널리스트 병렬 호출
• ✅ Parallelization (voting): 패널 majority vote
• ✅ Orchestrator-Workers: Layer A가 A12~A17을 동적 dispatch
• ✅ Evaluator-Optimizer: spec-author ↔ spec-critic, code ↔ self-correction-critic
• ✅ Prompt Chaining (with gates): Stage 1→8 결정 게이트
• ✅ Routing: chosen_preview의 primary_surface에 따라 scaffold 템플릿 분기

11.2 Anthropic 멀티에이전트 연구

• ✅ Detailed task descriptions: 에이전트별 컨트랙트 (allowed_scope, fail_modes, postconditions)
• ✅ Scaling rules: 패널 = 10, 프리뷰 = 26, self-correction max_iter = 10
• ✅ Tool selection heuristics: Layer 분리 — brain은 도구 없음, hands만 bash/file
• ✅ Extended thinking: spec-author + self-correction-critic 사용
• ✅ Token budget 인지: 단계별 예산 cap

11.3 Managed Agents 베스트 프랙티스

• ✅ Beta header managed-agents-2026-04-01 자동 (SDK 처리)
• ✅ Agent ID는 1회 생성 후 재사용 (세션마다 재생성 X)
• ✅ Environment ID는 1회 생성 후 재사용
• ✅ Session은 task당 1개 (cleanup 명시)
• ✅ SSE 스트림은 events.send 후 attach (quickstart 패턴)
• ✅ session.status_idle 이벤트로 종료 감지

11.4 Spec-Driven Development (GitHub Spec Kit 영향)

• ✅ Specify → Plan → Tasks → Implement 5-phase 정신 압축 (Stage 4 = Specify, Stage 5 = Plan/Tasks, Stage 6 = Implement)
• ✅ 사양이 실행가능 — OpenAPI에서 SDK·Swagger·Validators 자동 생성 (nestia)

11.5 멀티에이전트 GitHub 사례 (참고·차별화)

차용한 패턴: orchestrator/worker, parallel agents. 차별점: spec-lock + 점수판 + HITL 2-touch + LESSONS 자가학습 + Plugin 단일 설치.

11.6 Reflexion / Memory / Blackboard

• ✅ Reflexion (NeurIPS 2023) — 각 agent task 종료 후 verbal self-reflection을 /memories/agents/<id>/reflection.md에 기록. 다음 task에서 동일 agent가 자기 reflection부터 읽음
• ✅ Anthropic Memory Tool (memory_20250818) — 공식 client-side memory API. /memories 하위에서 view/create/str_replace/insert/delete/rename. +39% 성능 on multi-step (Anthropic 자체 보고)
• ✅ Multi-session software development pattern (Anthropic 공식 권장) — initializer 세션 + progress log + session bootstrap. 우리의 /pf:bootstrap + PROGRESS.md + LESSONS.md가 정확히 이 패턴
• ✅ Blackboard Architecture (arxiv 2510.01285) — 중앙 agent가 shared blackboard에 요청을 post, 워커가 volunteer. 위계와 혼합하여 cross-team 정보 전파
• ✅ social-seeding-platform LESSONS.md 패턴 차용 — 10+ 카테고리 실패 카탈로그. "새 세션에서 반드시 참조하여 반복 실수 방지"

11.7 Plugin 패키징 베스트 프랙티스

• ✅ 자기완결(Self-contained): 외부 스킬 의존 제거, 모든 agents/hooks/skills plugin 내부
• ✅ Semver 버전: plugin.json의 version 필드, 0.1.0부터
• ✅ Namespacing: /pf:* 로 통일, 다른 plugin과 충돌 방지
• ✅ 설치 3줄: marketplace add → install → bootstrap
• ✅ 비파괴: 사용자 기존 설정·.env·다른 plugin 건드리지 않음
• ✅ Optional deps lazy-install: Playwright, axe-core 등은 사용 시점에 pnpm dlx