--- slug: "appgenesisforge" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/pcliangx/AppGenesisForge@main/README.md" repo: "https://github.com/pcliangx/AppGenesisForge" source_file: "README.md" branch: "main" --- # App Genesis Forge > **Code the Origin, Forge the App.** > 给 Claude Code 装一支**有流程治理的 AI 开发团队**——不是更聪明的单 agent，更像一条精益产线：19 角色分工协作、层层把关，**缺陷流不进下一道工序**。 [![Release](https://img.shields.io/github/v/release/pcliangx/AppGenesisForge)](https://github.com/pcliangx/AppGenesisForge/releases) [![Claude Code](https://img.shields.io/badge/Claude%20Code-%E2%89%A5%20v2.1.154-orange?logo=anthropic)](https://claude.com/claude-code) [![Methodology](https://img.shields.io/badge/methodology-SDD%20%2B%20TDD%20%C2%B7%20%E7%B2%BE%E7%9B%8A%E4%BA%A7%E7%BA%BF-9b59b6)](docs/product-workflow.md) [![LLM](https://img.shields.io/badge/LLM-DeepSeek%20%7C%20Doubao%20%7C%20Qwen%20%7C%20MiniMax-ff6b6b)](.claude/skills/agf-wiring-multi-llm-sdk/) [![Hooks](https://img.shields.io/badge/hooks-4%20layers-2c3e50?logo=shieldsdotio&logoColor=white)](.claude/standards/security.md) [![Tracks](https://img.shields.io/badge/tracks-Web%20%C2%B7%20MiniApp%20%C2%B7%20Apple-3b82f6)](.claude/standards/) [![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE) **简体中文** · [English](https://github.com/pcliangx/AppGenesisForge/blob/HEAD/README.en.md) --- ![AGF 实时开发看板](https://github.com/pcliangx/AppGenesisForge/raw/HEAD/docs/assets/agf-board.png) *↑ 一句话提需求 → AI 团队并行交付 → 看板实时点亮，全程一个终端 tab。* > **单个 AI agent 一把梭，长流程会失控**——没人审、没人测，说「完成了」其实没跑通。AGF 不赌「更强的模型」，而是**把 AI 当一支需要流程约束的团队来管**——质量不靠更聪明的工人，靠更好的产线。 **AppGenesisForge（AGF）** 是基于 [Claude Code Agent Teams](https://code.claude.com/docs/en/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](https://claude.com/claude-code) ≥ v2.1.154 · git · macOS / Linux ·（分屏显示可选：`teammateMode` 默认 `"auto"`——iTerm2 / tmux 会话自动分屏，其余终端 in-process，不影响功能） **① 装**（~2 分钟） ```bash 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 分钟，在目标项目里） ```text /agf-init ``` Claude 接管：体检 + 合并 CLAUDE.md + **据你项目真实技术栈写 ADR-000** + 建 label。 > ⚠️ **唯一必做的人工关**：打开 `docs/adr/000-system-architecture.md` 核对语言 / 框架 / DB 是不是你项目真的——这是防 AI 编技术栈的最后一道关。 **③ 派第一个 feature**（团队启动） ```text /agf-team-start 加一个健康检查接口 GET /health 返回 {"status":"ok"} ``` （示例，按你的栈换。）`product-lead` 起变更文件夹 → 派 backend-dev 实现 → reviewer 审 → …… 分屏里多个 AI 同事并行干活。 **④ 开实时看板盯进度**（另开一个 tab） ```text /agf-board --watch ``` 然后 `open progress/board.html`——task 卡片三列流转、工序一道道点亮，≈3 秒刷新，实时看团队推进（首屏那张图就是它）。 **⑤ 验收签字** 走完 SIT → code review → UAT，`product-lead` 来找你签字。签了就交付——你的第一个 feature 由一支**有流程治理的 AI 团队**跑完。
无 TTY 非交互 / 升级 / 卡分屏 - **非交互 / CI 等价**：`agf-install.sh` 是交互壳，底层是这三个非交互脚本，CI / 无 TTY 环境可直接调用（TUI 遇非 TTY 也会自动降级打印这条等价命令）： ```bash 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 体检 ``` 可选 flag：`--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`](https://github.com/pcliangx/AppGenesisForge/blob/HEAD/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](https://github.com/Chachamaru127/claude-code-harness)，杜绝「文档写了、实际没接」（[ADR-023](https://github.com/pcliangx/AppGenesisForge/blob/HEAD/docs/adr/023-honesty-layer-claims-and-baseline.md)） | | **并行可控** | 同类任务 ≥2 自动 fan-out 多实例（dev / reviewer / qa 池），`agf-matrix.sh` 一张表 fan-in；另有 `/agf-code-map`（codemap 代码理解引擎 + `orphans` 报「写了没接线」的模块，[ADR-021](https://github.com/pcliangx/AppGenesisForge/blob/HEAD/docs/adr/021-code-understanding-engine.md) / [024](https://github.com/pcliangx/AppGenesisForge/blob/HEAD/docs/adr/024-module-reachability-advisory.md)） | | **实时看板** | `/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](https://github.com/pcliangx/AppGenesisForge/blob/HEAD/docs/adr/013-design-discipline-layer.md)）：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](https://github.com/pcliangx/AppGenesisForge/blob/HEAD/docs/adr/027-reinstate-tui-install.md)）。 --- ## 🔄 怎么工作 需求进、签字出，一条产线走到底；虚线是打回——缺陷退回实现工序重做，不往下流。 ```mermaid flowchart LR U([👤 需求]) --> S1["变更文件夹
brainstorming 澄清"] S1 --> S2["派单
AC 摘录 + worktree 隔离"] S2 --> S3["TDD 实现
Unit + SIT 自跑"] S3 --> S4["Code Review
+ SIT 证据审计"] S4 --> S5["UAT 部署
隔离栈 + 冒烟"] S5 --> S6["E2E
真浏览器控件遍历"] S6 --> S7["UAT
用例文档经你审核"] 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 秒上板： ```text /agf-board --watch # 然后 open progress/board.html ``` **19 个同事**（完整职责 / 模型 / 工具见 [`team-roles.md`](https://github.com/pcliangx/AppGenesisForge/blob/HEAD/.claude/standards/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` --- ## 📚 想深入 | 你想 | 看这里 | |---|---| | Day-1 上手 + 踩坑速查 | [`docs/FIRST_RUN.md`](https://github.com/pcliangx/AppGenesisForge/blob/HEAD/docs/FIRST_RUN.md) | | 端到端全景图（角色 × 阶段 × hook × skill） | [`docs/team-capability-map.md`](https://github.com/pcliangx/AppGenesisForge/blob/HEAD/docs/team-capability-map.md) | | 交付工作流 + 全部术语 | [`docs/product-workflow.md`](https://github.com/pcliangx/AppGenesisForge/blob/HEAD/docs/product-workflow.md) | | 团队规范（工作流 / 测试 / 安全 / 版本…） | [`.claude/standards/`](https://github.com/pcliangx/AppGenesisForge/tree/HEAD/.claude/standards/) | | 架构决策记录（Pool / Workflow / 契约同步…） | [`docs/adr/`](https://github.com/pcliangx/AppGenesisForge/tree/HEAD/docs/adr/) | | 每个版本改了什么 | [`CHANGELOG.md`](https://github.com/pcliangx/AppGenesisForge/blob/HEAD/CHANGELOG.md) | --- ## 📜 License MIT — 自由商用。结构灵感参考 [The Agency](https://github.com/msitarzewski/agency-agents)。
**19 个 AI 同事 · 7 道工序 · 缺陷流不进下一道工序** [⭐ Star](https://github.com/pcliangx/AppGenesisForge) · [🐛 Issue](https://github.com/pcliangx/AppGenesisForge/issues) · [📒 CHANGELOG](https://github.com/pcliangx/AppGenesisForge/blob/HEAD/CHANGELOG.md) · [🇬🇧 English](https://github.com/pcliangx/AppGenesisForge/blob/HEAD/README.en.md)