优化CLAUDE.md强制Agent先检索Skill再执行

背景

随着 AI 编程助手（如 Claude Code、Codex、Kimi 等）在开发工作流中的深度集成，提示词工程（Prompt Engineering）的复杂度日益增加。作者分享了一份正在迭代的 CLAUDE.md 配置文件，旨在解决当前 AI Agent 在调用 Skills（技能/上下文模块）时存在的“匹配不稳定”问题。

在早期实践中，CLAUDE.md 往往变得臃肿，导致模型注意力分散。作者通过将内容拆分至 skills 目录并建立软链接同步至不同 Agent 的方式优化了结构。然而，核心痛点在于：尽管人类能理解 Skill 的语义，但 Agent 有时无法正确匹配，反而选择“单干”或忽略既定流程。为此，新版配置引入了强制性的扫描与输出约束，以确保 Agent 在执行前必须显式声明是否匹配到相关 Skill，从而提升工作流的确定性和可控性。

核心内容

该 CLAUDE.md 文件定义了一套全局 Agent 规则，涵盖了语言、技能调用、优先级、协作模式、执行边界及安全规范等多个维度。以下是具体规则解析：

1. 语言与基础交互

• 默认语言：默认使用简体中文回复，仅在用户明确要求时切换其他语言。
• 格式限制：回答中禁止使用图标（icon），保持文本纯净。

2. 技能调用机制（Skill Blocking）

这是本次优化的核心部分，旨在解决 Agent 忽略 Skills 的问题：

• 强制扫描：在调用任何工具前，Agent 必须先读取可用 Skills 并进行语义匹配。
• 执行流程：若匹配到 Skill，必须先阅读对应的 SKILL.md 文件，然后再执行操作。
• 显式输出约束：每次回复的第一行必须严格遵循以下格式之一，禁止任何前缀、列表符号、缩进或引用符号包裹：
  • > Skill 匹配: <单一技能名>
  • > 无匹配 Skill
• 禁止多技能：禁止在同一行声明多个技能，确保每次交互只聚焦于一个明确的技能上下文。

3. 优先级与偏差管理

• 优先级顺序：用户显式指令 > 本文件规则 > 系统默认规则。
• 偏差声明：当用户指令覆盖本文件规则时，回复开头必须增加偏差声明，格式如下：
  • 偏差声明: [被覆盖规则] — [原因]
  • 覆盖范围: [本次任务/本次会话] 这有助于追踪规则被覆盖的具体场景和原因。

4. 协作与沟通原则

• 结论先行：先给出结论，再提供必要的上下文。
• 假设声明：在低风险且合理的假设下，先声明假设并继续执行，避免不必要的停顿。
• 最小化提问：仅在缺失信息会明显改变结果或带来风险时才向用户提问。
• 克制扩展：不扩展未请求的功能，不做无关的优化建议，严格聚焦于用户核心请求。

5. 执行边界与安全

• 进度说明：在多步骤编码任务中，首次工具调用前需发送 1-2 句进度说明（明确要做什么及第一步是什么）。
• 最小改动原则：默认“先读后写”，仅做最小必要改动。
• 错误处理：禁止使用静默 fallback、假成功路径或吞错式的大范围 try/catch。修复 Bug 应以根因为目标，优先删除冗余逻辑，避免叠加旁路修复。
• 安全基线：
  • 不硬编码密钥或凭据，必须使用环境变量或密钥管理服务。
  • 外部输入必须进行边界校验与清洗。
  • 涉及数据库操作时，必须使用参数化查询。

6. 环境与工具特定规则

• Windows Shell 规则：
  • 环境限定为 Windows 11 + PowerShell。
  • 禁止使用 Unix 文本工具（如 sed、awk、cut、head、tail）。
  • 强制使用 PowerShell 等价命令：
    • 前 N 行：Select-Object -First N
    • 后 N 行：Get-Content -Tail N
    • 文本替换：使用 -replace 配合 Get-Content/Set-Content。
• Git 只读限制：
  • 允许：git log、git status、git diff、git branch、git show（仅用于读取信息）。
  • 禁止：git commit、git push、git pull、git merge、git rebase、git reset（防止意外修改版本历史）。

7. 验证与停止规则

• 验证流程：改动后按顺序验证（如适用）： 3. 构建检查 4. 最小冒烟测试
  • 若无法验证，需明确写出原因与替代检查方案。
• 停止规则：每完成一个关键步骤，判断是否已能回答用户核心请求。若能回答，立即停止，不做非必要延伸。

8. 多 Agent 协同工作流

作者目前同时使用 Claude Code、Codex 和 Kimi，分工明确：

• Kimi：处理不太重要的任务，或作为第三方检测角色。
• Claude Code：使用 V4 Pro 作为模型底座。
  • 版本 A：用于思考方案、处理重要文本工作。
  • 版本 B：用于实现方案。
• Skills 管理：建立 .agent 文件夹存放 Skills，并通过软链接同步到不同的 Agent 环境中，确保上下文一致性。

关键要点

• 强制显式声明：通过要求 Agent 在回复第一行严格输出 > Skill 匹配: ... 或 > 无匹配 Skill，解决了 Agent “假装匹配”或“忽略 Skills”的黑盒问题，提升了可观测性。
• 单一技能聚焦：禁止同一行声明多个技能，强制 Agent 在每次交互中聚焦于一个明确的上下文模块，减少逻辑冲突。
• 安全与只读优先：Git 操作严格限制为只读，禁止直接提交或推送，防止 AI 误操作破坏版本控制；代码修改强调“最小必要改动”和“根因修复”，避免技术债务累积。
• 环境适配性：针对 Windows 用户，明确禁止 Unix 工具链，强制使用 PowerShell 原生命令，确保跨平台兼容性。
• 偏差透明化：当用户指令覆盖预设规则时，要求显式声明“偏差声明”，使规则覆盖过程透明化，便于调试和审计。
• 多模型分工协作：利用不同模型（Claude, Codex, Kimi）的特性进行分工（思考、实现、检测），并通过 .agent 文件夹和软链接实现 Skills 的统一管理，体现了高级 AI 工作流的设计思路。

意义与影响

这份 CLAUDE.md 的实践对 AI 辅助编程工作流具有重要的参考价值：

1. 提升 Agent 行为的确定性：通过强制性的扫描和输出约束，将原本隐式的 Skill 匹配过程显性化，显著降低了 Agent “幻觉”或“自作主张”的风险，使 AI 行为更可控、可预测。
2. 标准化提示词工程：提供了一套结构化的全局规则模板，涵盖了从语言、安全、工具调用到错误处理的方方面面，为开发者构建稳定的 AI 助手提供了最佳实践参考。
3. 促进多 Agent 协同：展示了如何通过统一的管理机制（如 .agent 文件夹和软链接）在不同 AI 模型间共享上下文和技能，为构建复杂的多 Agent 协作系统提供了可行的技术方案。
4. 强化安全与合规意识：将安全基线（如密钥管理、参数化查询）和只读操作限制嵌入到核心规则中，有助于在自动化开发