用途
qi-layer 关注的是如何编写和组织目录本地的知识文档，即 AGENTS.md 与 .context/CONTEXT.md 这一对文件。它不负责判断知识何时需要随源码变更而移动（那由 /qi-maintenance 负责），而是专注于知识本身的结构与写法。该技能适用于任何智能体工作的目录树，包括代码、知识库、文档和工作目录。
四项原则
- 分形压缩：叶子 AGENTS.md 概括其所在目录的内容，父级 AGENTS.md 概括其子级。每一层都是下一层的压缩。
- 层级摘要：根节点提供宏观架构框架，叶子节点提供本地工作知识。智能体在向下遍历时逐步积累理解。
- 最近公共祖先去重：共享知识只出现在覆盖所有相关路径的最浅节点上，兄弟节点之间绝不重复。
- 渐进式披露：在当前层级只提供足以正确工作的信息，深度内容通过链接指向 .context/CONTEXT.md。
编写 AGENTS.md
智能体在打开目录树中任何其他文件之前会先读取 AGENTS.md，因此要针对这一时刻来写。核心问题是：某人在此工作之前必须理解什么？AGENTS.md 应尽可能短，通常不超过 200 行，只包含有实质内容的部分：
- 目的：这个区域是什么、不是什么（1–3 句）
- 心智模型：如何思考这个区域，关键抽象
- 关键规则：约束条件，做错会破坏什么
- 反模式：这里不要做什么
- 下行链接：指向 .context/ 获取深度，指向相关区域
只读 AGENTS.md 的智能体应能在此正确工作；同时阅读 .context/ 的智能体应能安全地修改内容。
编写 .context/CONTEXT.md
这是参考深度的所在，与它所描述的代码放在一起。当智能体需要契约、架构或详细理由时会来到这里。可按需使用以下部分：
- 契约：接口、不变量、违反后会破坏什么
- 架构：组件关系、数据流、依赖方向
- 理由：为什么选 X 而非 Y，被否决的替代方案
- 模式：如何在此工作，具体陷阱
.context/ 目录可扩展，可在 CONTEXT.md 旁放置针对特定关注点的额外文件。
什么不该放进 AGENTS.md
- 每会话测试：根 AGENTS.md 每次会话都会加载。如果知识只在特定领域工作时相关，应放在该领域的 AGENTS.md 或 .context/ 中，而非根节点。
- 思考与查阅测试：删除后会导致错误决策的文本属于 AGENTS.md；智能体只需查阅的文本属于 .context/；不改变任何行为的文本应删除。
具体失败模式包括：会话渗漏（LLM 工作笔记固化成指令文件，表现为状态更新语言、无框架的实现术语、历史叙述）；伪装成意图的参考资料（表格、命令块、完整方案词汇表）；冗余防护（对已由测试或类型强制的不变量写散文警告）；重复知识（重述技能、领域 .context/ 或知识库页面中的内容）；根节点出现领域特定细节（URI 方案表、网关定价内部、认证实现细节）。
结构规则
- 所有链接使用相对路径
- AGENTS.md 与 .context/ 位于同一目录层级（兄弟关系）
- 链接到文件而非标题（标题变化更频繁）
- 有契约关系的 .context/ 目录之间建立横向链接
- 最近公共祖先去重：若两个兄弟节点共享上下文，放到父节点
CLAUDE.md 镜像
Claude 工具链读取 CLAUDE.md 而非 AGENTS.md。应为每个 AGENTS.md 提供同级的 CLAUDE.md，其第一行是 @AGENTS.md（通常即整个文件）。创建或移动 AGENTS.md 后，在包含树上运行 meridian qi claude-md-fix <target-root>：它会创建缺失的镜像、跳过完全一致的、将其他情况报告为冲突。切勿将共享指令写入 CLAUDE.md。Claude 专属知识很少见；若存在，放在 @AGENTS.md 导入之下，并预期 claude-md-fix 会持续标记该文件，使差异保持可见。
加载方式因层级而异。在根节点，各工具链每次会话自动加载自己的文件：Claude 读 CLAUDE.md，其他读 AGENTS.md。在子目录中，Claude 在触及文件时自动注入 CLAUDE.md；其他智能体只有进入时读取嵌套 AGENTS.md 才能看到。不要依赖 Claude 的自动注入：嵌套 AGENTS.md 携带智能体进入时所需的本地补充，其余从祖先继承。
适用场景与限制
该技能适用于需要为智能体维护目录级意图文档的项目，尤其是多层级目录树。它要求使用者理解分形压缩与去重原则，并配合 /qi-maintenance 和 /knowledge-layers 等技能使用。关于具体工具链的完整支持范围、meridian 命令的安装方式及其他平台细节，资料中暂未提供。