Skip to content

Getting Started

Jump to bottom
AgentForge Wiki edited this page May 1, 2026 · 2 revisions

Getting Started

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

前置要求

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

bash init-team.sh 会检查多数前置项；缺什么先补什么。

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

gh repo create my-app --template pcliangx/AppGenesisForge --private
cd my-app
bash init-team.sh

init-team.sh 跑 10 项校验：

  1. Claude Code 版本
  2. Hook 回归测试：block-dangerous-bash（约 67 条断言）
  3. Hook 回归测试：scan-secrets（约 35 条断言）
  4. .claude/settings.json JSON 合法性
  5. .claude/hooks/skill-rules.json JSON 合法性
  6. git pre-commit hook 已安装（缺则自动装）
  7. evals/*.jsonl 静态 lint
  8. CLAUDE.md 存在（缺则提示从 CLAUDE.example.md 复制）
  9. docs/PROJECT-PLAN.md 存在
  10. docs/adr/000-system-architecture.md 已定制（仍是模板示例时告警）

预期输出：通过: 10 警告: 2 失败: 0。两个常见警告：

  • CLAUDE.md 未创建 → cp CLAUDE.example.md CLAUDE.md 后改内容
  • docs/adr/000-*.md 还是模板示例 → 见下方 Step 4

方式 2：嵌入到已有仓库

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

  • .claude/（agents / standards / skills / hooks / rules / commands / settings.json / FIRST_RUN.md）
  • CLAUDE.example.md → 改名为 CLAUDE.md 并填项目特有内容
  • CHANGELOG.md、init-team.sh、evals/
  • docs/team-capability-map.md、docs/product-workflow.md、docs/PROJECT-PLAN.md
  • docs/prd/_TEMPLATE.md、docs/reviews/_TEMPLATE.md、docs/qa/_TEMPLATE.md

然后跑 bash init-team.sh。

init-team.sh 跑完后的逐步配置

Step 1：校准权限白名单

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

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

常见调整：

  • 用 npm/yarn → 把 pnpm * 替换为 npm * / yarn *
  • 不用 alembic → 删 Bash(alembic*)
  • 用 poetry / uv → 加 Bash(poetry*) / Bash(uv*)

Step 2：写 CLAUDE.md

参考 CLAUDE.example.md，复制成 CLAUDE.md 后填：

  • ## Project Overview — 2-4 行项目目标
  • ## Tech Stack — 留空，agf-tech-lead 在第一个 feature 启动时填
  • ## Project-Specific Rules — 项目特有的合规约束 / 部署窗口 / 第三方依赖限制

保留 "Team Runtime Contract" 节原样——这是 Agent Team 协议的入口硬约束。

Step 3：处理 ADR-000

docs/adr/000-system-architecture.md 是模板示例。三选一：

方案 何时用 命令
A 起新版 新项目，让 PM 决定技术栈 请启动 agf-tech-lead，为本项目起 ADR-000 固化技术栈
B 改写现状 接手老代码库 请启动 agf-tech-lead，扫描仓库识别实际技术栈，输出 ADR-000
C 删掉 后面再说 rm docs/adr/000-system-architecture.md

Step 4：验证 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 5（可选）：启用 Agent Teams 显示模式

macOS 装 iTerm2 + it2 或 tmux，让 teammateMode: "auto" 自动用 split panes。

Step 6：跑第一条链路

最简入口：

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

agf-product-lead 会：

  1. 需求模糊时先 brainstorm（superpowers:brainstorming skill）
  2. 写 PRD 到 docs/prd/[feature]-[YYYY-MM-DD].md
  3. 实施计划（≥3 AC / 跨角色时调用 superpowers:writing-plans）
  4. spawn agf-frontend-dev / agf-backend-dev 等 teammate，任务消息带 AC 摘录
  5. 推进链路：code review → SIT → E2E → UAT → 业务签字

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

验证链路跑通了

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

路径 应包含
docs/prd/[feature]-*.md 10 节 PRD + AC 表
docs/design/[feature]/ spec.md + index.html 静态原型
docs/reviews/[feature]-*.md code review 报告（Critical / Warning / Suggestion）
docs/qa/[feature]-{sit,e2e,uat}-*.md 各阶段测试报告
docs/PROJECT-PLAN.md ## Active 节有任务条目 + 状态 emoji

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

常用动作

动作 命令
看当前进度 请启动 agf-product-lead，汇总当前项目进度
派单角色任务 请启动 agf-frontend-dev，根据 docs/prd/X 实现 Y
起 ADR 请启动 agf-tech-lead，评估 [选型] 并输出 ADR
跑 SIT /agf-sit <feature>
跑 UAT /agf-uat <feature>
看会话成本 /agf-usage

下一步

🚀 入门

👥 团队

🔌 专项

🛡️ 基础设施

❓ 实战

主仓 CHANGELOG Releases

Clone this wiki locally