> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # Factory 操作手册 > **这不是参考文档。** 参考文档见 `agentic-software-factory.md`。 > 这是你今晚可以跟着走的手册：设计 → 验证 → 睡觉 → 醒来有 PR。 > > 创建日期：2026-03-20 *** ## 三个文档各自是什么 ``` agentic-software-factory.md ← 研究参考（17个问题、行业案例、工具对比） agentic-software-factory-playbook.md ← 本文档，操作手册（今晚就能跟着走） doc-structure-for-agents.md ← 文件放哪里：specs/plans/working-memory 目录规范 ``` *** ## 什么是 Superpowers Skills Superpowers skills 是以 `.md` 文件形式存储的执行框架，通过 `Skill` tool 调用，引导 agent 按标准化流程完成特定阶段的工作。 | Skill | 什么时候用 | 触发方式 | | -------------------------------- | ----------------------------------------- | ------------------------------------ | | `brainstorming` | Step 1 开始前：探索功能意图，确认边界 | 你说"帮我做 Step 1" | | `writing-plans` | Step 1 产出：基于 design.md 生成 impl.md | 你说"帮我生成 impl.md" | | `using-git-worktrees` | Step 2 启动：创建隔离工作区 | brainstorming / executing-plans 自动调用 | | `executing-plans` | Step 2 执行框架：批量执行 + checkpoint | impl.md 第一行指令触发 | | `test-driven-development` | 每个 task：先写失败测试再实现 | executing-plans 执行每个 task 前 | | `systematic-debugging` | 遇到 bug / test 失败：找根因，不猜 | 失败超过 1 次时 | | `verification-before-completion` | 说"完成"之前：跑验证命令，看到实际输出 | 每个 task 结束 / 开 PR 前 | | `finishing-a-development-branch` | 所有 task 完成后：确认测试通过，呈现合并选项 | executing-plans 最后一步 | | `requesting-code-review` | 开 PR 前：自检代码质量 | 可选，finishing-a-development-branch 之前 | | `subagent-driven-development` | 当前 session 内用子 agent 执行 plan（非隔离 session） | 选择"Subagent-Driven"模式时 | ::: info skill 怎么触发 只要你告诉 agent 用某个 skill，或者某个 skill 的指令写在 impl.md / 另一个 skill 里，agent 会自动通过 `Skill` tool 调用它。`executing-plans` 调用了 `using-git-worktrees` 和 `finishing-a-development-branch`；`systematic-debugging` 调用了 `test-driven-development`。整条链条是自动的。 ## ::: ## 启动前必读 | # | 文档 | 路径 | 为什么读 | | - | --------------------------- | ------------------------------------------------------ | ---------------- | | 1 | 本文档（Playbook） | `docs/ai/factory/agentic-software-factory-playbook.md` | 整体流程 | | 2 | CLAUDE.md（各 repo） | `[repo]/CLAUDE.md` | 每个 repo 的命令和约束 | | 3 | execution-policy.md（各 repo） | `[repo]/.claude/rules/execution-policy.md` | 决策规则（不问用户，自己查这里） | | 4 | Superpowers skills | 通过 `Skill` tool 调用时自动加载 | 执行框架（下表速查） | *** ## 核心模型：2 步走 ``` Step 1: 设计（你 + AI 协作，30 分钟） AI 读代码库 → 告诉你现状和方案 → 你提问确认 → 你写验收标准 ↓ 复杂任务额外产出 design.md（你 review）→ superpowers:writing-plans → impl.md ↓ Step 2: 执行（全自动，你睡觉） Claude Code 自动加载 CLAUDE.md → @import execution-policy.md（规则） → 读 impl.md（任务） → superpowers:executing-plans（执行框架） → 实现 → 写测试 → 跑 CI → 自动修 → 开 PR ↓ 你：review PR summary（15 分钟）→ approve → merge ``` **分工**：你的工作 = 设方向、定验收标准、review PR（约 15–30 分钟）。Agent 的工作 = 读代码库、写实现、跑测试、开 PR（全自动，你去睡觉）。 *** ## Step 1：设计阶段（你来主导） ### 开始前：`superpowers:brainstorming` 在进入设计前，先调用 `superpowers:brainstorming`。它会探索功能意图、确认边界，并自动调用 `superpowers:using-git-worktrees` 创建隔离工作区（不污染 main 分支）。 ``` 你说："帮我做 Step 1，feature 是 X" AI 调用 brainstorming → 确认方向 + 创建 worktree → 然后才开始读代码、设计方案 ``` ### AI 负责做 1. 读现有代码库（Lambda、schema、现有 pattern） 2. 告诉你：现在的状态是什么、做这个 feature 有哪些可行路径、每条路径的风险 3. 指出你可能没想到的 edge case 或技术约束 ### 你负责做 1. 提问、质疑、讨论（"为什么不用 X？""如果 Y 怎么办？"） 2. 拍板决定：选哪条路、不做什么、边界在哪 3. **写验收标准** ← 这一步最关键，决定了 Step 2 能不能跑通 ### 产出：Task Spec（小任务）或 Plan 文件（复杂任务） #### 小任务（≤ 3 个文件改动 / ≤ 50 行代码） 直接写一份 Task Spec 即可，用本文末尾的 [Task Spec 完整模板](#task-spec)。Task Spec 需包含以下字段：任务描述、前置读取、参考实现、边界、已决定的事、验收标准。 #### 复杂任务（跨多个 Lambda / 涉及 DB schema / 跨 repo） 两步产出：先 design，再 impl。 **第一步：设计文档** — `design.md` `brainstorming` 是当前 session 里的交互过程，本身不产出独立文件。交互结束后，AI 在这次 session 里生成 `design.md`（你来 review）。包含背景、方案对比、最终决定、影响范围。 `design.md` 的落脚点：**所有 repo 统一用 `.claude/specs/YYYY-MM-DD-[feature]-design.md`**，不管任务涉及几个 repo。 **第二步：执行计划** — `impl.md` 用 `superpowers:writing-plans` skill 根据 design.md 自动生成。包含任务分解、每步的文件改动、预期结果、commit message。路径与 design.md 同目录，后缀改为 `.impl.md`。 ``` 你告诉 AI：帮我基于 design.md 生成 impl.md AI 调用 superpowers:writing-plans → 生成 impl.md 你做最终 review（确认 task 顺序、边界） impl.md 就是 Step 2 的输入 ``` ::: tip impl.md 是给 agent 的完整说明书 impl.md 第一行会有 `> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans`。 agent 读到这行就知道要调用 `superpowers:executing-plans` 来执行任务，不需要你再告诉它。 ## ::: ## Step 2：执行阶段（全自动） ### Agent 如何加载上下文（自动发生，无需手动） ``` Claude Code 启动时自动加载 CLAUDE.md ↓ CLAUDE.md 里有 @.claude/rules/execution-policy.md → execution-policy.md 自动被 import（规则、技术栈决策、Park 条件） ↓ 你传入 impl.md（或 task spec）作为任务输入 → agent 读 impl.md → 看到 "REQUIRED SUB-SKILL: Use superpowers:executing-plans" → 调用 superpowers:executing-plans（执行框架：任务节点 → checkpoint → 自我验证） ``` 这个链条的设计原则：**规则永久存在于 git，任务临时传入，执行框架统一用 superpowers**。你不需要每次告诉 agent "记得读规则"或"记得用什么工具"。 ### Agent 按顺序做 ``` [启动阶段] 1. superpowers:using-git-worktrees → 创建隔离工作区，验证 baseline tests 全过才继续 2. 读 impl.md（或 task spec）+ 所有前置读取文件 → 批判性 review：有疑问先提出，没问题再开始执行 3. superpowers:executing-plans → 按 impl.md 逐节执行，每批 3 个 task 后 checkpoint，报告状态 [每个 task 节点内] 4. 若修改已有文件 → `ask` skill 查询历史 AI session，理解原始 intent 5. superpowers:test-driven-development → 先写失败测试（RED），再写最小实现（GREEN），最后重构（REFACTOR） → 铁律：没看到测试失败过，就不算测试有效 6. 遇到 bug 或 test 持续失败 → superpowers:systematic-debugging → 找根因（Phase 1: 读错误 → 复现 → 追溯），不猜 → 3 次修改仍失败 → 停下来，质疑架构，Park & Notify [完成阶段] 7. superpowers:verification-before-completion → 跑所有验证命令，看到实际输出再说"完成" → 禁止用 "should work"、"probably passes" 这类说法 8. superpowers:finishing-a-development-branch → 确认所有测试通过，呈现合并方式（squash / rebase / PR），执行选定方式 ``` ### 你的工作（15 分钟） 只看 PR 里的三件事： 1. 验收标准是否全部 ✅ 2. CI 是否绿 3. 有没有 ⚠️ 标注（agent 遇到不确定的情况会在 PR 里标注） *** ## 新 Feature 的 Integration Test 从哪来 **问题**：新 feature 没有现成的 integration test，agent 怎么知道它 work 了？ **答案**：验收标准就是 integration test 的 spec。 你在 Step 1 写了： ```markdown 当 phone +16502530000 打进来，Neon contacts 表出现一条记录 ``` Agent 在 Step 2 翻译成： ```typescript it('新电话打进来应该创建 contact 记录', async () => { // 模拟 SQS 事件（用现有 test-data/fixtures/） await handler(mockCallEvent('+16502530000')); const contact = await db.select().from(contacts) .where(eq(contacts.phone, '+16502530000')); expect(contact).toHaveLength(1); expect(contact[0].phone).toBe('+16502530000'); }); ``` **结论**：没有验收标准 = agent 写了代码，不知道对不对 = "some random code"。 有了验收标准 = agent 有目标 + 有办法自我验证 = 你收到的是"跑通了的代码"。 *** ## 完整 Overnight 流程 ``` 22:00 你完成 3 个 task spec（含验收标准） 22:05 Agent 开始并行执行（git worktree × 3） ├── Task A：实现 → 写测试 → CI green → PR ✅ ├── Task B：实现 → CI 失败 → 自己修 → CI green → PR ✅ └── Task C：实现到一半，发现 contacts 表没有 phone 索引 → Park（保存进度） → Slack 通知："需要你决定：加索引(A) 还是换查询方式(B)?" → 继续做 Task A/B，不浪费时间等你 07:00 你醒来 ├── PR #1 ✅ review 10 分钟 → approve ├── PR #2 ✅ review 10 分钟 → approve └── Slack 消息 → 回复 "A" → Task C 继续执行 ``` *** ## 什么会阻止自动化 | 阻断原因 | 表现 | 解法 | | ------------ | ---------------------------------------- | ------------------------------------ | | 验收标准没写 | Agent 开了 PR 但写着 "我不确定这样对不对" | Step 1 必须写验收标准 | | Task 之间有依赖 | B 依赖 A 完成才能开始 | 串行，或 A 完成后再触发 B | | 外部服务没有 mock | Integration test 真实打 RC API，被 rate limit | 用现有 test-data/fixtures/；未来上 WireMock | | 遇到 prod 数据格式 | Agent 不知道真实数据长什么样 | test-data 里补充样本 | | 任务范围不清 | Agent 开始做周边"改进"，改了不该改的文件 | Task spec 明确写"不能碰" | *** ## 你的 11 个问题在哪个阶段解决 | 问题 | 阶段 | 解法 | | ---------------------------- | ---------- | --------------------------------------- | | Q1-3：什么是 agentic factory | 理解 | 本文档就是答案 | | Q4：设计文档 → Agent 自动实现 | 两步都有 | Step 1 产出 task spec，Step 2 执行 | | Q5：有状态，不总来问我 | Step 2 | `execution-policy.md` + CLAUDE.md 预写决策 | | Q6：VM 隔离，不做危险操作 | Step 2 | Claude Code 沙盒 + **没有 prod 凭证** | | Q7：10+ PRs 并行 | Step 2 | N 个 task spec → git worktree × N | | Q8：AI stuck 了 | Step 2 | Park & Notify：存草稿 + 通知你 | | Q9：Integration test，能 work 吗 | **Step 1** | 你写验收标准 → agent 翻译成 test 代码 | | Q10：Context 丢失 | Step 2 | `working-memory/` 文件 + CLAUDE.md 永久记忆 | | Q11：Digital Twin | Step 2（未来） | LocalStack + WireMock（你已有 fixtures/ 雏形） | *** ## Task Spec 完整模板 \{ #task-spec } 保存为 `.github/ISSUE_TEMPLATE/agent-task.md`，每次新任务复制一份： ```markdown --- name: Agent Task labels: agent-task --- ## 任务描述 [一句话] ## 背景（为什么要做） [设计文档链接 或 1-2 句说明] ## 前置读取（按顺序） - [ ] `[文件路径]` — [为什么要读这个] - [ ] `.claude/rules/execution-policy.md` - [ ] `.claude/rules/[相关规则].md` ## 参考实现 - `[现有代码路径]` — 照这个 pattern 写 ## 边界：绝对不碰 - [文件或资源] - 不改 prod 环境任何东西 ## 已经决定（不用再讨论） - [决策 1] - [决策 2] ## 验收标准 - [ ] [具体可测试的行为 1] - [ ] [具体可测试的行为 2] - [ ] `bun test` 全部通过 - [ ] `cdk diff` 无 replacement ## 遇到这些情况，Park & Notify 我 - 发现需要改超过 2 个 Lambda 的架构 - 发现设计文档有矛盾 - 需要修改 prod 配置 ``` *** ## 第一次实验：怎么开始 **目标**：走完一次完整的 2-step 流程，验证这个模型在 retaintive 上 work。 **建议第一个任务**：选一个边界清晰的 GAP，做 Step 1。 选 GAP 的标准： - ✅ 不依赖其他 GAP 完成 - ✅ 有明确的数据流（从 X 到 Y） - ✅ 不需要碰 production 配置 - ✅ 有现有代码可以作为 pattern 参考 **具体走法**： ``` 1. 你选一个 GAP 2. 你说 "帮我做 Step 1" 3. AI 读相关代码 → 输出：现状分析 + 可行方案 + 风险 4. 你提问 + 确认 5. 你写验收标准（AI 可以帮你起草，你来审） 6. 产出：一份 task spec 7. 用这份 task spec 启动 Step 2（你实际执行，或给 agent 执行） ``` *** ## Plan 文件位置 所有 spec 文件统一放 `.claude/specs/`，不管任务在几个 repo 里： | 文件 | 路径 | 说明 | | ------ | ---------------------------------------------- | ------------------------- | | 设计文档 | `.claude/specs/YYYY-MM-DD-[feature]-design.md` | 你 review，决策留档 | | 执行计划 | `.claude/specs/YYYY-MM-DD-[feature]-impl.md` | agent 执行，含 superpowers 指令 | | 任务状态缓存 | `.claude/working-memory/[feature].md` | 临时，PR 合并后删除 | **注意**：`superpowers:writing-plans` 默认输出到 `docs/plans/`，所有 repo 的 `execution-policy.md` 都必须覆盖这个默认值，改用 `.claude/specs/`。 **跨 repo 执行时**：impl.md 里的 `Design Doc:` 字段必须填 GitHub URL（`https://github.com/retaintive/docs/blob/main/.claude/specs/...`），而不是相对路径。docs repo 是 private，`raw.githubusercontent.com` 返回 404。Agent 需要读内容时用 `gh api repos/retaintive/docs/contents/ --jq '.content' | base64 -d`。