智能体指令与 MCP

是什么，为什么存在

智能体一开始并不知道仓库维护者默认掌握的隐性知识。它可以从附近文件推断模式，但无法可靠找出权威测试命令、生成目录、所有权边界，或尚未由架构测试强制执行的规则。版本化的指令文件能在智能体提出修改前展示这些要求。

AGENTS.md 与 CLAUDE.md 是特定编程智能体宿主读取的 Markdown 指引文件。它们不是语言标准，发现规则也不能互换。二者共同的实用思想，是把稳定且针对仓库的事实放在受其约束的代码附近。

指令回答修改应放在哪里、由什么命令验证，以及哪些内容不能编辑。它们通过 上下文窗口（context window） 影响模型行为，但不会授予或撤销操作系统权限。因此，「绝不读取 .env」属于指引，而不是安全控制。

模型上下文协议（Model Context Protocol，MCP） 通过结构化消息，把 AI 应用连接到提供工具、资源和提示词的服务器。对于工具，服务器会发布名称、描述和输入模式；客户端可以列出这些工具并发送 工具调用（tool call） 。MCP 标准化了这项交换，而信任、授权与副作用仍由应用和服务器负责。

这两种机制分别解决同一类故障的两半。没有明确指令时，智能体可能遵循局部看似合理、实际却错误的约定；没有严格工具契约时，同一个智能体又可能用宽泛的 shell 或数据库凭据，完成原本只需一次受限读取的任务。

指引、契约与强制控制

设计智能体集成时，应把三个层次分开：

风险需要时，成熟的仓库会同时采用这三个层次。指引要求智能体修改 src/payments/ 并运行指定测试；工具只接受该目录下的规范化路径；交付门再检查差异和测试退出码。与其在每层重复同一句规则，不如给每层安排它真正能够执行的检查。

编程 CLI 或 IDE 打开仓库时会遇到指令文件；宿主连接本地或远程能力时会遇到 MCP。MCP 不只适用于编程工具，但仓库工作能清楚展现边界：源码读取、Issue 查询、模式检查、测试和部署各有不同的数据与权限要求。

工作原理

智能体宿主先发现与当前位置或文件有关的指令来源，再把文本连同用户任务和选定的仓库证据放进模型上下文。宽泛指引与局部指引可能重叠，因此顺序会影响结果。

Codex 会从全局指引和项目文件构造指令链，并从仓库根目录向当前工作目录逐层读取。在每个项目目录中，它至多选择一个已识别的指令文件，且 AGENTS.override.md 优先于 AGENTS.md。越靠近工作目录的指引在链中出现得越晚。

Claude Code 读取 CLAUDE.md，并支持项目、用户、本地与托管范围。它在处理子目录时可以加载其中更具体的文件。Claude Code 不把 AGENTS.md 当作原生项目文件，但 CLAUDE.md 可以导入 AGENTS.md，让团队集中维护共享规则，再单独添加产品专用内容。

不要为所有宿主臆造一套通用合并算法。仓库应记录支持哪些产品，在文件名不同时保留简短适配文件，并要求运行中的智能体报告实际加载的指令来源。如果当前宿主从未发现仓库根目录的指引，那么该文件内容再正确也不会生效。

从指令走向证据

仓库规则应写成开发者或程序都能判断是否遵守的形式。每条重要规则都应标明范围、操作或约束，以及可观察的证据。

1. 写明规则管理的目录、文件模式、软件包或操作。
2. 用确切路径、命令或接口名称说明所需行为。
3. 如果某项意外约束的原因在代码中不可见，应简短解释原因。
4. 写明用什么检查证明合规，以及从哪个工作目录执行。
5. 只有边界真实且稳定时，才说明哪些内容不能修改。
6. 临时任务细节应放进当前请求，不要不断堆积在仓库指引中。

「保持代码整洁」没有可审查的含义。「修改 src/payments/ 时，从仓库根目录运行 pnpm test:payments；不要编辑 src/generated/」则给出了范围、命令、位置和排除项，之后的交付门可以逐项检查。

指引应指向权威文档，不要复制冗长的架构说明。又长又重复的指令会占用上下文，还会各自过期。只适用于一个子树的规则，应放进宿主支持的范围化机制，不必让每项任务都携带它。

从声明走向工具结果

MCP 工具声明是展示给客户端和模型的 API 契约（API contract） 。名称与描述帮助模型选择工具，inputSchema 描述可接受参数，可选的 outputSchema 描述结构化结果。工具通过 tools/list 发现，通过 tools/call 调用。

模式验证是第一道检查，而不是最后一道。语法有效的路径仍可能通过 .. 或符号链接逃逸；有效的项目标识符可能属于另一个租户；有效查询可能要求返回超出任务所需的行数。执行器必须规范化参数，并在每次调用时执行资源级授权。

结果应区分协议故障和工具报告的执行错误，还应保留足够结构，让宿主识别状态、资源、大小、截断情况以及能否安全重试。自由文本形式的成功说明可以补充这些事实，但不能取代它们。

来自不受控制服务器的工具描述同样是不可信输入。它们会影响模型选择，也可能包含 提示词注入（prompt injection） 。客户端应只接入可信服务器，向用户展示敏感调用，而且绝不能把描述性注解解释为权限。

能力与审批边界

工具应围绕领域操作设计，而不是暴露无限制的传输方式。read_source({ path })、run_payment_tests({ target }) 和 create_preview({ revision }) 的意外权限小于 shell({ command }) 或 http_request({ url, body })。受限工具产生的日志也更容易审查，无需重新推导命令字符串的含义。

最小权限原则（least privilege） 要应用两次：先只向该智能体提供必要工具，再限制每项工具能为当前调用方访问哪些资源。只读源码浏览器不应仅仅因为和部署能力运行在同一服务器进程中，就继承部署凭据。

审批门（approval gate） 适合目标或影响需要人工判断的操作。审批界面应显示工具、规范化参数、目标和预期副作用。批准一次预览部署，不应变成之后每次部署调用的长期权限。

指令可以要求智能体先征求批准，但强制控制属于宿主或服务器。即使模型忘记规则、遭注入的文档与规则冲突，或另一个客户端连接到同一 MCP 服务器，策略仍必须拒绝或暂停调用。

示例

下面的 Node 示例把控制逻辑与具体模型 SDK 分离。它们依次模拟 Codex 风格的指令发现、把仓库指引转化为交付检查，并实现受限 MCP 风格工具的核心。所有输出都来自 Node v24.14.0。

为目标文件解析指令

第一个程序表示一个含有根目录 AGENTS.md 和支付模块专用 AGENTS.override.md 的仓库。解析器从根目录向目标所在目录逐层遍历，并在每层优先选择覆盖文件。

支付模块目标同时收到仓库级要求和更近的覆盖指令。搜索模块目标所在目录路径中没有其他已识别文件，因此只收到根目录指引。这个程序演示的是 Codex 发现规则，不能代替 Claude Code 不同的加载行为。

真实发现过程还会从检测到的项目根目录和当前工作目录开始，而不是接受任意目标字符串。应使用开发者与自动化真正采用的启动位置进行测试。内容正确但放错目录的文件，仍然是不生效的指引。

把指引变成交付检查

自然语言指令帮助模型选择工作方式，但机器能够判断的部分应交给确定性交付门验证。下面的契约限制修改路径，并记录必须成功退出的两条命令。

const contract = {
  allowedRoots: ["src/payments/", "tests/payments/"],
  forbiddenSuffixes: [".snap"],
  requiredChecks: ["pnpm test:payments", "pnpm lint"],
};

function verifyChange(change) {
  const failures = [];
  for (const file of change.files) {
    if (!contract.allowedRoots.some((root) => file.startsWith(root))) {
      failures.push(`path outside scope: ${file}`);
    }
    if (contract.forbiddenSuffixes.some((suffix) => file.endsWith(suffix))) {
      failures.push(`generated file changed: ${file}`);
    }
  }
  for (const command of contract.requiredChecks) {
    const result = change.checks.find((check) => check.command === command);
    if (result === undefined || result.exitCode !== 0) {
      failures.push(`check not passed: ${command}`);
    }
  }
  return failures.length === 0 ? ["PASS"] : failures;
}

const changes = [
  {
    files: ["src/payments/refund.ts", "tests/payments/refund.test.ts"],
    checks: contract.requiredChecks.map((command) => ({ command, exitCode: 0 })),
  },
  {
    files: ["src/payments/refund.ts", "src/generated/schema.snap"],
    checks: [{ command: "pnpm test:payments", exitCode: 0 }],
  },
];

for (const [index, change] of changes.entries()) {
  console.log(`change ${index + 1}: ${verifyChange(change).join(" | ")}`);
}

change 1: PASS
change 2: path outside scope: src/generated/schema.snap | generated file changed: src/generated/schema.snap | check not passed: pnpm lint

第二项修改违反了三个可独立审查的条件。交付门不会询问智能体是否记得指令，而是根据修改路径、确切命令标识和退出码得出结论。生产系统应从版本控制层和进程层获取这些证据，不能接受模型自行提供的对象。

只有在这个小例子假设的、已规范化的仓库相对路径中，字符串前缀才足够。任何接收操作系统路径的交付门都必须解析分隔符和符号链接，再证明路径确实位于范围内。指引与强制控制代码应使用相同范围，但不能共享不安全的捷径。

提供一个受限源码工具

最后一个程序声明了带有输入、输出模式的工具，并实现参数验证和结果结构。它刻意不提供通用文件读取或 shell 参数。内存仓库让两次调用都可以复现。

import { posix } from "node:path";
const repository = new Map([
  ["src/config.ts", "export const port = 8080;\n"],
]);
const readSourceTool = {
  name: "read_source",
  description: "Read one UTF-8 TypeScript source file under src/.",
  inputSchema: {
    type: "object",
    properties: { path: { type: "string" } },
    required: ["path"],
    additionalProperties: false,
  },
  outputSchema: {
    type: "object",
    properties: { path: { type: "string" }, bytes: { type: "integer" } },
    required: ["path", "bytes"],
  },
};
function readSource(arguments_) {
  const raw = arguments_?.path;
  if (typeof raw !== "string" || Object.keys(arguments_).length !== 1) {
    return { isError: true, message: "invalid arguments" };
  }
  const path = posix.normalize(raw);
  if (posix.isAbsolute(path) || !path.startsWith("src/") || !path.endsWith(".ts")) {
    return { isError: true, message: "path outside source scope" };
  }
  const text = repository.get(path);
  if (text === undefined) return { isError: true, message: "source not found" };
  return {
    isError: false,
    content: [{ type: "text", text }],
    structuredContent: { path, bytes: Buffer.byteLength(text) },
  };
}
console.log(`${readSourceTool.name}: ${readSourceTool.description}`);
for (const request of [{ path: "src/config.ts" }, { path: "src/../secrets/token.txt" }]) {
  console.log(JSON.stringify(readSource(request)));
}

read_source: Read one UTF-8 TypeScript source file under src/.
{"isError":false,"content":[{"type":"text","text":"export const port = 8080;\n"}],"structuredContent":{"path":"src/config.ts","bytes":26}}
{"isError":true,"message":"path outside source scope"}

规范化会把第二个参数转换成 secrets/token.txt，因而无法通过 src/ 边界。声明帮助模型选择工具，处理器则在读取前再次检查。真实 MCP 服务器还要通过 SDK 与传输层连接这个处理器，为经过认证的调用方授权，并安全解析实际路径。

成功结果同时提供模型可读文本和结构化元数据。输出模式让元数据可以检查，但不会让文本自动变得可信。客户端仍应把文件内容当作不可信仓库数据，并限制送入模型上下文的字节数。

陷阱

指引含糊或彼此冲突

修复方法： 写准确切范围、命令、路径与验收证据。定期从代表性目录启动每种受支持的智能体，列出加载来源，再删除过期或重复规则。意外约束旁应附上简短原因，让未来维护者知道它何时可以改变。

假设一个文件名具有通用语义

修复方法： 记录支持的宿主，并验证每种产品当前的发现行为。集中维护共享指引，再按需使用简短 CLAUDE.md 导入或其他有文档依据的适配方式。执行高风险工作前，让会话列出活跃指令来源。

把指令当作权限边界

修复方法： 移除不必要的凭据和网络路径，对每项操作强制授权，并为敏感目标设置审批门。即使禁止调用的结构有效，模型也给出了自信的解释，测试仍应证明该调用会失败。

发布万能 MCP 工具

修复方法： 发布面向任务的工具，使用带类型字段、有限结果与明确副作用。拆分读取、修改和部署能力，只提供当前会话需要的子集。无法移除自由文本 shell 时，应把它放在更严格的策略之后。

止步于 JSON Schema 验证

修复方法： 每次调用都要规范化资源并授权，设置大小与时间限制，净化输出，并为可重试修改记录幂等条件或资源版本条件。语义边界情况要与格式错误的 JSON 分开测试。

把机密作为工具上下文返回

修复方法： 在服务器边界选择并脱敏输出字段，限制结果大小；原始数据无需进入上下文时，应返回产物引用。日志可以记录元数据和拒绝原因，但不能回显含机密的参数值。最小化工具输出也是契约的一部分。

延伸阅读

• OpenAI 文档：使用 AGENTS.md 定制指令
• Claude Code 文档：CLAUDE.md 与项目记忆
• 模型上下文协议：架构概览
• 模型上下文协议规范：工具
• 模型上下文协议：安全最佳实践