Task Control Doc

任务总控文档

当用户要求"为某件事做总控文档"时，使用本 skill。

真值源：~/.claude/skills/control/references/总控规范.md。本 skill 只描述如何创建总控；生命周期、归档定义、目录结构都在那里。

方法论补充：references/方法论.md（为什么要做、何时做、常见风险）。

1. 适用场景

• 任务很大、很复杂
• 任务可能跨多个会话完成
• 用户希望每个子任务都开新会话执行（这是默认假设）
• 上下文可能过长、容易污染或遗忘

中小任务用计划模式或 lightweight-design 即可，不需要总控。

2. 核心原则：子任务即工作包

这是本 skill 最重要的一条设计原则。

每个子任务都应该是一个自包含的工作包：

• 新会话读「子任务详情 + 强制阅读文件」即可开工——这是准入下限，不是视野上限
• 鼓励执行会话开工前主动补读：「背景导航」列出的文件、父级总控、其他子任务详情、相关正式文档、代码现状——把背景挖够再动手。强模型（Fable 5 / GPT-5.6 级）能自主取舍读什么；背景不足导致误判的代价，远大于多读几个文件
• 视野放开、扇出焊死：自主补读 = 亲自读（直接读文件 / 检索），禁止为"补背景"派子 agent / 起深度调查（读是加法、派 agent 是乘法；执行会话对背景问题是叶子）。觉得背景缺口大到需要专门调查 → 说明工作包本身没写清，停下向用户报告
• 执行与写入范围仍严格限于本子任务——读什么放开 ≠ 做什么放开
• 每个工作包必须记录 start_commit、allowed_write_paths、allowed_cross_task_writes；交付前对本子任务明确列出的候选提交运行 control/scripts/check_write_scope.py。无关提交不参与本子任务检查，候选提交夹带越界文件则直接失败
• 用户在新会话开头自己选模型，不预定义执行模式
• 子任务详情末尾有「会话启动提示词」可直接复制

写总控时按这个原则切分子任务：强制阅读（核心必读）精准 1-3 个（超了说明背景没消化成任务），背景导航不设上限（一行一条「路径 + 读它获得什么」，宁多勿缺）。

标准研发总控的强制阅读按职责放置，禁止只在背景导航里“提到但不读”：测试用例阶段绑定 test-standards + test-case-design；goal 章程阶段绑定 goal-charter；goal 执行阶段绑定章程、test-execution-router 与项目执行/部署/架构入口；候选终审阶段绑定证据协议、项目证据规则与冻结 L7。具体项目名由研发流程补丁填充。

3. 文件位置与结构

默认路径：<PROJECT_ROOT>/docs/00-任务总控/{YYYY-MM-DD}-{任务名}/

任务目录用日期前缀（创建日，YYYY-MM-DD），防多 worktree 编号撞车。同日创建多任务可加字母后缀 2026-05-10b-... 或时分 2026-05-10-1430-...。

支持两种模式（创建时选择）：

3.1 单文件模式（默认，适合中小总控）

{YYYY-MM-DD}-{任务名}/
├── README.md       # 主总控（含全部子任务详情）
└── _shared/        # 可选：唯一过程资产目录（归属由文件名前缀区分，见 §3.3）

适用：3-7 个子任务、各子任务详情不超过 50 行。

3.2 拆分模式（适合大总控）

{YYYY-MM-DD}-{任务名}/
├── README.md             # 主总控（任务背景 + 子任务总表 + 进展记录，不含子任务详情）
├── T1-{子任务名}.md       # T1 自包含工作包
├── T2-{子任务名}.md       # T2 自包含工作包
├── T6-{子任务名}.md
└── _shared/              # 可选：唯一过程资产目录（归属由文件名前缀区分，见 §3.3）
    ├── T3-{资产文件}.csv  # 子任务专属资产
    └── {资产文件}.md      # 任务级共享资产（无前缀）

适用：8+ 个子任务、每个子任务详情很长（带大量强制阅读、设计明细）。

优点：执行 T3 时只读 T3-xxx.md 一个文件，最小上下文。

⚠️ 拆分模式文件命名为脚本硬依赖：子任务文件名前缀必须与子任务总表「编号」列的内容完全一致。例如表中编号写 T1，对应文件必须命名为 T1-{子任务名}.md（next_subtask.py 用 glob("T1-*.md") 定位文件）。T01-xxx.md 或 t1-xxx.md 均无法被识别。

3.3 过程资产目录（唯一 _shared/，文件名前缀标归属）

任务执行过程中产生的中间文档（设计稿、数据样本、批判稿、清单等），不进入项目正式文档体系的，全部放进唯一资产目录 _shared/，归属由文件名前缀区分：

判定口诀：这个文件能填进某个 T{n} 的「输出物」字段吗？能 → 带 T{n}- 前缀；不能 → 无前缀。

高频资产标准名：T{n}-轻量设计方案.md / T{n}-goal章程.md / T{n}-goal飞行日志.md / T{n}-对抗评审报告.md / 用户裁决记录.md / 自愈清单.md（后两者为任务级无前缀），不得自创变体。对抗评审报告同时承载封闭式整改验收结果，不另建 R2/R3 报告。（T{n}-施工蓝图.md / T{n}-蓝图评审报告.md 本流程不再产出）

硬约束：

1. 资产目录只有 _shared/ 一个，必须以 _ 开头——脚本只在任务根目录一层 glob T{n}-*.md，不进 _shared/，资产带 T{n}- 前缀不会撞车
2. 禁止在任务根目录平铺资产；禁止新建 _T{n}/ 目录（旧规则已废除；存量任务的 _T{n}/ 原地只读）
3. 出现第一个资产时即建 _shared/，即使只有 1 个文件
4. 所有资产路径必须列在对应子任务详情的「输出物」字段——「输出物」是真值源，不再单独维护「资产清单」

详见 ~/.claude/skills/control/references/总控规范.md §1.1.1。

模板见：

• 单文件：assets/任务总控模板.md
• 拆分：assets/拆分模板/README.md + assets/拆分模板/子任务包.md

4. 必须包含的章节（单文件模式）

每份单文件总控（README.md）至少包含：

1. 任务背景
2. 总目标
3. 完成定义
4. 范围
5. 非范围
6. 全局强制阅读（最多 1-2 个项目级文件）
7. 全局约束与注意事项
8. 子任务总表
9. 子任务详情（每个独立小节）
10. 风险与待确认
11. 进展记录
12. 更新规则

不再单独写「本目录相关资产」章节：所有资产（_shared/ 下的过程资产）一律登记在对应子任务详情的「输出物」字段，避免双重维护。

拆分模式结构详见 §3.2 提及的两份模板。

⚠️ 脚本硬依赖（以下约束不可违反）：

1. 章节标题：子任务总表 这个名称是脚本正则匹配的固定锚点，不可改为 任务清单、子任务列表 等任何别名
2. 状态值：脚本精确匹配以下枚举，拼写不能变体：待完成 / 进行中 / 已完成 / 阻塞 / 已取消

5. 各章节写法要点

5.1 任务背景

• 任务起因
• 当前现状
• 为什么需要单独做总控

不要写已经过期的历史过程。

5.2 总目标

3-7 条结果表达（不是动作表达）。详见 references/方法论.md §6.1。

5.3 完成定义

可检查的标准。

5.4 范围 / 非范围

明确包含什么、不包含什么。非范围章节用于防止后续 agent 自动扩张任务范围。

5.5 全局强制阅读

最多 1-2 个项目级文件。具体执行所需的文件应放到子任务级强制阅读，不在这里堆。

5.6 全局约束与注意事项

放任务通用规则：真值优先级、不能动的目录、输出格式硬约束。

6. 子任务总表（§8）

| 编号 | 子任务 | 状态 | 依赖 | 预期输出 |
|------|------|------|------|---------|
| T1 | 需求明确与架构设计 | 待完成 | 无 | 架构方案、接口契约 |
| T2 | 数据管理模块开发 | 待完成 | T1 | 数据管理后台代码 |

状态枚举：待完成 / 进行中 / 已完成 / 阻塞 / 已取消

创建阶段不写二级：初始化总控时只列一级 T1/T2/T3...。需要拆分时由用户在执行过程中触发 /control <key> split Tn（详见下方 §6.1），不在创建阶段就预先拆好二级。这是因为大多数任务在动手前根本不知道哪一级会真的太大。

⚠️ 列名为脚本硬依赖，不可自定义：render_control_status.py 和 next_subtask.py 依赖固定列名匹配，不得重命名或替换以下四列：

• 编号（或 序号）
• 子任务（或 任务名称 / 子任务文件）
• 状态（或 当前状态）
• 预期输出（或 输出物 / 做什么）

如需追加任务专属列（如 批判编号），在这四列之后追加，不要替换。

注意：本 skill 不在子任务总表里写「执行模式」列。模型选择由用户在新会话开头决定（用 /model）。

6.1 中途拆分（一级 → 二级）

任务执行过程中，发现某个一级父任务 Tn 工作量超出预期、单一会话做不完 → 用户触发 /control <key> split Tn 把它原地拆为 Tn.1 ~ Tn.N。

只允许两级：Tn.x 不可再拆。深层就该开新总控、或重新设计任务边界。

拆分后表格自动变成：

| T1 | 父任务名 | 派生 | 无 | 父预期输出 |   ← 状态列固定占位「派生」，渲染时聚合
| T1.1 | 子任务一 | 待完成 | 无 | 子1输出 |
| T1.2 | 子任务二 | 待完成 | T1.1 | 子2输出 |
| T2 | ... | ... | T1 | ... |              ← 依赖 T1 自动语义为「所有 T1.* 完成」

详细规则：

• 父任务状态列固定写 派生（脚本会自动从子任务聚合实际状态）
• 二级编号必须形如 T{父}.{m}，m 从 1 起递增
• /control <key> split Tn 由用户显式触发；AI 不可自行决定拆分粒度
• 详细规范见 ~/.claude/skills/control/references/总控规范.md §1.2.1
• 执行流程见 control skill §5.5

7. 子任务详情（§9）—— 自包含工作包

每个子任务展开为独立小节，结构如下：

### Tn 子任务名称

- **当前状态**：待完成

#### 子任务背景
（这一个子任务的上下文，用一段话讲清楚为什么要做这件事）

#### 强制阅读（核心必读 1-3 个，准入下限、非视野上限）
- `路径`：为什么必须读 + 读完获得什么结论
- `路径`：为什么必须读

#### 背景导航（可选，不设上限）
- `路径`：读它获得什么背景（读不读由执行会话自行判断；**亲自读，不派 agent**）

#### 输入
（前置依赖的产出物，明确列出）

#### 写入范围（机器检查）
- `start_commit`: `<开工前当前提交 SHA>`
- `allowed_write_paths`:
  - `本工作包路径`
  - `本子任务输出物路径或目录/**`
- `allowed_cross_task_writes`:
  - `父级 README.md::子任务总表`
  - `父级 README.md::进展记录`
- 交付检查：`python3 ~/.claude/skills/control/scripts/check_write_scope.py --repo <项目根> --start-commit <SHA> --candidate <本子任务提交SHA> --allow <路径> ... --allow-cross '<路径>::<Markdown标题>' ...`

#### 要做的事情
- 第一步
- 第二步
- 第三步

#### 不做什么（可选，建议填）
- 不做 X（属于 T<n+1>）
- 不修改 Y（属于其他模块）

#### 预期效果
（执行完后系统/文档应该是什么状态）

#### 输出物（必填，可检查）
- `具体路径/文件名`：内容简述
- `具体路径/文件名`：内容简述

> **路径写法**：进入项目正式文档体系的写正式路径（如 `docs/03-技术设计/...md`）；不进的过程资产写 `_shared/T{n}-{资产名}`（子任务专属）或 `_shared/{资产名}`（任务级共享）。**所有资产都必须列在这里**，不再单独维护「资产清单」段。

#### 完成判定
- [ ] 输出物 1 已产出且通过自检
- [ ] 输出物 2 已产出且通过自检
- [ ] （其他可检查条件）

#### 依赖关系
- 依赖：T1 已完成
- 阻塞：T<n+1>

#### 风险与注意事项
- 风险点 1
- 风险点 2

#### 会话启动提示词（可直接复制到新会话）

​```
我要执行 docs/00-任务总控/{YYYY-MM-DD}-{任务名}/README.md 的 Tn 子任务。

【主体任务】{一句话：本子任务做什么、产出什么}
【目标终态】{完成判定的可度量压缩提要}
【边界提要】{「不做什么」关键禁令压缩；详细以本子任务详情为准，冲突时以详情为准}

请按以下步骤：
1. 读取这份总控的「任务背景」和子任务总表
2. 读取本子任务详情：Tn - {子任务名}
3. 读取「强制阅读」列出的文件；再主动补读「背景导航」和你自己判断需要的背景（其他子任务详情、相关正式文档、代码现状），把背景挖够再动手
4. 自主补读必须亲自读（直接读文件/检索），不要为补背景派子 agent 或起深度调查
5. 严格在 Tn 范围内执行，做完「要做的事情」、产出「输出物」、通过「完成判定」——读什么放开，做什么、写什么仍只限 Tn
6. 交付前对本子任务候选提交运行写入范围检查器；越界不得交付
7. 完成后回填总控状态为已完成
8. **不要做其他子任务**，做完立刻停止并向我报告
​```

会话启动提示词三要素（硬要求）：提示词开头、步骤清单之前必须有三段——①【主体任务】一句话说明本子任务做什么、产出什么；②【目标终态】完成判定的可度量压缩提要；③【边界提要】「不做什么」关键禁令压缩转述 + 显式声明「详细以工作包对应段为准」。三段全部是压缩转述 + 指针：验证命令、哈希值、豁免细节等易变真值只留在工作包 / 章程里，禁止复制进提示词——两处真值必漂移。goal 执行类子任务的【目标终态】须含各退出线的一行版提要。（对齐 Claude Code /goal 官方三要素——可度量终态 / 明确验证方式 / 关键约束。指针架构不变：提示词只做压缩提要，全量真值仍在工作包 / 章程）

唯一例外——goal 执行类子任务建总控时不写提示词，留占位：它的三要素原料（章程 §1 终态 / §3.2 禁令 / §4 白名单）全部来自终版章程，而章程要到 goal 章程子任务才产出、还要经风险整改与对应授权角色批准。建总控时写它只能猜，且评审整改可能改 §1/§3.2，写了必漂移。故该段由 goal 章程子任务在获批之后回填——这是全流程唯一被授权的跨子任务写入，只准写那一段。占位对下方 §13 落盘自检的「无残留 {{}}」不计违规。

且该段回填的不是本节这套「三要素 + 步骤清单」格式，而是一条 /goal 完成条件（四段式，写法与逐段取料表见 goal-charter §13.3～§13.5）：/goal 的条件本身就是首轮指令，官方设计里不需要另发提示词，拆成"提示词 + 条件"两块 = 双份真值必漂移。三要素不丢，承载在条件内——主体任务→开工指令段、目标终态→完成条件段、边界提要→约束段。

8. 进展记录与更新规则

8.1 进展记录

只写"会影响后续接手者"的关键进展：

- YYYY-MM-DD：[Tn] 完成，[摘要]

8.2 更新规则

• 子任务开始时改 进行中，开始前必须重新读取该子任务的强制阅读文件
• goal 首次启动、--resume、新会话或自动上下文压缩后，第一次写入前必须再次从磁盘完整读取当前工作包、全部强制阅读、章程、goal 断点与飞行日志尾部；连续未压缩轮次不机械复读整套 skill
• 子任务完成后改 已完成，立刻停止，不顺手做下一个
• 阻塞时改 阻塞 并写明原因
• 产出文件后回填到对应「输出物」
• goal 执行子任务跑完只到 CANDIDATE_READY：状态保持 进行中，进展记录登记「候选待终审」；候选终审 PASS 后才改 已完成
• 总控被另一任务接管收尾（未验收即移交）→ 进展记录登记「候选已交付·未验收·由 {接管任务} 接管」，子任务状态保持真实，不得补标已完成；该总控不归档，等接管任务闭环后一并处置
• 整体完成 → 用 archive_control.py --apply 自动归档（详见总控规范 §2.3）
• 任务删除 → 见总控规范 §2.4，不进归档

9. 输出物的好坏写法

好（明确可交付）：

• 补齐 docs/01-需求/{某具体文件}.md
• 完成某模块的 README 导航结构

差（抽象）：

• 把需求整理好
• 大概搞清楚业务

详见 references/方法论.md §6.2。

10. 使用模板

创建新总控文档时，必须基于模板填充。两个正交维度——模式（标准 / 自定义）×载体（单文件 / 拆分）：

两轴正交，不是三选一：不存在"单文件 vs 拆分 vs 研发流程"。模式决定「有哪些阶段 / 怎么连依赖」，载体决定「写进一个文件还是多个文件」。改任一轴时不得破坏正交性。

载体（按子任务数 / 详情长度自动选）：

标准模式 = 研发流程预设（正交，可叠加在任一载体上）：研发型任务（新功能 / 跨模块重构 / 带前后端+测试+部署链路）默认套用「八阶段动作菜单」，由 AI 据一句总需求实例化子任务树。模板见 assets/研发流程模板/，详见 §12、§13 与 references/标准研发流程.md。

自定义模式：用户显式声明"不套标准流程 / 我自己指定阶段"时，按用户指定编排，本 skill 不强加任何阶段，载体仍按上表自动选。

如该任务需要独立 git worktree，按总控规范 §3.3 命令模板手动 git worktree add 即可，无需在文档里登记。

11. 创建检查表

新建总控前自检：

• 任务大小确实达到"总控级"，不是 lightweight-design 能解决的
• 项目已 bootstrap（<PROJECT_ROOT>/docs/00-任务总控/README.md 存在），未初始化先跑 ~/.claude/skills/control/scripts/bootstrap_project.py
• 任务目录命名符合规范：{YYYY-MM-DD}-{中文任务名}/，日期为创建日
• 选择了合适的载体（单文件 / 拆分）——注意「载体」与「模式（标准 / 自定义）」是两个正交维度，别混为一谈
• 主总控文档名为 README.md（不是任务名+任务总控.md）
• 必备章节全部填充
• 全局强制阅读不超过 2 个文件
• 每个子任务都是自包含工作包：强制阅读（核心必读）精准 1-3 个、背景导航按需列出（宁多勿缺）、输出物可检查、完成判定可验
• 每个子任务都有结构化写入范围：start_commit、allowed_write_paths、allowed_cross_task_writes；状态回填与唯一跨任务写入均精确到 Markdown 标题
• 每个子任务详情末尾有「会话启动提示词」，且开头含三要素（【主体任务】/【目标终态】/【边界提要】，见 §7）——goal 执行类子任务除外：该段留占位，由 goal 章程子任务拍板后回填成一条 /goal 条件（非本套格式，见 §7 末）
• 子任务总表不含「执行模式」列
• 若需 worktree，已按总控规范 §3.3 命令模板创建（路径在主仓库兄弟目录）
• 已在顶层 docs/00-任务总控/README.md 「当前活跃任务」表追加该任务行
• 过程资产规范：尚未平铺资产到任务根目录；预先告知子任务作者，过程资产只能进 _shared/，且按文件名前缀标归属（详见 §3.3）
• （研发流程预设时） 已加载项目研发流程补丁；子任务树无残留 {{槽位}}；依赖引用 ⊆ 编号集合（无孤儿、无环）
• （含对抗评审时） 同一对象只安排一次开放式评审；整改后安排 {{封闭验收 skill}}，没有 R2/R3；业务决策负责人的授权裁决统一落 _shared/用户裁决记录.md#DEC-x 并记录实际角色

12. 标准研发总控流程（可选预设）

绝大多数研发型任务遵循同一条流水线：调查 → 探讨 → 轻量设计 → 测试用例设计 → 真值收敛与规格冻结 → goal 章程 → goal 执行产候选 → 候选终审。goal 章程同步产出无闸门的启动服务单，提前清算可预见的候选无关用户动作；goal 的第一个里程碑仍固定为 M0 启动检查，在既有授权内准备并修复环境、测试资产、runner、夹具与证据工具。两者都不恢复独立执行准备阶段。

两种模式，默认标准模式：用户不声明即套用上面这条八阶段流水线；用户显式声明「自定义」时按其指定编排，本 skill 不强加阶段。模式与载体（单文件 / 拆分）正交。

• 真值源：references/标准研发流程.md（八阶段菜单、拆分决策表、评审风险触发、DAG 连法、槽位发现协议）。
• 触发：用户说"按标准研发流程建总控" / "研发流程总控" / "标准研发流程"，或任务明显是研发流水线。
• 定位：正交预设（见 §10），不新增 /control 命令。
• 项目绑定：八阶段是抽象的；具体"每阶段读什么 / 产出落哪 / 怎么验证 / 哪是死亡线"由项目研发流程补丁填充（发现协议见 标准研发流程.md §6.1）。

13. 研发流程实例化交互流程

套用研发流程预设创建总控时按此走。前三步是对话（不落盘），第四步才写文件。

第一步（fail-stop）：加载项目补丁。 先按 标准研发流程.md §6.1 在项目 skills 目录定位「研发流程补丁」。找不到 → 停机询问用户（先建补丁 / 改用通用拆分模式手工编排），禁止用带 {{槽位}} 的纯抽象模板直接落盘。

第二步：第 0 步明确任务 → README 头部。 收集用户总目标 / 总内容，确认整体需求，写进 研发流程模板/README.md 头部（背景/总目标/完成定义/范围/非范围）。此步不占编号。

第三步：实例化子任务树草案（表格呈现，不落盘）。 按 标准研发流程.md §4 拆分决策表，针对本任务把八阶段菜单实例化成线性一级 T1..Tn 草案——含每阶段拆几个 / 塌缩 / 跳过、评审是否独立、DAG 依赖列。以表格呈现给用户勾选 / 增删。

第四步：定稿落盘。 用户定稿后：① 重排线性编号并同步重写依赖引用；② 从对应阶段片段（assets/研发流程模板/阶段片段库/）生成被选中阶段的 T{n}-*.md，用补丁槽位对照表替换全部 {{槽位}}；③ 回填 README 子任务总表 + DAG 依赖列；④ 顶层 docs/00-任务总控/README.md 活跃任务表追加一行。

阶段片段库对照（八阶段 + 1 张评审片段）：

施工蓝图.md / 文档闸门.md / 文档收尾.md / 交付发布.md 已退役删除，不要再引用或凭记忆重建。

落盘前自检（硬）：

• 无残留 {{}} 占位（补丁已填实）；例外：goal 执行片段的「会话启动提示词」段本就留占位，由 goal 章程阶段拍板后回填（见 §7 末），不计违规
• 依赖引用 ⊆ 编号集合（无孤儿依赖）、无环
• 子任务文件名 T{n}-*.md 前缀与总表编号列完全一致
• 落的是现行八阶段；第八阶段是候选终审，不是施工蓝图 / 文档收尾 / 交付发布类子任务
• goal 章程与 goal 执行均为显式子任务；goal 执行的 M0 启动检查覆盖全部命中面，可在授权边界内构建或修复测试资产、runner、夹具、环境适配与证据工具，但不得改变冻结 AC 的业务语义
• goal 章程已产出 _shared/T{n}-goal启动服务单.md，完成治理角色/职责分离声明、环境占用策略引用、四分类、PRE_GOAL 清算与 planned_human_windows 合并复核；服务单无 PASS/FAIL、不扩权、不限制 M0 刷新现场
• 调查清单只作影响面种子；轻量设计含最终真值切片、完整 SD-x 与 design_index_hash（哈希规范见 lightweight-design §7.2）
• 正式 L7 是用例唯一全文；规格冻结子任务产出规格物化覆盖报告，SD → 正式规格 → AC 全绿且任务切片内已知债务为零
• 规格冻结要求 materialization_pass / semantic_uniqueness_pass / satisfiability_pass / decision_provenance_pass / semantic_diff_pass 五项全真，且凡触发过评审的对象其封闭式整改验收终态 = PASS（以报告为证据，不设自报布尔）
• goal 只产出 CANDIDATE_READY；候选终审已实例化为显式子任务（不可塌缩），依赖精确 commit/tree、执行证据清单与飞行日志；终审 PASS 前 goal 执行子任务保持「进行中」并登记「候选待终审」，缺终审不得将 goal 子任务或总控标完成
• 每个被评对象同一基线只开放评审一次；回补后由 {{封闭验收 skill}} 的原生子线程检查、主线程裁决，PASS 才进入下游
• {{goal 执行绑定}} 复合槽位已逐项填全（goal 章程方法回读 + M0 启动检查 + 交付/部署 + 测试执行路由 + 项目执行 skill + 环境边界/架构规范 + 检查器命令，检查器命令可落「验证」列）——漏一项 goal 就不知道怎么准备执行面 / 怎么部署 / 怎么跑测试 / 拿什么判代码合规