Skip to main content

难点：docs + TODO.md 到 openspec

下面把 「先列 docs + 写 TODO.md」 补进演进叙事，形成面试里更好讲的 三阶段对比（你们仓库里两种形态都还在：docs/ 与 openspec/）。

演进路线（面试用一句话）​

docs + TODO.md 解决了「记下来、拆任务」；OpenSpec 在此基础上解决了「可验收的需求、可评审的变更、跨会话不丢意图」——不是推翻文档，而是 把文档升级成可 diff、可归档的 spec 体系。

三阶段对比​

阶段做法解决了什么仍存在的痛点
0. 无体系口头 + 直接改代码快需求漂移、评审只能靠 diff、上下文在聊天里
1. docs + TODO.md（你最初）docs/mpc-share-design.md、docs/create-mpc-wallet-refactor-plan.md、docs/TODO.md有设计说明、有 checklist、新人能读见下表「TODO/docs 的局限」
2. OpenSpecopenspec/specs/ + openspec/changes/<id>/能力级 spec + 变更级 delta + tasks需要维护 spec，不能「只勾 TODO」

阶段 1：你实际做过的（可举真实文件）​

1）docs/TODO.md —— 任务清单​

  • 勾选项：mpc backupShare、loss one share、send transaction 等
  • 附带 JSON 数据格式示例
  • 优点：上手快、和 Jira/脑内任务一致、实现时逐项打勾很有成就感
  • 局限：
    • 只有 做了什么 / 没做什么，很少写清 系统必须怎样（SHALL）
    • 勾选完就「过期」，不会自动变成 团队对行为的长期约定
    • 边界场景（中途退出、失败回滚）容易漏在 checkbox 之间

2）docs/*.md 设计/重构计划 —— 叙述型文档​

例如 docs/create-mpc-wallet-refactor-plan.md：Goal、Why、Scope、Current vs Target Architecture。

  • 优点：适合 一次性重构、讲清 Why 和架构
  • 局限：
    • 和 最终代码是否一致 要靠人记得改文档
    • PR 评审时很难像 spec delta 那样 一眼看到「需求变了哪几条」
    • 多链 MPC（EVM / Bitcoin / Solana…）各写一份 plan，模式重复、不易对齐

3）分散的 topic docs​

如 docs/mpc-share-design.md、docs/chain.md —— 知识在，但 没有统一「能力 ID + Requirement + Scenario」，Agent 也难稳定检索「当前权威行为是什么」。

阶段 1 → 2：为什么从 TODO/docs 走到 OpenSpec（动机叙事）​

痛点（docs + TODO 阶段）OpenSpec 的对应物
TODO 勾完，行为契约 仍只在代码里openspec/specs/<capability>/spec.md 长期保留 MUST/SHALL + Scenario
重构 plan 写完就 和实现分叉change 归档后 spec 合并进主库，意图跟代码一起走 git
「预创建 share 何时 persist」这种 安全边界 写在 plan 段落里，评审易漏spec MODIFIED 增量 + 明确 Scenario（放弃流程不得持久化）
多链对齐靠复制粘贴 plan每条能力一条 spec + 一条 change（如 *-send-mpc-alignment）
换会话 / 换 Agent 要重读多篇 docs固定结构：proposal → design → tasks → spec delta

这和 OpenSpec FAQ 里几条一致：不是不要计划，而是计划要可携带、可评审、可活在仓库里；Brownfield 按需长 spec，不是一次性写完全部文档。

更新后的「使用前 / 使用后」（含你的真实路径）​

使用前（你的阶段 1）​

  • 规划：docs/TODO.md 列 MPC backup / sign / send；大改写 docs/*-plan.md
  • 对齐：评审看 markdown 全文 + 代码 diff
  • 验收：checkbox [x]
  • 沉淀：docs 目录越堆越多，权威行为 仍要读代码确认

使用后（阶段 2）​

  • 规划：openspec/changes/<id>/proposal.md（Why/What）+ tasks.md
  • 对齐：先看 spec delta（意图），再看实现
  • 验收：Scenario 是否满足（GIVEN/WHEN/THEN），tasks 是否做完
  • 沉淀：openspec/specs/ 按能力维护；TODO 可保留作 个人/冲刺 scratch，但 不以 TODO 为契约

重要表述（防面试官觉得你在否定自己）：

docs + TODO 并没有错，在探索期和单点重构上很合适；当 MPC 边界变多、多人/多 Agent 协作变频繁时，缺的是可版本化的需求层，才引入 OpenSpec——是 演进，不是推翻。

30 秒口述（含 docs/TODO 版本）​

项目早期我先用 docs 里的设计说明和 docs/TODO.md 管 MPC 大项——备份、丢 share、多链 send，实现时勾选 checklist，大重构再写 refactor plan。这在单线程、单功能时够用，但 TODO 只反映进度不反映系统必须行为，plan 也容易和代码分叉。后来引入 OpenSpec：能力 spec 写清 Scenario，每次改动有 proposal 和 spec 增量，评审先对意图再对代码。TODO 我仍会用来跟冲刺，但 契约以 spec 为准。

STAR 里可加的一句（Action 段）​

A（补充）

  • 第一阶段：用 docs/TODO.md + docs/create-mpc-wallet-refactor-plan.md 拆 MPC 工作与重构范围
  • 第二阶段：对 persist 时机、多链 signing 对齐 等易漂移边界，改为 OpenSpec change + spec delta
  • 保留 docs/ 作 背景/历史设计；行为真相 以 openspec/specs 为准

若被问：「那 TODO.md 还要不要？」​

建议答法：

  • 要，适合个人冲刺、临时拆解、和工具无关的 checklist
  • 不要 用它替代「系统 SHALL…」和 PR 上的需求评审
  • 理想分工：OpenSpec = 契约与变更；TODO = 执行进度；docs = 背景、架构叙事、一次性方案（与 OpenSpec：specs live in your code 不矛盾）

如果你愿意，我可以把上一版完整面试稿和这份 三阶段版 合并成一份可直接打印的「一页纸」结构（仍控制在 1～2 页）。