tomevault-io 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.md20260205.refactor-auth-middleware.md
命名原则：
yyyymmdd使用创建当天日期short-description用 英文短描述、kebab-case、尽量 3–8 个词- 避免过泛：不要用
fix-bug.md；要用fix-login-redirect-loop.md
必须包含的 Frontmatter（YAML）
每个长期计划文件开头必须包含且只包含如下字段（按顺序）：
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_atupdated_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>
Converted and distributed by TomeVault — claim your Tome and manage your conversions.