name: ctx-alignment-audit description: “审计文档与智能体指令的一致性。当配方或文档声称智能体具有某些行为，而这些行为可能没有在操作手册或技能中得到支持时使用。” allowed-tools: Bash(ctx:*), Read, Grep, Glob
审计文档中的行为声明是否得到操作手册和技能中实际智能体指令的支持。识别文档承诺的内容与智能体被教导执行的内容之间的差距。
何时使用
- 编写或更新配方文档后
- 修改智能体操作手册或技能后
- 当配方声称智能体具有主动行为时
- 定期检查，以捕获文档与指令之间的漂移
- 当用户询问“这是真实的还是空想？”时
何时不使用
- 用于代码级漂移（改用
/ctx-drift） - 用于上下文文件陈旧性检查（改用
/ctx-status） - 当审查文档的文本质量时（非行为声明）
审计内容
行为声明是文档中描述智能体将做什么、可能做什么或提供做什么的陈述。它们出现在：
- 配方中的**“智能体说明”块引用**
- **“对话方法”**部分
- **“提示”**部分中描述主动行为的内容
- 任何使用以下措辞的段落：“智能体将”、“智能体提供”、“主动地”、“无需被要求”、“自动地”
流程
步骤1：收集声明
阅读目标文档文件。提取每个行为声明——描述用户应期望的智能体行为的每个陈述。记录：
- 文件和行号
- 确切的声明
- 它描述的行为
步骤2：追踪每个声明
对于每个声明，在以下位置搜索匹配的指令：
.context/AGENT_PLAYBOOK.md— 主要行为来源；智能体在会话开始时读取此文件.claude/skills/*/SKILL.md— 调用技能时加载的特定技能指令CLAUDE.md— 始终在上下文中的项目级指令
对于每个声明，确定：
- 已覆盖：存在匹配的指令，将产生所描述的行为
- 部分覆盖：存在相关指令但未完全覆盖声明（例如，操作手册说“在里程碑处持久化”，但配方声称智能体识别特定的后续任务）
- 差距：不存在会产生该行为的指令
步骤3：报告
以表格形式呈现发现：
| 声明（文件:行号） | 状态 | 支持指令 | 差距描述 |
|---|---|---|---|
| “智能体创建后续任务” (task-mgmt:57) | 差距 | 无 | 操作手册未教导后续任务识别 |
| “智能体提供保存学习成果” (knowledge:237) | 已覆盖 | 操作手册：工作期间的主动行为 | — |
步骤4：修复（如请求）
对于每个差距，提出修复建议：
- 操作手册补充：如果该行为应广泛适用于所有会话（添加到 AGENT_PLAYBOOK.md）
- 技能补充：如果该行为特定于一个技能（添加到相关的 SKILL.md）
- 文档更正：如果声明过度承诺，应予以缓和
始终更新实时副本（.context/AGENT_PLAYBOOK.md 或 .claude/skills/）和模板副本（internal/assets/AGENT_PLAYBOOK.md 或 internal/assets/claude/skills/）以保持同步。
什么使声明“已覆盖”
当智能体指令将可靠地产生所描述的行为时，声明即被覆盖。检查：
- 指令是否足够具体？“在里程碑处持久化”是模糊的。“完成任务后，提供添加后续任务”是具体的。
- 触发条件是否清晰？指令必须说明何时行动，而不仅仅是做什么。
- 机制是否清晰？如果智能体需要运行命令或检查文件，是否已说明？
- 指令是否包含示例措辞？智能体遵循示例比遵循抽象规则更可靠。
常见差距模式
- “智能体主动执行X” 但操作手册仅说明在被要求时执行X → 添加主动触发条件
- “自然语言触发Y” 但不存在对话触发映射 → 添加到触发表
- “智能体链接A然后B然后C” 但每个步骤都是独立教授的 → 添加链式流程指令
- 配方显示示例对话 但基础技能未教授该流程 → 更新技能
- “智能体在工作期间注意到X” 但未描述检测机制 → 添加如何检测，而不仅仅是注意到什么
指令文件健康度
审计一致性后，检查指令文件的大小是否仍适合智能体使用。臃肿的指令文件会被忽略——智能体停止遵循深埋在长文档中的规则。
大小启发式
| 文件 | 健康 | 警告 | 危险 |
|---|---|---|---|
| AGENT_PLAYBOOK.md | < 5k tokens | 5-8k tokens | > 8k tokens |
| 单个 SKILL.md | < 2k tokens | 2-3k tokens | > 3k tokens |
| CLAUDE.md | < 2k tokens | 2-3k tokens | > 3k tokens |
总计 .context/ |
< 25k tokens | 25-40k tokens | > 40k tokens |
如何测量
# 总上下文令牌估计
ctx status | grep "Token Estimate"
# 粗略的每文件估计（约每令牌4个字符）
wc -c .context/AGENT_PLAYBOOK.md # 除以4
wc -c .claude/skills/*/SKILL.md # 除以4
当文件过大时
- 操作手册过大：将项目特定部分（飞行前检查清单、Go文档标准）提取到它们所属的 CONVENTIONS.md 中。操作手册应教授行为，而非编码标准。
- 技能过大：拆分为一个重点技能和一个参考文档。技能教授何时和如何；参考文档提供智能体在需要时可以查找的详细信息。
- 总上下文过大：运行
ctx compact以归档已完成的任务并去重学习成果。
指令臃肿的迹象
- 智能体忽略文件下半部分的规则
- 相同的指令出现在多个位置（操作手册和技能和 CLAUDE.md）
- 指令部分包含可以缩短的长示例
- 文件包含智能体已具备的一般知识
质量检查清单
完成审计后：
- [ ] 目标文件中的每个行为声明都已追踪
- [ ] 每个声明都有清晰的状态（已覆盖 / 部分覆盖 / 差距）
- [ ] 差距有具体位置的修复建议
- [ ] 修复已应用于实时和模板副本
- [ ] 没有引入没有支持指令的新声明