SKILL.md
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
核心产出契约（必须遵守）
- 计划文件必须落在：
docs/plans/{Story-Key}/
- 首次计划文件名固定为：plan.md - 若 plan.md 已存在，新计划必须使用：plan-{序号}.md（如 plan-1.md、plan-2.md） - 序号 从 1 开始递增，始终取当前目录下下一个可用序号 - 禁止覆盖已有计划文件（包括 plan.md 与历史 plan-{序号}.md）
- 文件必须包含：
- 状态管理（整体进度、任务状态总览、执行记录） - 需求理解、风险与范围边界 - UI / 交互约束（如适用） - 任务拆解（每个任务 2-5 分钟） - 测试用例与验收标准（可测试、无歧义） - AI 执行指引（明确执行顺序、约束、人工 Gate 节点） - 档案系统回补任务（若 analysis.md 已建议回补）
- 每个任务必须以 TDD 方式描述：RED → 验证失败 → GREEN → 验证通过 → REFACTOR → 再次验证
- 状态管理必须可追踪：每个任务都要有
状态、负责人、开始时间、完成时间、阻塞原因，初始状态统一为待开始 - 计划内容必须显式标注：
- Story 描述中的原始约束 - analysis.md 中的关键结论（若存在） - analysis.md 中的档案系统回补建议（若存在） - 基于当前代码/测试/文档推导出的实现现状 - 缺失上下文下的关键假设与待确认项 - 计划阶段新增的实现决策
- 只有在以下场景才允许停止生成计划：
- Story 描述、现有文档与代码现状之间存在重大冲突，且无法合理判定以哪一份为准 - 缺少 Story/需求输入，且从代码与文档也无法识别本次变更目标
上下文降级规则（必须遵守）
- 标准模式： 存在
analysis.md
- 优先继承其中的需求理解、风险、验收标准、UI 约束 - 若其中包含“档案系统回补建议”，必须转写为计划中的显式任务，不能停留在建议层 - 再用 Story、文档与代码校验边界
- 降级模式： 不存在
analysis.md
- 不得停止计划生成 - 必须改为基于 Story 描述、相关文档、当前代码与测试现状生成计划 - 计划中必须显式标注：当前计划未基于 analysis.md，属于降级生成 - 必须增加： - 上下文来源说明 - 关键假设 - 待确认问题 - 代码现状观察
- 补全模式：
analysis.md存在但内容不完整
- 不得因为缺少某个章节而直接停止 - 应由计划阶段补齐最小必需信息，并在计划中标注来源： - 来自 analysis.md - 来自 Story - 来自代码推导 - 计划阶段补齐
- 冲突模式： 不同来源存在重大矛盾
- 必须列出冲突点 - 必须请求用户确认或在计划中明确采用的判定依据 - 若无法做出低风险判断，才允许停止
一口大小的任務粒度
每一步都是一個動作（2-5 分鐘）：
- “編寫失敗的測試”-步驟
- 「運行它以確保它失敗」-步驟
- “實現最少的程式碼以使測試通過” - 步驟
- “運行測試並確保它們通過”- 步驟
- “提交”-步驟
上下文优先级（必须遵守）
- 第一优先级：
docs/plans/{Story-Key}/analysis.md（如存在）
- 作为任务拆解、风险边界、验收标准、测试思路的优先依据
- 第二优先级： Jira Story 描述 / AC / 附件链接
- 用于校验 analysis.md 是否偏离原需求 - 在无 analysis.md 时，作为计划主输入
- 第三优先级： 相关规格与模块文档
- docs/specs/PRD.md - docs/specs/SAD.md - docs/modules/*.md
- 第四优先级： 当前代码、测试与配置现状
- 用于识别已有实现、影响面、复用点与验证入口
- 若 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