名称: file-todos 描述: 当管理 todos/ 目录中的文件型待办事项跟踪系统时，应使用此技能。它提供了创建待办事项、管理状态和依赖关系、进行分级以及与斜杠命令和代码审查流程集成的 workflows。

文件型待办事项跟踪技能

概述

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

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

从发现或反馈创建新待办事项
管理待办事项生命周期（待处理 → 就绪 → 完成）
对待处理项目进行分级审批
检查或管理依赖关系
将 PR 评论或代码发现转换为跟踪的工作
在待办事项执行期间更新工作日志

文件命名约定

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

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

组件：

issue_id: 顺序号（001, 002, 003…）- 永不重复使用
status: pending（需要分级）、ready（已批准）、complete（已完成）
priority: p1（关键）、p2（重要）、p3（可有可无）
description: 短横线分隔，简短描述

示例：

001-pending-p1-邮件测试.md
002-ready-p1-修复-n-plus-1.md
005-complete-p2-重构-csv.md

文件结构

每个待办事项是一个带有 YAML frontmatter 和结构化部分的 markdown 文件。在创建新待办事项时，使用 todo-template.md 中的模板作为起点。

必需部分：

问题陈述 - 什么被破坏、缺失或需要改进？
发现 - 调查结果、根本原因、关键发现
提议解决方案 - 多种选择，包括优缺点、工作量、风险
推荐行动 - 明确计划（在分级期间填写）
验收标准 - 可测试的检查清单项
工作日志 - 按时间顺序的记录，包括日期、行动、学习

可选部分：

技术细节 - 影响文件、相关组件、数据库更改
资源 - 错误链接、测试、PR、文档
注释 - 额外上下文或决策

YAML frontmatter 字段：

---
status: ready              # pending | ready | complete
priority: p1              # p1 | p2 | p3
issue_id: "002"
tags: [rails, 性能, 数据库]
dependencies: ["001"]     # 此待办事项被这些 issue IDs 阻塞
---

常见 Workflows

创建新待办事项

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

确定下一个 issue ID：ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1
复制模板：cp assets/todo-template.md todos/{NEXT_ID}-pending-{priority}-{description}.md
编辑并填写必需部分：
- 问题陈述
- 发现（如果来自调查）
- 提议解决方案（多种选择）
- 验收标准
- 添加初始工作日志条目
确定状态：pending（需要分级）或 ready（预批准）
添加相关标签以过滤

何时创建待办事项：

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

何时立即行动：

问题很琐碎（< 15 分钟）
现在有完整上下文可用
无需规划
用户明确请求立即行动
具有明显解决方案的简单错误修复

对待处理项目进行分级

对待处理待办事项进行分级：

列出待处理项目：ls todos/*-pending-*.md
对于每个待办事项：
- 阅读问题陈述和发现
- 审阅提议解决方案
- 做决策：批准、推迟或修改优先级
更新已批准待办事项：
- 重命名文件：mv {file}-pending-{pri}-{desc}.md {file}-ready-{pri}-{desc}.md
- 更新 frontmatter：status: pending → status: ready
- 填写“推荐行动”部分，提供明确计划
- 如果初始评估不同，调整优先级
推迟的待办事项保持在 pending 状态

使用斜杠命令： /triage 进行交互式审批 workflow

管理依赖关系

跟踪依赖关系：

dependencies: ["002", "005"]  # 此待办事项被 issues 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 未完成"
done

更新工作日志

在处理待办事项时，始终添加工作日志条目：

### YYYY-MM-DD - 会话标题

**作者：** Claude Code / 开发者姓名

**行动：**
- 具体更改（包括文件:行引用）
- 执行的命令
- 运行的测试
- 调查结果

**学习：**
- 什么有效 / 什么无效
- 发现的模式
- 对未来工作的关键见解

工作日志用作：

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

完成待办事项

标记待办事项为完成：

验证所有验收标准已勾选
在工作日志中添加最终会话和结果
重命名文件：mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md
更新 frontmatter：status: ready → status: complete
检查未阻塞的工作：grep -l 'dependencies:.*"002"' todos/*-ready-*.md
提交并引用 issue：feat: 解决 issue 002

与开发 Workflows 的集成

触发器	流程	工具
代码审查	`/workflows:review` → 发现 → `/triage` → 待办事项	审查代理 + 技能
PR 评论	`/resolve_pr_parallel` → 个别修复 → 待办事项	gh CLI + 技能
代码 TODOs	`/resolve_todo_parallel` → 修复 + 复杂待办事项	代理 + 技能
规划	头脑风暴 → 创建待办事项 → 工作 → 完成	技能
反馈	讨论 → 创建待办事项 → 分级 → 工作	技能 + 斜杠

快速参考命令

查找工作：

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

# 列出所有需要分级的待处理项目
ls todos/*-pending-*.md

# 查找下一个 issue 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 工具：

在代理会话期间的内存任务跟踪
单个对话的临时跟踪
不持久化到磁盘
与以上两个系统不同