Prompt Engineering 关注指令如何表达；Context Engineering 关注模型在每次推理时应该获得哪些信息，以及这些信息如何被选择、组织和维护。模型只能依据当前上下文决策；上下文容量和注意力有限，因此关键不是堆积信息，而是在正确时机提供与决策相关的内容。
Agent Harness 将这种上下文设计落实为运行机制，负责组织规则、工具、任务状态和运行时反馈。AGENTS.md 是其中一种可版本化的规则载体：通过文件位置承载不同作用域的约束、决策规则和验收标准。
AGENTS.md 官网将其称为 README for agents，一种使用 Markdown 语法编写、供 Agent 获取上下文和指令的开放格式。各层都应优先记录 Agent 无法从环境中稳定、低成本获得的判断依据，例如架构约束、方案取舍和验收标准；package.json、formatter 等已经明确表达的事实无需重复。
值得注意的是，AGENTS.md 通过自然语言影响模型的决策，但无法替代项目工程的确定性机制：类型检查、自动化测试、CI 检查和权限控制。
Progressive disclosure
把架构、测试、安全和发布规则全部写进仓库级 AGENTS.md，会让每次任务都加载无关信息。这时可采用 渐进式披露（progressive disclosure）上下文编排策略：把所有任务都需要的通用规则注入前置上下文，而特定任务需要的细节留到触发后再加载。它包含两个维度：作用域轴和检索轴。
作用域轴决定规则的覆盖范围：
用户全局规则
└── 仓库级规则
└── 子目录局部规则
全局规则适用于保存跨仓库的通用约定，例如沟通语言、变更流程和破坏性操作的授权边界。仓库级规则约束当前仓库的通用工作方式。子目录规则补充模块特有的架构、风险和验证方式。
具体的发现、合并和刷新机制由 Agent Harness 决定。在设计目录层级之前，应先确认目标 Harness 的 context discovery 语义。
检索轴用于安排任务特有细节的加载。认证、数据库迁移和发布各自需要不同的约束；如果把它们全部放进默认上下文，每次任务都会加载无关信息，关键规则也更容易被稀释。
因此，自动加载的规则只保留适用多数任务的通用约定；特定任务的细节通过带触发条件的入口按需读取。任务命中条件后，Agent 再读取对应内容。这样的入口引用就是上下文指针（context pointer），需要同时说明读取条件和目标资料。
- 修改认证流程前，读取 `docs/security.md`，并遵循其中的授权边界和验收标准。
高频、跨任务且遗漏代价高的规则进入最小有效作用域的 Automatic Context；任务特有的细节则通过 context pointer、Skill 或参考文档按需加载。
维护策略层
随着项目、模型和 Agent Harness 演进，模型依赖的上下文发生变化，而原有规则编排可能失效，影响 Agent 的判断和行为。因此，维护需要持续校准规则对模型决策的影响，以及它在上下文中的位置和进入时机。
writing-for-agents 提供了适用于 Agent 文档的维护视角：用行为增益、触发可靠性和完成强度判断规则的效果，用 Context Load、Cognitive Load 和维护成本衡量代价。这些判断可以延续前文的作用域轴和检索轴，而不必把维护方法复制进项目规则。
这套权衡可以压缩为一个启发式关系（仅归纳用于表示维护决策，无实际依据）：
公式中的分子衡量上下文策略对 Agent 行为的影响：规则是否改变默认选择，是否在需要时提供决策所需的信息，以及是否用明确的完成标准推动任务完成。分母衡量这种影响带来的代价：自动加载的内容产生 Context Load，按需资料增加 Cognitive Load，重复事实、失效指针和过期规则则增加维护成本。Context Engineering 要在行为收益和这些成本之间取舍，而不是单纯增加规则或压缩文本。
因此，维护时需要重新判断内容应当保留、移动还是删除。高频且遗漏代价高的规则放入最小有效作用域，任务特有的细节通过 context pointer 或 Skill 按需加载；不能改变 Agent 行为，或已经由环境表达的内容则应删除。
writing-for-agents 将这套维护方法封装在独立 Skill 中，相关任务触发时再加载详细内容，避免把完整方法写入项目级 AGENTS.md。
小结
AGENTS.md 的本质不是知识库，而是面向模型决策的上下文策略层：用自然语言规定哪些判断需要被保留、何时进入上下文，以及如何以较低成本影响 Agent 的行为。它的价值不在于让 Agent 知道更多，而在于让关键信息在正确时机发挥作用。
