Spec-First

Appearance

Todo 管理系统 ​

概述 ​

Spec-First 提供基于文件的持久化待办管理系统，支持从创建、审批到批量解决的全生命周期。Todo 项以 Markdown 文件形式存储，跨会话持久存在。

三个核心技能 ​

技能命令用途
todo-create/todo-create创建新的待办项
todo-triage/todo-triage交互式审批待办项
todo-resolve/todo-resolve批量解决已审批的待办项

文件命名规范 ​

{issue_id}-{status}-{priority}-{description}.md
字段说明示例
issue_id顺序编号，三位数001, 002
status当前状态pending, ready, complete
priority优先级p1, p2, p3
description简短描述（kebab-case）fix-n-plus-1

示例： 002-ready-p1-fix-n-plus-1-queries.md

存储路径 ​

.context/spec-first/todos/     ← 规范路径（写入）
todos/                          ← 遗留路径（只读兼容）

生命周期 ​

创建 (todo-create)        → pending
    ↓
审批 (todo-triage)        → pending → ready (或删除)
    ↓
执行 (todo-resolve)       → ready → complete
    ↓
清理                       → 文件删除

状态说明 ​

状态含义可执行操作
pending已创建，等待审批triage 审批
ready已审批，等待执行resolve 执行
complete已完成自动清理

创建待办 ​

bash
/todo-create

何时创建 Todo：

条件建议
工作需要 > 15 分钟创建 Todo
有依赖关系创建 Todo
需要规划或排优先级创建 Todo
简单修复（< 15 分钟）直接执行，不创建 Todo

文件结构：

markdown
---
status: pending
priority: p2
issue_id: "001"
tags: [rails, performance]
dependencies: []
---

## Problem Statement
[问题描述]

## Findings
[调查发现]

## Proposed Solutions
[建议方案]

## Acceptance Criteria
[验收标准]

审批待办 ​

bash
/todo-triage

交互式逐项审批，对每个 pending 项提供三个选项：

选项动作
yes批准，状态改为 ready
next跳过，删除 Todo 文件
custom修改后再审批

优先级映射：

严重度优先级说明
P1 (Critical)p1必须修复
P2 (Important)p2应该修复
P3 (Nice-to-have)p3可选改进

注意： 审批阶段不写代码，只做决策。

批量解决 ​

bash
/todo-resolve

批量处理所有 ready 状态的待办项：

  1. 分析 — 按状态分区，检查依赖关系
  2. 规划 — 创建任务列表，分析执行顺序
  3. 并行执行 — 为每个待办项启动独立代理
  4. 提交 — 提交代码变更，标记完成
  5. 知识沉淀 — 触发 /spec:compound 记录经验
  6. 清理 — 删除已完成的 Todo 文件

并行策略：

待办数量执行策略
1-4 个直接并行
5+ 个分批执行，每批 4 个

与 Review 工作流的集成 ​

/spec:review mode:autofix
    │
    ├─ safe_auto 问题 → 自动修复
    ├─ gated_auto/manual 问题 → 生成 Todo (pending)
    ↓
/todo-triage
    │
    ├─ 审批通过 → ready
    ↓
/todo-resolve
    │
    ├─ 批量执行
    ↓
/spec:compound
    │
    ├─ 沉淀经验

最佳实践 ​

  • ✅ 精简描述 — Todo 标题控制在 5 个词以内
  • ✅ 明确验收标准 — 每个Todo 都有可验证的完成条件
  • ✅ 标注依赖 — 有前置条件的 Todo 标注 dependencies
  • ✅ 定期审批 — 不让 pending 积压过多
  • ✅ 及时清理 — 完成后删除 Todo 文件

常见错误 ​

  • ❌ 所有事情都建 Todo → ✅ 简单修复直接做，>15 分钟才建 Todo
  • ❌ 审批阶段写代码 → ✅ 审批只做决策，实现留给 resolve
  • ❌ 不标依赖关系 → ✅ 有关联的 Todo 标注 dependencies
  • ❌ 积压不处理 → ✅ 定期运行 triage 和 resolve

下一步 ​