TODO 管理与执行

术-操作 · 术层 skill 全文

本页是 <code>rules/skills/workflow_todo.md</code> 的逐字投影（仅隐私清洗，零改写）。

Skill: TODO 管理与执行

When to Use

• 用户说「开始 TODO」「做 TODO」「查看 TODO」「添加 TODO」等
• 用户通过 Dispatch 发来任务创建请求
• 需要检查或管理未完成任务时

使用的工具

工具路径见 tools/INDEX.md。

数据位置：

• contexts/todo/TODO.md — 任务列表
• contexts/todo/history/ — 每日操作历史
• contexts/daily_records/claude/ — 对话日志（用于上下文回溯）

外部依赖：Apple Reminders "项目待办" 列表（iCloud 同步）、remindctl（已授权）

todo CLI 命令

# 查看
todo list
todo list --status all
todo show <id>

# 添加
todo add "标题" --priority high --desc "描述" --context "file1,file2"

# 状态变更
todo start <id>
todo done <id> --notes "完成说明"
todo cancel <id> --notes "原因"

# 编辑
todo edit <id> --desc "新描述" --priority medium

注：todo 是 python3 tools/todo/todo.py 的简写（从仓库根执行）。该入口含 repo bootstrap，支持手册和 cron 直接用 path-script 写法；路径真源仍从 tools/INDEX.md 查。

执行流程

场景 A: 用户说「开始 TODO」「去完成 TODO」

主对话只做调度，不做执行。每个 TODO 通过独立 Claude Code 进程完成。

阶段 1：同步与排序

1. 同步：todo_sync（全量双向同步）
2. 列出任务：todo list，展示给用户
3. 筛选：判断每个 pending 任务是否可由 AI 独立完成。需要用户参与的（如"同步微信内容"）标记跳过，告知用户
4. 排序：按优先级排序（high > medium > low），同优先级内检查是否有依赖关系（如 T012 依赖 T011 的产出），确定执行顺序
5. 确认：向用户报告执行计划（顺序、预计跳过的任务），用户确认后开始

阶段 2：串行执行（每个 TODO = 独立 CC 进程）

对每个待执行的 TODO，按顺序执行以下步骤：

a. 标记开始：todo start <id>

b. 准备 prompt：组装 CC 子实例的任务 prompt，包含：

• 任务标题、描述、context_files
• workspace 根目录路径
• 必读文件列表：rules/SOUL.md、rules/USER.md、rules/WORKSPACE.md、rules/COMMUNICATION.md、rules/skills/INDEX.md
• 任务相关的 skill 路径（从 INDEX.md 判断）
• 明确的完成标准和输出要求
• 语言要求（中文为主，技术术语保留英文）

c. 通过 sub-agent 调用 CC 子实例：

主对话不直接调用 claude CLI。通过 Agent tool 派出一个 sub-agent（run_in_background=true），由 sub-agent 执行 CC 调用。

sub-agent 内部执行：

PROMPT="<组装好的任务 prompt>"
TASK_ID="T011"
LOG_DIR="/tmp/cc_selfinvoke"
mkdir -p "$LOG_DIR"

printf '%s' "$PROMPT" | env -u CLAUDECODE claude -p \
  --model opus \
  --setting-sources "user,project" \
  --strict-mcp-config \
  --permission-mode acceptEdits \
  --max-turns 50 \
  --output-format json \
  --allowedTools "Bash,Read,Write,Edit,Glob,Grep,Agent,WebSearch,WebFetch" \
  > "$LOG_DIR/todo_${TASK_ID}_result.json" 2> "$LOG_DIR/todo_${TASK_ID}_error.log"

遵循 Claude Code Self Evoke / Call Codex / Loop 硬规则（详见 skill claude_code_self_evoke_call_codex_loop）：

1. env -u CLAUDECODE：移除嵌套检测
2. --setting-sources "user,project" --strict-mcp-config：加载 workspace 规则，隔离默认 MCP
3. 输出重定向到文件：不依赖 stdout

注意：不加 --no-session-persistence。CC 子实例的 session 会自动保存到 [session-path]，与正常交互 session 格式一致。每天 06:00 的 extract_claude_conversations cron 会自动将这些 session 提取到 contexts/daily_records/claude/，纳入记忆管线。

CC 子实例是完整的 Claude Code 进程，拥有 Agent tool，可以自行派出 sub-agent 处理子任务。

d. 等待完成：等系统通知 sub-agent 完成，取回结果

e. 验证结果与记录：

主对话检查 CC 子实例的产出：

• 读取 result.json，检查 subtype 是否为 success
• 从 result.json 提取 session_id，记录到 history（todo done 的 notes 中包含 session_id，便于日后回溯）
• 检查任务描述中要求的文件是否已生成/修改
• 如果失败（error_max_turns 或实际产出不符预期），可通过 --resume <session_id> 续接调试，或决定跳过

f. 标记完成：todo done <id> --notes "完成说明。session: <session_id>"

g. 进入下一个 TODO，重复 a-f

阶段 3：汇总

所有 TODO 执行完毕后：

• 汇总每个 TODO 的执行结果（成功/失败/跳过）
• 报告给用户

场景 B: 用户说「添加 TODO」

1. 先同步：todo_sync（全量双向同步），确保 ID 不冲突、两侧状态一致
2. 从用户消息中提取任务标题、描述、优先级
3. 识别相关文件路径作为 context
4. 执行 todo add ...
5. 确认添加成功

场景 C: 用户通过 Dispatch 发来任务

Dispatch 消息通常简短。处理方式：

1. 解析消息意图
2. 如果是任务创建：同场景 B
3. 如果是查询状态：同「查看 TODO」
4. source 标记为 dispatch

CC 子实例内部行为

以下是 CC 子实例启动后应自行完成的事项（写在 prompt 中指导它）：

上下文回溯（CC 子实例自行完成）

1. 读取必读文件：SOUL/USER/WORKSPACE/COMMUNICATION/skills INDEX
2. 关键词搜索：从任务标题和描述中提取关键词，在 contexts/daily_records/claude/ 中 grep
3. 时间窗口：优先搜索任务创建日期前后 3 天的日志
4. 文件关联：如果 context_files 指向具体文件，读取这些文件了解当前状态
5. 历史完成记录：检查 contexts/todo/history/ 中是否有相关任务的完成记录
6. 调研报告：在 contexts/survey_sessions/ 中搜索相关调研

迭代执行（CC 子实例自行完成）

对于探索性或开发性任务，采用 autoresearch 循环：

1. 理解目标和当前状态
2. 执行一步改动
3. 验证结果
4. 如果不满足：分析原因，调整方案，重复
5. 如果满足：写入完成产物

CC 子实例可以使用 Agent tool 派出 sub-agent 处理子任务（如并行调研、代码编辑等）。

Prompt 模板

主对话组装给 CC 子实例的 prompt 应包含以下结构：

你是一个独立的 Claude Code 执行进程，负责完成以下 TODO 任务。

## 任务
- ID: {task_id}
- 标题: {title}
- 描述: {description}
- 优先级: {priority}
- 关联文件: {context_files}

## Workspace
根目录: ~/context-infra

## 必读文件（启动后立即读取）
1. rules/SOUL.md
2. rules/USER.md
3. rules/WORKSPACE.md
4. rules/COMMUNICATION.md
5. rules/skills/INDEX.md

## 相关 Skill
{相关 skill 路径列表}

## 上下文回溯
启动后先做上下文回溯：
- grep contexts/daily_records/claude/ 搜索与任务相关的历史对话
- 读取 context_files 中列出的文件
- 搜索 contexts/survey_sessions/ 中的相关调研
- 检查 contexts/todo/history/ 中的相关记录

## 完成标准
{具体的完成标准和输出要求}

## 约束
- 语言：中文为主，技术术语保留英文
- 所有重要发现写入文件，不要只留在输出中
- 可以使用 Agent tool 派出 sub-agent 处理子任务
- 完成后在输出中明确说明做了什么、产出了什么文件

自动提取

定时任务 todo_extractor（路径见 config/CRONTAB.md）每日 08:30 扫描 claude_logs，提取未完成任务自动添加到 TODO 列表（source=extracted）。

多设备输入与双向同步

用户可以从任何设备添加任务到"项目待办"列表：

• iPhone/iPad：提醒事项 app → "项目待办" 列表
• Siri：通过"项目记事"快捷指令（见 contexts/todo/SETUP_SHORTCUT.md）
• Mac：remindctl add "内容" --list "项目待办"
• Claude Code session：直接说「添加 TODO: XXX」

todo_sync 工具每 30 分钟自动双向同步。同步包括：新增同步、完成同步、删除检测（通过 .sync_state.json 跟踪上次状态，检测两侧的删除操作）。

todo_sync              # 全量双向同步（含删除检测）
todo_sync --pull       # 仅 Reminders → TODO.md
todo_sync --dry-run    # 预览

冲突策略：以最新操作为准。Reminders 侧删除 → TODO.md 自动 cancel；TODO.md 侧 cancel/done → Reminders 自动标记完成。

Session 开始时：执行 TODO 前必须先跑 todo_sync，不要依赖 30 分钟的 cron 间隔。

与现有系统的关系

• Apple Reminders：通过 remindctl 双向同步，"项目待办" 专用列表隔离生活事项
• Observer：observer 负责提炼观察，todo_extractor 负责提取任务，二者互补
• Reflector：reflector 将经验晋升到 rules/，TODO 系统管理待执行的工作项
• UX Observer：UX 痛点可以触发 TODO（如"为这个痛点写 draft skill"）
• Heartbeat 时间线：todo_extractor 08:30，todo_sync 每 30 分钟，todo_daily_reminder 09:00

相关文档（最新，2026-04-11）

TODO 工具自身

微信接入（weclaude）相关

下一轮优化的集中入口