GSD-2 Planner 规划 Agent 深度指南：只产出计划、不写代码的架构设计专家

导读

Planner（规划 Agent）是 gsd-2 开源仓库中一类职责高度收敛的专职 subagent：它只产出实施计划、从不写代码，输出粒度精确到"另一个 Agent 无需任何歧义即可直接执行"。本文围绕 src/resources/agents/planner.md 这一权威定义文档展开，讲解它的角色定位、六步规划流程、计划质量标准、标准输出模板，并结合仓库中的 Agent 加载机制（frontmatter 解析）、任务计划模板、GSD 自动编排流水线（scout → planner → worker 链式模式）给出源码级佐证。读完后你将理解：如何阅读与复刻这样一个规划 Agent，如何让它的输出被下游执行 Agent 与 GSD 工具链无缝消费，以及它在"先计划、后实施"的多 Agent 协作范式中的准确位置。

Planner 的定义与 frontmatter：一个"只出计划"的 Agent 契约

Planner 的系统提示词存放在 src/resources/agents/planner.md，其 YAML frontmatter 定义了该 Agent 的元数据契约：

---
name: planner
description: Architecture and implementation planning — outputs plans, not code
model: sonnet
conflicts_with: plan-milestone, plan-slice, plan-task, research-milestone, research-slice
---

这五个字段不是摆设，而是被仓库中的 Agent 发现机制真实读取的结构化配置。src/resources/extensions/subagent/agents.ts 中的 loadAgentsFromDir（第 63-111 行）会解析每个 *.md 的 frontmatter：name 与 description 是硬性要求（缺失即跳过该文件），model 决定 Agent 默认绑定的模型（此处为 sonnet），而 conflicts_with 通过 parseConflictsWith（第 37-41 行）按逗号拆分、去空格、过滤空串，转为冲突 Agent 名列表。同一个目录还定义了 scout、worker、reviewer、refactorer、tester 等专职 Agent（见 src/resources/agents 目录），构成一套完整的专职 Agent 池。

conflicts_with 声明了 planner 与 plan-milestone、plan-slice、plan-task、research-milestone、research-slice 这些角色/单元互斥——即当流水线正在执行规划类或研究类单元时，不应再以普通 planner 身份介入，避免同一上下文中出现重复规划或职责重叠。

frontmatter 之下，正文用一句话定义了 planner 的核心行为边界：

You are a planning specialist. You analyze requirements and produce detailed implementation plans. You output plans — never code. Your plans are specific enough that another agent can execute them without ambiguity.

这句话同时划出两条铁律：只输出计划；计划必须具体到可无歧义执行。它明确将"思考架构"与"动手实现"分离——规划 Agent 与通用 worker 的分工由此确立（对比 src/resources/agents/worker.md 中"full capabilities、isolated context"的定位，worker 负责在隔离上下文中执行委派任务，而 planner 只负责设计）。

六步规划流程：从需求到有序实施序列

Planner 的内部流程被规定为六个步骤，每一步都有明确的产出意图：

1. Understand（理解目标）——弄清要构建、修改或修复什么。含糊的目标在此阶段必须被澄清，而不是带病进入设计。
2. Explore（探索代码库）——阅读现有代码，理解约束、既有模式与约定。这一阶段决定了计划是否建立在真实代码基线上，而非凭空想象。
3. Identify（识别变更面）——定位需要修改的组件及其依赖关系，找出"牵一发动全身"的地方。
4. Design（设计方案）——决定构建什么、放在哪里、如何连接。这是架构决策的主战场。
5. Sequence（排序实施步骤）——把工作排成依赖清晰的有序步骤。
6. Risk（标注风险）——明确未知项、权衡取舍与可能出错的环节。

值得注意的是，步骤 2 的"探索"在 GSD 流水线中往往被前置的 scout（侦察 Agent） 承担。在 src/resources/extensions/gsd/prompts/research-slice.md 中，scout 被明确告知："You are the scout. A planner agent will read your output in a fresh context and use it to decompose the slice into executable tasks"，并要求"Write for the planner, not for a human"——即侦察输出要面向 planner 消费，主动给出关键文件及其用途、自然切分点、最高风险/最大解锁点（first proof）、验证方式。同一约束也出现在 src/resources/extensions/gsd/prompts/guided-research-slice.md："You are the scout. A planner agent reads your output in a fresh context to decompose this slice into tasks... If the research doc is vague, the planner re-explores code you already read. If it's precise, the planner decomposes immediately."这表明 planner 的 Explore 环节是被设计为可继承 scout 压缩报告、按需再探索的——精确的研究文档能显著节省 planner 的上下文预算。

计划质量标准：什么才算一份"好计划"

Planner 被强制要求对照以下五条质量标准自检输出：

• Every step references specific files and functions——每一步都必须引用具体文件与函数。泛泛的"优化性能"不合格，重构 src/api/client.ts 中的 fetch 重试逻辑才算合格。
• Dependencies between steps are explicit——步骤间依赖关系必须显式声明，执行方据此确定先后顺序与并行可能。
• Each step is small enough to verify independently——每步足够小、可独立验证。这保证下游执行 Agent 在隔离上下文中能单步确认成效。
• Trade-offs are stated with reasoning, not just chosen silently——取舍必须说明理由，而不是悄悄替执行者做决定。
• Risks and unknowns are flagged, not hidden——风险与未知项必须显式标注，不允许隐藏。

"可独立验证"这一点在 GSD 的落地模板中被进一步制度化。看 src/resources/extensions/gsd/templates/task-plan.md 中的 Verification 与 Verify Rules 小节：

## Verification
- {{howToVerifyThisTaskIsActuallyDone}}
- {{commandToRun_OR_behaviorToCheck}}

## Verify Rules
- Use a real executable check, not prose.
- If the check needs file-content assertions, write a `node:test` file and run it with `node --test` or a package test script.
- Do not use inline `node -e` assertions for verification.

"Use a real executable check, not prose"正是对"每个步骤足够小、可独立验证"的执行级强化——验证必须是真实可运行的检查，而不是一段描述性文字。

标准输出格式：一份可被机器与 Agent 双读的计划书

Planner 的输出被规定为固定结构的 Markdown 文档，各节职责如下：

## Goal
What we're building and why.

## Current State
Relevant architecture and code that exists today.

## Plan

### Step 1: [action]
- **Files:** `path/to/file.ts` — what changes
- **Depends on:** nothing / Step N
- **Verification:** how to confirm this step worked

### Step 2: [action]
(same structure)

## Trade-offs
Decisions made and alternatives considered.

## Risks
What could go wrong and how to mitigate it.

要点解析：

• Goal：一句话说清"构建什么、为什么"，避免执行者迷失方向。
• Current State：记录当下真实存在的架构与代码，为后续步骤提供基线，也防止计划与代码库实际状态脱节。
• Plan：每个 Step 必须携带三个字段——Files（改动文件及改动内容）、Depends on（依赖的前置步骤或"nothing"）、Verification（如何确认该步完成）。三步结构全部继承自原文档，这是整个模板的执行骨架。
• Trade-offs：已做决策与备选方案。呼应质量标准"取舍必须说明理由"。
• Risks：可能出错的地方与缓解措施，必须显式呈现而非隐藏。

这套输出格式与仓库中实际落盘的计划产物高度一致。在 GSD 的 refine-slice 单元（src/resources/extensions/gsd/prompts/refine-slice.md）中，planner 把 slice 草图扩展为完整计划后，必须通过 gsd_plan_slice 工具持久化，且每个任务必须携带固定键：taskId、title、description、estimate、files、verify、inputs、expectedOutput，可选 observabilityImpact。其中 files、inputs、expectedOutput 必须是字符串数组（即使只有一个路径也要写成 "expectedOutput": ["src/index.ts"]），因为这些路径会被机器解析以推导任务依赖——这正对应模板 Step 中 Files: 字段的机器化版本。

在 GSD 流水线中的位置：scout → planner → worker 链式协作

Planner 不是孤立存在的，它在仓库的编排策略中被明确嵌入"先计划、后实施"的链式流水线。证据来自 src/resources/extensions/subagent/index.ts 中的编排规则：

• 第 826 行："Use chain mode to pipeline: scout finds context, planner designs, worker implements."——链式模式下 scout 负责找上下文，planner 负责设计，worker 负责实现。
• 第 831 行："Before any change touching ≥2 packages, the orchestration kernel, auto-mode, or a public API, dispatch the planner agent first. Plan first, then implement."——凡是触及 2 个及以上包、编排内核、auto-mode 或公共 API 的变更，必须先派发 planner 做计划，再进入实现。
• 第 833 行："Use chain mode for sequential pipelines where each step's output feeds the next: scout → planner → worker, or worker → reviewer → worker."——链式模式的输出逐级喂养下游。

这三条规则精确刻画了 planner 的生态位：它是"上下文侦察"与"隔离执行"之间的设计枢纽。上一环节是 scout 的研究产物（通过 gsd_summary_save 以 artifact_type: "RESEARCH" 落盘并入库），下一环节是 worker 等执行 Agent 以隔离上下文消费任务计划。而在 src/resources/extensions/gsd/prompts/reassess-roadmap.md 中还有反向引用：当某 slice 完成后若调整了 roadmap，"the next slice's researcher and planner agents work from your updated version"——说明 planner 还要消费更新的路线图与已完成 slice 的总结，保持计划与现实同步。

质量护栏：任务规模预警与计划自审计

在细化环节（refine-slice），planner 产出的计划还要经过规模与完整性自审计：

• 规模预警：src/resources/extensions/gsd/templates/task-plan.md 的 frontmatter 注释写明："Tasks with 10+ estimated steps or 12+ estimated files trigger a warning to consider splitting."——estimated_steps 与 estimated_files 两个预估字段由计划校验器读取，帮助 planner 判断单个任务是否过度膨胀。
• 依赖可推导：模板要求每个 Input/Output 必须是反引号包裹的文件路径（"These paths are machine-parsed to derive task dependencies — vague descriptions without paths break dependency detection"），从机制上杜绝模糊描述。
• 完整性自审计：refine-slice 提示词要求"Self-audit the plan. If every task were completed exactly as written, the slice goal/demo should be true. Every must-have maps to a task."——即若所有任务按计划完成，slice 目标必须为真，任何 must-have 都必须有对应任务。

此外，planner 的设计产物还会被下放到任务级模板的其他小节：Failure Modes（依赖失败时的 error/timeout/malformed 策略表）、Load Profile（共享资源、单次操作成本、10x 负载断点）、Negative Tests（畸形输入/错误路径/边界条件）与 Observability Impact（信号变化与未来 Agent 的排查途径）。这些小节在简单任务中被允许整体省略（模板注释明确 "OMIT ENTIRELY for trivial tasks"），体现了"计划规模与任务复杂度成正比"的设计取向。

如何查看与复刻一个 Planner Agent

• 查看内置定义：直接阅读 src/resources/agents/planner.md，它同时是"如何写一个规划 Agent"的范例——frontmatter 声明身份与冲突约束，正文定义流程、质量门槛与输出模板。
• 理解加载机制：src/resources/extensions/subagent/agents.ts 说明 Agent 从两类目录发现：用户级目录（getAgentDir()/agents）与项目级目录（向上逐级查找 .gsd/agents 或 .pi/agents，见第 121-135 行 findNearestProjectAgentsDir）。如果你要在自己的项目中复刻 planner，将同样的 frontmatter + 系统提示词放入 .gsd/agents/planner.md 即可被发现与加载。
• 与其他 Agent 配套阅读：scout（侦察与上下文压缩）、worker（隔离执行）、reviewer（结构化评审）构成了 planner 上下游的完整闭环；src/resources/extensions/gsd/prompts/refine-slice.md 则展示了 planner 在 GSD 流水线中的真实作业环境与 gsd_plan_slice 持久化约定。

小结

Planner Agent 是 gsd-2 多 Agent 协作体系中的"架构设计中枢"：通过"只出计划、不写代码"的严格边界、六步流程、五条质量标准和固定的 Goal/Current State/Plan/Trade-offs/Risks 输出模板，它把模糊需求转化为可被 scout 研究结果喂入、可被 worker 无歧义执行的精确实施序列。源码层面，frontmatter 的解析（conflicts_with 与 model）、任务计划模板的机器可解析路径、gsd_plan_slice 的持久化约定，以及"变更触及 ≥2 个包必须先派发 planner"的编排硬规则，共同保证了"先计划、后实施"这一原则在真实流水线中不是口号而是机制。