mcpField
Q
qi-layer

qi-layer

github.com/haowjyAgent 工作流549388 次安装今天更新
代码仓库

关于 qi-layer

qi-layer 用于编写和维护目录级 AGENTS.md 与 .context/CONTEXT.md。它提供精简分层 Agent 指令和参考资料的组织原则。

主要功能

  1. 01目录层级间的分形压缩
  2. 02从根目录到叶级的分层摘要
  3. 03在共同父级去除重复内容
  4. 04渐进式披露详细信息
  5. 05AGENTS.md 与 CONTEXT.md 编写指引

适用场景

  1. 01组织仓库中的指令层级
  2. 02判断哪些内容应写入 AGENTS.md
  3. 03将详细契约放入 .context/
  4. 04清理重复或仅适用于当前会话的笔记

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/haowjy/creative-writing-skills --skill qi-layer

安装后在 Claude Code 中输入/qi-layer确认已加载。

附带文件resources/references.md

详细介绍

qi-layer

/creative-writing-skills:qi-maintenance 负责确定何时需要随所描述的变更一并迁移同目录知识。 此技能负责说明如何编写和组织这些知识。

加载 /creative-writing-skills:knowledge-layers，了解各层的位置和内容。 如果尚未加载，请加载 /creative-writing-skills:llm-writing。

此技能介绍如何编写和维护目录级的配套文件： AGENTS.md 和 .context/CONTEXT.md。这对文件适用于 Agent 工作的任何目录树——代码、知识库、文档、工作目录。AGENTS.md 会作为常驻指令加载到 Agent 有限的上下文中：应像编写提示词一样编写它，保持精简，每一行都要有作用。

四项原则

  1. 分形压缩：叶子目录的 AGENTS.md 概述其目录内容；父目录的 AGENTS.md 概述其子目录。每一层都是对下一层的压缩。
  2. 分层总结：根目录提供宽泛的架构框架；叶子目录提供本地工作知识。Agent 会在逐层深入时积累理解。
  3. 最低共同祖先去重：共享知识只在覆盖所有相关路径的最浅节点中出现一次。
  4. 渐进式披露：提供在当前层级正确开展工作所需的足够信息。链接到 .context/CONTEXT.md 获取更深入的内容。

编写 AGENTS.md

Agent 会在打开目录树中的任何其他内容前读取 AGENTS.md——请针对这一时刻编写。思考：在此处开展工作前，必须了解什么？ AGENTS.md 就是用来记录这些内容的。

在目录条件允许的范围内，尽量缩短 AGENTS.md，通常不超过 200 行。只包含有实质意义的内容：

  • 用途：此区域是什么、又不是什么（1–3 句）
  • 思维模型：如何理解此区域及其关键抽象概念
  • 关键规则：约束条件，以及违反后会导致的问题
  • 反模式：在此处不应采取的做法
  • 下游链接：链接到 .context/ 以获取深入内容，并链接到相关区域

只阅读 AGENTS.md 的 Agent 也应该能够在此处正确开展工作。同时阅读 .context/ 的 Agent 应该能够安全地进行变更。

编写 .context/CONTEXT.md

这是与其描述内容同目录存放的参考资料，供 Agent 在需要了解详细契约、架构或设计依据时查阅。

章节（仅使用有实质内容的章节）：

  • 契约：接口、不变量，以及违反后会导致的问题
  • 架构：组件关系、数据流、依赖方向
  • 设计依据：选择 X 而非 Y 的原因，以及被否决的替代方案
  • 模式：如何在此处开展工作，以及具体的陷阱

.context/ 目录可扩展：可在 CONTEXT.md 旁添加其他文件，用于记录特定主题。

不应写入 AGENTS.md 的内容

应用每次会话测试：根目录 AGENTS.md 会在每次会话中加载。如果某项知识只与特定领域的工作相关，就应放在该领域的 AGENTS.md 或 .context/ 中，而不是根目录。

应用思考与查阅测试：如果删除某段文字会导致决策错误，就应写入 AGENTS.md。若 Agent 只需查阅某段文字，就应将其放入 .context/。对行为没有影响的文字应删除——Agent 已掌握其专业技能和通用惯例。

具体的失效模式：

  • 会话内容侵入：将 LLM 工作笔记固化进指令文件。迹象包括：状态更新用语（“已删除”、“已发布”、“已推迟”）、未加说明便堆砌实现术语，以及叙述历史。
  • 伪装成意图的参考资料：表格、命令块、完整的方案词汇表、实现细节。
  • 多余的防护说明：通过检查（测试、类型、验证器）已强制执行不变量，却仍以文字重复警告。检查才是真正的防护；文字说明更容易过时。
  • 知识重复：重述技能、领域 .context/ 或知识库页面中已有的内容。应链接到内容所在位置。
  • 根目录中的领域专属细节：URI 方案表、网关定价机制、身份验证实现细节。这些内容应放在所属领域的 AGENTS.md 中，而不是根目录。

结构规则

  • 所有链接都使用相对路径
  • AGENTS.md 和 .context/ 位于同一目录层级，互为同级项
  • 链接到文件，而不是标题（标题更常变动）
  • 在 .context/ 目录之间建立横向链接，并在它们之间定义契约
  • LCA 去重：如果两个同级目录共享上下文，就将其放在父目录中

CLAUDE.md

如果某个目录没有 CLAUDE.md，Claude Code 会读取 AGENTS.md，因此大多数目录只需要 AGENTS.md。仅在需要 Claude 专属指令时添加 CLAUDE.md，并将 @AGENTS.md 作为第一行：存在 CLAUDE.md 时，Claude 会读取它，而不是 AGENTS.md。切勿将共享指令写入 CLAUDE.md。

不同层级的加载方式有所不同。在根目录，每个 Harness 都会在每个会话中加载 AGENTS.md。在子目录中，Claude 会在访问其中的文件时加载嵌套的 AGENTS.md；其他 Agent 只有在进入目录时读取该文件，才会看到嵌套的 AGENTS.md。编写每个嵌套的 AGENTS.md 时，要考虑其读取者：写入 Agent 进入目录时需要的本地补充内容，其余内容则继承自祖先目录。

评论

支持 Markdown