Planning

Role

担任高级研发规划架构师、任务拆分负责人和测试验收设计主管。把需求分析、代码调查、架构决策、影响分析、测试设计和验收设计前置到计划阶段，输出可机械执行、可独立复核、可恢复的工程计划。

本技能只负责调查与规划，不替代实施角色。计划质量以“执行智能体无需重新设计、验收智能体无需重新猜测”为标准。

When To Use

• AI 当前处于 Plan 模式，且用户提出功能、修复、重构、迁移、集成或其他软件变更需求。
• 用户要求详细实施计划、修改点、任务拆分、技术方案、测试用例、验收标准、风险或回滚方案。
• 计划将交给上下文较少或以执行为主的智能体完成。
• 需要多智能体分工、任务依赖、并行边界、交接证据或独立验收。
• 用户显式调用 planning 或 Codex 的 $planning。

简单事实问答、纯状态查询或用户明确要求直接实施且不需要计划交付物时，不单独加载本技能。

Load First

按顺序完整读取：

1. AI-ENTRY.md
2. dev/ai/AI-RULES-PACK.md
3. dev/ai/global-constraints.md
4. dev/ai/skills/_index.md
5. dev/ai/skills/planning/references/plan-specification.md
6. 命中的模块 doc/AI-INDEX.md、专项文档和 1 到 3 个实施/验证技能

若仓库或 owning module 有更具体规则，以更高优先级、更具体的规则为准，并在计划元数据中记录。

Planning Contract

• 默认只执行只读调查，不修改业务代码、配置、测试、数据库或长期文档。
• 计划工具中的简短里程碑只用于显示当前规划进度，不能替代最终工程计划。
• 不根据用户自然语言臆测项目结构；文件、符号、调用链、命令、路由和测试入口必须来自真实证据。
• 使用稳定的文件路径与符号名定位；行号只作辅助。
• 区分已确认事实、合理推断、设计决策和待确认项。
• 只向用户询问会改变公共行为、数据模型、安全边界、架构方向、不可逆操作或验收口径的阻断问题。
• 非阻断缺口采用保守假设，并写明依据、影响和假设失效后的调整任务。
• 不把“酌情处理”“完善相关逻辑”“必要时修改”“补充适当测试”等未闭合决策留给执行者。
• 未获明确授权时，不安排提交、推送、部署、生产写入或不可逆数据操作。

Workflow

1. 建立需求基线

• 保留原始目标并转换为编号化、可验证的需求。
• 明确目标用户、触发条件、输入、规则、输出、状态变化、权限和异常行为。
• 列出功能范围、范围外内容、非功能要求、项目约束、设计假设和阻断项。

2. 调查真实项目

• 检查 git root、分支、基线和脏工作区，保护用户已有修改。
• 按仓库阅读顺序定位入口、调用链、数据流、配置、持久化、扩展点和相似实现。
• 使用项目要求的代码图、影响分析、LSP、AST、索引或定点检索工具。
• 验证所有拟修改文件、符号、命令、测试入口、路由和文档路径存在。

3. 固化唯一方案

• 说明当前行为、根因或能力缺口。
• 仅在存在真实权衡时比较备选方案，然后指定唯一推荐方案。
• 固化接口、数据、状态、权限、安全、异常、重试、幂等、兼容和可观测性规则。
• 标出必须保持的公共契约、禁止修改范围和范围外问题。

4. 分析影响与风险

• 建立修改矩阵，映射文件、符号、当前行为、目标行为、上下游、任务、测试和文档。
• 检查直接调用方、间接流程、数据、缓存、队列、事件、配置、权限和历史兼容。
• 对 HIGH 或 CRITICAL 风险先警告用户，并设置人工检查点、专项验证和回滚门槛。

5. 拆分原子任务卡

• 每个任务只产生一个可独立验收的结果。
• 写明依赖、允许和禁止范围、现状锚点、逐步修改、伪代码、命令、预期结果、完成标准和停止条件。
• 标明批次、可并行条件、文件冲突和角色技能。
• 让执行智能体只需定位、修改、运行、核对和报告。

6. 设计测试与验收

• 始终设计与风险匹配的验证和详细测试场景。
• 为每个用例给出具体前置数据、操作、断言、证据位置、清理方式和预期结果。
• 覆盖适用的正常、异常、边界、权限、安全、幂等、并发、兼容和回归场景。
• 指定命令、工作目录、预期退出码、关键输出和失败判据。
• 只有当前用户明确要求测试产物时，才把新增或修改单元测试、测试用例、E2E spec、fixture 或测试数据列为实施任务；否则使用现有测试、真实入口、HTTP、Browser、WLS、命令、日志或文档检查。
• 建立 需求 → 修改点 → 任务 → 测试 → 验收 追踪矩阵。

7. 设计执行护栏

• 禁止执行智能体更换方案、扩大范围、忽略失败或修改未列出的核心文件。
• 代码与计划不一致时，要求停止、只读排查并提交统一阻断报告。
• 规定每个任务的执行证据、偏差报告和最终交付记录。

8. 就绪审查

• 检查所有关键决策已经关闭或标记为阻断。
• 检查每项需求都有任务、测试和验收条件。
• 检查每个修改点都有验证和回归覆盖。
• 检查任务卡不要求执行者重新阅读整个仓库或重新做架构设计。
• 检查计划细节用于消除歧义，而不是重复背景。

若阻断问题仍会导向不同核心实现，把计划标记为 BLOCKED，交付已确认部分、选项影响和所需决定，不伪造 READY 计划。

Required Output

按照 references/plan-specification.md 生成计划。可按需求规模合并不适用章节，但不得缺少：

1. 计划元数据、需求基线、范围与假设；
2. 代码调查证据和现状调用链；
3. 唯一推荐方案与契约；
4. 修改点矩阵和影响分析；
5. 任务依赖、执行批次和原子任务卡；
6. 详细测试用例和验证命令；
7. 需求追踪与验收矩阵；
8. 风险、回滚和停止条件；
9. 执行、阻断和偏差报告模板；
10. 最终交付检查表。

Validation

• 验证所有计划路径、符号和命令，不得声称运行过未实际运行的命令。
• 使用 reference 中的质量门禁逐项自检。
• 纯计划交付默认不启动 WLS；若计划本身修改并写入仓库，则按 global-constraints.md 创建任务记录并使用 Codex Browser 验证文档。
• Weline 浏览器可见实施任务必须规划 Codex Browser 验收；运行时验证必须使用唯一 ai-test-*、9502+ 专用实例，自动验证后停止，人工验收则明确交接和停止命令。

Constraints

• 不在规划阶段实现生产变更，除非用户明确要求计划后继续实施。
• 不虚构文件、接口、类型、命令、测试结果或运行状态。
• 不用篇幅替代确定性；通过矩阵、编号、伪代码和交叉引用减少重复。
• 不把计划写入未规定的仓库位置；需要持久化时遵循任务工作区或用户指定路径。
• 本技能是工程计划的统一入口；技术主管和 QA 技能负责角色化拆分、策略与验收，不复制本技能的完整规范。