AI 编程上下文文件：架构、安全、评测与工程治理指南

核心摘要

AGENTS.md、CLAUDE.md、Copilot Instructions 与 Cursor Rules 等 AI 编程上下文文件，是宿主 Context Resolver 的版本化输入，不是统一运行标准、权限系统或代码质量保证。团队应像治理软件一样治理它们：定义消费者与作用域，维护单一事实源，实测实际解析结果，保护文件变更，评测任务结果，并在独立可信控制面中执行安全策略。

目录

• 什么是 AI 编程上下文产物
• 区分不同产物类型
• 显式建模宿主解析行为
• 用精简 Adapter 维护单一事实源
• 只保留值得占用上下文的信息
• 建立机器可检查的 Registry
• 把安全控制留在自然语言之外
• 把上下文文件作为干预项评测
• 安全发布与持续维护
• 常见问题
• 总结

核心要点

• 加载 Context 的是宿主，不是底层模型：文件发现、作用域、优先级和支持的客户端随产品与版本变化。
• Context 不等于 Authority：Rule 可以请求安全行为，但不能授予或拒绝文件、网络、仓库、Secret 或部署权限。
• 复制多份规则会产生漂移：共享指引只保留一份 Owner 管理的事实源，宿主 Adapter 应保持精简。
• 指令更多不代表表现更好：只保留稳定、不可直接推断的信息，并通过任务结果测量收益。
• 上下文文件本身也需保护：恶意或误操作修改可能持续影响后续 Agent Session。

什么是 AI 编程上下文产物

AI 编程上下文产物是宿主工具用来组装模型上下文、配置工作流或暴露复用能力的版本化文件或 Bundle。它的行为由消费者决定，不能只根据文件名推断。

AGENTS.md 官方站点将 AGENTS.md 描述为写给 Agent 的纯 Markdown README。这为团队提供了可预测的约定，但不代表所有宿主使用同一套 Resolver。一个仓库还可能同时包含 CLAUDE.md、.github/copilot-instructions.md、.github/instructions/*.instructions.md、.cursor/rules/*.mdc、Skill、Subagent Profile、Settings、Hook 和 MCP 配置。

这些产物位于更大的 Coding Agent Harness 中：

Model Context 影响提议，可信控制面决定哪些操作真正可以发生。

本文关注跨宿主架构与治理层。单个文件如何设计可阅读 AGENTS.md 版本化上下文契约；宿主格式选择可参考 AI 编程 Rule File 对比。

区分不同产物类型

不同 Context Artifact 解决不同问题，不应全部塞入一个巨大 Instruction File。

2026 年的探索研究 Harness Engineering for Agentic AI Coding Tools识别了多类仓库级配置机制，包括 Context File、Skill、Subagent、Command、Rule、Settings、Hook 与 MCP Server。它证明这些机制已经被采用，但观察性数据不能证明某种机制会提高任务正确率。

大多数任务都需要的事实放在 Always-on Context；路径特定行为放在 Scoped Rule；多步骤流程与 Reference 放进 Skill；重复任务框架放在 Prompt File；权限和高影响动作检查放在可强制执行的系统。

这种区分可以避免常见错误：Markdown 写着「禁止部署生产」，同时却给 Agent 一枚不受限制的生产 Credential。

显式建模宿主解析行为

每个受支持宿主都需要版本化兼容性记录，因为 Discovery 与 Precedence 属于 Runtime Behavior。

当前官方文档展示了明显差异：

不要把这张表复制到企业 Policy 后永久不更新。应链接 Codex AGENTS.md 指南、Claude Code Memory 文档、GitHub Copilot Custom Instructions与 Cursor Rules 文档，然后记录团队实际测试的版本和客户端。

兼容性记录应描述观察到的行为：

{
  "host": "example-coding-host",
  "hostVersion": "immutable-version",
  "clientSurface": "cli",
  "workingDirectory": "services/payments",
  "fixtureRevision": "git:8f3a1c2",
  "claims": {
    "rootDiscovery": "passed",
    "nestedScope": "passed",
    "conflictResolution": "passed",
    "truncationBoundary": "passed",
    "manualAttachment": "not-applicable"
  },
  "checkedAt": "2026-08-23T12:00:00Z"
}

时间戳应进入兼容性证据，而不是 Instruction 正文。Host、Extension、Client 或 Configuration 变化后重新运行 Fixture。

用精简 Adapter 维护单一事实源

单一事实源用于减少漂移，精简 Adapter 则把共享指引转换成宿主专属交付格式。

agent-context/
  shared/
    repository-map.md
    build-and-test.md
    change-boundaries.md
    review-evidence.md
  adapters/
    codex/AGENTS.md
    claude/CLAUDE.md
    copilot/copilot-instructions.md
    cursor/project-rules.mdc
  fixtures/
    discovery/
    precedence/
    injection/
    forbidden-actions/
  registry.json

以上目录只是 Ownership Model，实际路径必须采用目标宿主真正支持的格式。

不要盲目把完整文件做成 Symlink。Adapter 可能需要宿主专属 Import、Frontmatter、Glob、Size Limit 或 Fallback。只有生成过程确定且产物可审查时才自动生成 Adapter；否则应保持手工文件精简，并在 CI 比较共享 Claim。

每条共享 Claim 应包含：

• 稳定 Key，例如 package-manager 或 required-checks；
• Owner；
• Scope；
• 权威来源与 Revision；
• Value 或引用指令；
• Expiry 或 Revalidation Trigger；
• 接收它的 Consumer。

如果两份 Artifact 在同一 Scope 声称使用不同 Package Manager，构建应在模型自行选择之前失败。

只保留值得占用上下文的信息

只有稳定、非显而易见、与任务相关且可验证的信息，才值得持续占用 Context。

应包含

• 已验证的 Bootstrap、Test、Lint、Typecheck 与 Build 命令；
• 不得直接编辑的 Generated 或 Vendored Path；
• 无法从单个源码文件发现的架构边界；
• Canonical Interface 与 Decision Record；
• 特定 Change Class 需要执行的 Focused Check；
• Owner 与 Escalation Trigger；
• 已知环境前置条件和确定性故障恢复；
• 交付证据要求，例如更新测试和报告未执行检查。

应删除或迁移

• Secret、Token、Private Key、Credential 和客户数据；
• 模型本身已掌握的通用建议；
• Formatter 或 Linter 已能执行的完整 Style Guide；
• 会发生漂移的 API 文档副本；
• 易变 Issue 状态、Branch Name 或临时事故信息；
• 未经验证的命令；
• 「扮演高级工程师」等 Persona 指令；
• 必须由可信基础设施判断的权限主张。

宿主能够读取来源时，应使用带 Revision 的链接。无法访问正文的 Link 不是证据，而复制整份易变文档又会产生新的过时来源。对于高影响 Invariant，保留短声明和版本化 Source Reference。

有效 Task Contract 应足够具体：

## Scope
- Allowed paths: `services/orders/**`
- Escalate before schema, authorization, or deployment changes.

## Evidence
- API contract: `docs/orders-api.md@revision`
- Focused check: `npm run test:orders`
- Generated client: read only; regenerate with `npm run generate:orders`

## Delivery
- Add or update a test for changed behavior.
- Report skipped checks and unresolved assumptions.

不存在通用最佳行数。Context Cost 与 Adherence 取决于宿主、模型、任务和竞争信息。先测试精简 Baseline，再只加入能修复已测量失败、且不会制造冲突或无关上下文的内容。

建立机器可检查的 Registry

Context Registry 让 Ownership、Scope、Provenance 与 Consumer 可审计，而不需要解析每条自然语言指令。

{
  "schemaVersion": "agent-context/v1",
  "artifacts": [
    {
      "id": "shared-build-contract",
      "kind": "context",
      "source": "agent-context/shared/build-and-test.md@8f3a1c2",
      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "owner": "developer-experience",
      "scope": "**",
      "priority": 100,
      "consumers": ["codex-cli", "claude-code"],
      "expiresOn": "2026-11-23",
      "containsSecrets": false
    }
  ]
}

Registry 记录的是交付主张，不能授予 Tool Permission。

下面这段无第三方依赖的 TypeScript 会拒绝证据不完整、重复 ID、无效 Digest、过期 Review、包含 Secret 的 Context，以及同一 Consumer 与 Scope 下含糊的 Priority：

type ContextArtifact = {
  id: string;
  source: string;
  sha256: string;
  owner: string;
  scope: string;
  priority: number;
  consumers: string[];
  expiresOn: string;
  containsSecrets: boolean;
};

export function validateRegistry(
  artifacts: ContextArtifact[],
  now = new Date(),
): string[] {
  const errors: string[] = [];
  const ids = new Set<string>();
  const slots = new Map<string, string>();

  for (const artifact of artifacts) {
    if (ids.has(artifact.id)) {
      errors.push(`${artifact.id}: duplicate id`);
    }
    ids.add(artifact.id);

    if (!artifact.source.includes("@")) {
      errors.push(`${artifact.id}: source revision is missing`);
    }
    if (!/^[a-f0-9]{64}$/u.test(artifact.sha256)) {
      errors.push(`${artifact.id}: sha256 is invalid`);
    }
    if (!artifact.owner.trim() || !artifact.scope.trim()) {
      errors.push(`${artifact.id}: owner or scope is missing`);
    }
    if (artifact.containsSecrets) {
      errors.push(`${artifact.id}: context must not contain secrets`);
    }
    if (now >= new Date(`${artifact.expiresOn}T00:00:00Z`)) {
      errors.push(`${artifact.id}: review has expired`);
    }

    for (const consumer of artifact.consumers) {
      const slot = `${consumer}:${artifact.scope}:${artifact.priority}`;
      const previous = slots.get(slot);
      if (previous) {
        errors.push(`${artifact.id}: ambiguous priority with ${previous}`);
      } else {
        slots.set(slot, artifact.id);
      }
    }
  }

  return errors;
}

const artifacts: ContextArtifact[] = [
  {
    id: "shared-build-contract",
    source: "agent-context/shared/build-and-test.md@8f3a1c2",
    sha256: "a".repeat(64),
    owner: "developer-experience",
    scope: "**",
    priority: 100,
    consumers: ["codex-cli", "claude-code"],
    expiresOn: "2026-11-23",
    containsSecrets: false,
  },
];

if (validateRegistry(artifacts, new Date("2026-08-23")).length > 0) {
  throw new Error("context registry validation failed");
}

console.log("context registry checks passed");

预期输出：

context registry checks passed

代码只能证明 Registry Invariant，不能证明宿主已经加载 Artifact、正文事实正确或 Agent 会遵循它。

把安全控制留在自然语言之外

Instruction File 可以减少歧义，却不能执行 Identity、Authorization、Isolation 或 Side Effect Policy。

Claude Code 官方文档明确区分 Context 与 Enforced Configuration；OWASP Prompt Injection Prevention Cheat Sheet也把 Code Comment、Documentation、Commit Message、Issue 与 Tool Result 列为间接注入来源。

所有 Model-readable Source 都应按信任等级处理：

保护 Context Artifact 的措施包括：

• 使用 CODEOWNERS 并要求 Owner Review；
• 使用 Branch Ruleset 与 Required Status Check；
• 检查隐藏 BiDi 与 Zero-width 控制字符；
• 校验 Digest 与 Source Revision；
• 禁止 Agent 未经明确 Review 自行修改长期规则；
• 最小化 Log，并执行 Secret Scan；
• 可以回滚到 Known-good Artifact Set。

GitHub CODEOWNERS 文档说明，只有仓库保护规则要求 Code Owner Approval 时，Owner 才会成为强制门禁。

可信控制面必须执行：

• 已认证的 Repository、Tenant 与 Actor Identity；
• Filesystem 与 Process Sandbox；
• Command、Network、Time 与 Output Limit；
• Secret Scope 与 Redaction；
• Package Publish、Merge、Release、Delete、Credential 和生产动作审批；
• Side Effect 的 Idempotency 与 Audit Record。

这些控制符合 NIST SP 800-218A 等生命周期安全开发指南。模型拒绝或 Markdown 句子只能作为纵深防御，不能作为最终控制。

把上下文文件作为干预项评测

Context File 应通过受控任务评测，因为当前证据无法证明它具有普遍收益。

两项近期研究展示了这种不确定性：

• On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents使用 10 个仓库、124 个 PR 和一套 Codex-family 配置做配对比较，观察到 Root AGENTS.md 条件下 Median Runtime 与 Output Token 较低，而 Task Completion Behavior 接近。
• Do Context Files Help Coding Agents?在两个 Agent、17 个 Task、3 个仓库上得到 288 个已评估运行，未发现 None、Always-on 与 Selective Strategy 之间存在可测量的正确率提升。

两者的 Task、Agent、Corpus 和 Delivery Mechanism 都不同，只能支持团队自己做实验，不能推导固定收益。

建立 Fixture Suite：

至少在同一 Task 与 Repository Snapshot 上比较 No Artifact、Current Artifact 和 Candidate Artifact。记录：

gold_test_pass_rate
scope_violation_rate
forbidden_action_attempts
relevant_check_execution
unsupported_completion_claims
unnecessary_files_changed
correct_escalation_rate
tool_calls
input_and_output_tokens
wall_clock_time
cost

模型非确定性会影响结论时，应执行多次重复。报告 Task-level Distribution 与 Failure Slice，而不是只给一个总体平均值。更快但跳过必需测试属于回归。

安全发布与持续维护

Context 变更需要与代码变更相同的 Review、Evidence 和 Rollback 纪律。

发布流程

1. 明确已测量的失败或重复歧义。
2. 修改最小的权威 Source。
3. 只生成或编辑必要的 Host Adapter。
4. 验证 Registry、Digest、Link 和冲突规则。
5. 在支持的 Host/Client Version 上运行 Discovery 与 Precedence Fixture。
6. 运行代表性正确性与安全任务。
7. 由 Artifact Owner 审查 Diff。
8. 向小范围团队发布，并与 Baseline 比较。
9. 保留 Known-good Revision 和 Rollback Command。

复核触发器

以下变化发生时重新验证：

• Host、Extension、Client、Model 或 Context Limit 变化；
• Path 或 Precedence Rule 变化；
• Build、Test、Ownership、Architecture 或 Deployment Process 变化；
• Skill、Subagent、Hook、Tool 或 MCP Dependency 变化；
• Artifact 反复被 Override、忽略或导致 Token 增长；
• 安全事件涉及 Repository Context。

故障处理

如果怀疑 Context Artifact 被污染：

1. 停止消费它的自动化运行。
2. 定位受影响 Revision、Session、Branch 与生成变更。
3. 恢复 Known-good Artifact Set。
4. 必要时轮换已暴露 Credential，并使未授权输出失效。
5. 审查完整 Instruction Chain、Import、Memory、Tool 与外部 Context。
6. 重新通过安全与正确性 Fixture 后再启用自动化。

不要让 Agent 从一次失败 Session 自动学习永久规则。Durable Rule 必须具备 Owner、Evidence、有界 Scope、Review，以及 Expiry 或 Supersession 路径。

常见问题

AGENTS.md 是统一标准吗？

它是开放且广泛支持的约定，但不是统一 Runtime Standard。不同宿主的 Discovery、Nested Scope、Override、Truncation、Supported Client 与刷新时机可能不同。团队必须测试实际部署的宿主和版本。

每个仓库都应该只用一个根文件吗？

小仓库可能只需一个文件。Monorepo 往往适合 Scoped Artifact，但前提是宿主支持其解析，且团队能够避免冲突。应按 Ownership 和任务相关性拆分，而不是按任意文件大小拆分。

指令文件应该重复 README 和 API 文档吗？

不应该。只保留非显而易见的任务指引，并链接版本化来源。复制大文档会消耗 Context 并制造过时副本。若宿主无法访问链接，则保留最少必要 Invariant 并对它做测试。

Agent 能否修改自己的规则？

它可以提交 Patch，但不能未经正常 Review 持久化新指令。应保护 Instruction Path、要求 Owner、扫描隐藏字符并重跑 Fixture，因为恶意或错误修改会影响未来 Session。

什么时候应该删除一条规则？

当仓库已经能自动执行该 Invariant、事实变得可直接发现、命令已过时、规则制造冲突，或受控评测显示没有收益时，应删除或迁移。Context 本身有维护成本和 Token 成本。

总结

AI 编程上下文文件是 Host Resolver 的受治理输入。团队应把 Consumer、Scope、Precedence、Provenance、Owner 与 Expiry 作为数据管理，保持共享指引权威、Adapter 精简，通过受控任务评测结果，并在自然语言之外执行身份、权限、Secret、副作用、Review 与 Deployment。

相关资源

• AGENTS.md 上下文契约指南
• AI Coding Rule File 对比
• Context Engineering Task Packet
• Agent Harness 工程
• Prompt Injection 防御
• AI Code Review Pipeline
• Context Engineering 术语
• Prompt Injection 术语
• AI Agent 术语
• AGENTS.md 官方站点
• OpenAI Codex AGENTS.md 指南
• Claude Code Memory 文档