# AI Agent 服从性工程 — 让 AI 读完工作流后真正干活

> 来源：2026 年多来源综合（Anthropic Skill Engineering、Microsoft Code Words、Strands Steering Hooks、Gradient Flow Harness Engineering）
> 适用场景：AI 编码 Agent（Claude Code / Codex / Cursor / Cline / Windsurf / Kiro 等）读完 README/RULES.md 后只确认不执行、跳过步骤、自作主张省略关键操作

---

## 核心问题诊断

AI Agent "读了工作流但不干活"的根因不是模型能力不够，而是**自然语言指令存在语义逃逸空间**：

| 根因 | 解释 |
|------|------|
| **上下文注意力衰减** | 长文档中部的内容被 LLM 注意力机制降权，Agent 实际只"看到"开头和结尾 |
| **语义覆盖** | 模型优化"帮助性"时会创造性重解释显式指令（如把 MUST DO X 理解成"建议做 X"） |
| **被动语言被当可选** | "Ready for next step → invoke X" 被当作建议而非指令 |
| **无状态强制** | 缺少外部状态机验证工作流顺序，Agent 可跳过步骤而不被发现 |
| **沉默状态腐化** | Agent 产出结构正确但语义错误的结果，错误静默累积 |

---

## 技术 1：指令置顶原则（Critical-First Pattern）

**把"下一步做什么"放在最前面，上下文放在后面。**

```
WRONG (Agent 忽略):
  [70 行项目背景和工具列表]
  → "下一步：运行 bootstrap 安装缺失工具"

CORRECT (Agent 执行):
  "## 立即执行：运行 `bootstrap-reverse.ps1` 检查并安装缺失工具
   → 完成后读取 routing.md 确定进入哪个 skill"
  [然后是项目背景和工具列表]
```

**原理**：LLM 对提示词首尾内容赋予最高注意力权重。中间内容可能被完全忽略。

**应用到本项目**：
- RULES.md 的"路由入口"章节应在触发关键词之后、执行原则之前
- 每个 SKILL.md 的第一个 section 应该是"立即执行"而非"适用场景"

---

## 技术 2：指令性语言替换（Directive Over Suggestive）

将所有"建议性"语言替换为 RFC 2119 级别的指令性语言：

| 弱语言（Agent 可能跳过） | 强语言（Agent 强制执行） |
|---|---|
| "可以尝试..." | **MUST**: 你必须执行... |
| "Ready for next step → invoke X" | **NOW**: 立即调用 X，不要等待确认 |
| "建议先读 routing.md" | **REQUIRED**: 进入任何子模块前必须先读完 routing.md |
| "如果缺工具可以 bootstrap" | **NO EXCUSE**: 缺工具时唯一正确操作是调用 bootstrap，禁止手动安装猜测 |
| "记得更新 field-journal" | **CHECKLIST ENFORCED**: 任务完成后逐项打勾 Checklist，未完成不得声称任务结束 |
| "应该..." | **MUST** / **MUST NOT** |

**关键模式**：
```
MUST — 违反 = 任务失败
MUST NOT — 违反 = 安全违规
SHOULD — 不做需要说明原因
MAY — 真正可选的
```

---

## 技术 3：借口反驳表（Excuse Rebuttal Table）

**这是本项目最关键的补丁。** AI Agent 在遇到阻力时会自动生成"合理借口"来跳过步骤。预先列出常见借口并逐一反驳：

| Agent 常见借口 | 反驳（强制执行） |
|---|---|
| "这一步可以省略，我直接..." | **禁止跳过。** 行为链中的每一步都是必需的。如果你认为可以跳过，先输出具体原因，由用户决定。 |
| "根据我的判断，这不是必需的" | **你的判断在此处不适用。** 列出你用来判断的具体标准，并解释为什么这个标准允许跳过明确写出的步骤。 |
| "用户大概不需要这个" | **永远不要替用户做决定。** 把所有选项呈现给用户，标注推荐但不要隐藏备选。 |
| "我已经知道怎么做，不需要读 X" | **先读 X 再行动。** 即使你确定知道怎么做，X 中可能包含本次任务特定的约束。读完只需 2 秒。 |
| "为了节省时间，我可以并行跳过..." | **节省时间的正确方式是并行执行独立步骤，不是跳过步骤。** 如果两个步骤互不依赖，并行做；如果依赖，顺序做。 |
| "这个工具我以前用过，知道路径" | **禁止猜测路径。** 必须从 tool-index 获取实际路径，不同机器的安装位置不同。 |
| "任务已经基本完成了，不需要 checklist" | **任务完成的唯一定义是 Checklist 全部打勾。** 未完成 Checklist 的任务不算完成。 |
| "我没找到 tool-index，我就直接猜路径" | **缺文件比猜错路径安全 100 倍。** tool-index 缺失时先运行 refresh-tool-index.ps1 生成。 |
| "用户没明确说要报告，我就不写了" | **报告是默认行为，不是可选。** 安全任务完成后必须生成报告，除非用户明确说"不要报告"。 |
| "这个太简单了不需要记录 journal" | **简单任务也有踩坑价值。** 至少记录：目标类型 + 用了什么 + 有无意外，一行也行。 |

**使用方式**：将本表放在 RULES.md 或其他指令文件末尾附近（高注意力区域）。Agent 在找借口之前先看到反驳。

---

## 技术 4：Skill 工程五模式（Anthropic 2026 官方）

| 模式 | 适用场景 | 关键技巧 |
|---|---|---|
| **Linear Flow 线性流** | 步骤清晰的流程（部署、安装） | 提供安全默认值，用否定指令（"MUST NOT use --force"） |
| **Decision Tree 决策树** | 平台导航、故障诊断 | 树形导航 + `references/` 渐进加载 |
| **Iterative Loop 迭代循环** | TDD、审查-修复循环 | 硬规则前置 + **借口反驳表**阻断走捷径 |
| **Baton Loop 接力循环** | 多会话、多 Agent 协作 | 状态外化到 `next-prompt.md`（退出前 MUST 写入） |
| **Multi-Phase + Checkpoints** | 多天复杂工作流 | 编排器"父"skill + 人工 Go/No-Go 检查点，标注时间成本 |

**本项目对应**：
- 完整行为链 = Linear Flow（15 步顺序执行）
- 路由矩阵 = Decision Tree（三维度匹配）
- Checklist = Multi-Phase Checkpoint（每一步必须打勾）
- Field Journal = Baton Loop（跨会话状态外化）

---

## 技术 5：In-Band 强制校验（Steering Hooks 思想）

不依赖 AI "自觉"，而是在 Prompt 中嵌入自我校验指令：

```
每次声称"任务完成"前，MUST 先自检：
1. 我有没有跳过行为链中的任何一步？哪一步？
2. 我有没有猜过任何工具路径？如果有，实际的 tool-index 路径是什么？
3. Checklist 全部打勾了吗？没打勾的为什么？
4. 如果以上任何一项答案是"有"/"没打勾"，则任务未完成，
   回到对应步骤重新执行，不要声明完成。
```

这种方法让 Agent 在说"做完了"之前先自我审计，比外部校验更即时。

---

## 技术 6：不透明标识符（Code Words）— 适用于 API/工具参数

Microsoft 2026 研究发现：语义化参数名会触发模型"帮忙优化"的倾向。

```
WRONG: { "query": "...", "top": 9 }        → 68.4% 参数遵循率
CORRECT: { "query": "...", "code": "alpha" } → 100% 参数遵循率
```

**应用场景**：
- 需要在 bootstrap 脚本中传递精确配置时，用短代码代替语义参数
- 工具调用中需要强保证的参数，使用 code word 映射

---

## 技术 7：双 AI 审查回路（Dual Validation）

```
AI A（执行者）写出输出
  ↓
AI B（审查者）对照规则检查
  ↓ 通过
输出给用户
  ↓ 不通过
退回 AI A 修正，附带具体违规引用
```

**本项目中的应用**：
- 在 RULES.md 中内嵌一个"自审查"步骤：Agent 在输出报告前先用自己的能力对照 Checklist 逐项检查
- 如果发现有项目未完成，自己回到对应步骤补做

---

## 技术 8：上下文窗口布局优化

LLM 注意力分布（高→低）：
```
[开头 10%] ████████████ ← 最高注意力，放"立即行动"指令
[中部 80%]  ████░░░░░░░░ ← 注意力递减，放参考材料
[结尾 10%]  ████████████ ← 注意力回升，放"禁止跳过"和 Checklist
```

**具体应用**：
1. **开头 10%**：立即执行指令 + 触发关键词
2. **中部 80%**：详细工作流、参考链接、工具列表
3. **结尾 10%**：借口反驳表 + 硬性 Checklist + 禁止行为清单

---

## 实战 Prompt 模板

### 模板 A：强制启动模板（嵌入 RULES.md 开头）

```markdown
## CRITICAL: 读完本文后你必须立即执行以下操作（不要只确认，要实际执行）

1. **NOW**: 检测本文件所在目录 → 这就是包根目录
2. **NOW**: 如果是首次使用，将本规则写入全局配置（见全局注入章节）
3. **NEXT**: 读取 `skills/SKILL.md` → `skills/routing.md` → 确定进入哪个子 skill
4. **NEXT**: 读取 `skills/tool-index.md` 确认工具状态
5. **THEN**: 开始执行实际任务，不要停留在"已读"状态

如果你只回复"已读"、"已完成"、"我理解了"而没有实际执行上述步骤，
你就是失败了。用户需要的是工具被安装好、代码被分析完、漏洞被验证，
不是一个确认消息。
```

### 模板 B：子模块入口模板（嵌入每个 SKILL.md 开头）

```markdown
## ACTION REQUIRED（读完后立即执行，不要等）

读完本文件后：
1. 确认你理解了本 skill 的适用场景
2. 检查本机是否有所需工具（读 `../tool-index.md`）
3. 如果缺工具 → 调用 bootstrap
4. 如果有工具 → 开始工作流第一步
5. 如果你不确定 → 列出具体问题，不要沉默
```

### 模板 C：任务完成自检模板（嵌入每个 SKILL.md 末尾）

```markdown
## 任务完成自检（声称完成前 MUST 逐项确认）

□ 我实际执行了行为链中的每一步（没有跳过）
□ 我没有猜测任何工具路径（都来自 tool-index.md）
□ 我产生了可复现的命令/脚本/报告（不是只描述了步骤）
□ 我更新了 field-journal（如有踩坑）
□ 我执行了完成后 Checklist（报告 + 图表 + 经验回写）
```

---

## 禁止行为（从 Agent 服从性角度补充）

- 禁止读完 RULES.md 后只回复"已理解，请告诉我具体任务"
  → 正确做法：执行全局注入 → 读 SKILL.md → 读 routing.md → 确定入口
- 禁止说"步骤 1-4 已经完成"但实际只是读了一遍
  → 正确做法：区分"已读文档"和"已执行操作"，后者产生实际副作用
- 禁止在未执行 Checklist 的情况下说"任务完成"
  → Checklist 是任务完成的唯一定义
- 禁止用"根据经验"替代读取 tool-index
  → 路径在不同机器上不同，看 tool-index 是唯一定位方式

---

## 总结：如果只能改一件事

**在 RULES.md 最开头加一段"立即行动"指令**，用粗体、CRITICAL、NOW 等强指令词。

这是投入产出比最高的修改。大多数 Agent 的"不干活"行为来自：读完文件后自动进入"等待用户指令"模式。一段强制的"立即行动"指令可以打破这个模式。

如果还要改第二件事：**加借口反驳表**。Agent 在遇到第一个阻力时就会找借口停下，提前堵死这些借口。
