name: 文件待办事项 description: 该技能应用于管理 todos/ 目录中的文件型待办事项跟踪系统。它提供了创建待办事项、管理状态和依赖、进行处理以及集成斜杠命令和代码审查流程的工作流。

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

概述

todos/ 目录包含一个文件型跟踪系统，用于管理代码审查反馈、技术债务、功能请求和工作项。每个待办事项都是一个带有 YAML 前言的 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加1问题.md
005-complete-p2-重构CSV.md

文件结构

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

必需部分：

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

可选部分：

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

YAML 前言字段：

---
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
编辑并填写必需部分：
- 问题陈述
- 发现（如果来自调查）
- 建议解决方案（多个选项）
- 验收标准
- 添加初始工作日志条目
确定状态：pending（需要处理）或 ready（预批准）
添加相关标签以便过滤

何时创建待办事项：

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

何时立即行动而不是：

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

处理待处理项

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

列出待处理项：ls todos/*-pending-*.md
对于每个待办事项：
- 阅读问题陈述和发现
- 审查建议解决方案
- 做决策：批准、推迟或修改优先级
更新已批准的待办事项：
- 重命名文件：mv {file}-pending-{pri}-{desc}.md {file}-ready-{pri}-{desc}.md
- 更新前言：status: pending → status: ready
- 填写“推荐行动”部分，包含清晰计划
- 如果不同于初始评估，调整优先级
推迟的待办事项保持 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 "问题 $dep 未完成"
done

更新工作日志

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

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

**由：** Claude Code / 开发者名称

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

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

工作日志用作：

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

完成待办事项

标记待办事项为完成：

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

与开发工作流的集成

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

快速参考命令

查找工作：

# 列出最高优先级的未阻塞工作
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/

关键区分

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

todos/ 目录中的 markdown 文件
开发/项目跟踪
独立的 markdown 文件带 YAML 前言
由人类和代理使用

Rails Todo 模型：

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

TodoWrite 工具：

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