Agentic Software 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"模式时 |
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/agentic-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 分支）。
AI 负责做¶
- 读现有代码库（Lambda、schema、现有 pattern）
- 告诉你：现在的状态是什么、做这个 feature 有哪些可行路径、每条路径的风险
- 指出你可能没想到的 edge case 或技术约束
你负责做¶
- 提问、质疑、讨论（"为什么不用 X？""如果 Y 怎么办？"）
- 拍板决定：选哪条路、不做什么、边界在哪
- 写验收标准 ← 这一步最关键，决定了 Step 2 能不能跑通
产出：Task Spec（小任务）或 Plan 文件（复杂任务）¶
小任务（≤ 3 个文件改动 / ≤ 50 行代码）¶
直接写一份 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 的输入
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 写了：
Agent 在 Step 2 翻译成：
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 完整模板¶
保存为 .github/ISSUE_TEMPLATE/agent-task.md，每次新任务复制一份：
---
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/<path> --jq '.content' | base64 -d。