App Genesis Forge

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 带 19 个 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/install-to-existing.sh ~/path/to/your-repo   # 目标须是 git 仓；新项目先 mkdir + git init

非交互安装核心资产（自动备份你已有的 .claude/ 与 CLAUDE.md，永不覆盖）。可选 flag：--with-office-skills（装 docx/pptx 报告技能组）。角色裁剪在下一步 /agf-init 里选（或手动 bash setup/customize.sh --preset web-only --yes）。

② 初始化 + 复核技术栈（~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 团队跑完。

• 升级：已装 AGF 的项目重跑 bash setup/install-to-existing.sh ~/path/to/your-repo --refresh-docs（旧版 → 新版，旧文件自动备份；永不覆盖你的 CLAUDE.md / ADR-000 / settings.json）。
• 角色裁剪 + 体检（可选，在目标项目里）：

  bash setup/customize.sh --preset web-only --yes                 # 纯 Web 项目：去 Apple + 小程序轨（19→12 角色）
  bash setup/init-team.sh                                          # Day-1 体检
  

• 卡分屏：模板默认 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。

✨ 它给你什么

🔄 怎么工作

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-dev backend-dev ai-agent-dev ml-engineer uiux-designer miniapp-dev · 🍎 apple-dev（Swift / SwiftUI，macOS+iOS）
• 🟡 评审：code-reviewer miniapp-code-reviewer apple-code-reviewer（review-only，verdict 必从 frontmatter 原子事实推导【code / SIT / QA】+ hook 守门，ADR-010）
• 🔴 测试：qa-engineer miniapp-qa-engineer apple-qa-engineer（E2E / UAT 执行，无证据不给 Pass）
• 🩶 部署/发布：deploy-engineer（隔离 UAT 栈）· apple-release-engineer（签名公证 + 四渠道分发包）· 🟪 上线后：content-writer growth-analyst

📚 想深入

📜 License

MIT — 自由商用。结构灵感参考 The Agency。

19 个 AI 同事 · 7 道阶段门 · 机制兜底而非 agent 自觉

⭐ Star · 🐛 Issue · 📒 CHANGELOG · 🇬🇧 English