Code the Origin, Forge the App. 给 Claude Code 装一支有流程治理的 AI 开发团队——不是更聪明的单 agent，是 19 角色按阶段门协作、流程靠机制兜底而非 agent 自觉。
简体中文 · English
↑ 一句话提需求 → AI 团队并行交付 → 看板实时点亮，全程一个终端 tab。
单个 AI agent 一把梭，长流程会失控——没人审、没人测，说「完成了」其实没跑通。AGF 不赌「更强的模型」，而是把 AI 当一支需要流程约束的团队来管。
AppGenesisForge（AGF） 是基于 Claude Code Agent Teams 的 AI 团队脚手架：装进你的项目，product-lead 带 18 个 AI 同事按「需求 → 实现 → 审查 → 部署 → 测试 → 签字」的阶段门交付——流程不靠 agent 自觉，靠三层机制兜底：skill 强制 + hook 硬阻断 + DoD 清单。落到实处就是：失败不跳级、说「完成」必须附证据、reviewer 不改自己审的码、QA 不签自己的业务字。
- ✅ 适合：Web 全栈（默认 React + FastAPI + Postgres，可换栈）· AI Agent / RAG / 多模态 · 微信小程序 · Apple 原生（macOS 桌面 / iOS）
- ❌ 不适合：Android 原生 · Windows / Linux 桌面 · 大模型训练
目标：5 分钟从零到看见一支 AI 团队在你项目里真的协作起来——不是读文档，是跑起来。（feature 越小越快；完整交付含 review / UAT 的时间随 feature 大小，但"看到团队动起来"5 分钟够。）
前置：Claude Code ≥ v2.1.154 · git · macOS / Linux ·（分屏显示需 iTerm2 + it2，无则改 tmux，见末尾）
① 装（~2 分钟）
git clone https://github.com/pcliangx/AppGenesisForge.git
cd AppGenesisForge
bash setup/agf-install.sh交互式 TUI：选目标目录（新项目 / 已有仓库都行，不存在自动 mkdir + git init）→ 选角色裁剪 → 确认。完成页一键进入下一步。
② 初始化 + 复核技术栈（~1 分钟，在目标项目里）
/agf-init
Claude 接管：体检 + 合并 CLAUDE.md + 据你项目真实技术栈写 ADR-000 + 建 label。
⚠️ 唯一必做的人工关：打开docs/adr/000-system-architecture.md核对语言 / 框架 / DB 是不是你项目真的——这是防 AI 编技术栈的最后一道关。
③ 派第一个 feature（团队启动）
/agf-team-start 加一个健康检查接口 GET /health 返回 {"status":"ok"}
（示例，按你的栈换。）product-lead 起变更文件夹 → 派 backend-dev 实现 → reviewer 审 → …… 分屏里多个 AI 同事并行干活。
④ 开实时看板盯进度（另开一个 tab）
/agf-board --watch
然后 open progress/board.html——task 卡片三列流转、阶段门逐个点亮，≈3 秒刷新，实时看团队推进（首屏那张图就是它）。
⑤ 验收签字
走完 SIT → code review → UAT，product-lead 来找你签字。签了就交付——你的第一个 feature 由一支有流程治理的 AI 团队跑完。
升级 / 无 TTY 非交互 / 卡分屏
- 升级：已装 AGF 的项目重跑
bash setup/agf-install.sh进升级模式（旧版 → 新版，可选刷新 docs，旧文件自动备份；永不覆盖你的CLAUDE.md/ADR-000/settings.json）。 - 非交互（CI / 无 TTY）：
bash setup/install-to-existing.sh ~/path/to/your-repo # 升级加 --refresh-docs cd ~/path/to/your-repo bash setup/customize.sh --preset minimal --yes # 可选：去小程序角色 bash setup/init-team.sh # Day-1 体检
- 卡分屏：把
.claude/settings.json的teammateMode从"iterm2"改"tmux"或"auto"，无it2也能跑（非 iTerm2 自动降级 in-process，不影响功能）。
完整 Day-1 复核清单 + 前置知识 + 常见踩坑 →
docs/FIRST_RUN.md。
| 能力 | 一句话 |
|---|---|
| 19 个 AI 同事 | PO+SM（product-lead）统一编排；开发 / 评审 / QA / 部署职责互锁——Reviewer 不改源码、QA 不签业务字、dev 自跑 Unit + SIT |
| 7 道阶段门 | 变更文件夹（OpenSpec 风格需求入口，取代 PRD）→ 派单 → TDD 实现+SIT → Code Review（含 SIT Audit）→ UAT 部署 → E2E → UAT 签字；失败不跳级，一律回实现层重做（Apple 轨用「签名分发包发布门」替代 UAT 部署门）。按规模分 full / fast lane——小改（Small+PATCH+非高风险）走轻量尾部（仍部署+冒烟+P0），高风险一律全门 |
| TDD 强制 | red → green → refactor 写进 DoD，commit 历史可查（test 先于 impl）；跳过会被 review 打回 |
| UAT 用例先行 | UAT 用例文档（每条 AC ≥1 用例、6 字段）dev 期并行起草、审批移出关键路径，用户审核确认后才开测；P0 用例连续 2 次通过才放行 |
| 4 层安全 hook | 危险命令硬阻断（rm -rf / DROP TABLE / curl|sh…）· 11 厂商密钥扫描 · prompt-injection 告警 · commit 前 diff 再扫 |
| 并行可控 | 同类任务 ≥2 自动 fan-out 多实例（dev / reviewer / qa 池），agf-matrix.sh 一张表 fan-in；另有 /agf-understand、/agf-review-sweep 两个多 agent Workflow |
| 实时看板 | /agf-board --watch 生成自包含 HTML 看板——每个 task 一张卡片，完成自动标 ✓，阶段门 chips 同步点亮；零 server 零依赖，浏览器开着即可盯进度 |
| 前后端契约同步 | 后端 OpenAPI 为单一契约源，前端 orval 生成类型 / hooks / mock——"按钮点了没反应、字段对不上"在编译期就炸 |
| 国产生态 | DeepSeek / Doubao / Qwen / MiniMax 多 LLM 切换 skill · 微信小程序专属三角色（原生优先，Taro 兜底） |
| Apple 原生轨 | macOS / iOS 用 Swift 6 + SwiftUI；apple-* 四角色镜像小程序三件套 + 独立签名身份；swift-openapi-generator 契约同步 · fastlane + notarytool 四渠道发布 |
flowchart LR
U([👤 需求]) --> S1["变更文件夹<br/>brainstorming 澄清"]
S1 --> S2["派单<br/>AC 摘录 + worktree 隔离"]
S2 --> S3["TDD 实现<br/>Unit + SIT 自跑"]
S3 --> S4["Code Review<br/>+ SIT 证据审计"]
S4 --> S5["UAT 部署<br/>隔离栈 + 冒烟"]
S5 --> S6["E2E<br/>真浏览器控件遍历"]
S6 --> S7["UAT<br/>用例文档经你审核"]
S7 --> D([🎁 签字交付])
S4 -.打回.-> S3
S6 -.打回.-> S3
S7 -.打回.-> S3
style U fill:#3b82f6,color:#fff
style S7 fill:#f97316,color:#fff
style D fill:#22c55e,color:#fff
团队跑起来后，一行命令开实时看板——task 卡片三列流转，teammate 每次更新 ≈3 秒上板：
/agf-board --watch # 然后 open progress/board.html
19 个同事（完整职责 / 模型 / 工具见 team-roles.md）：
- 🟠 编排：
product-lead（PO+SM，唯一签字人）· 🔵 顾问：tech-lead（选型 / ADR / 架构风险才介入） - 🟢 执行：
frontend-devbackend-devai-agent-devml-engineeruiux-designerminiapp-dev· 🍎apple-dev（Swift / SwiftUI，macOS+iOS） - 🟡 评审：
code-reviewerminiapp-code-reviewerapple-code-reviewer（review-only，verdict 必从 frontmatter 原子事实推导【code / SIT / QA】+ hook 守门，ADR-010） - 🔴 测试：
qa-engineerminiapp-qa-engineerapple-qa-engineer（E2E / UAT 执行，无证据不给 Pass） - 🩶 部署/发布：
deploy-engineer（隔离 UAT 栈）·apple-release-engineer（签名公证 + 四渠道分发包）· 🟪 上线后：content-writergrowth-analyst
| 你想 | 看这里 |
|---|---|
| Day-1 上手 + 踩坑速查 | docs/FIRST_RUN.md |
| 端到端全景图（角色 × 阶段 × hook × skill） | docs/team-capability-map.md |
| 交付工作流 + 全部术语 | docs/product-workflow.md |
| 一个真实 feature 的全套产物（需求 → Retro） | docs/training/samples/postcard-feature/ |
| 团队规范（工作流 / 测试 / 安全 / 版本…） | .claude/standards/ |
| 架构决策记录（Pool / Workflow / 契约同步…） | docs/adr/ |
| 每个版本改了什么 | CHANGELOG.md |
MIT — 自由商用。结构灵感参考 The Agency。
19 个 AI 同事 · 7 道阶段门 · 机制兜底而非 agent 自觉
⭐ Star · 🐛 Issue · 📒 CHANGELOG · 🇬🇧 English