get-shit-done（GSD）plan-phase 深度解析：从 Roadmap 阶段到可执行 PLAN.md 的多智能体编排流水线
【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done
导读
plan-phase（对应/gsd:plan-phase命令）是 get-shit-done（GSD）这套基于 Claude Code 的 spec-driven 开发系统中最核心的"计划生成"环节：它把一个 Roadmap 中的阶段（Phase）转译为一组可直接交给执行器（executor）的 PLAN.md 提示词文件，并内置研究（research）、质量校验（verification）与修订（revision）闭环。本文以 commands/gsd/plan-phase.md 与其背后的完整工作流 get-shit-done/workflows/plan-phase.md 为主线，结合gsd-planner、gsd-plan-checker、gsd-phase-researcher等子智能体契约，讲解该命令的全部参数语义、编排步骤、内置安全门（gate）与产出物规范，让读者理解 GSD 如何在"执行之前"用一套可审计、可回滚的流水线把模糊的阶段目标收敛成高保真的执行蓝图。
一、plan-phase 在全生命周期中的位置
在 GSD 的阶段工作流中，plan-phase 前承discuss-phase（捕获用户设计决策，产出 CONTEXT.md）、phase（管理 Roadmap 阶段）与review（跨 AI 评审），后接execute-phase（真正执行计划）。命令自身声明的依赖为[discuss-phase, phase, review, update]，而其默认流程被定义为一条四段式管线（见 commands/gsd/plan-phase.md）：
Research (if needed) → Plan → Verify → Done与"直接让模型写计划"的朴素做法不同，plan-phase 在规划前后引入了研究（gsd-phase-researcher产出的RESEARCH.md）与校验（gsd-plan-checker对 PLAN.md 的逐维度审查）两个智能体，从而把一次性的、难以纠错的规划行为，变成可迭代、可回滚、有质量上限的工程流程。工作流对自身目的的定义也印证了这一点（get-shit-done/workflows/plan-phase.md）：
Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification. Default flow: Research (if needed) -> Plan -> Verify -> Done. Orchestrates gsd-phase-researcher, gsd-planner, and gsd-plan-checker agents with a revision loop (max 3 iterations).
工作流在运行时依赖的编排用子智能体包括（见 get-shit-done/workflows/plan-phase.md）：
| 子智能体 | 职责 |
|---|---|
gsd-phase-researcher | 为一个阶段研究技术方案，产出RESEARCH.md（定义见 agents/gsd-phase-researcher.md） |
gsd-pattern-mapper | 分析代码库已有模式，产出PATTERNS.md |
gsd-planner | 依据阶段范围创建可执行计划（契约见 agents/gsd-planner.md） |
gsd-plan-checker | 在执行前审查计划质量（契约见 agents/gsd-plan-checker.md） |
工作流文件中的
@~/.claude/get-shit-done/...是对已安装运行时位置的引用；在开源仓库中，这些文件对应get-shit-done/目录（如 get-shit-done/workflows/plan-phase.md、get-shit-done/references/ui-brand.md）。
二、命令签名与完整参数语义
命令的前置声明如下（commands/gsd/plan-phase.md）：
argument-hint: [phase] [--auto] [--research] [--skip-research] [--research-phase <N>] [--view] [--gaps] [--skip-verify] [--prd <file>] [--ingest <path-or-glob>] [--ingest-format <auto|nygard|madr|narrative>] [--reviews] [--text] [--tdd] [--mvp] requires: [discuss-phase, phase, review, update]位置参数phase可以省略——当省略时工作流会自动从 ROADMAP 中探测"下一个尚未规划的阶段"（auto-detects next unplanned phase if omitted）。阶段编号既支持整数（如2）也支持十进制（如2.1），且在进入目录查找之前必须先做归一化处理。主要标志位语义汇总如下：
| 标志 | 含义 |
|---|---|
--research | 强制重新研究：即使RESEARCH.md已存在也无条件重新派发研究员并覆盖 |
--skip-research | 跳过研究，直接进入规划（还能把智能体链条从 3 个减到 2 个，缓解部分运行时的冻结问题） |
--research-phase <N> | 纯研究模式：仅为阶段 N 派发gsd-phase-researcher、写出RESEARCH.md后在规划器运行前退出 |
--view | 纯查看：把已有的RESEARCH.md打印到 stdout，不派发任何智能体；若文件不存在则报错并提示去掉--view |
--gaps | 缺口闭合模式：读取VERIFICATION.md，跳过研究，针对验证失败的缺口补计划 |
--skip-verify | 跳过计划校验循环 |
--prd <file> | 使用 PRD/验收标准文件替代 discuss-phase：自动把需求解析进CONTEXT.md并整体跳过 discuss-phase |
--ingest <path-or-glob> | 使用一个或多个 ADR 文件替代 discuss-phase：自动把已锁定的决策与范围围栏解析进CONTEXT.md |
--ingest-format <auto\|nygard\|madr\|narrative> | 可选 ADR 解析格式覆盖（默认auto） |
--reviews | 依据/gsd:review产出的REVIEWS.md中的跨 AI 评审反馈进行重规划 |
--text | 用纯文本编号列表替代 TUI 菜单（Claude Code 远程/rc会话必需） |
--mvp | 垂直 MVP 模式：任务按"功能切片"（UI→API→DB）而非水平分层组织；新项目 Phase 1 还会产出SKELETON.md |
工作流正文中还补充了若干命令文档未展开的标志：--skip-ui（跳过 UI-SPEC 检查）、--bounce/--skip-bounce（外部计划精修脚本开关）、--chunked（分块规划模式）、--force（覆盖"已关闭阶段"门禁）、--auto/--chain（自动推进链）、--skip-ai-spec（跳过 AI 设计契约检查）。--tdd模式下规划器会对符合条件的任务套用type: tdd启发式规则（详见 get-shit-done/references/tdd.md）。
两个重要互斥与组合规则值得注意：
--prd与--ingest互斥，同时给出时直接报错退出：Invalid arguments: cannot combine --prd with --ingest.--reviews与--gaps互斥（冲突模式）；--mvp与--prd则可组合（PRD 决定"骨架要证明什么"，两者正交）。
三、编排的初始化与运行前提
plan-phase 并非让模型自由发挥，而是由一个严格的编排脚本驱动。初始化阶段（工作流 Step 1）通过一次集中式 SDK 调用装载全部上下文（路径而非全文，以节省编排器上下文窗口）：
INIT=$(gsd-sdk query init.plan-phase "$PHASE") if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi AGENT_SKILLS_RESEARCHER=$(gsd-sdk query agent-skills gsd-phase-researcher) AGENT_SKILLS_PLANNER=$(gsd-sdk query agent-skills gsd-planner) AGENT_SKILLS_CHECKER=$(gsd-sdk query agent-skills gsd-plan-checker) CONTEXT_WINDOW=$(gsd-sdk query config-get context_window 2>/dev/null || echo "200000") TDD_MODE=$(gsd-sdk query config-get workflow.tdd_mode 2>/dev/null || echo "false") MVP_MODE_CFG=$(gsd-sdk query config-get workflow.mvp_mode 2>/dev/null || echo "false")从 init JSON 中解析出的字段包括：各子智能体所用模型（researcher_model、planner_model、checker_model）、研究/校验开关、commit_docs、text_mode、阶段元数据（phase_found、phase_dir、phase_number、phase_name、phase_slug、padded_phase）、已有产物标记（has_research、has_context、has_reviews、has_plans、plan_count）、阶段状态phase_status（#3569，取值为Pending | Planned | In Progress | Executed | Complete | Needs Review）以及response_language（若配置，需注入到所有子智能体提示词中）。
上下文窗口相关逻辑值得一提：当CONTEXT_WINDOW >= 500000（约等于 1M 模型）时，规划器提示词会额外携带最近 3 个已完成阶段的CONTEXT.md/SUMMARY.md/LEARNINGS.md，以及当前阶段在 ROADMAP 中Depends on:字段显式声明的所有阶段的上下文（显式依赖无视新旧恒载入）。这是为了让"巨型上下文模型"在做规划时能保持跨阶段一致性，同时用"最近 3 个 + 显式依赖"的界限把预算控制住。
若planning_exists为 false，则直接报错要求先运行/gsd:new-project。
四、进入规划前的防御性门禁（Gates）
GSD 把校验点抽象为 Pre-flight / Revision / Escalation / Abort 四类门禁（get-shit-done/references/gates.md），plan-phase 是这些模式最密集的使用者之一。
4.1 Git 分支不变量（Step 0）
工作流开篇即声明：plan-phase 期间禁止创建、重命名或切换 git 分支。分支身份在 discuss-phase 阶段就已确立，归属用户的 git 工作流。即使 init JSON 中的phase_slug与当前分支名不一致，这也是预期行为——ROADMAP 中的阶段改名只是计划层面的变更，不改变分支名。
4.2 已关闭阶段门禁（Step 1.5，#3569）
Complete意味着该阶段既有全部 SUMMARY 又有status: passed的VERIFICATION.md。对一个已关闭阶段重新规划，会静默重写不再匹配已交付代码的计划文档，因此工作流默认硬性拦截，除非显式--force：
if [ "${phase_status}" = "Complete" ]; then if [[ "$ARGUMENTS" =~ (^|[[:space:]])--reviews([[:space:]]|$) ]]; then # --reviews on a closed phase is never legitimate ... exit 1 fi if [ "$FORCE_REPLAN" != "true" ]; then # Replanning a closed phase will overwrite plan docs that no longer match ... exit 1 fi # FORCE_REPLAN=true: continue, but emit a banner fi值得注意的边界：Executed与Needs Review不在拦截范围内——它们表示"规划已完成但验证未通过"，此时重规划是合法下一步。另外--reviews对已关闭阶段永远不合法，即使加--force也不行，提示应开后续阶段或对已关闭阶段的提交提 issue。
4.3 参数归一化与运行模式解析（Step 2）
--research-phase <N>会覆盖位置参数，把RESEARCH_ONLY置为 true，后续规划器/校验器/验证/缺口/弹跳等步骤全部跳过（该模式替代了被删除的/gsd-research-phase命令，#3042）。当已有RESEARCH.md时，纯研究模式提供三分支菜单：1. Update（重派研究员刷新）、2. View（打印后退出）、3. Skip（干净退出）。
4.4 文本模式与 MVP 模式解析
TEXT_MODE在--text出现或 init JSON 的text_mode为 true 时启用，届时所有AskUserQuestion都替换为"编号列表 + 输入数字"，以兼容 Claude Code 远程会话（/rc），TUI 菜单在 Claude App 中不可用。
MVP 模式通过集中式查询动词phase.mvp-mode解析，优先级链（首个命中即赢）为：CLI 标志 → ROADMAP 中**Mode:** mvp→ 配置workflow.mvp_mode→ false。查询动词是全系统唯一事实源，不允许在工作流里重复实现该链。此外该模式是每阶段全有或全无的（PRD 决策 Q1），绝不允许按任务选择性地应用。
Walking Skeleton 门：当MVP_MODE=true且padded_phase == "01"且不存在任何先前阶段 SUMMARY（全新项目）时，规划器进入 Walking Skeleton 模式（PRD 决策 Q2，仅新项目），除PLAN.md外还需产出SKELETON.md，其模板见 get-shit-done/references/skeleton-template.md，且计划必须覆盖"项目脚手架 + 路由 + 一条真实 DB 读写 + 一次真实 UI 交互 + 开发部署"这一最薄的端到端切片。
五、三种"上下文来源"表达路径
plan-phase 有两种便捷表达路径可完全跳过 discuss-phase，另有一条标准路径。
5.1 PRD 表达路径（Step 3.5，--prd）
读取 PRD 文件后，编排器负责：
- 抽取 PRD 中的所有需求、用户故事、验收标准与约束，每条都映射为一条锁定决策（PRD 中一切皆锁定）；
- 标记 PRD 未覆盖的区域为
Claude's Discretion； - 从 ROADMAP.md 以及 PRD 引用的 specs/ADRs 中抽取规范化引用并展开为完整相对路径（强制）；
- 在阶段目录写出
CONTEXT.md，其骨架为<domain>（Phase Boundary）、<decisions>（Implementation Decisions）、<canonical_refs>、<specifics>、<deferred>五段式； - 以
docs(${padded_phase}): generate context from PRD提交，随后跳过 Step 4直接进入研究处理。
5.2 ADR 摄取表达路径（Step 3.6，--ingest）
逐个通过get-shit-done/bin/lib/adr-parser.cjs（--input、--format）解析 ADR 并归一化记录：
- 状态门：拒绝
superseded/rejected/deprecated，对proposed告警，缺失状态默认视为accepted； - 空决策回退：若所有 ADR 的
decisions[]均为空，则输出ADR ingest produced no locked decisions; fall back to discuss-phase for this phase.并退出引导用户运行/gsd:discuss-phase {N}； - 生成的
CONTEXT.md中把consequences_positive[]映射为 Success Criteria、consequences_negative[]映射为 Risk Summary，并标记**Source:** ADR Ingest Express Path。
5.3 标准路径：CONTEXT.md 缺失时的分叉（Step 4）
若既无 PRD 又无 ingest，且阶段目录里没有 CONTEXT.md，编排器根据workflow.discuss_mode配置向用户提问：
discuss（默认）模式：推荐先运行/gsd:discuss-phase {X}捕获设计决策；assumptions模式：推荐"先分析代码库并浮现假设"再规划；- 或选择"在无上下文情况下继续，仅用研究 + 需求规划"。
关键实现约束（#1009）：编排器绝不能把 discuss-phase 作为嵌套 Skill/Task 调用——AskUserQuestion在嵌套子上下文中工作不正常。正确做法是打印命令并退出，让用户在顶层执行后再重跑 plan-phase。
5.4 AI-SPEC / UI-SPEC / 安全 / Schema 门
规划器真正开工前，还有一组条件门在 Step 4.5–5.7 依次触发：
- AI-SPEC 检查：若阶段目标命中
agent|llm|rag|chatbot|embedding|langchain|llamaindex|crewai|langgraph|openai|anthropic|vector|eval|ai system等关键词且无*-AI-SPEC.md，则非阻塞提示运行/gsd:ai-integration-phase {N}； - 安全威胁模型门：
workflow.security_enforcement缺省即启用（显式false才关闭），启用时每份 PLAN.md 必须含<threat_model>块，按workflow.security_asvs_level（默认 1）与workflow.security_block_on（默认 high）配置； - UI 设计契约门：用无 shell 的 Node 词边界检测（[仓库中对应的
bin/lib/ui-safety-gate.cjs逻辑，shell 内嵌版本 #3718 已去除 locale 依赖]）判定阶段是否含前端指示；若含前端指示而无*-UI-SPEC.md，在--auto链上自动调gsd-ui-phase生成，手动调用则打印提示后退出（可/gsd:ui-phase {N}或/gsd:plan-phase {N} --skip-ui逃生）； - Schema Push 检测门：扫描阶段范围/
CONTEXT.md/RESEARCH.md是否命中各 ORM 的文件模式，命中则注入一条[BLOCKING]schema push 任务（防止"类型来自配置、实际数据库未变"造成的假阳性验证）：
| ORM | 文件模式 | push 命令 |
|---|---|---|
| Payload CMS | src/collections/**/*.ts、src/globals/**/*.ts | npx payload migrate（非 TTY：CI=true PAYLOAD_MIGRATING=true npx payload migrate） |
| Prisma | prisma/schema.prisma、prisma/schema/*.prisma | npx prisma db push（破坏性时--accept-data-loss） |
| Drizzle | drizzle/schema.ts、src/db/schema.ts、drizzle/*.ts | npx drizzle-kit push |
| Supabase | supabase/migrations/*.sql | supabase db push（需SUPABASE_ACCESS_TOKEN） |
| TypeORM | src/entities/**/*.ts、src/migrations/**/*.ts | npx typeorm migration:run（可-d src/data-source.ts） |
若 push 需要无法抑制的交互提示，该任务须标记autonomous: false交由人工介入。
六、研究阶段：RESEARCH.md 的产生与消费
6.1 研究决策逻辑（Step 5）
研究步骤在以下情况下被跳过：--gaps、--skip-research、--reviews。否则进入决策分叉：
- 已有
RESEARCH.md且无--research→ 复用并跳到 Step 6； - 缺失或无显式标志且非
--auto→ 询问用户是否研究，推荐"Research first"（新功能、陌生集成、架构变更）而建议 bug 修复/简单重构/已熟知任务跳过； --auto且research_enabled=false→ 静默跳过。
6.2 研究员提示词与产出
研究员收到的核心问题是："要规划好这个阶段，我需要知道什么？"（Answer: "What do I need to know to PLAN this phase well?"）。它被要求阅读CONTEXT.md（用户决策）、需求文件与 STATE.md（项目决策与历史），并遵守项目级CLAUDE.md与.claude/skills//.agents/skills/中的技能约定，最终写到{phase_dir}/{phase_num}-RESEARCH.md。
研究员返回## RESEARCH COMPLETE表示完成；## RESEARCH BLOCKED则向用户提供三选：补充上下文 / 跳过研究 / 中止。
纯研究模式早退：RESEARCH_ONLY=true时，工作流打印✓ Research-only mode complete (#3042)后干净退出，规划器/校验器块全部跳过——这是跨阶段研究、提交规划方法前的文档评审、以及"无需重规划即可修正研究"（correction-without-replanning）场景的廉价通道。
6.3 验证策略（Nyquist）产物（Step 5.5）
若nyquist_validation_enabled与research_enabled均为真，且RESEARCH.md含## Validation Architecture段，则按 get-shit-done/templates/VALIDATION.md 模板生成{PADDED_PHASE}-VALIDATION.md并回填 frontmatter。没有 VALIDATION.md，计划将在"维度 8：Nyquist 合规"上失败。三边同时成立（研究关闭、无 RESEARCH.md、无--research）时 Nyquist 不适用，本阶段也无需这些产物。
6.4 模式映射：PATTERNS.md（Step 7.8）
当workflow.pattern_mapper未显式设为 false 且有 CONTEXT.md/RESEARCH.md 可抽取文件清单时，gsd-pattern-mapper会把要创建/修改的文件按角色与数据流分类，去代码库找最近的相似实现并摘录具体代码片段，产出PATTERNS.md供规划器参考（"复制既有约定而非重新发明"）。该步骤失败是非阻塞的（记警告并继续）。
七、规划器契约：把阶段"翻译"成可执行提示词
gsd-planner的工作哲学浓缩为一句话（agents/gsd-planner.md）："Plans are prompts, not documents that become prompts"——PLAN.md 本身就是提示词，不是将来会被转成提示词的文档。由此派生出一整套方法论。
7.1 用户决策保真（Context Fidelity）
规划器在创建任何任务前必须校验三类输入：
| CONTEXT.md 段落 | 对规划器的约束 |
|---|---|
## Decisions（D-01…） | 锁定决策必须逐字实现，任务 action 中要引用决策 ID 以保持可追溯 |
## Deferred Ideas | 严禁出现在任何计划中 |
## Claude's Discretion | 规划器自由裁量，但需在任务 action 中记录选择 |
若研究与用户锁定决策冲突（如研究推荐库 Y 但用户锁定了 X），则遵守用户决策并在 action 中注明。
7.2 严禁隐性削减范围（Scope Reduction Prohibition）
规划器契约明确禁止"v1/v2""simplified/static for now""will be wired later"等缩减性语言，并给出三处权威授权边界的例外：只有上下文成本超限（>50% 单 agent 窗口）、信息缺失、依赖冲突三类原因允许拆分或标记（planner_authority_limits）。每次规划必须做覆盖四类来源（GOAL/REQ/RESEARCH/CONTEXT）的多源审计，发现漏项就返回## ⚠ Source Audit: Unplanned Items Found，绝不带缺口静默收尾。
7.3 质量衰减曲线与上下文预算
规划器契约给出经验曲线（同一份内容也解释了为什么每个 PLAN 任务数要小）：
| 上下文占用 | 质量 | 状态 |
|---|---|---|
| 0-30% | 峰值 | 全面、彻底 |
| 30-50% | 良好 | 自信、扎实 |
| 50-70% | 下滑 | 进入效率模式 |
| 70%+ | 差 | 草率、最小化 |
规则：单个计划应在约 50% 上下文内完成，每个计划最多 2-3 个任务；任务按上下文成本而非时间估算（0-3 个文件 ≈10-15%，4-6 个 ≈20-30%，7+ ≈40% 应拆分；新子系统 ≈25-35%）。
7.4 任务解剖与类型
每个任务四要素齐全：<files>（精确路径）、<action>（具体指令，禁止fenced code block，action 是指令性散文）、<verify>（<60s 的自动化命令）、<done>（可测的完成状态）。任务类型决定自治程度：
| 类型 | 用途 | 自治性 |
|---|---|---|
auto | 一切 Claude 能独立完成的 | 全自动 |
checkpoint:human-verify | 视觉/功能验证 | 暂停等待用户 |
checkpoint:decision | 实现选型 | 暂停等待用户 |
checkpoint:human-action | 真正不可避免的人工步骤（罕见） | 暂停等待用户 |
自动化优先原则：只要 Claude 能通过 CLI/API 完成，就必须由 Claude 完成；checkpoint 只验证自动化结果，不替代它。外部服务场景下用user_setupfrontmatter 记录人类必经的配置（密钥来源、Dashboard 位置等），只含 Claude 字面上无法完成的事项。
7.5 目标回溯（Goal-Backward）与 must_haves
规划方法论要求"从终点反推"：先提出阶段目标（必须是 outcome 形态，如"可工作的聊天界面"而非任务形态"构建聊天组件"），再导出 3-7 条用户可观测的 truths、支撑每条 truth 的 artifacts、以及连接 artifacts 的 key_links。最终落到 PLAN.md frontmatter：
phase: XX-name plan: NN type: execute wave: N # 执行波次 (1, 2, 3...) depends_on: [] # 如 `01-01` files_modified: [] # 本计划触碰的文件 autonomous: true # 含 checkpoint 则为 false requirements: [] # 必须列出本计划覆盖的 REQ-ID，不得为空 user_setup: [] # 人类必做设置（可为空） must_haves: truths: [] # 可观测行为 artifacts: [] # 必须存在的文件 key_links: [] # 关键连接frontmatter 字段中requirements是硬约束：每个 Roadmap 需求 ID 至少要出现在一个计划中，空requirements的计划非法。wave在规划期预先算好，执行器直接从 frontmatter 读取。工作流在 Step 13c 还会从既有 frontmatter 派生出 ROADMAP 的波次依赖标注与跨计划约束（roadmap.annotate-dependencies，幂等操作）。
7.6 分块规划模式（Chunked Mode，Step 8.5）
当--chunked或配置workflow.plan_chunked=true时，单一的长生命周期 planner Agent 运行被拆成：一次 ~2 分钟的 outline Agent（只写PLAN-OUTLINE.md，含Plan ID | Objective | Wave | Depends On | Requirements表格，以## OUTLINE COMPLETE收尾）+ N 次每次 3-5 分钟的逐计划 Agent。每个计划独立提交、具备崩溃续跑能力——若终端被强杀，重跑/gsd:plan-phase {N} --chunked会从最后一个成功提交的计划处恢复（对已存在的、带合法 YAML frontmatter 的 PLAN.md 一律跳过不覆盖）。
7.7 规划器返回处理（Step 9-9c）
规划器返回以结构化标记驱动编排，含## PLANNING COMPLETE、## PHASE SPLIT RECOMMENDED（阶段超出保真实现预算，建议拆子阶段）、## ⚠ Source Audit: Unplanned Items Found、## CHECKPOINT REACHED、## PLANNING INCONCLUSIVE。对空返回/截断返回，走文件系统回退（Step 9a）：检查磁盘上*-PLAN.md数量，若 >0 说明"子智能体已完成但返回丢失"（典型的 Windows stdio hang 模式），提供"接受计划 / 重试规划器 / 停止"三选，保证已写盘的工作可被救回。
八、计划校验：gsd-plan-checker 的对抗性审查
8.1 前置哲学
校验器与执行后验证的关键分工（agents/gsd-plan-checker.md）：
gsd-verifier：验证代码在执行后确实达成了目标；gsd-plan-checker：验证计划在执行前将会达成目标。
两者方法论相同（目标回溯）、时序不同、对象不同。校验器采用对抗立场："假设每套计划都有缺陷，直到证据证明相反"，且每个发现必须带严重级别——BLOCKER（不修则阶段目标必然落空）或WARNING（质量/可维护性受损，可带病执行），无级别的 issue 不算有效输出。
8.2 十二个验证维度
| 维度 | 检查问题 | 典型失败 |
|---|---|---|
| 1. 需求覆盖 | 每个阶段需求是否有任务覆盖 | REQ 未出现在任何计划requirements中 → BLOCKER |
| 2. 任务完整性 | 每个任务是否有 Files+Action+Verify+Done | 缺<verify>或空<files> |
| 3. 依赖正确性 | 依赖是否有效且无环 | 循环依赖、引用不存在的计划、wave 与依赖不一致 |
| 4. 关键连接 | 工件是否被"接线"而非孤立创建 | 组件建了没人引用、API 建了没人调用 |
| 5. 范围健康 | 是否能在上下文预算内完成 | 每计划 5+ 任务（threshold 表见下） |
| 6. 验证推导 | must_haves 是否回溯到阶段目标 | truths 写成实现细节（"bcrypt installed"而非"passwords are secure"） |
| 7. 上下文合规 | 是否尊重 discuss-phase 用户决策 | 锁定决策被违背、Deferred Ideas 被实现 |
| 7b. 范围缩减检测 | 是否静默削减用户决策 | 计划"引用 D-26"却只交付静态标签 → 恒为 BLOCKER |
| 7c. 架构层合规 | 任务是否把能力放到正确的架构层 | 认证校验落在浏览器层而责任图规定在 API 层 |
| 8. Nyquist 合规 | 自动化验证是否充分、低延迟、采样连续 | 无VALIDATION.md、--watchAll标志、连续 3 个任务无自动化验证 |
| 9. 跨计划数据契约 | 共享数据管道的变换是否兼容 | 计划 A 剥离的数据恰是计划 B 需要的原始形态 |
| 10. CLAUDE.md 合规 | 计划是否遵守项目约定 | 用了 CLAUDE.md 明令禁止的库、漏掉必需步骤 |
| 11. 研究决议（#1602） | RESEARCH.md 未决问题是否全部解决 | ## Open Questions未带(RESOLVED)标记 |
| 12. 模式合规（#1861） | 计划是否引用 PATTERNS.md 中的相似模式 | 新建文件未引用类比实现 |
维度 5 的量纲阈值：每计划任务数 2-3 为佳、4 警告、5+ BLOCKER；每计划文件 5-8 为佳、10 警告、15+ BLOCKER；总上下文约 50% 为佳、70% 警告、80%+ BLOCKER。
8.3 结构化输出
校验器把所有 issue 汇总为 YAML 列表返回编排器：
issue: plan: "16-01" # 所属计划（阶段级为 null） dimension: "task_completeness" # 命中维度 severity: "blocker" # blocker | warning | info description: "..." task: 2 fix_hint: "..."整体结论要么是## VERIFICATION PASSED（附需求/计划覆盖表），要么是## ISSUES FOUND（分 blocker/warning/info 清单 + 推荐动作）。
九、修订循环与质量升级路径
9.1 修订循环（Step 12）：Check-Revise-Escalate，上限 3 轮
plan-phase 实现的正是 get-shit-done/references/revision-loop.md 中的标准模式：
prev_issue_count = Infinity LOOP: 1. 校验当前输出 2. 通过或仅剩 INFO → 接受并退出 3. 存在 BLOCKER/WARNING → a. iteration += 1；超过 3 → 升级给用户 c. issue_count >= prev_issue_count → 停滞检测，升级给用户 e. prev_issue_count = issue_count f. 携带校验反馈重新派发规划器（每次都是全新 spawn，不续上下文）修订提示词要求规划器针对性修改而非推倒重来（除非问题是根本性的），并把校验器的 YAML issue 原样注入。停滞检测（stall_reentry_count，跨重进保留、上限 2 次）在"issue 数不降"时允许用户选择进入一次自由讨论后全量重规划（re-enter Step 8）。
9.2 计划弹跳（Plan Bounce，Step 12.5）
--bounce标志或workflow.plan_bounce=true激活外部精修脚本（workflow.plan_bounce_script），默认 2 轮（workflow.plan_bounce_passes）。流程是：先备份*.pre-bounce.md→ 调用脚本 →YAML frontmatter 完整性验证→ 对弹跳后的计划重跑校验器→ 只有同时通过两者才算存活 → 提交存活计划并清理备份。任何一环失败（脚本非零退出、frontmatter 损坏、校验失败）都从备份还原，保证外部精修绝不破坏计划可解析性。--gaps与--skip-bounce都会禁用弹跳。
9.3 需求覆盖门与决策覆盖门（Step 13/13a）
- 需求覆盖门：把计划 frontmatter 中声明的 REQ-ID 集合与 ROADMAP 分配的
phase_req_ids比对，未覆盖项以REQ-ID | Description | Plans=None表格呈现，提供"重规划 / 移到下阶段 / 接受缺口"三选。 - 决策覆盖门（#2492）：翻译门禁——拒绝在 CONTEXT.md
<decisions>中的可追踪决策未被任何计划引用时把阶段标记为"已规划"。它调用check.decision-coverage-plan（缺省启用，workflow.context_coverage_gate=false才关闭）。这一点在 plan-phase 是阻断式 exit 1，而在 verify-phase 对应门是设计上非阻断的（评审发现 F15）。背后逻辑非常直白（工作流原话）："现在失败是廉价的。计划是 discuss-phase 与 execute-phase 之间的契约；如果一个决策在任何计划中都不可见，就不会有任何执行器实现它——在执行烧掉数千美元后才发现，远比现在抓住它糟糕。"
9.4 收尾四步（Step 13b-13e）
state.planned-phase：把 STATE.md 更新为Ready to execute、写入计划数与时间戳；roadmap.annotate-dependencies：给 ROADMAP 每波组加粗标注（如 "Wave 2(blocked on Wave 1 completion)"）并汇总 2+ 计划共现的must_haves.truths为跨切约束；commit_docs=true时提交全部 PLAN.md + STATE.md + ROADMAP.md；post_planning_gaps（默认 true）跑事后缺口分析：调用gsd-tools.cjs gap-analysis，用词边界匹配防止REQ-1误认REQ-10，输出确定性的Source | Item | Status表格——该报告非阻断、不重规划，只是让漏网的需求/决策在执行开始前集中现形。
十、结果呈现与自动推进
10.1 手动模式：offer_next
规划完成后输出阶段摘要：{N} plan(s) in {M} wave(s)、按波次列出计划与目标、研究/验证状态（Completed/Used existing/Skipped；Passed/Passed with override/Skipped），随后给出/gsd:execute-phase {X}主路径以及--research重研究、/gsd:review --phase {X} --all外部 AI 评审、--reviews吸收评审反馈重规划等备选。
10.2 自动推进链（Step 15）
当--auto/--chain标志或auto_advance配置生效时，plan-phase 直接经Skill 工具（而非嵌套 Task）拉起gsd-execute-phase，并以--no-transition保持链路扁平（每个阶段在同一嵌套层级运行，避免深 Agent 嵌套导致的运行时冻结）。执行器返回PHASE COMPLETE则提示下一步/gsd:discuss-phase ${NEXT_PHASE} --auto；返回GAPS FOUND / VERIFICATION FAILED则停止链路交由人工接管。手动调用时还会清理上次中断链遗留的临时链标记（workflow._auto_chain_active），且不触碰用户持久化的workflow.auto_advance偏好。
十一、运行注意事项与故障排查
11.1 编排器守则（CODEX RUNTIME）
工作流在每次Agent()调用后都插入同一条规则：立即停止本任务的其余工作——不得在子智能体活动期间继续读文件、改代码或跑测试，以避免重复工作、冲突编辑与上下文浪费。规划器/校验器 spawn 的典型形态：
Agent( prompt=filled_prompt, subagent_type="gsd-planner", model="{planner_model}", description="Plan Phase {phase}" )11.2 Windows 冻结排查
Windows 上 spawn 阶段可能因与 MCP 服务器的 stdio 死锁而冻结（文档引用了 Claude Code issue #28126）。get-shit-done/workflows/plan-phase.md 给出完整处置：强杀终端 → 清理超过 1 小时的孤儿 node 进程与~/.claude/tasks/陈旧目录 → 临时禁用非必要 MCP 服务器 → 仍不缓解则用--skip-research把 3 个智能体链条减到 2 个。
11.3 成功标准清单
工作流末尾的success_criteria是可审计的验收清单：.planning/已验证、阶段对 Roadmap 有效、CONTEXT.md 在 Step 4 尽早装载并传给所有智能体、研究完成或明确跳过、planner 在 CONTEXT.md+RESEARCH.md 之上产出计划、plan-checker 校验通过（或用户覆盖 / 达上限且用户决策）、智能体之间用户可见状态、用户明确下一步。这套清单本身就可作为团队审查 plan-phase 运行质量的模板。
小结
从命令签名到 15 个编排步骤，plan-phase 演示了 GSD 的一个核心判断：AI 规划的价值不在"一次生成"，而在"可重复、可校验、可回滚的生成过程"。它以RESEARCH.md（研究）→PATTERNS.md（模式）→PLAN.md（执行契约）→VALIDATION.md（验证策略）的产物链喂给规划器，再用gsd-plan-checker的 12 个维度（含范围缩减与决策保真这类"防偷工减料"对抗检查）做执行前把关，最后通过最多 3 轮的修订循环、需求/决策双覆盖门与事后缺口分析收敛到可执行状态。
对希望将其落地到自身流程的开发者，建议按 commands/gsd/plan-phase.md 的依赖声明，先跑通discuss-phase → phase → review → update前置环节，再以--research-phase <N>做一次纯研究热身，随后在真正规划时组合使用--mvp（垂直切片）、--chunked（崩溃续跑）与--reviews（跨 AI 评审回灌）等增强标志——并始终记得：PLAN.md 不是给人类看的文档，而是给下一个执行智能体的提示词，它的可执行精度决定了下游 execute-phase 的全部上限。
【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
