Task control doc
给「AI 驱动开发」立规矩的 Claude Code skill 方法论库：七层文档治理 · 对抗评审 · 任务总控三驾马车，外加老代码考古、施工蓝图等共 16 个 skill —— 让 AI 写代码又快又不失控。
npx -y skills add BackToCimaCoppi/Praxis --skill task-control-docAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Use when the user wants a master control document for a large, complex, long-running, or multi-session task. Defines how to create a task control doc that captures background, mandatory reads, subtask breakdown, and self-contained work packages so each subtask can be executed in a fresh session with minimal context.
SKILL.md
24.9 KB, as published. Nobody here has run it
任务总控文档
当用户要求"为某件事做总控文档"时，使用本 skill。
真值源：~/.claude/skills/control/references/总控规范.md。本 skill 只描述如何创建总控；生命周期、归档定义、目录结构都在那里。
方法论补充：references/方法论.md（为什么要做、何时做、常见风险）。
1. 适用场景
- 任务很大、很复杂
- 任务可能跨多个会话完成
- 用户希望每个子任务都开新会话执行（这是默认假设）
- 上下文可能过长、容易污染或遗忘
中小任务用计划模式或 lightweight-design 即可，不需要总控。
2. 核心原则：子任务即工作包
这是本 skill 最重要的一条设计原则。
每个子任务都应该是一个自包含的工作包：
- 新会话读「子任务详情 + 强制阅读文件」即可开工——这是准入下限，不是视野上限
- 鼓励执行会话开工前主动补读：「背景导航」列出的文件、父级总控、其他子任务详情、相关正式文档、代码现状——把背景挖够再动手。强模型（Fable 5 / GPT-5.6 级）能自主取舍读什么；背景不足导致误判的代价，远大于多读几个文件
- 视野放开、扇出焊死：自主补读 = 亲自读（直接读文件 / 检索），禁止为"补背景"派子 agent / 起深度调查（读是加法、派 agent 是乘法；执行会话对背景问题是叶子）。觉得背景缺口大到需要专门调查 → 说明工作包本身没写清，停下向用户报告
- 执行与写入范围仍严格限于本子任务——读什么放开 ≠ 做什么放开
- 用户在新会话开头自己选模型，不预定义执行模式
- 子任务详情末尾有「会话启动提示词」可直接复制
写总控时按这个原则切分子任务：强制阅读（核心必读）精准 1-3 个（超了说明背景没消化成任务），背景导航不设上限（一行一条「路径 + 读它获得什么」，宁多勿缺）。
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}-{资产名}.md | T2-模型能力调查.md |
| 二级子任务产出 | T{n}.{m}-{资产名}.md | T6.3-联调记录.md |
| 多文件资产 | T{n}-{资产名}/ 子目录 | T8-渲染样图/ |
| 任务级共享（无单一归属） | 无前缀自然中文名 | 需求资料.md |
| 进入项目正式文档体系 | 项目本地约定路径（不在总控目录） | 按项目自身规则 |
判定口诀：这个文件能填进某个 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 已随施工蓝图退役，新任务不得再产出）
硬约束：
- 资产目录只有
_shared/一个，必须以_开头——脚本只在任务根目录一层 globT{n}-*.md，不进_shared/，资产带T{n}-前缀不会撞车 - 禁止在任务根目录平铺资产；禁止新建
_T{n}/目录（旧规则已废除；存量任务的_T{n}/原地只读） - 出现第一个资产时即建
_shared/，即使只有 1 个文件 - 所有资产路径必须列在对应子任务详情的「输出物」字段——「输出物」是真值源，不再单独维护「资产清单」
详见 ~/.claude/skills/control/references/总控规范.md §1.1.1。
模板见：
- 单文件：
assets/任务总控模板.md - 拆分：
assets/拆分模板/README.md+assets/拆分模板/子任务包.md
4. 必须包含的章节（单文件模式）
每份单文件总控（README.md）至少包含：
- 任务背景
- 总目标
- 完成定义
- 范围
- 非范围
- 全局强制阅读（最多 1-2 个项目级文件）
- 全局约束与注意事项
- 子任务总表
- 子任务详情（每个独立小节）
- 风险与待确认
- 进展记录
- 更新规则
不再单独写「本目录相关资产」章节：所有资产（
_shared/下的过程资产）一律登记在对应子任务详情的「输出物」字段，避免双重维护。
拆分模式结构详见 §3.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**）
#### 输入
（前置依赖的产出物，明确列出）
#### 要做的事情
- 第一步
- 第二步
- 第三步
#### 不做什么（可选，建议填）
- 不做 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. **不要做其他子任务**，做完立刻停止并向我报告
```
会话启动提示词三要素（硬要求）：提示词开头、步骤清单之前必须有三段——①【主体任务】一句话说明本子任务做什么、产出什么；②【目标终态】完成判定的可度量压缩提要；③【边界提要】「不做什么」关键禁令压缩转述 + 显式声明「详细以工作包对应段为准」。三段全部是压缩转述 + 指针：验证命令、哈希值、豁免细节等易变真值只留在工作包 / 章程里，禁止复制进提示词——两处真值必漂移。goal 执行类子任务的【目标终态】须含各退出线的一行版提要。（依据：2026-07-22 用户裁决；对齐 Claude Code /goal 官方三要素——可度量终态 / 明确验证方式 / 关键约束。指针架构不变：提示词只做压缩提要，全量真值仍在工作包 / 章程）
唯一例外——goal 执行类子任务建总控时不写提示词，留占位：它的三要素原料（章程 §1 终态 / §3.2 禁令 / §4 白名单）全部来自终版章程，而章程要到 goal 章程子任务才产出、还要经红队整改与用户拍板。建总控时写它只能猜，且红队必改 §1/§3.2，写了必漂移。故该段由 goal 章程子任务在拍板之后回填——这是全流程唯一被授权的跨子任务写入，只准写那一段。占位对下方 §13 落盘自检的「无残留 {{}}」不计违规。
且该段回填的不是本节这套「三要素 + 步骤清单」格式，而是一条 /goal 完成条件（四段式，写法与逐段取料表见 goal-charter §13.3～§13.5）：/goal 的条件本身就是首轮指令，官方设计里不需要另发提示词，拆成"提示词 + 条件"两块 = 双份真值必漂移。三要素不丢，承载在条件内——主体任务→开工指令段、目标终态→完成条件段、边界提要→约束段。（依据：2026-07-22 + 2026-07-25 用户裁决）
8. 进展记录与更新规则
8.1 进展记录
只写"会影响后续接手者"的关键进展：
- YYYY-MM-DD：[Tn] 完成，[摘要]
8.2 更新规则
- 子任务开始时改
进行中，开始前必须重新读取该子任务的强制阅读文件 - 子任务完成后改
已完成，立刻停止，不顺手做下一个 - 阻塞时改
阻塞并写明原因 - 产出文件后回填到对应「输出物」
- goal 执行子任务跑完只到
CANDIDATE_READY：状态保持进行中，进展记录登记「候选待终审」；候选终审 PASS 后才改已完成 - 总控被另一任务接管收尾（未验收即移交）→ 进展记录登记「候选已交付·未验收·由 {接管任务} 接管」，子任务状态保持真实，不得补标已完成；该总控不归档，等接管任务闭环后一并处置
- 整体完成 → 用
archive_control.py --apply自动归档（详见总控规范 §2.3） - 任务删除 → 见总控规范 §2.4，不进归档
9. 输出物的好坏写法
好（明确可交付）：
- 补齐
docs/01-需求/{某具体文件}.md - 完成某模块的 README 导航结构
差（抽象）：
- 把需求整理好
- 大概搞清楚业务
详见 references/方法论.md §6.2。
10. 使用模板
创建新总控文档时，必须基于模板填充。两个正交维度——模式（标准 / 自定义）×载体（单文件 / 拆分）：
| 维度 | 取值 | 谁决定 |
|---|---|---|
| 模式 | 标准（默认） / 自定义 | 用户不声明即标准；显式声明才走自定义 |
| 载体 | 单文件 / 拆分 | AI 按子任务数 + 详情长度自动选 |
两轴正交，不是三选一：不存在"单文件 vs 拆分 vs 研发流程"。模式决定「有哪些阶段 / 怎么连依赖」，载体决定「写进一个文件还是多个文件」。改任一轴时不得破坏正交性。
载体（按子任务数 / 详情长度自动选）：
| 载体 | 模板 | 写到哪里 |
|---|---|---|
| 单文件（默认，≤7 子任务且各 <50 行） | assets/任务总控模板.md | <任务目录>/README.md |
| 拆分（8+ 子任务或单包很长） | assets/拆分模板/README.md + assets/拆分模板/子任务包.md | <任务目录>/README.md + <任务目录>/T{n}-{子任务名}.md |
标准模式 = 研发流程预设（正交，可叠加在任一载体上）：研发型任务（新功能 / 跨模块重构 / 带前后端+测试+部署链路）默认套用「八阶段动作菜单」，由 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 个、背景导航按需列出（宁多勿缺）、输出物可检查、完成判定可验
- 每个子任务详情末尾有「会话启动提示词」，且开头含三要素（【主体任务】/【目标终态】/【边界提要】，见 §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 执行产候选 → 候选终审。第八阶段是对精确候选的独立验收，不是恢复已退役的“交付发布”分段。
两种模式，默认标准模式：用户不声明即套用上面这条八阶段流水线；用户显式声明「自定义」时按其指定编排，本 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 |
| ⑤ 真值收敛与规格冻结 | 规格冻结.md |
| ⑥ goal 章程 | goal章程.md |
| ⑦ goal 执行 | goal执行.md |
| ⑧ 候选终审 | 候选终审.md |
| （风险触发的独立评审） | 评审.md |
施工蓝图.md/文档闸门.md/文档收尾.md/交付发布.md已退役删除，不要再引用或凭记忆重建。
落盘前自检（硬）：
- 无残留
{{}}占位（补丁已填实）；例外：goal 执行片段的「会话启动提示词」段本就留占位，由 goal 章程阶段拍板后回填（见 §7 末），不计违规 - 依赖引用 ⊆ 编号集合（无孤儿依赖）、无环
- 子任务文件名
T{n}-*.md前缀与总表编号列完全一致 - 落的是现行八阶段；第八阶段是候选终审，不是施工蓝图 / 文档收尾 / 交付发布类子任务
- 调查清单只作影响面种子；轻量设计含最终真值切片、完整
SD-x与design_index_hash（哈希规范见lightweight-design§7.2） - 正式 L7 是用例唯一全文；T5 产出规格物化覆盖报告，
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 章程方法回读 + 交付/部署 + 测试执行路由 + 项目执行 skill + 环境边界/架构规范 + 检查器命令，检查器命令可落「验证」列）——漏一项 goal 就不知道怎么部署 / 怎么跑测试 / 拿什么判代码合规