task-control-doc

任务总控文档

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

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

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

---

1. 适用场景

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

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

---

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

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

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

• 新会话读「子任务详情 + 强制阅读文件」即可开工——这是准入下限，不是视野上限
• 鼓励执行会话开工前主动补读：「背景导航」列出的文件、父级总控、其他子任务详情、相关正式文档、代码现状——把背景挖够再动手。具备充分上下文处理能力的模型能自主取舍读什么；背景不足导致误判的代价，远大于多读几个文件
• 视野放开、扇出焊死：自主补读 = 亲自读（直接读文件 / 检索），禁止为"补背景"派子 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+ 个子任务、每个子任务详情很长（带大量强制阅读、设计明细）。