App Genesis Forge
Code the Origin, Forge the App. 给 Claude Code 装一支有流程治理的 AI 开发团队——不是更聪明的单 agent，更像一条精益产线：19 角色分工协作、层层把关，缺陷流不进下一道工序。
简体中文 · 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 分钟跑通第一个 feature
目标：5 分钟从零到看见一支 AI 团队在你项目里真的协作起来——不是读文档，是跑起来。（feature 越小越快；完整交付含 review / UAT 的时间随 feature 大小，但"看到团队动起来"5 分钟够。）
前置：Claude Code ≥ v2.1.154 · git · macOS / Linux ·（分屏显示可选：teammateMode 默认 "auto"——iTerm2 / tmux 会话自动分屏，其余终端 in-process，不影响功能）
① 装（~2 分钟）
git clone https://github.com/pcliangx/AppGenesisForge.git
cd AppGenesisForge
bash setup/agf-install.sh # 交互式 TUI（在 AGF 仓库根运行）：选目标目录 / 版本 / preset，摘要确认后一键装完
TUI 六步（预检 → 版本选择 → 目标目录 → preset → 摘要确认 → 执行 + Day-1 体检）编排底层非交互脚本，摘要确认前零写盘、自动备份你已有的 .claude/ 与 CLAUDE.md（永不覆盖）。preset（web-only/minimal/miniapp-only/full，推荐默认 web-only）就地选好，无需再单独跑 customize.sh；装完直接回车可拉起下一步 /agf-init。无 TTY（CI / 管道）自动降级为打印等价非交互命令，见下方折叠块。
② 初始化 + 复核技术栈（~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 团队跑完。
- 非交互 / CI 等价：
agf-install.sh是交互壳，底层是这三个非交互脚本，CI / 无 TTY 环境可直接调用（TUI 遇非 TTY 也会自动降级打印这条等价命令）：
可选 flag：bash setup/install-to-existing.sh ~/path/to/your-repo # 目标须是 git 仓；新项目先 mkdir + git init bash setup/customize.sh --preset web-only --yes # 角色裁剪：纯 Web 项目去 Apple + 小程序轨（19→12 角色） bash setup/init-team.sh # Day-1 体检--with-office-skills（装 docx/pptx 报告技能组）。 - 升级：已装 AGF 的项目重跑
bash setup/install-to-existing.sh ~/path/to/your-repo --refresh-docs（旧版 → 新版，旧文件自动备份；永不覆盖你的CLAUDE.md/ADR-000/settings.json）。 - 卡分屏：模板默认
teammateMode: "auto"——iTerm2 / tmux 会话自动分屏、其余终端静默 in-process，不影响功能，无需配置。想强制 iTerm2 分屏 fail-loud 才在用户级~/.claude/settings.json设"iterm2"（需pip install it2+ iTerm2 Python API，缺it2会显式报错）。
完整 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 再扫 |
| 治理自审（诚实层） | 模板机器校验「文档声称 ↔ 现实」——注册的 hook 必有脚本、CLAUDE.md 点名的脚本必存在、permissions.deny 被悄悄改小即硬阻断；配 known-limitations.md（各 gate 真实强度 + 证据三态诚实 SSOT）。对标 claude-code-harness，杜绝「文档写了、实际没接」（ADR-023） |
| 并行可控 | 同类任务 ≥2 自动 fan-out 多实例（dev / reviewer / qa 池），agf-matrix.sh 一张表 fan-in；另有 /agf-code-map（codemap 代码理解引擎 + orphans 报「写了没接线」的模块，ADR-021 / 024） |
| 实时看板 | /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 四渠道发布 |
| 反 AI 味审美 | 设计纪律层（ADR-013）：uiux-designer 产出前给 Design Read + 三刻度，守 AI Tells 黑名单（紫渐变 / 三等分卡 / emoji icon / 假数据 / Inter 默认 / 纯黑白）；产品 UI motion 守红线（禁 scroll-hijack / GSAP）；agf-design-precheck.sh 机筛 + reviewer 人审 |
🖥️ 交互式安装器（TUI）
bash setup/agf-install.sh 是装 AGF 的交互入口：ANSI 封面 + 方向键选「版本 / 目标目录 / preset」，摘要确认前零写盘、q/Esc 随时零副作用退出，装完自动接管 /agf-init。它是薄 wrapper——只编排底层非交互脚本（install-to-existing.sh → customize.sh → init-team.sh），CI / 无 TTY 下自动降级为打印等价命令 + exit 2；test-install.sh 两条护栏（TUI preset 列表 ↔ customize.sh 一致 + 非 TTY 降级）机械锁死「壳」与「核」不漂移（ADR-027）。
🔄 怎么工作
需求进、签字出，一条产线走到底；虚线是打回——缺陷退回实现工序重做，不往下流。
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 |
| 团队规范（工作流 / 测试 / 安全 / 版本…） | .claude/standards/ |
| 架构决策记录（Pool / Workflow / 契约同步…） | docs/adr/ |
| 每个版本改了什么 | CHANGELOG.md |
📜 License
MIT — 自由商用。结构灵感参考 The Agency。
19 个 AI 同事 · 7 道工序 · 缺陷流不进下一道工序
⭐ Star · 🐛 Issue · 📒 CHANGELOG · 🇬🇧 English