plan-init

name	plan-init
description	初始化 Agent 框架，完成需求分析和任务分解。当用户说 "/plan-init"、"初始化项目"、"开始新项目"、"创建任务列表"、"设置 Agent"、"初始化任务"、"init"、"初始化" 时触发。这是一个项目初始化 skill，不是创意或功能开发——不需要先 brainstorming。审批后只输出确认，不自动串联任何 skill。

Plan Init

完成需求分析、技术决策和任务分解，将技术方案直接写入 .plan/task.md 供审批。本 skill 只负责"想"，审批后输出确认信息并停止，串联逻辑由调用方决定。

核心产物

文件	用途	何时产生
.plan/task.md	技术方案文档（含完整任务 JSON 数组，审批对象）	本 skill 执行过程中渐进写入
.plan/features.json	任务单一事实来源	/plan-write 执行后
.plan/dev-YYYY-MM-DD.log	统一开发日志	/plan-write 执行后
.plan/test-cases.json	用户提供的独立测试用例	/plan-write 从 .plan/task.md 提取

关键事实：下游 /plan-write 从 .plan/task.md 读取，所以本 skill 必须保证 .plan/task.md 内容完整，含完整 JSON 任务列表。

门控分级

SKILL.md 内出现的标记：

• 🔴 HARD GATE：必须等用户输入，不等不能继续
• 🟡 CHECK：AI 内部自检，不满足则回到前面步骤补充
• 📄 WRITE：向 .plan/task.md 的指定章节写入/更新内容

三档自适应

根据输入清晰度自动选择工作深度：

输入	模式	流程
模糊需求（口头描述）	深度模式	需求深挖 → 场景识别 → 代码探索 → 方案构建 → 任务分解
明确技术文档（task.md 无 JSON）	标准模式	理解确认 → 技术决策 → 任务分解
已有 JSON 任务列表（task.md 含 JSON）	极速模式	提取 JSON → 确认 → 组装 task.md

告知用户当前采用的模式及原因，用户可要求切换。

设计原则

• 抗遗忘：通过读取任务日志恢复上下文
• 抗范围蔓延：JSON 定义范围，日志提供详细上下文
• 可演进：AI 可在执行前优化方案
• 精准执行：只改该改的，不碰不该碰的
• 资深开发视角：考虑复用性、扩展性、健壮性
• 架构师视角（深度模式）：深入代码库理解现状后给出专业方案
• 代码驱动（深度模式）：方案基于实际代码探索，而非凭空设计

---

协议

步骤 1：检查现有文件（所有模式都执行）

执行 mkdir -p .plan 确保目录存在。检查 .plan/features.json 和 .plan/dev-*.log。

.plan/features.json 存在 → 🔴 HARD GATE：

选项	行为
覆盖	备份到 .plan/features.backup.{timestamp}.json，创建新文件
追加	向现有数组添加新任务
合并	保留现有，仅添加非重复项
取消	中止初始化

.plan/dev-*.log 存在 → 告知用户："发现现有日志，将保留它们。"

步骤 2：获取需求 + 判断模式

读取 .plan/task.md（如存在）。

task.md 状态	后续
存在且含完整 JSON 任务列表	走 极速模式分支（见 2A）
存在但无 JSON	走 标准模式：以文档为需求输入 → 跳到步骤 5
不存在	走 询问用户（见 2B）

2A. 极速模式分支（task.md 已含 JSON）

用户可能是"要沿用这份 task.md"，也可能是"忘了删上次的 task.md，这次想重新分析"。必须先确认。

🔴 HARD GATE：向用户展示并选择：

📄 检测到已有 .plan/task.md，含 [N] 个任务：
  • 任务 1: [description 前 60 字符]
  • 任务 2: [description 前 60 字符]
  ...（最多展示 5 条，超出用「...」省略）

请选择处理方式：
① 沿用这份 task.md，进入极速模式
② 当作不存在，重新描述需求（将覆盖现有 task.md）
③ 取消本次初始化

• 用户选 ① → 提取任务 JSON（同步检查 ## Test Cases 章节，有则一并提取，保持 task.md 不变）→ 跳到步骤 6
• 用户选 ② → 备份现有 task.md 到 .plan/task.backup.{timestamp}.md，按全新流程处理，走 2B
• 用户选 ③ → 中止 skill

2B. 询问用户目标（task.md 不存在）

🔴 HARD GATE：

请描述你要做的事情：
- 可以直接说需求
- 可以提供需求文档路径（我会读取并分析）
- 可以提供飞书/语雀文档链接

用户回答后判断：

• 含具体改动范围、实现思路、文件路径 → 标准模式 → 跳到步骤 5
• 只有笼统目标、一句话描述 → 深度模式 → 继续步骤 2.5

告知模式：🎯 模式：[深度/标准]，原因：[简述]。用户可要求切换。

步骤 2.5：测试用例检测（条件执行）

检测信号（命中任一即触发）：

• HTTP 方法 + 路径（如 POST /api/orders、curl -X GET）
• 请求/响应 JSON 配对
• 关键词：测试用例、test case、curl、Postman
• 引用测试文件（.json、.yaml、.postman_collection）
• 用户明确说"用这些数据测试"

未命中 → 跳过此步骤。命中 → 执行以下子步骤。

2.5.1 提取

从用户输入中提取：

• API 调用：method、path、headers、body、预期状态码和响应
• 流程：步骤间依赖（如"先创建再查询"）
• 异常测试：边界条件和错误场景
• 动态值：用 saveAs + {{变量}} 表达

2.5.2 推断 serviceConfig

从项目代码推断：

• 用户给了启动命令/端口 → 直接使用
• 否则 framework 设为 "auto"（backend-test 运行时自动检测）

2.5.3 向用户确认

🔴 HARD GATE：

📋 检测到测试用例，提取结果：

测试套件 1: [套件名] (顺序/并行执行)
  TC-1: POST /api/orders → 期望 200, body 含 orderId
  TC-2: GET /api/orders/{id} → 期望 200 (依赖 TC-1)
  TC-3: POST /api/orders (无效数据) → 期望 400

服务配置: framework=auto（执行时自动检测）
变量: token=test-token-12345

是否正确？需要添加/修改/删除测试用例吗？

确认后 📄 WRITE → .plan/task.md 的 ## Test Cases 章节（JSON 格式）：

{
  "metadata": { "createdAt": "ISO 时间戳", "source": "plan-init", "description": "..." },
  "serviceConfig": {
    "app": "应用名（可选）",
    "appPath": "应用路径（可选）",
    "framework": "auto",
    "startCommand": null,
    "port": null,
    "healthCheck": null,
    "envVars": {},
    "setupCommands": []
  },
  "testSuites": [
    {
      "id": "suite-1",
      "name": "套件名称",
      "sequential": true,
      "tests": [
        {
          "id": "tc-1",
          "type": "api",
          "request": { "method": "POST", "path": "/api/orders", "headers": {}, "body": {} },
          "expected": { "status": 200, "bodyContains": ["orderId"] },
          "saveAs": { "orderId": "$.orderId" }
        },
        {
          "id": "tc-2",
          "type": "api",
          "dependsOn": "tc-1",
          "request": { "method": "GET", "path": "/api/orders/{{orderId}}" },
          "expected": { "status": 200 }
        }
      ]
    }
  ],
  "variables": {}
}

test-cases.json 关键字段说明见 references/compatibility.md。

---

步骤 3：需求深挖 + 代码探索（仅深度模式）

3.1 场景识别

识别需求所属场景（五选一），告知用户：

🎯 场景识别：[新功能 / 性能优化 / 线上问题修复 / 结构优化 / 中间件创建]
理由：[简述]

不确定时列出候选让用户选。

五大场景的关注点：

场景	核心关注点	探索重点
新功能开发	在哪加？怎么加？影响什么？	相关模块结构、现有抽象、扩展点
性能/逻辑优化	瓶颈在哪？怎么改？副作用？	热点代码路径、调用链、数据流
线上问题修复	根因是什么？修复方案？防复发？	问题代码、上下游依赖、异常链
项目结构优化	当前问题？目标结构？迁移路径？	模块划分、依赖关系、分层架构
中间件/工具创建	解决什么问题？边界？API 设计？	现有工具类、使用场景、接口契约

3.2 理解确认

🔴 HARD GATE：

📋 我的理解：
- 要做什么：[复述核心目标]
- 核心诉求：[用户最关心的点]
- 预期产出：[最终交付物]

❓ 不确定的地方：[列出理解模糊的点，主动追问]

请确认是否正确，或指出理解偏差。

3.3 场景提问

根据场景挑选 3-5 个对方案有实质影响的问题，跳过用户已明确回答的问题。

场景	必问（直接影响方案方向）	按需（视情况补充）
新功能开发	① 目标用户角色和核心使用场景？② 数据从哪来、到哪去、关键字段？③ 项目中有类似功能可参考吗？④ 与现有模块的交互边界？	⑤ 并发/性能有特殊要求吗？⑥ 需要向后兼容已有接口吗？⑦ 错误/异常怎么处理？
性能/逻辑优化	① 当前性能数据（QPS/耗时/内存）？瓶颈表现？② 目标性能指标？③ 可接受的改动范围？④ 需要降级/兜底吗？	⑤ 历史优化尝试？⑥ 读写比例？⑦ 缓存策略偏好？
线上问题修复	① 复现条件？② 影响范围和紧急程度？③ 临时方案还是直接根治？④ 回归测试怎么做？	⑤ 上下游影响？⑥ 现有日志能定位到哪？⑦ 历史类似问题？
项目结构优化	① 当前结构最痛的点？② 目标架构愿景？③ 能否分阶段迁移？④ 兼容性约束？	⑤ 影响团队协作吗？⑥ 构建/部署流程变吗？⑦ 保留旧路径过渡？
中间件/工具创建	① 核心问题？② 使用者和使用场景？③ API 风格偏好（Builder/链式/函数式）？④ 有参考实现吗？	⑤ 扩展点预留？⑥ 错误处理和日志约定？⑦ 需要配套文档？

🔴 HARD GATE：等待用户回答。

3.4 完备性检查

🟡 CHECK：

通用维度（必查）：

• □ 核心目标：一句话能说清楚
• □ 成功标准：怎样算"做完了"
• □ 改动边界：改什么、不改什么
• □ 验证方式：怎么验证做对了

场景专属维度：

• [新功能] □ 数据流向 □ 用户交互流程 □ 异常场景
• [优化] □ 性能基线 □ 目标指标 □ 可接受副作用
• [修复] □ 复现路径 □ 紧急度 □ 回归范围
• [重构] □ 目标结构 □ 迁移约束 □ 兼容性
• [中间件] □ API 设计 □ 使用场景 □ 扩展性

未覆盖且对方案有影响 → 回到 3.3 补问。

📄 WRITE → .plan/task.md 的 ## 背景 和 ## 目标 章节。

3.5 代码探索

根据场景做针对性探索。

通用动作：项目结构概览、相关模块阅读、依赖关系梳理、现有模式和约定识别。

按场景的专项：

场景	专项探索
新功能开发	扩展点、相似功能实现、可复用基础设施
性能优化	热点路径、调用链、潜在瓶颈
线上问题	问题代码路径、异常处理链、边界条件
结构优化	模块依赖图、循环依赖、不合理耦合
中间件创建	现有工具类、潜在使用场景、API 风格

探索产出：

🔍 代码探索发现：
- 项目技术栈：[语言/框架/构建工具]
- 相关模块：[关键文件和模块]
- 现有模式：[项目约定]
- 可复用资源：[现有工具类/基础设施/抽象层]
- 关键代码路径：[核心调用链和数据流]
- 潜在风险：[可能影响方案的因素]

🔴 HARD GATE：以下情况需暂停回到需求层面：

• 发现与用户描述不一致
• 发现用户未提及但会受影响的模块
• 发现需求中隐含的技术约束
• 发现多种实现路径，需要用户提供业务优先级

📄 WRITE → .plan/task.md 的 ## 现状分析 章节（含「关键代码路径」和「现有抽象层」子节）。

🔴 HARD GATE：等待用户确认代码探索发现无误。

---

步骤 4：协作式方案构建（仅深度模式）

4.1 方案概述

📐 方案概述：
- 整体思路：[一句话描述方案核心]
- 改动范围：[涉及哪些模块/文件]
- 不改什么：[明确排除项]

4.2 技术决策点

情况	处理方式
代码库中已有明确约定	遵循现有约定，告知用户
用户指定了方案	直接采用，无需讨论
有多个可选方案	列出选项 + ⭐推荐 + 理由

🔴 HARD GATE：用户确认技术决策。

📄 WRITE → .plan/task.md 的 ## 技术方案 章节（含「整体思路」「数据流图」「接口设计」「技术决策」「改动范围」子节）。

4.3 任务拆解预览

拆解为可执行任务。字段定义完整列表见 references/task-schema.md，这里只用简化摘要向用户展示：

📝 任务拆解：

任务 1: [任务标题]  [domain: backend] [complexity: small]
- 做什么 / 为什么 / 改哪里 / 怎么改 / 参考实现 / 验收标准 / 依赖

dependsOn 核心原则：只有编译级依赖（import/引用对方新增的类、方法、接口）才设 dependsOn。运行时依赖（HTTP/RPC、不同 domain）不设，用 apiContracts 约定契约即可。详见 references/task-schema.md。

🔴 HARD GATE：用户确认任务拆解合理。

📄 WRITE → .plan/task.md 的 ## 任务列表 章节（完整 JSON 数组）。

→ 继续到步骤 6。

---

步骤 5：标准模式需求澄清 + 任务分解

5.1 理解确认

🔴 HARD GATE：

📋 我的理解：
- 要做什么：[复述]
- 要改什么：[精确到类/方法]
- 不改什么：[明确排除]
- 边界条件：[特殊情况处理]

❓ 不确定的地方：[主动追问]

5.2 需求澄清（资深开发视角）

类别	追问示例
复用性	有没有现成的原子能力/工具类可复用？
影响范围	这个改动会影响哪些模块？上下游依赖？
边界	只改 A 还是 A 和 B 都改？
兼容性	需要向后兼容吗？老接口怎么处理？
异常处理	失败场景怎么处理？
性能考量	性能要求？是否需要缓存？
测试策略	怎么验证改对了？

🔴 HARD GATE：关键问题未澄清前，不得开始任务分解。

5.3 技术实现决策点识别

在分解任务前识别实现时必然要确定的技术问题。

情况	处理方式
用户指定了参考方法/工具	按参考方法处理，无需询问
用户未指定	列出选项 + ⭐推荐 + 理由

识别方法：对每个任务问自己"写到这行代码时，我必须知道什么才能继续？"

🔴 HARD GATE：未指定参考方法时需用户确认技术决策。

5.4 提取参考资源和数据样例

从用户需求中识别：

• 参考方法/工具 → references 字段
• 数据样例 → dataSamples 字段
• 文档链接 → references 字段

用户提供的参考和数据样例是硬约束，不可忽略或自行替代。

5.5 任务分解

按 references/task-schema.md 的 schema 生成任务 JSON 数组。

字段速查（完整定义见 task-schema.md）：

字段	说明
id	字符串序号 "1"
domain	backend/frontend（全栈项目必填）
app / appPath	多应用项目必填
dependsOn	只设编译级依赖；跨应用用 app:id 格式
complexity	trivial/small/medium/large
category	core/ui/feature/optimization/bugfix/refactor/middleware
implementationGuide	深度模式必填，标准模式可选
apiContracts	涉及接口对接时必填
references / dataSamples	硬约束

步骤 6：组装 .plan/task.md + 请求用户审批

所有模式汇合到这一步，不同模式在此做的工作不同：

模式	这一步的工作
深度模式	前面已渐进写入 .plan/task.md，这里只需补 ## 风险与注意事项 + 完整性自检
标准模式	一次性把「需求理解 + 技术决策 + 任务 JSON」写入 .plan/task.md，骨架遵循 references/task-template.md
极速模式	.plan/task.md 已是用户提供的内容，无需重写；若有 2.5 新增的 Test Cases，追加到 ## Test Cases 章节即可

🟡 CHECK 清单：

• .plan/task.md 的 ## 任务列表 章节是完整的 JSON 数组
• 每个任务都有 passes: false
• 深度模式：各任务 implementationGuide 完整
• 涉及接口对接：apiContracts 已定义
• 若 2.5 命中：## Test Cases 章节已写入
• 应用覆盖性（多应用/全栈项目）：需求提到的每个应用在任务列表中都有对应任务

应用覆盖性检查（多应用/全栈项目必做）：

🔍 应用覆盖性检查：
需求涉及的应用：[列出需求中明确提到的所有应用]
任务列表覆盖的应用：[列出任务中所有 app 值]
未覆盖的应用：[列出差异] ← 需要补充任务

常见遗漏：

• 需求提到前端页面修改，但只分解了后端任务
• 需求涉及 share 包（公共接口定义），但只关注了业务服务
• 需求提到多个微服务，但只分解了部分任务

自检通过后，向用户输出审批请求：

✅ 技术方案已写入 .plan/task.md，含 [N] 个任务。

任务摘要：
  • 任务 1: [description 前 60 字符]  [domain] [complexity]
  • 任务 2: [description 前 60 字符]  [domain] [complexity]
  ...（最多展示 8 条，超出用「...还有 X 个任务」省略）

请审阅 .plan/task.md 后回复：
  ✓ 确认 / 通过 / OK  → 进入下一步
  ✗ 调整：[说明改动点] → 我会更新方案后再次请你审阅

🔴 HARD GATE：等待用户审批。未收到明确确认前不得进入步骤 7。

步骤 7：审批后输出

用户审批通过后，.plan/task.md 已是最终方案，无需额外归档。

输出确认信息（根据是否含测试用例选择模板）：

无测试用例：

✅ 计划已审批！

已创建:
• .plan/task.md - 技术方案文档（含 [N] 个任务定义）

---
⛔ 任务到此结束。请选择下一步执行方式：
• 运行 /backend-single  — 精简版编排（推荐）
• 运行 /backend-team    — 完整团队编排
• 运行 /plan-write + /plan-next — 手动逐步执行

含测试用例：在上面基础上最后追加一行：

• 开发完成后运行 /backend-test 执行测试验证（含用户测试用例）

HARD STOP：输出上述内容后立即停止，不得调用任何其他 Skill、不得运行 Bash、不得读文件、不得输出额外内容。等待用户下一条消息。

---

特殊情况处理

用户提供需求文档

MD 文件路径、飞书链接、语雀链接：读取内容 → 提取要点 → 按正常流程进入理解确认。

用户要求写入飞书/语雀

在步骤 7 额外用对应 MCP 工具创建远程文档并写入。本地 .plan/task.md 仍作为权威来源。

需求变更

任何步骤中用户提出变更 → 确认变更 → 评估影响 → 从受影响步骤重新开始 → 更新 .plan/task.md 对应章节。

后续修改同步

初始化后若用户要求修改任务（增删改），必须同步更新 .plan/features.json：

操作	处理方式
新增任务	追加到数组末尾，分配新 ID
修改任务	更新对应任务的字段
删除任务	从数组中移除
重排顺序	更新顺序和 ID

⚠️ .plan/features.json 是任务的单一事实来源，任何修改必须立即同步到文件。

---

附录

文件冲突处理全景

文件	何时检查	冲突处理
.plan/features.json	步骤 1（所有模式）	覆盖（备份）/ 追加 / 合并 / 取消
.plan/dev-*.log	步骤 1（所有模式）	告知用户保留，不询问
.plan/task.md	步骤 2A（极速模式分支）	沿用 / 当作不存在（备份后覆盖）/ 取消

章节映射表（.plan/task.md 写入点）

步骤	写入/更新的章节
3.4 需求深挖完成	## 背景、## 目标
3.5 代码探索完成	## 现状分析（含「关键代码路径」「现有抽象层」子节）
4.2 技术决策	## 技术方案（含「整体思路」「数据流图」「接口设计」「技术决策」「改动范围」）
4.3 任务拆解	## 任务列表（JSON 数组）
6 完善	## 风险与注意事项
2.5 测试用例确认	## Test Cases（JSON）

骨架格式见 references/task-template.md。

与 /plan-write 的衔接

.plan/task.md 的 ## 任务列表 章节采用与 .plan/features.json 兼容的 JSON 格式。/plan-write 从 .plan/task.md 读取并提取该章节写入 .plan/features.json。字段处理规则详见 references/compatibility.md。