dev-plan

步骤 0：发现项目根目录

运行发现脚本：

bash "$DISCOVER" root

其中，$DISCOVER 是此技能目录中 scripts/discover.sh 的绝对路径。

路径安全——工具调用之间的 shell 状态不会保留，因此每次调用都必须提供完整脚本路径：

• 使用 $HOME，而不是直接写出主目录路径（例如，使用 bash "$HOME/code/…/discover.sh"，而不是 bash "/Users/name/…/discover.sh"）。这样可以避免臆造用户名。
• 从工具输出中复制值。 重用先前命令返回的值（例如 $PROJECT_ROOT）时，请从该命令的输出中原样复制。切勿凭记忆重新输入路径。
• 首次调用时验证：如果脚本调用因 "No such file" 失败，说明路径有误——停止并根据技能加载上下文重新推导路径。
• 切勿忽略非零退出码。 如果此技能中的任何脚本失败，请停止并在继续之前报告错误。

将输出保存为 $PROJECT_ROOT。如果命令失败，请告知用户并停止。

首要指令

唯一交付内容是写入 $PROJECT_ROOT/.dev/$FEATURE_NAME/ 的 PRD 文件。 编写文档，而不是代码。每次会话都必须以磁盘上的文件结束。

这是 3 个技能组成的系统（/dev-plan → /dev-checkpoint → /dev-resume）的一部分。其他技能会使用状态标记（⬜ 待处理；✅/⏭️/⛔/⏹️ 已解决）、阶段门、文件变更摘要和子 PRD 链接来解析 PRD 文件。编写步骤时使用 ⬜——其他任何表情符号标记都会被解析为无法识别的状态：该步骤仍会计入总数，但会被视为未完成，且 status-update 会拒绝覆盖它。

AGENTS

此技能使用专用 Agent 进行研究和规划：

• prd-researcher（青色）——研究代码库中的模式、依赖项和参考实现
• prd-planner（绿色）——设计实现阶段和文件变更

Agent 定义位于此技能目录中的 agents/ 下。

阶段 1：了解需求

$ARGUMENTS

此阶段的 3 个关键问题：

1. 你想构建什么功能？（简要描述）
2. 它要解决什么问题？（用户需求或业务要求）
3. 是否有参考实现？（现有代码或类似功能）

路径 A——已提供参数

如果上方的 $ARGUMENTS 非空（用户提供了功能描述）：

1. 根据提供的文本推导出全部 3 个问题的答案。
2. 用 2-3 句话概述你的理解。
3. 直接进入阶段 2。 不要请求确认。

路径 B——未提供参数

如果上方的 $ARGUMENTS 为空（用户未提供参数运行 /dev-plan）：

1. 提出上述 3 个问题。
2. 停止。不要输出其他内容。收到用户回答前不要继续。
3. 收到回答后，用 2-3 句话概述你的理解。
4. 询问：“这符合你的意图吗？请确认，我就开始研究。”
5. 在用户明确确认之前，不要进入阶段 2。

护栏：路径 B 获得确认或路径 A 完成概述后，立即开始研究。不要停留在此阶段。

步骤 1.5：推导并验证 $FEATURE_NAME

创建任何目录或文件之前，请在 $FEATURE_NAME 中设置安全的功能标识。

使用验证脚本进行规范化和验证：

bash "$VALIDATE" normalize "<candidate-name>"

其中，$VALIDATE 是此技能目录中 scripts/validate.sh 的绝对路径。应用步骤 0 中的路径安全规则（$HOME，从输出中复制）。成功时输出 $FEATURE_NAME；失败时，立即停止——不要继续使用未经验证的路径。

规则：

• 切勿直接将原始 $ARGUMENTS 用于文件路径。
• 所有 .dev/ 路径引用都使用 $FEATURE_NAME。

阶段 1.8：查阅 Wiki（可选）

开始研究前，先检查跨项目 Wiki，了解已有方案：

cat "$HOME/.dev-wiki/index.md" 2>/dev/null

• 如果文件存在，扫描其中与当前任务相关的功能——相似名称、重叠领域、可复用模式。向研究 Agent 简报时，提及任何相关的已有方案。
• 如果文件不存在，静默跳过，继续进入阶段 2。

此步骤仅供参考。Wiki 不存在时，不要因此停下。

阶段 2：研究

使用 Task 工具并行启动 2-3 个 prd-researcher Agent，分别聚焦不同方面：

Agent 1: "Find similar implementations and patterns to reuse for [feature]. Include file:line references."
Agent 2: "Identify architecture constraints, dependencies, and integration points for [feature]."
Agent 3: "List all files that will need modification for [feature] and what changes are needed."

为每个 Agent 使用 subagent_type=dev-workflow:prd-researcher。

Agent 返回后

1. 综合研究结果 — 将各 Agent 的输出汇总为统一的研究摘要
2. 按以下格式呈现摘要：
   • 可复用的模式 — 可借鉴的现有代码/架构（附 file:line 引用）
   • 需要修改的文件 — 路径列表及 1 行说明
   • 关键决策 — 需要确认的 2-3 个架构选择
   • 待解决的问题 — 不明确之处（如有）

控制在约 10-15 行。

停止。在用户确认研究结果或提出更正前，不要进入阶段 3。

注意事项：研究应服务于 PRD。完成一轮研究后就开始撰写。如果用户要求深入调查，再进行一轮，然后撰写。

阶段 3：撰写 PRD

启动 1 个 prd-planner Agent 来设计实现结构：

"Design implementation phases for [feature].
Research findings: [summarize key patterns and files from Phase 2].
Determine if this needs sub-PRDs (complex) or a single PRD (simple)."

使用 subagent_type=dev-workflow:prd-planner。

Agent 返回后

1. 审查 Agent 的输出 — 确认各阶段安排合理且完整
2. 提出架构方案 — 向用户展示推荐的结构

停止。在用户确认架构方案或要求调整前，不要创建任何文件。

3. 在 $PROJECT_ROOT/.dev/$FEATURE_NAME/ 下创建文件：

   • 始终创建 00-master-plan.md — 使用 prd-templates.md 中的主计划模板
   • 对于复杂功能，创建 01-sub-prd-[name].md 等文件 — 使用 prd-templates.md 中的子 PRD 模板
     • 每个阶段的步骤只能在一个位置跟踪，绝不能重复。 可以让主计划的 Implementation Order 包含编号 ⬜ 步骤（子 PRD 只写叙述，不列步骤）；也可以让主计划将各阶段合并为不含步骤的范围标题，由子 PRD 的 ## Implementation Progress 表跟踪步骤。在两处列出相同步骤会导致子 PRD 计数器成为无效的重复项——status-update 只会写入一个文件，因此另一个文件会停滞，仪表板则会显示误导性的 0/N。
   • 将研究结果（阶段 2）和实现计划（Agent 输出）纳入 PRD

4. 验证 PRD 结构 — 运行 CLI，确认 PRD 可解析：

   node "$CLI" feature-show --json --dir "$PROJECT_ROOT/.dev/$FEATURE_NAME"
   

   $CLI 是此技能目录中 scripts/dev-workflow.cjs 的绝对路径。按照步骤 0 中的路径安全规则操作（使用 $HOME，并从输出中复制）。

   如果命令失败或返回意外数据，请先修复 PRD 文件再继续。

5. 说明创建了哪些内容 — 列出写入的每个文件路径。

6. 建议运行 /dev-checkpoint 以保存续接提示词。

注意事项：必须创建文件。如果进入此阶段后尚未写入文件，请暂停其他所有操作并撰写 PRD。

规则

• 研究一轮后就开始撰写——不要无休止地研究
• 将研究结果纳入主计划的“Research Findings”部分（不要单独创建 findings.md）

隐私规则

切勿在 PRD 文件中包含以下内容——请使用安全替代项：

• 含用户名的绝对路径 → 改用相对于项目根目录的路径
• 密钥、API 密钥、令牌、凭据 → 使用占位符（<API_KEY>、$ENV_VAR）
• 个人信息（姓名、电子邮件）→ 使用通用称谓