Context Guidance 不是 Authority

AGENTS.md 可帮助编程 Agent 找到已核验 Command、Owner、架构和 Test Expectation，却不能证明事实最新、让所有 Tool 加载它、授权动作或保护 Secret。

应将它视为 Repository File、User Request、Tool Output 和检索文档中的一个输入；所有这些来源都可能过期或被恶意修改。

构建 Context Contract

只写任务需要的决策：

markdown 
# Task Contract

## Scope
- Allowed paths: `services/orders/**`
- Do not modify: deployment manifests, access-control rules

## Evidence
- Commands: `npm run test:orders`
- Source of truth: `docs/orders-contract.md@revision`

## Delivery
- Add focused tests for changed behavior.
- Escalate before external writes or permission changes.

使用明确路径和 Revision Reference，但仍应在当前 Checkout 核验 Command。不能声称“就近文件”会自动覆盖另一份指令，因为 Discovery 和 Precedence 随 Agent Product/Release 而异。

分离四类信息

内容 应放位置 原因
Task Guidance/Convention Context Contract 便于规划与 Review
权威产品规则 Owner 管理的版本化 Policy/Docs 可审阅、可更新
Secret/Credential Secret Manager 与 Runtime Injection 不应 Commit 或 Prompt
Authorization/副作用 Server、CI、Branch Protection、Sandbox 自然语言不能强制

“禁止部署”不能阻止带 Credential 的 Tool 部署；受保护环境、Allowlisted Command Runner 和 Approval Workflow 才能。

防御指令注入

Agent Context 可能包括 Code Comment、Issue、Package Metadata、Generated File 和 Remote Doc。除非来自经过批准和 Review 的位置，否则其中指令均不可信。

使用最小权限 Tool、写前只读 Discovery、Sandboxed Execution、有界 Network Access、Protected Branch；重要改动必须 Human Review。不得要求 Agent 绕过 Test、关闭 Security Check、暴露 Token 或把 Repository Text 当授权。

保持可测试和可逆

当 Command、Owner 或架构变化时审阅 Contract。用代表性任务测试：正常变更、过时 Command、冲突 Nested Instruction、Injected Instruction、Secret-like Value 和 Forbidden Path Request。

不要测“Agent 是否服从每句话”，而要测其是否选择正确 Evidence、保持 Scope、产出可 Review 改动、运行相关 Check 并在不确定时 Escalate。

常见问题

Monorepo 应使用嵌套文件吗？

可以，前提是团队记录 Owner 和特定 Agent 的 Resolution Rule。Local File 应保持狭窄并链接共享权威 Policy；Tool Upgrade 后测试实际行为。

文件应该很短吗？

应优先简洁、任务相关的指引，但不存在通用行数限制。当读者无法快速识别 Scope、Evidence 和 Delivery Requirement 时，再拆分材料。

延伸阅读