# Build Cognitive Execution Engine

> 任务执行引擎——选择正确的执行模式。当 plan 已批准需要写代码，或提到"执行""实现""编码"

- Skill: `zeroz-lab/build-cognitive-execution-engine` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add zeroz-lab/build-cognitive-execution-engine`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zeroz-lab/build-cognitive-execution-engine/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zeroz-lab (https://skillmd.com/u/zeroz-lab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zeroz-lab/build-cognitive-execution-engine

---


# 执行引擎 — 3 种执行模式


## 入口/出口
- **入口**: `build-workflow-plan` 完成，任务列表已就绪
- **出口**: 所有任务完成 + 测试通过 + 代码合并
- **指向**: 全部任务完成后建议 `/review`
- **输出路径**: → verify-workflow-review
- **前置加载**: CANON.md + `build-quality-tdd/SKILL.md` + `build-workflow-execute/SKILL.md`

## 何时不使用
- 还没有批准的 plan 或任务列表
- 当前只是探索、诊断或写 spec/design，不进入实现
- 只有一个微小文档或配置改动，不需要选择执行模式

## 任务输入契约

执行引擎只消费 `/plan` 已批准的任务列表：**implement this plan task-by-task**。

- 每个 `### Task N` 是一个执行单元，必须有验收条件和验证证据
- `plans/*.md` 子计划也是执行单元；子计划内部仍按 `### Task N` 逐项执行
- 引擎可以选择 inline / subagent / parallel，但不能重新创建正式任务列表
- 任何 subagent 输入都必须绑定一个明确的 `Task N` 或 `plans/*.md` 子计划

## Subagent Operating Principle

Subagent 的目标是隔离高噪音上下文、执行专项任务、压缩可决策信息；并行只是可选收益，不是默认目标。

适合分派 subagent：
- 大量搜索、日志、测试输出、diff 或文件读取会污染主 session
- 任务能独立完成，主 session 只需要摘要、证据、风险和下一步
- 需要限制工具权限、Read Scope 或 Write Scope
- 多个模块、假设或风险点能独立验证

不适合分派 subagent：
- 小改动、简单格式化、单文件连续编辑
- 需要频繁 human partner 确认的决策
- plan -> implementation -> testing 之间强共享上下文且必须由主 session 连续判断
- 输出摘要会比任务本身更长

每次分派必须写清：Goal、Task Source、Selected Persona、Read Scope、Write Scope、Forbidden Actions、Allowed Tools、Output Limit、Completion Criteria。
默认优先 read-only；只有 implementer / debugger 类型任务允许 Edit / Write。
返回内容不得包含原始日志、完整 diff、大段代码、长篇推理或无关背景。默认压缩到 1200 字以内；最后一行必须是单行 JSON：`{"status":"...","changed_files":[],"test_results":[],"artifact_paths":[]}`。

## Agent Dispatch Contract

执行引擎选择执行模式时，也必须选择明确 persona；persona 选择不改变 Task N / Write Scope / Verification Evidence。

- Plan / mode selection → `agents/task-planner.md`
- Software implementation → `agents/software-engineer.md`
- API contract task → `agents/api-designer.md` first, then `agents/software-engineer.md`
- Data schema / migration task → `agents/data-architect.md` first, then `agents/software-engineer.md`
- Document / article task → `agents/content-writer.md`
- Deck task → `agents/content-writer.md` for narrative first, then `agents/visual-designer.md` for layout
- Visual task → `agents/visual-designer.md`

Mode B fan-out can use different personas in parallel only when their Write Scope does not overlap and semantic independence is explicit. Mode C implementer/reviewer prompts must name the selected persona and include its required skills, inputs, outputs, scope, allowed tools, output limit, and completion criteria.

## 三种执行模式

### 模式 A: 直接执行

主 agent 按 `### Task N` 顺序执行。适用单文件修改、简单 bug 修复、配置变更。

规则：实现 → 测试验证 → 记录/提交 → 下一个 Task N。当前 Task N 验证未通过前不进入下一个。每个任务 < 100 行变更。不要同时开多个实现分支。

### 模式 B: 并行 Fan-Out

面对 2+ 个真正独立的 `Task N` 或 `plans/*.md` 子计划（无共享文件、无共享状态、无顺序依赖），一次性分派。

**规则：**
- 一个消息分派所有 subagent（真正并行）
- 每个 subagent 独立上下文、独立文件、独立结果
- 并行输入必须来自 `Parallel Execution Matrix` 中明确 `parallel_safe: yes` 的 task 或子计划
- 每个 subagent 只能修改所属子计划的 `Write Scope`
- 分派完 → 等结果 → 审查 → 合并

**禁止并行：** 任务有依赖关系、修改同一文件、共享 DB schema 变更、共享 API/type/flag/config/test 契约未冻结、子计划缺 Write Scope / Verification Evidence / Merge Checkpoint / Cross-check Command / Semantic Independence Reason、release/export/ship 收口子计划。

### gated-parallel

当 `Plan Topology` 是 `gated-parallel`：主 agent 先串行执行 contracts/gated/serial 子计划 → 共享契约验证通过 → 才分派依赖该契约的 `parallel_safe` 子计划。契约变化时已分派子计划全部作废。

**分派模板：** 每个 subagent 必须指定 Goal、Task Source、Selected Persona、Write Scope、Read Scope、Forbidden Actions、Allowed Tools、Shared Contracts、Global Invariants、Verification Evidence、Cross-check Command、Merge Checkpoint、Output Limit、Completion Criteria。最后一行输出 JSON 包含 status + changed_files + test_results + artifact_paths。

### 模式 C: Subagent Pre-Review Gate 流水线

用于高复杂度任务（跨多模块、关键业务逻辑、需安全审查）。

**流程：** Implementer subagent → 返回 status → Spec Gate subagent（独立验证）→ Code Quality Gate subagent（五轴审查）。

**定位：** 这是 build 阶段的内部保险丝，不是 formal `/review`。通过此 gate 只表示“允许继续集成 / 进入正式审查候选”，不表示“已经完成正式审查”。

**关键规则：**
- Implementer 输入必须包含具体 Task N / 子计划路径、验收条件、Write Scope、Verification Evidence
- Implementer / reviewer 输入必须包含 Allowed Tools、Forbidden Actions、Output Limit 和 Completion Criteria
- 每个 subagent 新鲜上下文 — 不传递前一个 subagent 对话历史
- Spec Gate 不信任 Implementer 报告 — 独立验证
- Code Quality Gate 必须等 spec 合规确认后才开始
- 严禁并行分派 Implementer
- 审查阶段串行门控：先 Spec Gate，SPEC_MATCH 后才分派 Code Quality Gate
- Mode C 结果不得写成 APPROVED / LGTM / READY TO MERGE；formal `/review` 仍需单独产出 `04-review.md`

**提示词模板：** 使用 `implementer-prompt.md`、`spec-reviewer-prompt.md`、`quality-reviewer-prompt.md`。

## Subagent 模型选择

| 复杂度 | 模型 | 适用 |
|--------|------|------|
| 低 | Haiku / 廉价模型 | 样板代码、格式变更、copy-paste 重构 |
| 中 | Sonnet / 标准模型 | 常规实现、CRUD、前端组件 |
| 高 | Opus / 能力最强模型 | 核心业务逻辑、复杂算法、安全关键代码 |

**原则：** 不省不该省的钱。Entity 关系重构用 Opus，改颜色变量用 Haiku。

## Fan-Out 合并

并行 agent 返回后：全部 DONE → 合并变更 + 跑全量测试；有失败 → 回退失败 agent 变更 + 重新分派；有冲突 → 合并有效部分 + 手动处理冲突。

**合并前必做：**
- [ ] 每个 agent 测试通过
- [ ] 全量测试套件通过（交叉影响检测）
- [ ] 每个子计划的 `Cross-check Command` 已运行并通过
- [ ] 无文件冲突
- [ ] 每个 agent 绑定的 Task N 返回 DONE 或 BLOCKED
- [ ] changed_files ⊆ Write Scope
- [ ] Verification Evidence 和 Merge Checkpoint 已满足

## 何时不使用这些模式

- 不用模式 B 当任务有顺序依赖/共享文件，或 `Parallel Execution Matrix` 没有证明 `parallel_safe`
- 不用模式 C 当任务简单到 1 个 agent 20 分钟能完成 — 两阶段审查是复杂任务保险，不是流程税
- 不用 subagent 处理需要实时人类确认的决策 — 主 agent 直接问
- 不用 subagent 处理同一文件内的连续小修改 — 主 agent 串行执行更清晰
- 不用 subagent 只为了"多开几个 agent" — 没有噪音隔离、权限收窄或独立验证价值就保持 inline

## 常见说辞

| 说辞 | 现实 | 后果 |
|------|------|------|
| "分派太慢，我直接写" | 1 个复杂任务 subagent 做 15min > 你猜 2h。并行 3 个 15min vs 串行 45min。 | 主 agent 猜测实现 > 单次返工 30-50%，总耗时 2-3x |
| "并行不会冲突" | 两个 agent 改同一文件 = 必定合并冲突。 | 合并冲突手动解决 > 30min/冲突，严重时丢弃一个 agent 全部变更 |
| "build 里已经审过了，不用 /review" | Mode C 只是 pre-review gate，不能替代 formal `/review`。 | 缺少独立 formal review → 合并质量门失效 → 返工和漏检风险叠加 |
| "跳过审查，代码看起来对" | 两阶段审查防止"看起来对但不符 spec"的错误。 | 无审查 → Implementer 偏离 spec → 合入不合规代码 → 返工 > 2x |
| "再分派一次也一样" | 第一次偏离 → 补约束 → 第二次才可能对。 | 不补约束重分派 → 同样偏离 → 3 次循环浪费 45+ min |
| "多开几个 agent 更保险" | 未限定目标、工具和输出上限的 subagent 会把噪音变成多份噪音摘要。 | 主 session 被重复背景、完整日志和无关建议污染，决策质量下降 |

## 红旗 — STOP

- 没有明确 `Task N` 或子计划就分派 subagent
- Subagent 派发缺 Goal / Scope / Forbidden Actions / Allowed Tools / Output Limit / Completion Criteria
- 模式 B 任务之间不是真正独立的（隐式依赖或共享文件）
- Subagent 报告 "DONE" 但没有 changed_files 列表
- Subagent 返回原始日志、完整 diff、大段代码或长篇推理
- Spec Gate 报告 SPEC_MATCH 但没提供独立验证证据
- 连续 3 次 Implementer 返回 ISSUES — 约束/任务描述可能有问题
- 两个并行 agent 在改同一文件 — 回退，串行化
- subagent 修改了 Write Scope 外文件 — 回退变更，重新分派或串行执行
- `parallel_safe` 不是来自 `Parallel Execution Matrix` 的显式结论 — 停止并行
- 子计划缺 `Cross-check Command` 或 `Semantic Independence Reason` 却被标为 `parallel_safe`
- Code Quality Gate 发现了 Spec Gate 应发现的问题 — 审查顺序错了
- Subagent 上下文不包含 spec 文档 — 盲区工作

## 验证清单

- [ ] 执行模式匹配任务性质（独立/依赖/复杂）
- [ ] 并行任务文件不重叠
- [ ] 并行任务的共享契约、全局不变量和语义独立性已显式记录
- [ ] 多计划 fan-out 只使用 `parallel_safe` 子计划
- [ ] 每个执行单元绑定明确 `Task N` 或子计划
- [ ] 每个 subagent 有子计划路径、Write Scope、Read Scope、Verification Evidence、Merge Checkpoint、Cross-check Command
- [ ] 每个 subagent 有 Forbidden Actions、Allowed Tools、Output Limit、Completion Criteria
- [ ] 每个 subagent 返回压缩摘要，最后一行为 status / changed_files / test_results / artifact_paths JSON
- [ ] changed_files 没有越过 Write Scope
- [ ] 两阶段审查顺序正确
- [ ] 合并后全量测试通过
- [ ] 没有"看起来 DONE 但没证据"的状态

## 验证失败处理

| 失败场景 | 处理方式 |
|---------|---------|
| Implementer 返回 BLOCKED | 人类介入。不猜测原因，不静默跳过 |
| Implementer 返回 NEEDS_CONTEXT | 提供更多上下文，重新分派 |
| Spec Gate 返回 SPEC_GAP | 退回 Implementer 修正，列出具体 gap |
| Code Quality Gate 发现 Spec Gate 应发现的问题 | STOP，重走 Spec → Quality 顺序 |
| 连续 3 次 Implementer 返回 ISSUES | STOP。回到 `/plan` 修补，不第四次分派 |
| 并行 agent changed_files 越界 | 回退越界 agent，降级串行或重切 Write Scope |
| 并行 agent 文件冲突 | 合并有效部分，冲突部分串行重做 |
| Cross-check Command 失败 | 视为语义耦合未被控制，回退相关并行结果并降级串行 |
| 全量测试合并后失败 | 定位失败 agent，回退其变更，修复后重跑 |

## 输出模板

```markdown
### Execution Engine 交付记录

**执行模式**: [inline / subagent / parallel fan-out]
**任务来源**: [03-plan.md Task N / plans/*.md 子计划名]

**任务完成状态**:
| Task N | 状态 | changed_files | test_results | 验证证据 |
|--------|------|--------------|-------------|---------|
| [Task N] | DONE / BLOCKED / NEEDS_CONTEXT | [文件列表] | [通过/失败] | [描述] |

**并行结果**（如适用）:
- Agent 1: [status] — Write Scope: [范围] — changed_files ⊆ Write Scope ✓/✗
- Agent 2: [status] — Write Scope: [范围] — changed_files ⊆ Write Scope ✓/✗

**Cross-check 结果**: [命令 + PASS/FAIL]
**合并后全量验证**: [通过 / 失败 — 具体原因]
```