Write Tasks 指南

spec-write-tasks 是 spec-plan 与 spec-work 之间的可选派生层。它不执行代码，只做三件事之一：把已定稿的 source plan 编译成 derived task pack、校验已有 task pack，或返回"不需要 task pack"的决定。Claude 入口是 spec-write-tasks，Codex 入口是 spec-write-tasks。

入口

场景	Claude Code	Codex
把计划拆成可执行任务	spec-write-tasks docs/plans/<plan>.md	spec-write-tasks docs/plans/<plan>.md
校验已有 task pack	spec-write-tasks docs/tasks/<pack>.md	spec-write-tasks docs/tasks/<pack>.md

执行逻辑图

已定稿的本地 source plan
  |
  v
判断是否值得派生 task pack（体量、依赖、执行风险、上下文负载）
  |
  +-- 不值得 --> skip / return-to-plan
  |
  v
编译 derived task pack 或校验已有 task pack
  |
  v
写 docs/tasks/ 下的 task pack（带 spec_id、source_plan、source_plan_hash、
generated_by: spec-write-tasks、mode: derived 和 Task Pack Contract JSON）
  |
  v
交给 spec-work 执行；plan 仍是 single source of truth

何时使用

• 已定稿的本地 source plan 太大或依赖复杂，不适合直接执行。
• 用户明确要求把 plan 拆成任务。
• 已有 task pack 需要在 spec-work 前校验。

什么时候不该用

• 产品或架构范围尚未收敛。
• 小改动，不需要派生层。
• 远程仓库、包名、marketplace 标识或通用任务清单。
• 应直接进 spec-work 的实现型请求。
• 手改 generated runtime mirror。

产物与契约

可执行 task pack 位于 docs/tasks/，必须携带 spec_id、source_plan、source_plan_hash、generated_by: spec-write-tasks、mode: derived 和有效的 Task Pack Contract JSON block。task pack 是派生执行索引，永远不替代 source plan。

失败以 machine-readable reason code 表达，例如 source_plan_missing、ambiguous_plan、missing_spec_id、wrong_chain、stale_hash、unverifiable_hash、invalid_contract、repo_scope_missing、scope_gap。

下一步

• 需要先产出计划：Plan 指南
• task pack 就绪后执行：Work 指南
• 理解任务系统整体：Task Pack 与任务系统