# Long Term Todo Management

> 长期 Todo 列表管理技能：使用 .agents/todos/ 保存长期计划。当一个计划**复杂**、需要**多阶段推进**、需要**定期复查**，或会跨越多天/多周完成时创建 Todo，确保其他 agents 可快速接手，知道进行到哪一步，人类开发者也能按计划手工执行，复查时能快速判断“这份计划是否仍与当前任务相关”。 Use when this capability is needed.

- Skill: `tomevault-io/long-term-todo-management` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/long-term-todo-management`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/long-term-todo-management/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/long-term-todo-management

---


# 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`：目标达成（可保留复盘信息）

---

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

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

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

硬性要求：

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

---

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

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

1. **先读取文件开头 20 行**

   - 看标题、目标、状态、关键约束是否仍匹配当前任务

2. 若不相关：

   - 不要硬推进旧计划
   - 新建文件或在旧文件中明确写 `## 变更说明` 并更新 `status/updated_at`

3. 若相关：

   - 进入对应阶段 checklist 继续推进
   - 推进后及时勾选完成项、补充验证结果
   - 更新 `updated_at/updated_by`

---

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

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

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

避免：

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

---

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

```md
---
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](https://tomevault.io/claim/inpageedit) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->