企业官网建设流程全解析

如何写出高质量的实施计划：agent-toolkit的gepetto多阶段规划技能深度剖析

【免费下载链接】agent-toolkitA curated collection of skills for AI coding agents. Skills are packaged instructions and scripts that extend agent capabilities across development, documentation, planning, and professional workflows.项目地址: https://gitcode.com/gh_mirrors/agentt/agent-toolkit

你是不是也有这样的经历：对 AI 编码助手说一句"帮我做个登录系统"，它立刻开写，结果反复返工、边界情况漏掉一大片？agent-toolkit 中的gepetto正是一剂良方——它是一款多阶段规划技能（planning skill），通过"调研 → 访谈 → 规格综合 → 计划生成 → 多 LLM 评审 → 章节拆分"六个环节，把模糊的想法雕琢成一份高质量实施计划。读完本文，你将在 10 分钟内掌握它的全部工作机制，以及让 AI 产出靠谱实施计划的 5 个实用技巧。

🪵 gepetto 是什么：把"原木"雕成"木偶"

gepetto 的名字致敬了《木偶奇遇记》中的杰佩托老爹：粗木经过耐心雕琢，才会变成活灵活现的木偶。同理，这个技能也不追求"一句话出方案"，而是像工匠一样分步打磨：

这套"先想清楚，再动手"的理念正是它与传统"边写边改"模式的根本区别。技能的完整定义见 skills/gepetto/SKILL.md，其中一行就概括了整条流水线：

Research → Interview → Spec Synthesis → Plan → External Review → Sections

⚙️ 工作原理：gepetto 的 6 个阶段逐层拆解

gepetto 内部其实是一个17 步工作流，对外抽象为 6 个阶段。每个阶段都有明确的输入、输出和落盘文件，全程可追溯。

阶段一：智能调研（Research）

gepetto 会先阅读你的规格文件，自动提取其中提到的技术、功能类型与架构模式，生成 3–5 个候选调研主题（如"React 认证模式""Redis 会话存储最佳实践"），然后向你确认是否调研代码库（现有模式与约定）和网络（最新最佳实践）。

两个调研任务会并行交给子代理执行，结果由主上下文汇总后写入claude-research.md。详细规则见 research-protocol.md。这一步的价值在于：访谈时不会再问调研已回答的问题，而是追问调研中暴露出的复杂点。

阶段二：需求访谈（Interview）

这是最容易被低估、也最能拉开计划质量差距的一步。gepetto 扮演"对本项目负责的高级架构师"，遵循 interview-protocol.md 中的提问哲学：

• ✅ 好的问题："X 失败时是重试、记录日志还是提示用户？"
• ❌ 坏的问题："还有什么要补充的吗？"

每轮只问 2–4 个开放式问题，直到它有信心不靠任何假设就能写出详细计划为止。完整问答会存档为claude-interview.md——需求藏在用户脑中的那些"理所当然"，正是这里被问出来的。

阶段三：规格综合（Spec Synthesis）

三个来源在此熔为一体，写入claude-spec.md：

1. 你的原始规格文件（哪怕只是几条要点）
2. 调研发现（若执行过阶段一）
3. 访谈答案（阶段二）

从此往后，一切都以这份"合成规格"为准，避免原始需求中的模糊表述污染计划。

阶段四：生成实施计划（Plan）

产出的claude-plan.md是核心交付物。gepetto 有一条硬性要求：为陌生读者而写——任何没有背景知识的工程师（或 LLM）只读这一份文档，就应该完全理解我们做什么、为什么做、怎么做。这解释了为什么计划必须自包含，不能依赖聊天记录。

阶段五：外部多 LLM 评审（External Review）

gepetto 会把claude-plan.md同时发给Gemini CLI和Codex CLI两个独立评审者，让它们以"资深架构师"身份并行审查：潜在的坑与边界情况、遗漏项、安全漏洞、性能问题、架构缺陷、模糊需求（提示词设计见 external-review.md）。

评审意见存入reviews/目录后，gepetto 会写一份claude-integration-notes.md，逐条说明采纳了哪些建议、放弃了哪些以及原因——你始终是最终裁决者，外部 AI 只提供参考。若未安装对应 CLI，该阶段自动跳过，工作流不中断。

阶段六：章节拆分（Sections）

最终计划会被切成编号章节（section-01-foundation、section-02-config……），每章由并行子代理独立撰写。每个章节文件严格遵循 section-splitting.md 中的模板，必须包含：

• 背景：为什么存在这一节
• 需求：完成时必须为真的条件
• 依赖：requires / blocks 关系
• 实现细节+验收标准（勾选清单）+待创建/修改文件

关键原则是"完全自包含"：实施者只读这一个文件就能开工，无需翻回总计划。sections/index.md还会给出依赖图与执行顺序，标明哪些章节可并行开发（格式规范见 section-index.md）。

🚀 快速上手：一条命令启动规划流程

第 1 步：准备规格文件。它可以非常粗糙，比如：

planning/ └── auth-spec.md # 认证系统 需要 OAuth2 登录（Google / GitHub）， 会话存 Redis，API 鉴权用 JWT

第 2 步：运行技能

/gepetto @planning/auth-spec.md

第 3 步：跟着提示走。回答调研选择与访谈问题，审阅计划，完成。整个规划目录会包含 9 类产物（详见下文文件清单），并自动生成两份"一键执行"文件，供 ralph-loop 或 Ralphy 自动实施。

💡 安装方式：按 skills/gepetto/README.md 的说明，通过 Claude Code 插件市场安装，或将skills/gepetto目录复制到~/.claude/skills/即可。

📦 交付物：规划完成后你得到什么

运行结束后，planning/目录会呈现这样一棵"计划树"：

🔁 计划变代码：3 种落地方式

无论哪种方式，章节的自包含设计都保证了执行侧"零上下文切换成本"。

🎯 5 个技巧：让实施计划质量更上一层楼

1. 从"有点东西"开始——哪怕三五个要点也够，访谈阶段会帮你把细节问出来；
2. 认真回答访谈——这是隐藏需求浮出水面的唯一窗口，别急着点"随便你"；
3. 批判性审阅外部评审——外部 LLM 能发现盲区，但也可能过度设计，取舍权在你；
4. 善用并行章节——无依赖的章节可以同时开工或分派给不同人/不同 AI 会话；
5. 迭代而非推倒重来——计划不满意时，编辑claude-plan.md后重跑章节生成即可。

中断了怎么办？自动断点续跑

gepetto 的一个实用设计：规划状态完全由落盘文件决定。上下文耗尽、中途休息都没关系，用同一个规格文件再次执行/gepetto @planning/auth-spec.md，它会根据已存在的文件自动判断从哪一步续跑（完整恢复点对照表见 SKILL.md）。想从头再来，删掉规划目录里的文件即可。

⚖️ 什么时候该用、什么时候该跳过

📍 延伸阅读：去哪里看源码与协议

• 技能主定义（17 步工作流全文）：skills/gepetto/SKILL.md
• 用户文档（含安装与 ralph-loop / Ralphy 集成）：skills/gepetto/README.md
• 五份阶段协议文档：skills/gepetto/references/

gepetto 证明了一个朴素却常被忽视的道理：AI 写代码的速度早已不是瓶颈，想清楚要做什么才是。把规划这件事本身交给一条可审计、可续跑、可多人评审的流水线，你的下一次开发就从"边写边返工"变成了"按计划推进"。🪵

【免费下载链接】agent-toolkitA curated collection of skills for AI coding agents. Skills are packaged instructions and scripts that extend agent capabilities across development, documentation, planning, and professional workflows.项目地址: https://gitcode.com/gh_mirrors/agentt/agent-toolkit