Skip to content

Getting Started

Jump to bottom
pcliangx edited this page Jul 1, 2026 · 3 revisions

Getting Started

30 分钟从 git clone 到第一个 feature 通过团队交付。

前置要求

工具 版本 用途
Claude Code ≥ v2.1.154 启用 Agent Teams 实验功能（min 版本随模板升）
git 任意现代版本 仓库 + git pre-commit hook
python3 3.x hook 测试 + setup/init-team.sh 校验 JSON
jq 任意 hook 脚本解析 JSON 输入
gh（可选） 任意 gh repo create --template 和发版本
iTerm2 + it2 或 tmux（macOS 可选） — Agent Team 自动 split-pane 显示（teammateMode 默认 "iterm2"，ADR-004）

启用 Agent Teams：环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1（TeamCreate / TeamDelete 已在 v2.1.178+ 移除，每 session 隐式团队——直接 spawn teammate，不再建团）。

bash setup/agf-install.sh 会编排各项校验；缺什么先补什么。

方式 1：用作新项目脚手架（推荐）

gh repo create my-app --template pcliangx/AppGenesisForge --private
cd my-app
bash setup/agf-install.sh

setup/agf-install.sh 是 TUI 安装器（source setup/agf-tui.sh 编排），新项目入口。它依次跑：

  1. setup/install-to-existing.sh — 非交互核心安装（hook 装载 / settings 注入 / 目录就位）
  2. setup/customize.sh — preset 裁剪（--preset minimal / miniapp-only，按需删角色）
  3. setup/init-team.sh — Day-1 体检：hook 回归测试 + JSON 语法 + 文件存在校验

init-team.sh 跑的体检项（约 10 项）：Claude Code 版本、block-dangerous-bash 回归（约 67 条断言）、scan-secrets 回归（约 35 条断言）、.claude/settings.json 合法性、git pre-commit hook 安装、evals/*.jsonl 静态 lint 等。预期输出：通过为主，失败为 0。

所有安装脚本都在 setup/，仓库根零 .sh（v6.x 整理过目录结构）。

装完后进入 Claude Code 跑 /agf-init（Claude 接管）：体检复核 + 合并 CLAUDE.md + 据项目真实栈写 ADR-000 + 建 gh label。这一步取代手工编辑 CLAUDE.example.md 与手敲 ADR 模板。

方式 2：嵌入到已有仓库

复制以下到目标仓库根（不要复制本仓库自己的 CLAUDE.md——那是 AppGenesisForge 自己的项目说明，不是模板）：

  • .claude/（agents / standards / skills / hooks / rules / commands / settings.json）
  • setup/（agf-install.sh / install-to-existing.sh / customize.sh / init-team.sh / agf-tui.sh）
  • CHANGELOG.md、evals/、Makefile
  • docs/team-capability-map.md、docs/adr/、docs/specs/、docs/changes/、docs/design/、docs/qa/、docs/reviews/
  • 各模板：docs/changes/_TEMPLATE/、docs/qa/uat-cases-_TEMPLATE.md、docs/reviews/_TEMPLATE.md

然后跑：

bash setup/install-to-existing.sh   # 核心安装
bash setup/customize.sh             # 可选 preset 裁剪
bash setup/init-team.sh             # 体检
# 进入 Claude Code 后：
/agf-init                           # Claude 接管：合并 CLAUDE.md + 写 ADR-000 + 建 label

CLAUDE.md 由 /agf-init 据项目情况合并生成，不再需要手工 cp CLAUDE.example.md CLAUDE.md（example 已不存在）。docs/PROJECT-PLAN.md 也已不存在——进度跟踪由 Agent Teams 原生 task list（/agf-tasks）+ 每个 change 的 tasks.md 承担。

装完后的逐步配置

Step 1：跑 /agf-init（Claude 接管初始化）

在装好 AGF 的目标项目里启动 Claude Code，跑：

/agf-init

它会：

  • 复核体检（hook / JSON / 文件）
  • 合并生成项目 CLAUDE.md（保留 "Team Runtime Contract" 节原样，填项目特有内容）
  • 据项目真实技术栈写 ADR-000（不是手敲模板示例——扫仓库识别 React / FastAPI / Postgres / Tailwind / orval 等，落决策背景）
  • 建 GitHub label（type / area / epic / priority / severity / phase 锁定集）

Step 2：校准权限白名单

打开 .claude/settings.json，把 permissions.allow 改成项目实际用的命令。默认基线假设：

  • 前端：pnpm test/lint/build/typecheck/install
  • 后端：pytest、ruff、black、alembic、docker compose、uv（Python 包管理）
  • Git：只读（status、diff、log）

常见调整：用 npm/yarn → 把 pnpm * 替换为 npm * / yarn *；不用 alembic → 删 Bash(alembic*)。

Step 3：验证 hooks

.claude/hooks/test-block-dangerous-bash.sh
.claude/hooks/test-scan-secrets.sh

两份都应输出 All assertions passed。失败先装 jq（brew install jq / apt install jq）。

Step 4（可选）：启用 Agent Teams 显示模式

macOS 装 iTerm2 + it2 或 tmux，让 teammateMode "iterm2"（默认）/ "tmux" / "auto" 用 split panes 显示 teammate。缺 it2 会 fail-loud 报错（ADR-004）。

Step 5：跑第一条链路

最简入口：

/agf-team-start <你的第一个 feature 描述（中英文都行）>

product-lead 会：

  1. 需求模糊时先 brainstorm（superpowers:brainstorming skill）
  2. 建变更文件夹 docs/changes/<change>/（四件套 proposal + specs delta + design + tasks，skill agf-writing-change）——取代旧 PRD
  3. 把行为需求表达成对活规格 docs/specs/<cap>/spec.md 的 delta（ADDED/MODIFIED/REMOVED Requirements + #### Scenario）
  4. 实施计划（superpowers:writing-plans，轻量化，见 .claude/standards/plans-format.md）
  5. spawn frontend-dev / backend-dev 等 teammate（直接 Agent 工具 name 参数，不再建团），任务消息带 AC 摘录
  6. 推进链路：派单（worktree 隔离）→ TDD 实现 + SIT 自跑 → code review（含 SIT Audit）→ UAT 部署 → E2E → UAT 业务签字

任何阶段你都可以打断重定向。但如果团队走得对，不要硬把它拉回——它就是按流程走的。

验证链路跑通了

第一个 feature 完成后，应看到：

路径 应包含
docs/changes/<change>/ 四件套：proposal.md + specs delta（对 docs/specs/<cap>/spec.md 的 ADDED/MODIFIED）+ design + tasks.md
docs/specs/<cap>/spec.md 活规格（UAT 签字后 delta 才 merge 进来，由 agf-spec-archive 确定性合并）
docs/design/DESIGN.md 设计 token SSOT（color/typography/spacing/radius/component + on-* 配对）
docs/design/[feature]/ spec.md + index.html 静态原型（可 open 打开）
docs/reviews/[feature]-*.md code review 报告（frontmatter verdict：approve / approve with changes / block）
progress/<role>.md 5 段格式含 **SIT 证据** 段（dev 自跑 SIT 的证据落点，code-reviewer audit）
docs/qa/[feature]-*.md E2E / UAT 报告（SIT 不在此——SIT 在 progress/）

任一缺失说明跳过了某道阶段门——见 Troubleshooting-FAQ。

常用 slash commands

动作 命令
启动 Agent Team 交付 feature /agf-team-start <描述>
看当前 task list /agf-tasks
看开发看板（HTML kanban） /agf-board
部署 UAT 隔离栈 /agf-deploy-uat
联跑 UAT 业务签字 /agf-uat
Apple 签名分发包构建 /agf-apple-release
交接执行层给 Codex / opencode /agf-handoff
Release 后复盘（MAJOR/MINOR） /agf-release-retro vX.Y.Z
关闭执行层 teammate /agf-team-stop
看本次会话用量 Claude Code 内置 /usage（不是 /agf-usage）

注意：没有 /agf-sit——SIT 由 dev 自跑（skill agf-running-sit-tests，证据落 progress/<role>.md），不是独立阶段或独立命令。

真实样本参考

学第一个 feature 长什么样，看主仓的真实样本 docs/training/samples/postcard-feature/（不是 examples/login-feature/，那个已不在）。

下一步

🚀 入门

👥 团队

🔌 专项

🛡️ 基础设施

❓ 实战

主仓 CHANGELOG Releases

Clone this wiki locally