file-todos

用途

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

该技能适用于以下场景：

从发现或反馈中创建新待办
管理待办生命周期（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"]     # 阻塞此待办的问题 ID
---

常见工作流

创建新待办

从发现或反馈创建新待办：

确定下一个问题 ID：ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1
复制模板：cp assets/todo-template.md todos/{NEXT_ID}-pending-{priority}-{description}.md
编辑并填写必需章节：Problem Statement、Findings（如来自调查）、Proposed Solutions（多个选项）、Acceptance Criteria
添加初始 Work Log 条目
确定状态：pending（需要分诊）或 ready（已预先批准）
添加相关标签以便过滤

何时创建待办：

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

何时应立即行动：

问题微不足道（< 15 分钟）
当前有完整上下文
无需规划
用户明确要求立即行动
解决方案明显的简单错误修复

分诊待审批项

分诊待办：

列出待审批项：ls todos/*-pending-*.md
对每个待办：阅读 Problem Statement 和 Findings、审查 Proposed Solutions、做出决定：批准、推迟或修改优先级
更新已批准的待办：
- 重命名文件：mv {file}-pending-{pri}-{desc}.md {file}-ready-{pri}-{desc}.md
- 更新 frontmatter：status: pending → status: ready
- 填写 "Recommended Action" 章节，给出清晰计划
- 如与初始评估不同，调整优先级
推迟的待办保持 pending 状态
使用斜杠命令：/triage 进行交互式批准工作流

管理依赖

跟踪依赖：

dependencies: ["002", "005"]  # 此待办被问题 002 和 005 阻塞
dependencies: []               # 无阻塞 - 可立即工作

检查什么阻塞了待办：

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

工作日志的作用：

调查的历史记录
尝试过的方法的文档
团队知识共享
未来类似工作的上下文

完成待办

将待办标记为完成：

验证所有验收标准已勾选
更新 Work Log，记录最终会话和结果
重命名文件：mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md
更新 frontmatter：status: ready → status: complete
检查解除阻塞的工作：grep -l 'dependencies:.*"002"' todos/*-ready-*.md
提交并引用问题：feat: resolve issue 002

与开发工作流的集成

触发	流程	工具
代码审查	/ce:review → Findings → /triage → Todos	Review agent + skill
PR 评论	/resolve_pr_parallel → Individual fixes → Todos	gh CLI + skill
代码 TODO	/resolve-todo-parallel → Fixes + Complex todos	Agent + skill
规划	Brainstorm → Create todo → Work → Complete	Skill
反馈	Discussion → Create todo → Triage → Work	Skill + slash

快速参考命令

查找工作：

# 列出最高优先级的未阻塞工作
grep -l 'dependencies: \[\]' todos/*-ready-p1-*.md

# 列出所有需要分诊的待审批项
ls todos/*-pending-*.md

# 查找下一个问题 ID
ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}'

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

依赖管理：

# 什么阻塞了此待办？
grep "^dependencies:" todos/003-*.md

# 此待办阻塞了什么？
grep -l 'dependencies:.*"002"' todos/*.md

搜索：

# 按标签搜索
grep -l "tags:.*rails" todos/*.md

# 按优先级搜索
ls todos/*-p1-*.md

# 全文搜索
grep -r "payment" todos/

关键区别

file-todos 系统（本技能）：

todos/ 目录中的 Markdown 文件
开发/项目跟踪
带 YAML frontmatter 的独立 Markdown 文件
供人类和智能体使用

Rails Todo 模型：

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

TodoWrite 工具：

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