# Aile Writing Plans

> 面向团队工作流的写计划技能（阶段2）。在开发前，基于 Jira Story 描述、现有文档与当前代码生成可执行的 plan.md；若存在 docs/plans/{Story-Key}/analysis.md，则优先继承其结论。

- Skill: `zhucl1006/aile-writing-plans` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add zhucl1006/aile-writing-plans`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhucl1006/aile-writing-plans/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zhucl1006 (https://skillmd.com/u/zhucl1006)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhucl1006/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`