agent-context-loader

Agent 上下文加载器

概述

自动发现并加载项目层级结构中的 AGENTS.md 文件，供 AI 编码 Agent 使用。此技能会扫描当前工作区及其父目录，查找 Agent 指令文件，然后呈现其内容，让当前 Agent 会话获得完整的操作上下文。

先决条件

• 项目工作区中任意目录深度至少包含一个 AGENTS.md 文件
• 具有 Read 和 Glob 权限，以遍历目录树
• 具有 Grep 访问权限，以便在存在多个候选文件时搜索文件内容

指令

1. 扫描当前工作目录及所有祖先目录（直到文件系统根目录或仓库根目录），查找名为 AGENTS.md 或 agents.md 的文件。
2. 搜索当前工作区的子目录，查找可能适用于子项目或模块的其他 AGENTS.md 文件。
3. 确定加载顺序：靠近仓库根目录的文件先加载（全局上下文），更深层目录中的文件后加载（覆盖或补充）。
4. 读取发现的每个 AGENTS.md 文件，并提取其中的指令块、工作流定义和约束声明。
5. 将指令合并为统一的上下文，并注明不同层级之间的冲突（例如，子目录中的 Agent 指令覆盖根级规则）。
6. 将加载的上下文整理成结构化摘要：源文件路径、指令数量以及检测到的冲突。
7. 将发现结果缓存于当前会话中，避免后续激活时重复扫描文件系统。

输出

• 按顺序列出发现的 AGENTS.md 文件路径及其目录深度
• 合并所有已发现 Agent 上下文后得到的指令集
• 突出显示不同层级之间矛盾指令的冲突报告
• 会话缓存状态，注明结果是新鲜的还是复用的

错误处理

错误	原因	解决方案
未找到 AGENTS.md	工作区中没有 Agent 指令文件	确认工作目录正确；如有需要，在项目根目录创建 AGENTS.md
遍历目录时权限被拒绝	工作区上方的父目录受到限制	将扫描深度限制为仓库根目录（通过 .git/ 是否存在来检测）
检测到循环符号链接	符号链接目录导致无限遍历循环	扫描时跳过符号链接目录；记录警告并注明符号链接路径
不同层级的指令冲突	子目录中的 AGENTS.md 与根级文件矛盾	在输出中标记冲突；默认应用更具体（更深层）的指令
文件编码错误	AGENTS.md 使用非 UTF-8 编码	尝试使用 latin-1 作为备用编码；报告文件路径和编码问题

示例

示例 1：为每个软件包配置 Agent 指令的单体仓库

• 结构：根目录的 AGENTS.md 设置全局规范；packages/api/AGENTS.md 添加 API 专用工具规则。
• 结果：按顺序加载两个文件。API 专用规则补充全局上下文，且不产生冲突。

示例 2：提交策略冲突的嵌套工作区

• 结构：根目录的 AGENTS.md 写明“始终对提交进行签名”；services/legacy/AGENTS.md 写明“跳过提交签名”。
• 结果：检测到冲突并报告。应用更深层的（legacy）指令，并警告该指令覆盖了上级规则。

示例 3：首次设置时没有 Agent 文件

• 结构：新克隆的仓库中没有任何 AGENTS.md 文件。
• 结果：扫描完成，未找到任何文件。输出会建议在仓库根目录创建包含最简模板的 AGENTS.md。

资源

• Claude Code 的 AGENTS.md 规范：https://docs.anthropic.com/en/docs/agents
• Agent 配置的单体仓库工作区模式：https://docs.anthropic.com/en/docs/claude-code
• 分层配置加载的文件发现最佳实践