Back to Details

util-manage-todo

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Manage Todo

待办事项管理

Purpose

目标

Manage 
./todo.md
in project root with task state tracking, TodoWrite synchronization, and ADR-governed refactor support. Primary use: Claude proactively creates/updates todos when detecting multi-step work.
管理项目根目录下的
./todo.md
文件，支持任务状态跟踪、TodoWrite同步，以及受ADR管控的重构支持。主要用途：当Claude检测到存在多步骤工作时，主动创建/更新待办事项。

CRITICAL: Todo File Location

重要提示：待办文件位置

Use 
./todo.md
for 95% of work (this skill)
Use This SkillSession Todo (rare)
Bug fixes, features, refactorsTemporary spikes only
Multi-step work, team coordinationThrowaway research
Work committed to gitQuick experiments (<1hr)
If unsure → use this skill
Session todos: 
.claude/artifacts/YYYY-MM-DD/todos/todo-{name}.md
95%的工作场景请使用
./todo.md
（本功能）
使用本功能会话待办（罕见场景）
Bug修复、功能开发、重构仅临时突发任务
多步骤工作、团队协作一次性调研工作
需提交至Git的工作快速实验（耗时<1小时）
若不确定→使用本功能
会话待办文件路径：
.claude/artifacts/YYYY-MM-DD/todos/todo-{name}.md

When to Use

适用场景

Agent-Initiated (PRIMARY)

智能体主动触发（主要场景）

PROACTIVELY invoke when Claude detects:
  • "I need to create a todo to track this work"
  • "User has given me multiple tasks to coordinate"
  • "This is complex enough to warrant tracking"
当Claude检测到以下情况时，主动调用本功能：
  • "我需要创建待办事项来跟踪这项工作"
  • "用户给了我多项任务需要协调"
  • "这项工作复杂度较高，需要进行跟踪"

User-Initiated

用户主动触发

When user requests:
  • "Create a todo for [feature]"
  • "Update task [N] to [state]"
  • "Track these tasks"
当用户提出以下请求时：
  • "为[功能]创建待办事项"
  • "将任务[N]的状态更新为[状态]"
  • "跟踪这些任务"

NOT to Use

不适用场景

  • Single, straightforward tasks
  • Trivial operations (<3 steps)
  • Purely informational requests
  • 单一、简单的任务
  • 琐碎操作（步骤<3）
  • 纯信息查询请求

Quick Start

快速开始

Creating a Todo

创建待办事项

  1. Read project context
  2. Create 
    ./todo.md
    with structured tasks
  3. Assign states (🔴 pending by default)
  4. Add acceptance criteria
  5. Sync with TodoWrite
  1. 读取项目上下文
  2. 创建结构化任务的
    ./todo.md
    文件
  3. 分配状态（默认🔴 待处理）
  4. 添加验收标准
  5. 与TodoWrite同步

Updating State

更新状态

  1. Read 
    ./todo.md
  2. Update task state: 🔴 → 🟡 → 🟢
  3. Update TodoWrite to match
  4. Update progress summary
  1. 读取
    ./todo.md
    文件
  2. 更新任务状态：🔴 → 🟡 → 🟢
  3. 更新TodoWrite保持同步
  4. 更新进度摘要

Checking Progress

查看进度

  1. Read 
    ./todo.md
  2. Calculate completion %
  3. Identify blockers
  4. Suggest next actions
  1. 读取
    ./todo.md
    文件
  2. 计算完成率%
  3. 识别阻塞点
  4. 建议下一步操作

Basic Todo Structure

基础待办事项结构

markdown
undefined
markdown
undefined

Todo: [Feature Name]

待办事项：[功能名称]

Date: YYYY-MM-DD
日期：YYYY-MM-DD

Objective

目标

[Clear statement of goal]
[清晰的目标说明]

Tasks

任务

Task 1: [Title]

任务1：[标题]

Status: 🔴 Not Started | 🟡 In Progress | 🟢 Complete Priority: High | Medium | Low
Description: What needs to be done.
Acceptance Criteria:
  • Functionality implemented
  • Tests pass
  • Code follows conventions
状态： 🔴 未开始 | 🟡 进行中 | 🟢 已完成 优先级： 高 | 中 | 低
描述： 需要完成的工作内容。
验收标准：
  • 功能已实现
  • 测试通过
  • 代码符合规范

Progress Summary

进度摘要

  • Total: X | Completed: Y (Z%)
undefined
  • 总计：X | 已完成：Y（Z%）
undefined

Task States

任务状态

StateMeaning
🔴 PendingNot started
🟡 In ProgressActively working
🟢 CompleteAcceptance criteria met
⚫ BlockedWaiting on dependency
状态含义
🔴 待处理未开始
🟡 进行中正在积极推进
🟢 已完成满足验收标准
⚫ 阻塞等待依赖项

Integration Requirements (CRITICAL)

集成要求（重要）

Prevents "done but not integrated" failures.
避免“已完成但未集成”的失败情况。

The CCV Principle

CCV原则

PhaseWhat It Proves
CREATIONArtifact exists
CONNECTIONWired into system
VERIFICATIONWorks at runtime
Missing any phase = NOT complete
阶段验证内容
创建（CREATION）确认工件已存在
连接（CONNECTION）确认已接入系统
验证（VERIFICATION）确认运行时正常工作
缺少任一阶段 = 未完成

Four Questions Test

四项问题测试

Before "done", answer ALL:
  1. How do I trigger this?
  2. What connects it to the system?
  3. What proves it runs?
  4. What shows it works?
标记“已完成”前，必须全部回答：
  1. 如何触发该功能？
  2. 它与系统的连接点是什么？
  3. 如何证明它能运行？
  4. 如何证明它能正常工作？

Three-Phase Todo Pattern

三阶段待办事项模式

For integration work:
markdown
undefined
针对集成工作：
markdown
undefined

Phase 1: CREATION

阶段1：创建

  • Create [module]
  • Unit tests pass
  • 创建[模块]
  • 单元测试通过

Phase 2: CONNECTION

阶段2：连接

  • Import in [consumer]
  • Register in [system]
  • Verify: 
    grep "module" src/
  • 在[消费方]中导入
  • 在[系统]中注册
  • 验证：
    grep "module" src/

Phase 3: VERIFICATION

阶段3：验证

  • Integration test passes
  • Execution logs attached
  • Expected outcome observed

**See:** [references/integration-requirements.md](references/integration-requirements.md)
  • 集成测试通过
  • 附上执行日志
  • 观察到预期结果

**参考：** [references/integration-requirements.md](references/integration-requirements.md)

Key Integrations

关键集成

TodoWrite Synchronization

TodoWrite同步

Rule: 
todo.md
is source of truth
Update todo.md → Update TodoWrite → Verify sync
规则： 
todo.md
为唯一可信源
更新todo.md → 更新TodoWrite → 验证同步状态

Refactor/Migration Tracking

重构/迁移跟踪

Rule: Refactors REQUIRE an ADR
  1. Detect refactor keywords
  2. Invoke 
    validate-refactor-adr
    skill
  3. If no ADR: STOP, instruct user to create
  4. If ADR exists: Use enhanced template
规则： 重构工作必须有对应的ADR
  1. 检测重构关键词
  2. 调用
    validate-refactor-adr
    功能
  3. 若无ADR：停止操作，指导用户创建ADR
  4. 若有ADR：使用增强模板

Task Sizing

任务规模

Good size:
  • 1-4 hours of focused work
  • Clear deliverable
  • Single responsibility
  • Testable outcome
Too large: "Implement entire auth system" Too small: "Add import statement"
合适的任务规模：
  • 1-4小时的专注工作
  • 交付成果清晰
  • 单一职责
  • 可测试的结果
规模过大： "实现完整的认证系统" 规模过小： "添加导入语句"

Enforcement Rules

执行规则

  1. No Create Without Connect — Creation needs connection tasks
  2. No Connect Without Verify — Connection needs verification
  3. No Verify Without Evidence — Attach proof when checking
  4. Phase 3 Blocks Completion — Cannot complete without runtime proof
  1. 无连接不创建 — 创建任务时必须包含连接相关任务
  2. 无验证不连接 — 连接任务时必须包含验证相关任务
  3. 无证据不验证 — 完成验证时必须附上证明材料
  4. 阶段3阻塞完成 — 未完成阶段3则不能标记为已完成

Supporting Files

支持文件

References

参考文档

  • references/reference.md - Task states, sync protocol, refactor tracking
  • references/integration-requirements.md - CCV principle, patterns
  • references/reference.md - 任务状态、同步协议、重构跟踪
  • references/integration-requirements.md - CCV原则、模式

Templates

模板

  • templates/todo-templates.md - Five use-case templates
  • templates/refactor-todo-template.md - ADR-governed refactor
  • templates/integration-verification-checklist.md - Integration verification
  • templates/todo-templates.md - 五种场景模板
  • templates/refactor-todo-template.md - 受ADR管控的重构模板
  • templates/integration-verification-checklist.md - 集成验证清单

Examples

示例

  • examples/examples.md - Workflows and examples
  • examples/examples.md - 工作流及示例

Red Flags

警示信号

Anti-PatternWhy Bad
Todos for trivial tasksOverhead exceeds value
Vague descriptionsNo clear acceptance criteria
Refactor without ADRViolates policy
TodoWrite out of syncBreaks single source of truth
Tasks too large/smallPoor granularity
Session todo for production workShould use ./todo.md
反模式危害
为琐碎任务创建待办管理成本超过价值
描述模糊缺乏清晰的验收标准
无ADR的重构违反规范
TodoWrite不同步破坏唯一可信源
任务规模过大/过小颗粒度不合理
用会话待办处理生产工作应使用./todo.md

Success Metrics

成功指标

MetricTarget
Context reduction80% vs agent prompts
Sync accuracy100% todo.md ↔ TodoWrite
ADR compliance100% for refactors
Integration verificationAll Phase 3 tasks have evidence
Version: 2.0.0 | Updated: 2025-12-07
指标目标
上下文减少率比智能体提示减少80%
同步准确率todo.md ↔ TodoWrite 100%同步
ADR合规率重构工作100%符合ADR要求
集成验证率所有阶段3任务均有验证证据
版本： 2.0.0 | 更新日期： 2025-12-07