Agent配置：AGENTS.md可移植性与结构化文件的分工

结构化 Agent 文件应该拥有细节。AGENTS.md 应该保持便携性。

APC 最有效的做法是同时完成两项工作而不混淆它们。

第一项工作：为每个工具提供一个显而易见的项目入口点。那就是仓库根目录下的 AGENTS.md。

第二项工作：为 APC 感知工具提供一个更清洁的位置来存储结构化细节。那就是 .apc/project.json 旁边的 .apc/agents/<slug>.md。

这种分离之所以重要，是因为兼容性和结构是不同的问题。

在 AGENTS.md 的 APC 配套规范中，根文件被定义为面向兼容性的 agent 发现契约。它位于项目根目录，紧邻 .apc/，许多工具已经知道如何找到和读取它。同一规范还指出，当同一 slug 的 .apc/agents/<slug>.md 存在时，该结构化文件应被视为权威的结构化定义。

这就是正确的边界。

如果你试图把所有细节都放进 AGENTS.md，根契约就会变得很庞杂。冗长的描述、自定义字段、内存覆盖、技能列表和格式边界情况全都挤到了每个运行时必须最先扫描的那个文件中。便携式发现变得更难，正好因为"简单入口点"开始表现得像一个数据库。

如果你走另一个极端、完全放弃 AGENTS.md，便携性会更差。许多工具能够上溯仓库寻找一个熟悉的根文件。但较少工具会在第一天就知道你的内部结构化布局。

APC 通过保持两个层级来避免这种权衡。

一个轻量级的根契约看起来可以是这样的：

# Agents

## reviewer
- **Role**: Code review
- **Model**: gpt-5
- **Skills**: documentation
- **Description**: Reviews risks, tests, and regressions.

这足以用于发现、路由和对项目的初步理解。

然后更丰富的定义可以放在 APC 感知工具期望的地方：

.apc/
  project.json
  agents/
    reviewer.md

这也匹配 APX 使用项目的方式。

APX 在运行时将 AGENTS.md 作为项目指导读入。在 buildProjectAgentsBlock 中，它加载根文件，必要时截断，然后作为"项目指导 (AGENTS.md)"注入到 prompt 中。这是一个关于预期大小和目的的强烈暗示：有用的启动规则，而不是持续增长的 agent 内部转储。

APX 还有一个专门的 AGENTS.md 部分解析器。它查找一个 # Agents 标题，读取每个 ## <slug> 块，并提取角色、模型、技能和描述等项目符号字段。这个解析器存在是因为根契约需要保持可预测和便携。

所以实际规则很简单：

在 AGENTS.md 中放置跨工具发现信息。

在 .apc/agents/ 中放置结构化的逐 agent 细节。

将运行时会话、对话和私有状态都排除在两者之外；APX 将这些存储在 ~/.apx/ 下。

这为 APC 提供了一个持久的便携层，为 APX 提供了一个干净的日常使用运行时层。

AGENTS.md 保持对人类和广泛兼容工具的可读性。.apc/agents 保持对更丰富的 APC 原生结构的可用性。APX 随后可以连接两者，而不会将其中任何一个变成错误类型的存储。

便携式项目通常因为重载每个人都触及的第一个文件而失败。APC 通过保持索引精简、将细节放在结构应该在的位置而走得更远。