todo-create

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

File-Based Todo Tracking

基于文件的待办事项跟踪

Overview

概述

The

.context/compound-engineering/todos/

directory is a file-based tracking system for code review feedback, technical debt, feature requests, and work items. Each todo is a markdown file with YAML frontmatter.

Legacy support: Always check both
.context/compound-engineering/todos/
(canonical) and
todos/
(legacy) when reading. Write new todos only to the canonical path. This directory has a multi-session lifecycle -- do not clean it up as scratch.

.context/compound-engineering/todos/

目录是一个基于文件的跟踪系统，用于管理代码评审反馈、技术债务、功能请求和工作项。每个待办事项是一个带有YAML前置元数据的Markdown文件。

遗留版本支持：读取时请同时检查
.context/compound-engineering/todos/
（标准路径）和
todos/
（遗留路径）。新的待办事项仅写入标准路径。该目录具有跨会话生命周期——请勿将其作为临时目录清理。

Directory Paths

目录路径

Purpose	Path
Canonical (write here)	`.context/compound-engineering/todos/`
Legacy (read-only)	`todos/`

用途	路径
标准路径（写入此路径）	`.context/compound-engineering/todos/`
遗留路径（只读）	`todos/`

File Naming Convention

文件命名规范

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

issue_id: Sequential number (001, 002, ...) -- never reused
status:
```
pending
```
|
```
ready
```
|
```
complete
```
priority:
```
p1
```
(critical) |
```
p2
```
(important) |
```
p3
```
(nice-to-have)
description: kebab-case, brief

Example:

002-ready-p1-fix-n-plus-1.md

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

issue_id：连续编号（001、002……）——永不重复使用
status：
```
pending
```
（待处理）|
```
ready
```
（就绪）|
```
complete
```
（已完成）
priority：
```
p1
```
（关键）|
```
p2
```
（重要）|
```
p3
```
（锦上添花）
description：短横线分隔命名（kebab-case），简洁明了

示例：

002-ready-p1-fix-n-plus-1.md

File Structure

文件结构

Each todo has YAML frontmatter and structured sections. Use the todo template included below when creating new todos.

yaml

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

Required sections: Problem Statement, Findings, Proposed Solutions, Recommended Action (filled during triage), Acceptance Criteria, Work Log.

Optional sections: Technical Details, Resources, Notes.

每个待办事项包含YAML前置元数据和结构化章节。创建新待办事项时请使用下方提供的模板。

yaml

---
status: ready
priority: p1
issue_id: "002"
tags: [rails, performance]
dependencies: ["001"]     # 此任务依赖的问题ID
---

必填章节： 问题说明、发现内容、解决方案建议、推荐操作（分类处理时填写）、验收标准、工作日志。

可选章节： 技术细节、参考资源、备注。

Workflows

工作流程

Tool preference: Use native file-search/glob and content-search tools instead of shell commands for finding and reading todo files. Shell only for operations with no native equivalent (
mv
,
mkdir -p
).

工具偏好：查找和读取待办事项文件时，请使用原生文件搜索/全局匹配和内容搜索工具，而非Shell命令。仅在没有原生等效操作时使用Shell（如
mv
、
mkdir -p
）。

Creating a New Todo

创建新待办事项

mkdir -p .context/compound-engineering/todos/

Search both paths for
```
[0-9]*-*.md
```
, find the highest numeric prefix, increment, zero-pad to 3 digits.
Use the todo template included below, write to canonical path as
```
{NEXT_ID}-pending-{priority}-{description}.md
```
.
Fill Problem Statement, Findings, Proposed Solutions, Acceptance Criteria, and initial Work Log entry.
Set status:
```
pending
```
(needs triage) or
```
ready
```
(pre-approved).

Create a todo when the work needs more than ~15 minutes, has dependencies, requires planning, or needs prioritization. Act immediately instead when the fix is trivial, obvious, and self-contained.

mkdir -p .context/compound-engineering/todos/

在两个路径中搜索
```
[0-9]*-*.md
```
，找到最大的数字前缀，递增后补零至3位数字。
使用下方提供的待办事项模板，以
```
{NEXT_ID}-pending-{priority}-{description}.md
```
为文件名写入标准路径。
填写问题说明、发现内容、解决方案建议、验收标准和初始工作日志条目。
设置状态：
```
pending
```
（需要分类处理）或
```
ready
```
（预先批准）。

创建待办事项的场景：工作耗时超过约15分钟、存在依赖关系、需要规划或需要优先级排序时。立即处理的场景：修复操作简单明了且独立完成时。

Triaging Pending Items

分类处理待处理项

Glob
```
*-pending-*.md
```
in both paths.
Review each todo's Problem Statement, Findings, and Proposed Solutions.
Approve: rename
```
pending
```
->
```
ready
```
in filename and frontmatter, fill Recommended Action.
Defer: leave as
```
pending
```
.

Load the

todo-triage

skill for an interactive approval workflow.

在两个路径中全局匹配
```
*-pending-*.md
```
文件。
查看每个待办事项的问题说明、发现内容和解决方案建议。
批准：将文件名和前置元数据中的
```
pending
```
改为
```
ready
```
，填写推荐操作。
推迟：保持
```
pending
```
状态不变。

加载

todo-triage

技能以使用交互式批准工作流。

Managing Dependencies

管理依赖关系

yaml

dependencies: ["002", "005"]  # Blocked by these issues
dependencies: []               # No blockers

To check blockers: search for

{dep_id}-complete-*.md

in both paths. Missing matches = incomplete blockers.

yaml

dependencies: ["002", "005"]  # 被这些问题阻塞
dependencies: []               # 无阻塞

检查阻塞项：在两个路径中搜索

{dep_id}-complete-*.md

文件。未找到匹配项表示阻塞项未完成。

Completing a Todo

完成待办事项

Verify all acceptance criteria.
Update Work Log with final session.
Rename
```
ready
```
->
```
complete
```
in filename and frontmatter.
Check for unblocked work: search for files containing
```
dependencies:.*"{issue_id}"
```
.

验证所有验收标准是否满足。
在工作日志中添加最终会话记录。
将文件名和前置元数据中的
```
ready
```
改为
```
complete
```
。
检查是否有未阻塞的工作：搜索包含
```
dependencies:.*"{issue_id}"
```
的文件。

Integration with Workflows

与现有工作流集成

Trigger	Flow
Code review	`/ce:review` -> Findings -> `/todo-triage` -> Todos
Autonomous review	`/ce:review mode:autofix` -> Residual todos -> `/todo-resolve`
Code TODOs	`/todo-resolve` -> Fixes + Complex todos
Planning	Brainstorm -> Create todo -> Work -> Complete

触发条件	流程
代码评审	`/ce:review` -> 发现内容 -> `/todo-triage` -> 待办事项
自动评审	`/ce:review mode:autofix` -> 剩余待办事项 -> `/todo-resolve`
代码TODO	`/todo-resolve` -> 修复 + 复杂待办事项
规划	头脑风暴 -> 创建待办事项 -> 执行工作 -> 完成

Key Distinction

关键区别

This skill manages durable, cross-session work items persisted as markdown files. For temporary in-session step tracking, use platform task tools (

TaskCreate

TaskUpdate

in Claude Code,

update_plan

in Codex) instead.

本技能管理以Markdown文件持久化的持久化跨会话工作项。若需临时的会话内步骤跟踪，请使用平台任务工具（如Claude Code中的

TaskCreate

TaskUpdate

，Codex中的

update_plan

）。

Todo Template

待办事项模板

@./assets/todo-template.md