file-todos

基于文件的待办事项跟踪技能

概述

todos/ 目录包含一个基于文件的跟踪系统，用于管理代码审查反馈、技术债务、功能请求和工作事项。每个待办事项都是一个包含 YAML frontmatter 和结构化章节的 Markdown 文件。

在以下情况下应使用此技能：

• 根据发现或反馈创建新的待办事项
• 管理待办事项生命周期（pending → ready → complete）
• 梳理待审核的待办事项
• 检查或管理依赖关系
• 将 PR 评论或代码问题转化为可跟踪的工作事项
• 执行待办事项期间更新工作日志

文件命名约定

待办事项文件遵循以下命名模式：

{issue_id}-{status}-{priority}-{description}.md

组成部分：

• issue_id：顺序编号（001、002、003……），不得重复使用
• status：pending（需要梳理）、ready（已批准）、complete（已完成）
• priority：p1（关键）、p2（重要）、p3（锦上添花）
• description：简短描述，采用 kebab-case 格式

示例：

001-pending-p1-mailer-test.md
002-ready-p1-fix-n-plus-1.md
005-complete-p2-refactor-csv.md

文件结构

每个待办事项都是一个包含 YAML frontmatter 和结构化章节的 Markdown 文件。创建新的待办事项时，请使用 todo-template.md 作为模板。

必需章节：

• Problem Statement - 哪些内容存在问题、缺失或需要改进？
• Findings - 调查结果、根本原因、关键发现
• Proposed Solutions - 多种方案及其优缺点、工作量和风险
• Recommended Action - 明确的计划（在梳理时填写）
• Acceptance Criteria - 可测试的检查项
• Work Log - 按时间顺序记录日期、操作和经验

可选章节：

• Technical Details - 受影响的文件、相关组件、数据库变更
• Resources - 错误、测试、PR、文档的链接
• Notes - 其他背景信息或决策

YAML frontmatter 字段：

---
status: ready              # pending | ready | complete
priority: p1              # p1 | p2 | p3
issue_id: "002"
tags: [rails, performance, database]
dependencies: ["001"]     # Issue IDs this is blocked by
---

常见工作流

创建新的待办事项

根据发现或反馈创建新的待办事项：

1. 确定下一个 issue ID：ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1
2. 复制模板：cp assets/todo-template.md todos/{NEXT_ID}-pending-{priority}-{description}.md
3. 编辑并填写必需章节：
   • Problem Statement
   • Findings（如果来自调查）
   • Proposed Solutions（多种方案）
   • Acceptance Criteria
   • 添加初始 Work Log 条目
4. 确定状态：pending（需要梳理）或 ready（已预先批准）
5. 添加用于筛选的相关标签

适合创建待办事项的情况：

• 需要超过 15-20 分钟的工作
• 需要研究、规划或考虑多种方案
• 依赖其他工作
• 需要经理批准或确定优先级
• 属于较大型功能或重构的一部分
• 需要记录的技术债务

适合立即处理的情况：

• 问题很简单（少于 15 分钟）
• 当前已有完整背景信息
• 无需规划
• 用户明确要求立即处理
• 解决方案明确的简单 Bug 修复

梳理待处理事项

梳理待处理的待办事项：

1. 列出待处理事项：ls todos/*-pending-*.md
2. 对每个待办事项：
   • 阅读 Problem Statement 和 Findings
   • 审查 Proposed Solutions
   • 做出决定：批准、延期或调整优先级
3. 更新已批准的待办事项：
   • 重命名文件：mv {file}-pending-{pri}-{desc}.md {file}-ready-{pri}-{desc}.md
   • 更新 frontmatter：status: pending → status: ready
   • 在“Recommended Action”章节中填写明确的计划
   • 如与初步评估不同，调整优先级
4. 延期的待办事项保持 pending 状态

使用斜杠命令： /triage 进入交互式审批工作流

管理依赖关系

跟踪依赖关系：

dependencies: ["002", "005"]  # This todo blocked by issues 002 and 005
dependencies: []               # No blockers - can work immediately

检查哪些事项会阻塞某个待办事项：

grep "^dependencies:" todos/003-*.md

查找某个待办事项会阻塞哪些事项：

grep -l 'dependencies:.*"002"' todos/*.md

开始前确认阻塞事项已完成：

for dep in 001 002 003; do
  [ -f "todos/${dep}-complete-*.md" ] || echo "Issue $dep not complete"
done

更新工作日志

处理待办事项时，始终添加一条工作日志记录：

### YYYY-MM-DD - Session Title

**By:** Claude Code / Developer Name

**Actions:**
- Specific changes made (include file:line references)
- Commands executed
- Tests run
- Results of investigation

**Learnings:**
- What worked / what didn't
- Patterns discovered
- Key insights for future work

工作日志的作用：

• 记录调查过程
• 记录尝试过的方法
• 共享团队知识
• 为日后处理类似工作提供背景信息

完成待办事项

将待办事项标记为已完成：

1. 确认所有验收标准均已勾选
2. 使用最终工作记录和结果更新 Work Log
3. 重命名文件：mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md
4. 更新 frontmatter：status: ready → status: complete
5. 检查是否有工作因此解除阻塞：grep -l 'dependencies:.*"002"' todos/*-ready-*.md
6. 使用问题编号提交：feat: resolve issue 002

与开发工作流的集成

触发条件	流程	工具
代码审查	/ce:review → 发现项 → /triage → 待办事项	Review Agent + 技能
PR 评论	/resolve_pr_parallel → 单项修复 → 待办事项	gh CLI + 技能
代码 TODO	/resolve-todo-parallel → 修复 + 复杂待办事项	Agent + 技能
规划	头脑风暴 → 创建待办事项 → 处理 → 完成	技能
反馈	讨论 → 创建待办事项 → 分类 → 处理	技能 + 斜杠命令

快速参考命令

查找工作：

# List highest priority unblocked work
grep -l 'dependencies: \[\]' todos/*-ready-p1-*.md

# List all pending items needing triage
ls todos/*-pending-*.md

# Find next issue ID
ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}'

# Count by status
for status in pending ready complete; do
  echo "$status: $(ls -1 todos/*-$status-*.md 2>/dev/null | wc -l)"
done

依赖管理：

# What blocks this todo?
grep "^dependencies:" todos/003-*.md

# What does this todo block?
grep -l 'dependencies:.*"002"' todos/*.md

搜索：

# Search by tag
grep -l "tags:.*rails" todos/*.md

# Search by priority
ls todos/*-p1-*.md

# Full-text search
grep -r "payment" todos/

关键区别

文件待办事项系统（此技能）：

• todos/ 目录中的 Markdown 文件
• 用于开发和项目跟踪
• 带有 YAML frontmatter 的独立 Markdown 文件
• 供人类和 Agent 使用

Rails Todo 模型：

• app/models/todo.rb 中的数据库模型
• 应用中的面向用户功能
• Active Record CRUD 操作
• 与这个基于文件的系统不同

TodoWrite 工具：

• Agent 会话期间的内存任务跟踪
• 用于单次对话的临时跟踪
• 不会持久化到磁盘
• 与上述两个系统都不同