Agent 上下文加载器
概述
自动发现并加载 AI 编码代理在项目层次结构中的 AGENTS.md 文件。此技能扫描当前工作空间及其父目录,定位代理指令文件,并将其内容呈递给当前代理会话,从而提供完整的操作上下文。
前提条件
- 项目工作空间中包含一个或多个位于任意目录深度的
AGENTS.md文件 - 具有遍历目录树的读取和 Glob 权限
- 当存在多个候选文件时,需具备用于搜索文件内容的 Grep 访问权限
指令
- 扫描当前工作目录及其所有祖先目录(直到文件系统根或仓库根),查找名为
AGENTS.md或agents.md的文件。 - 搜索当前工作空间的子目录,查找可能适用于子项目或模块的其他
AGENTS.md文件。 - 确定加载顺序:距离仓库根目录较近的文件先加载(全局上下文),位于更深层目录的文件后加载(覆盖或补充)。
- 读取每个发现的
AGENTS.md文件,提取其中的指令块、工作流定义和约束声明。 - 将指令合并为统一的上下文,注意各个层级之间的冲突(例如,子目录代理覆盖了根层级的规则)。
- 将加载的上下文呈现为结构化摘要:源文件路径、指令数量和检测到的冲突。
- 缓存当前会话的发现结果,以避免在后续激活时重复进行文件系统扫描。
输出
- 已发现的
AGENTS.md文件路径的有序列表及其目录深度 - 合并所有已发现代理上下文的指令集
- 冲突报告,突出显示各层级之间存在的矛盾指令
- 会话缓存状态,指示结果是新获取的还是复用的
错误处理
| 错误 | 原因 | 解决方案 |
|---|---|---|
未找到 AGENTS.md | 工作空间没有代理指令文件 | 确认正确的工作目录;必要时在项目根目录创建 AGENTS.md |
| 遍历目录时权限被拒绝 | 工作空间上方的父目录受限 | 将扫描深度限制为仓库根目录(通过检测 .git/ 是否存在) |
| 检测到循环符号链接 | 符号链接目录创建了无限遍历循环 | 扫描时跳过符号链接目录;记录包含符号链接路径的警告 |
| 跨层级指令冲突 | 子目录的 AGENTS.md 与根层级文件矛盾 | 在输出中标记冲突;默认应用更具体的(更深层)指令 |
| 文件编码错误 | AGENTS.md 使用了非 UTF-8 编码 | 尝试 latin-1 回退;报告文件路径和编码问题 |
示例
示例 1:包含每个包代理指令的 Monorepo
- 结构:根目录的
AGENTS.md设置全局约定;packages/api/AGENTS.md添加 API 特定的工具规则。 - 结果:按顺序加载两个文件。API 特定的规则补充全局上下文,没有冲突。
示例 2:包含冲突提交策略的嵌套工作空间
- 结构:根目录的
AGENTS.md规定“始终签名提交”;services/legacy/AGENTS.md规定“跳过提交签名”。 - 结果:检测到并报告冲突。应用更深层(旧版)指令,并附带覆盖警告。
示例 3:首次设置,无代理文件
- 结构:一个刚克隆的仓库,没有任何
AGENTS.md。 - 结果:扫描完成,找到零个文件。输出包含建议,在仓库根目录创建一个含有最小模板的
AGENTS.md。
资源
- Claude Code AGENTS.md 规范:https://docs.anthropic.com/en/docs/agents
- 代理配置的 Monorepo 工作空间模式:https://docs.anthropic.com/en/docs/claude-code
- 分层配置加载的文件发现最佳实践