Aile Writing Plans

Aile：写计划（aile-writing-plans）

来源原 Skill

• 来源：团队内部阶段 2 计划拆解能力
• 当前定位：基于需求、文档与代码上下文生成可执行计划；若已有 analysis.md，则优先继承并细化

概述

这是团队自有的计划产出技能，用于把阶段 1（PM 需求 + UI 示意）的输入，转化为阶段 2 的标准化产物：

• 计划主入口：docs/plans/{Story-Key}/plan.md（若已存在则使用 plan-{序号}.md）
• 可选设计文件：docs/plans/{Story-Key}/design.pen
• 优先上下文文件：docs/plans/{Story-Key}/analysis.md

假設工程師對我們的程式碼庫的背景為零且品味有問題，則編寫全面的實施計劃。記錄他們需要知道的一切：每個任務要接觸哪些文件、程式碼、測試、他們可能需要檢查的文檔、如何測試它。將整個計劃作為小任務交給他們。

假設他們是一位熟練的開發人員，但對我們的工具集或問題領域幾乎一無所知。

假設他們不太瞭解良好的測試設計。

边界约束：

• 本技能负责读取 Story 描述、现有文档与当前代码，并产出 plan.md
• 若存在 analysis.md，它是第一优先级上下文；若不存在，也必须继续基于需求与代码完成计划产出
• 若 analysis.md 已确认存在，本技能必须把其中的“档案系统回补建议”转写为可执行计划任务，供后续执行阶段真正回补
• 本技能不负责创建 Jira Sub-task
• 本技能不默认执行 Jira 写操作；如需 Jira 变更，应由后续独立流程处理

工作流程概览

项目初始化：project-docs-init（创建文档）
      ↓
需求分析：aile-requirement-analysis（结构化需求分析  + 更新文档）
      ↓
计划制定：aile-writing-plans（设计 + 计划）
      ↓
执行开发：aile-executing-plans 或 aile-subagent-dev（按计划执行 + 人工检查点）
      ↓
交付总结：aile-delivery-report（整理交付材料 + 回链 Story）

何时使用

在以下情形使用：

• 你已经拿到 Jira Story 的需求描述
• docs/plans/{Story-Key}/analysis.md 已存在，或当前只有 Story / 代码上下文
• 需要产出可被执行的、任务颗粒度 2-5 分钟的实施计划
• 需要把需求输入或分析结果转成可执行、可验证、可交接的 plan.md

核心产出契约（必须遵守）

1. 计划文件必须落在：docs/plans/{Story-Key}/
   • 首次计划文件名固定为：plan.md
   • 若 plan.md 已存在，新计划必须使用：plan-{序号}.md（如 plan-1.md、plan-2.md）
   • 序号 从 1 开始递增，始终取当前目录下下一个可用序号
   • 禁止覆盖已有计划文件（包括 plan.md 与历史 plan-{序号}.md）
2. 文件必须包含：
   • 状态管理（整体进度、任务状态总览、执行记录）
   • 需求理解、风险与范围边界
   • UI / 交互约束（如适用）
   • 任务拆解（每个任务 2-5 分钟）
   • 测试用例与验收标准（可测试、无歧义）
   • AI 执行指引（明确执行顺序、约束、人工 Gate 节点）
   • 档案系统回补任务（若 analysis.md 已建议回补）
3. 每个任务必须以 TDD 方式描述：RED → 验证失败 → GREEN → 验证通过 → REFACTOR → 再次验证
4. 状态管理必须可追踪：每个任务都要有 状态、负责人、开始时间、完成时间、阻塞原因，初始状态统一为 待开始
5. 计划内容必须显式标注：
   • Story 描述中的原始约束
   • analysis.md 中的关键结论（若存在）
   • analysis.md 中的档案系统回补建议（若存在）
   • 基于当前代码/测试/文档推导出的实现现状
   • 缺失上下文下的关键假设与待确认项
   • 计划阶段新增的实现决策
6. 只有在以下场景才允许停止生成计划：
   • Story 描述、现有文档与代码现状之间存在重大冲突，且无法合理判定以哪一份为准
   • 缺少 Story/需求输入，且从代码与文档也无法识别本次变更目标

上下文降级规则（必须遵守）

• 标准模式： 存在 analysis.md
  • 优先继承其中的需求理解、风险、验收标准、UI 约束
  • 若其中包含“档案系统回补建议”，必须转写为计划中的显式任务，不能停留在建议层
  • 再用 Story、文档与代码校验边界
• 降级模式： 不存在 analysis.md
  • 不得停止计划生成
  • 必须改为基于 Story 描述、相关文档、当前代码与测试现状生成计划
  • 计划中必须显式标注：当前计划未基于 analysis.md，属于降级生成
  • 必须增加：
    • 上下文来源说明
    • 关键假设
    • 待确认问题
    • 代码现状观察
• 补全模式： analysis.md 存在但内容不完整
  • 不得因为缺少某个章节而直接停止
  • 应由计划阶段补齐最小必需信息，并在计划中标注来源：
    • 来自 analysis.md
    • 来自 Story
    • 来自代码推导
    • 计划阶段补齐
• 冲突模式： 不同来源存在重大矛盾
  • 必须列出冲突点
  • 必须请求用户确认或在计划中明确采用的判定依据
  • 若无法做出低风险判断，才允许停止

一口大小的任務粒度

每一步都是一個動作（2-5 分鐘）：

• “編寫失敗的測試”-步驟
• 「運行它以確保它失敗」-步驟
• “實現最少的程式碼以使測試通過” - 步驟
• “運行測試並確保它們通過”- 步驟
• “提交”-步驟

上下文优先级（必须遵守）

1. 第一优先级： docs/plans/{Story-Key}/analysis.md（如存在）
   • 作为任务拆解、风险边界、验收标准、测试思路的优先依据
2. 第二优先级： Jira Story 描述 / AC / 附件链接
   • 用于校验 analysis.md 是否偏离原需求
   • 在无 analysis.md 时，作为计划主输入
3. 第三优先级： 相关规格与模块文档
   • docs/specs/PRD.md
   • docs/specs/SAD.md
   • docs/modules/*.md
4. 第四优先级： 当前代码、测试与配置现状
   • 用于识别已有实现、影响面、复用点与验证入口
5. 若 Story 描述与 analysis.md 冲突：
   • 不得直接继续写计划
   • 必须先在输出中标记冲突点
   • 提示用户先更新 analysis.md 或确认以哪一份为准

执行流程

开始时声明：“我正在使用 aile-writing-plans 技能来生成团队计划。”

Step 0：读取上下文

• 读取 Jira Story 描述、AC、附件链接（若可获得）
• 优先读取 docs/plans/{Story-Key}/analysis.md（如存在）
• 读取 docs/README.md 与相关模块文档（如影响范围涉及 docs/modules/*）
• 读取（如存在）docs/specs/PRD.md、docs/specs/SAD.md
• 读取（如存在）本 Story 之前的计划产物（docs/plans/{Story-Key}/）
• 阅读当前代码、测试与配置，确认受影响模块、复用点与验证入口

Step 0.1：校验分析文件

• 若 docs/plans/{Story-Key}/analysis.md 不存在：
  • 不得停止
  • 明确输出：当前以“降级模式”生成计划
  • 必须转而依赖 Story、文档与代码现状完成计划
• 若 analysis.md 存在但缺少章节：
  • 不得仅因缺少章节而停止
  • 必须列出缺失项
  • 由计划阶段结合 Story、文档与代码补齐最小必要信息
• 若 analysis.md 不存在且 Story 信息较弱：
  • 必须优先通过代码、测试、模块文档收敛范围
  • 计划中前置加入“现状盘点 / 假设确认 / 缺口验证”任务
• 若 Story 描述与 analysis.md 明显冲突：
  • 列出冲突点
  • 请求用户确认
  • 未确认前不得生成 plan.md
• 若即使结合代码与文档仍无法判断最小变更目标：
  • 才允许停止
  • 必须明确说明缺失了什么关键信息

Step 1：确认 Story-Key 与范围边界

• 明确 Story-Key（例如 ABC-123），作为目录名
• 优先以 analysis.md 为主明确“做什么 / 不做什么”；若不存在，则以 Story + 代码现状归纳
• 用 Story 描述、文档与代码校验边界，防止遗漏或偏差

Step 2：任务拆解与排序

• 任务粒度：单任务 2-5 分钟
• 输出：每个任务明确文件路径、测试、验证命令、预期输出
• 每项任务都需要能回溯到某个来源条目：analysis.md、Story、文档或代码现状观察
• DRY：复用现有模式，不新增不必要抽象
• 若缺少 analysis.md：任务 1 必须优先处理“现状确认 / 测试基线 / 需求边界固化”
• 若 analysis.md 已包含“档案系统回补建议”：
  • 必须拆成独立的文档任务
  • 每个回补任务都要明确目标文件、回补原因、触发来源、验收方式
  • 这些任务默认进入计划，不得只放在备注或风险区

Step 3：写入计划文件

先确定“当前计划文件”：

• 若 docs/plans/{Story-Key}/plan.md 不存在：写入 plan.md
• 若 plan.md 已存在：按 plan-1.md、plan-2.md…顺序查找并写入首个不存在的文件
• 不得覆盖任何已有计划文件

将内容写入“当前计划文件”，并确保其至少包含以下结构：

• 文档元数据（Story-Key、输入来源、生成日期）

• 上下文摘要

  • Story 描述摘要
  • analysis.md 关键结论摘要（若存在）
  • 当前代码/测试现状摘要

• 任务拆解

• 测试与验收映射

• 执行顺序与人工 Gate

• 风险与待确认事项

• 档案系统回补任务（若 analysis.md 已建议回补）

• 若 analysis.md 不存在或内容不完整：增加“计划阶段补齐信息”小节，并逐项标注来源

• 若以降级模式生成：增加“降级生成说明”小节，写明未读取到 analysis.md 及对应风险

• 初始化状态管理模块：

  • 填写“整体进度”
  • 建立“任务状态总览”（所有任务默认 待开始）
  • 建立“执行记录”并写入首条记录

Step 4：提交 Git 变更（需用户明确要求）

• 仅当用户明确要求“提交代码/提交变更”时执行 git commit
• 仅提交当前 Story 相关文件（至少包含当前计划文件，必要时包含 design.pen）
• 提交前检查变更范围，避免混入无关文件：
  • git status
  • git add docs/plans/{Story-Key}/
  • git status
• 推荐提交信息模板：docs(plan): add {Story-Key} {plan-file}
  • plan-file 示例：plan.md、plan-1.md
• 提交命令示例：git commit -m "docs(plan): add {Story-Key} {plan-file}"

Step 5：交接到执行阶段

• 推荐后续执行技能：aile-executing-plans 或 aile-subagent-dev