需要让编码 agent 自主完成长周期、规格驱动的项目时…

适用场景：把结构化规格交给 gsd-pi CLI，让它自主研究、规划、执行、提交、恢复并控制成本地完成长周期编码任务。

适用场景

解决思路

1. 运行 `npm install -g gsd-pi` 安装 CLI；它通过 Pi SDK 使用 Claude (Anthropic) 作为底层模型。
2. 按 Milestone → Slice → Task 组织工作：Milestone 是可交付版本（4–10 个 slice），Slice 是一个可演示的垂直能力（1–7 个 task），Task 是一个 context-window 大小的单元。
3. 遵守铁律：一个 task 必须能放进一个 context window；放不下就拆成两个 task。
4. 在项目中创建 `ROADMAP.md`，按 Milestone/Slice 结构写清每个 slice 的目标。
5. 创建 `PROJECT.md`，写项目描述、技术栈和约定。
6. 运行 `/gsd init`：从 `ROADMAP.md` 和可选 `PROJECT.md` 生成 `.gsd/` 目录，创建初始 `STATE.md`，注册 milestones/slices，设置 cost ledger。
7. 运行 `/gsd auto` 进入主自动模式：读取 `.gsd/STATE.md`，每个 unit 在 fresh session 中派发，处理恢复，推进整个 milestone。
8. 给 `/gsd auto` 加选项：`--budget 5.00` 在成本超过 $5 时暂停；`--milestone M1` 只运行 milestone 1；`--dry-run` 只显示 dispatch plan 而不执行。
9. 用 `/gsd status` 查看当前位置、每个 slice 成本、token 使用和队列。
10. 用 `/gsd run` 手动执行单个 unit：`--slice M1/S4` 跑 research + plan + execute；`--task M1/S4/T2` 跑单个 task；`--phase research M1/S4` 只跑 research；`--phase plan M1/S4` 只跑 plan。
11. 用 `/gsd migrate` 从 v1 迁移旧 `.planning/` 目录；可跟路径参数迁移指定目录。
12. 用 `/gsd costs` 查看详细成本分解与预测；`--by-phase` 按阶段；`--by-slice` 按 slice；`--export costs.csv` 导出 CSV。
13. 按自动模式状态机推进：Research → Plan → Execute (per task) → Complete → Reassess → Next Slice。
14. 让每个 phase 都在 fresh session 中运行，并把上下文预内联到 dispatch prompt：Research 接收 `PROJECT.md`、`ROADMAP.md`、slice 描述、codebase index，产出 `RESEARCH.md`。
15. Plan 接收 research 输出、slice 描述、must-haves，产出 `PLAN.md`，其中包含任务拆分和验证步骤。
16. Execute 第 N 个 task 时接收 task plan、先前 task 摘要、依赖摘要、`DECISIONS.md`，产出提交到 git 的工作代码。
17. Complete 接收所有 task 摘要和 slice plan，产出 `SUMMARY.md`、UAT script，并更新 `ROADMAP.md`。
18. Reassess 接收完成的 slice 摘要和完整 `ROADMAP.md`，产出修正后的 roadmap。
19. 在每个 task plan 中写 must-haves：用 shell 命令或文件存在检查写成显式、可勾选的完成标准。
20. must-haves 示例包括：`npm test -- --testPathPattern=auth` 0 失败；`src/features/auth/jwt.ts` 存在并导出 `signToken`、`verifyToken`；`curl -X POST http://localhost:3000/auth/login` 返回 200 和 `{ data: { token } }`；`npx tsc --noEmit` 退出 0。
21. 让 Execute phase 只有在 LLM 能勾选每个 must-have 后才结束。
22. 让 GSD 在 auto mode 自动管理 git：开始时从 main 创建 `milestone/M1` worktree 分支。
23. 每个 task 用结构化消息提交，例如 `[M1/S1/T1] implement user model`。
24. 每个 slice 提交一个 summary commit。
25. milestone 完成后用 squash merge 将 `milestone/M1` 合并到 main，作为一条干净记录，例如 `[M1] Auth system`。
26. 崩溃恢复：GSD 在 unit 开始时写 `.gsd/LOCK`，干净完成时删除；进程死亡后下次运行 `/gsd auto` 会检测 lock 并自动恢复。
27. 恢复简报从所有已到达磁盘的 tool call（文件写入、shell 输出、部分完成）合成，让恢复 session 有上下文连续性。
28. 成本控制：用 `/gsd auto --budget 10.00` 设置预算上限，在超支前暂停 auto mode。
29. 成本记录在 `.gsd/costs/ledger.json`，包含每个 unit 的 `id`、`model`、`inputTokens`、`outputTokens`、`costUsd`、`completedAt`，以及 `totalCostUsd`、`budgetUsd`。
30. 在 `.gsd/DECISIONS.md` 记录架构决策；该文件自动注入每个 task dispatch，LLM 会跨 session 遵守。
31. 决策条目格式：`D1: 决策标题`、`Date`、`Reason`、`Impact`。
32. 卡住检测：同一 unit 两次派发未产出预期 artifact 时，GSD 先重试一次，带深度诊断 prompt，包含期望 vs 磁盘实际存在。
33. 第二次仍失败则停止 auto mode，并报告卡住的 unit、期望文件、最后 session log 路径，以及用 `/gsd run --task M1/S3/T1` 手动重试。
34. 技能集成：在项目创建 `SKILLS.md`，用 `- name: postgres-kysely` 等格式列出项目技能。
35. GSD 在 research 阶段自动检测并安装相关技能，并注入 research 和 plan dispatch prompt，提供项目栈的精选知识。
36. 超时监督：软超时默认 8 分钟，发送“please wrap up”引导消息。
37. 空闲超时默认 3 分钟无 tool calls，发送“are you stuck?”恢复提示。
38. 硬超时默认 15 分钟，暂停 auto mode，保留所有磁盘状态。
39. 在 `.gsd/config.json` 配置 `timeouts` 的 `softMinutes`、`idleMinutes`、`hardMinutes`，以及 `defaultModel`、`researchModel`。
40. TypeScript 集成：用 `import { GSDProject, AutoRunner } from 'gsd-pi';` 加载项目并扩展。
41. 用 `await GSDProject.load('/path/to/project')` 加载项目，用 `await project.getState()` 查看 `currentMilestone`、`currentSlice`。
42. 用 `new AutoRunner(project, { budget, onUnitComplete, onStuck })` 编程运行单个 slice，例如 `await runner.runSlice('M1/S4')`。
43. 自定义 dispatch hooks：在 `.gsd/hooks.ts` 导出 `beforeTaskDispatch`，返回 `extraContext` 追加自定义上下文。
44. 在 `.gsd/config.json` 中用 `"hooks": "./hooks.ts"` 注册 hooks。
45. Roadmap 重新评估：每个 slice 完成后 GSD 运行 reassessment pass，可能重排 upcoming slices、拆分过大的 slice、标记不再需要的 slice、添加发现的新 slice。
46. LLM 原地编辑 `ROADMAP.md`；用 `git diff ROADMAP.md` 审查。
47. 用 `{"reassessment": false}` 禁用重新评估。
48. 故障排查：auto mode 立即停止并提示 "no pending slices" 时，所有 slice 被标记 `[x]`；移除该项的 `[x]` 并删除 `.gsd/milestones/M1/slices/S3/SUMMARY.md` 来重置。
49. LLM 反复失败 must-haves 时，检查 `.gsd/sessions/` 最后 session log；常见原因是 must-have 路径错误或测试命令需要环境变量；调整 task 的 `PLAN.md` 中 must-haves 并用 `/gsd run --task M1/S3/T2` 重跑。
50. 成本上限意外触发时，在 config 将 `researchModel` 设为更便宜模型，或减少 codebase index depth。
51. 干净退出后仍留 lock 文件时，执行 `rm .gsd/LOCK` 再 `/gsd auto`。
52. Git worktree 冲突时，执行 `git worktree list` 查看，`git worktree remove .gsd/worktrees/M1 --force` 移除，再 `/gsd auto` 重新创建。
53. session 文件太大无法恢复时，GSD 会自动压缩超过 24h 的 session；手动清理用 `/gsd cleanup --sessions --older-than 7d`。

适用边界 · 注意事项

• 任务很小、一次性或不需要长周期自主执行时，手动完成更直接。
• 无法使用 Node.js 18+、Claude/Anthropic 模型或 gsd-pi CLI 的环境。
• 不允许 agent 自动提交 git、创建 worktree，或仓库状态不干净且不便隔离时。