Skill: 长期 Todo 列表（Long-term Plan / Todo）

目的

当一个计划复杂、需要多阶段推进、需要定期复查，或会跨越多天/多周完成时，必须把计划保存到项目目录：

•.agents/todos/

以 Markdown 文件形式沉淀，确保：

•其他 agents 可快速接手，知道进行到哪一步
•人类开发者也能按计划手工执行
•复查时能快速判断“这份计划是否仍与当前任务相关”

何时必须创建长期 Todo 文件

满足任一条件就创建（不要犹豫）：

•任务拆分后仍然很长（> 10 个明确步骤，或 > 2 个阶段）
•需要反复验证/回归/对照，存在明显风险点
•需要定期复查（例如每周/每次迭代都要回头检查）
•需要跨多个模块/仓库协作、需要明确的“入口文件/路径/命令”
•需要记录大量背景约束、决策理由、关键假设

不满足以上条件的短任务，优先用普通对话或短清单，不必落盘。

文件位置与命名

•路径：.agents/todos/
•文件名格式：yyyymmdd.short-description-in-kebab-case.md

示例：

•20260205.workers-kv-cache-plan.md
•20260205.refactor-auth-middleware.md

命名原则：

•yyyymmdd 使用创建当天日期
•short-description 用 英文短描述、kebab-case、尽量 3–8 个词
•避免过泛：不要用 fix-bug.md；要用 fix-login-redirect-loop.md

必须包含的 Frontmatter（YAML）

每个长期计划文件开头必须包含且只包含如下字段（按顺序）：

yml

created_at: iso格式时间戳
created_by: agent自己的签名，比如openai/gpt-5.2
updated_at: iso格式时间戳
updated_by: agent自己的签名，比如openai/gpt-5.2
status: DRAFT/WIP/SCHEDULED/COMPLETED

规则：

•
created_at/updated_at 必须是 ISO 时间戳（带时区）
•
每次对计划做实质更新（内容、状态、阶段推进、关键决策变化），都要更新：
- •updated_at
- •updated_by
•
status 含义：
- •DRAFT：初稿，方向未完全确定
- •SCHEDULED：已排期，等待开始
- •WIP：进行中（默认最常见）
- •COMPLETED：目标达成（可保留复盘信息）

内容结构要求（必须“标题 + 段落 + 列表”）

长期计划必须使用清晰层级，最少包含以下结构：

•# 一级标题：计划名称（明确主题）
•目标段落：一句到三句说明要达成什么、成功标准是什么
•## 背景与约束：关键事实/限制/假设（列表化）
•## 现状盘点：入口点、相关模块/文件、接口、数据结构（列表化，尽量带路径）
•## 总体方案：方案概览（段落 + 列表）
•## 里程碑/阶段计划：按阶段列出可执行步骤（用 checklist）
•## 风险与回滚：主要风险、验证方式、回滚策略（列表化）
•（可选）## 参考链接/术语：方便人类跟进

硬性要求：

•必须有阶段，每阶段必须有 checklist（- [ ] / - [x]）
•任何“需要人执行的动作”必须写成可操作步骤（含文件路径/命令/验证点）
•任何“关键决策”必须解释理由（至少一句）

复查（Review）规则：先读开头 20 行

每次要继续推进、或要判断“这个计划是否还相关”时，执行如下步骤：

•
先读取文件开头 20 行
- •看标题、目标、状态、关键约束是否仍匹配当前任务
•
若不相关：
- •不要硬推进旧计划
- •新建文件或在旧文件中明确写 ## 变更说明 并更新 status/updated_at
•
若相关：
- •进入对应阶段 checklist 继续推进
- •推进后及时勾选完成项、补充验证结果
- •更新 updated_at/updated_by

更新规范（让接手者一眼看懂进度）

当计划进入推进状态后，建议在阶段里加入这些信息（用段落 + 列表表达）：

•当前进度摘要（1–3 行）
•已完成（- [x]）
•下一步（- [ ]，尽量具体）
•验证结果/证据（例如日志、截图、指标、命令输出摘要）
•未决问题（明确阻塞点、需要谁/需要什么信息）

避免：

•大段流水账
•只有 TODO 没有背景与约束
•只有“做 A/B/C”没有“怎么验证成功”

模板（建议直接复制使用）

---
created_at: 2026-02-05T17:32:13+08:00
created_by: openai/gpt-5.2
updated_at: 2026-02-05T17:32:13+08:00
updated_by: openai/gpt-5.2
status: DRAFT
---

# <计划标题：清晰、具体>

目标：<用 1-3 句说明要达成什么 + 成功标准>

## 背景与关键约束

- <约束 1：为什么重要>
- <约束 2：影响哪些方案选择>
- <假设/依赖：如果不成立会怎样>

## 现状盘点

- 入口/触发点：
  - <路径/接口/命令>
- 相关模块/文件：
  - `<path/to/file>`：<作用一句话>
- 当前问题/痛点：
  - <现象、指标、用户影响>

## 总体方案

<一段话概述思路：做什么、怎么做、为什么这样做>

- 方案要点：
  - <要点 1>
  - <要点 2>
- Key 设计（如 key/参数归一化/数据模型等）：
  - <规则列表>

## 里程碑与阶段计划

### 阶段 A：<阶段名>

- [ ] <可执行步骤（含路径/命令）>
- [ ] <可执行步骤（含验证点）>

验证：

- <如何验证成功，列命令/指标/预期结果>

### 阶段 B：<阶段名>

- [ ] ...
- [ ] ...

## 风险与回滚

- 风险：
  - <风险 1：触发条件/影响>
- 缓解：
  - <怎么降低概率或降低损失>
- 回滚：
  - <如何安全回退到之前状态>

## 参考

- <链接/术语/相关 PR/issue>