Back to Details

qi-layer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

qi-layer

qi-layer

/qi-maintenance
owns when colocated knowledge must move with source changes. This skill owns how to write and structure that knowledge.
Load 
/knowledge-layers
for where each layer lives and what it holds. Load 
/llm-writing
if it isn't already loaded.
This skill is about how to write and maintain the directory-local pair: AGENTS.md and 
.context/CONTEXT.md
. The pair governs any tree agents work in — code, the KB, docs, work directories. AGENTS.md loads into an agent's bounded context as standing instructions: write it like a prompt, minimal, every line load-bearing.
/qi-maintenance
负责管理随源码变更而同步迁移的协同知识。本skill负责规范这类知识的撰写与结构。
如需了解各层级的存储位置及内容，请加载
/knowledge-layers
。如果尚未加载
/llm-writing
，请先加载它。
本skill聚焦于如何撰写与维护目录级的配套文件对：AGENTS.md和
.context/CONTEXT.md
。这对文件管控着Agent工作的所有目录树——代码、知识库、文档、工作目录。AGENTS.md会加载到Agent的限定上下文当中，作为常驻指令：撰写时需像提示词一样，简洁凝练，每一行都具备实际指导意义。

The Four Principles

四大原则

  1. Fractal Compression: leaf AGENTS.md summarizes its directory's content; parent AGENTS.md summarizes its children. Each level is a compression of the level below.
  2. Hierarchical Summarization: root provides broad architectural frame. Leaves provide local working knowledge. Agents accumulate understanding as they descend.
  3. LCA Deduplication: shared knowledge appears once at the shallowest node covering all relevant paths. Never duplicate between siblings.
  4. Progressive Disclosure: give just enough to work correctly at this level. Link to 
    .context/CONTEXT.md
    for depth.
  1. 分形压缩：叶子节点的AGENTS.md总结其所在目录的内容；父节点的AGENTS.md总结其子节点的内容。每一层都是下一层内容的压缩版本。
  2. 层级总结：根节点提供宽泛的架构框架。叶子节点提供本地工作知识。Agent在遍历目录树时逐步积累认知。
  3. 最近公共祖先去重：共享知识仅出现在覆盖所有相关路径的最浅节点中。切勿在兄弟节点间重复内容。
  4. 渐进式披露：仅提供当前层级所需的足够信息以确保正确工作。如需深入内容，请链接至
    .context/CONTEXT.md
    。

Writing AGENTS.md

撰写AGENTS.md

Agents read AGENTS.md before opening anything else in the tree — write for that moment. Ask: what must someone understand before working here? That's what AGENTS.md captures.
Keep AGENTS.md as short as the directory allows, rarely past 200 lines. Include only what has substance:
  • Purpose: what this area IS and what it ISN'T (1–3 sentences)
  • Mental model: how to think about this area, key abstractions
  • Key rules: constraints, what breaks if you get it wrong
  • Anti-patterns: what NOT to do here
  • Downlinks: to 
    .context/
    for depth, to related areas
An agent that only reads AGENTS.md should be able to work correctly here. An agent that also reads .context/ should be able to change things safely.
Agent在打开目录树中的任何其他文件前会先读取AGENTS.md——请针对这个场景撰写内容。思考：**在开始在此处工作前，必须理解哪些内容？**这就是AGENTS.md需要涵盖的信息。
尽量让AGENTS.md保持简短，篇幅很少超过200行。仅包含有实质价值的内容：
  • 用途：该区域的定位与边界（1-3句话）
  • 心智模型：如何理解该区域，核心抽象概念
  • 关键规则：约束条件，出错会导致的问题
  • 反模式：此处禁止的操作
  • 下行链接：指向
    .context/
    以获取深入内容，或指向相关区域
仅读取AGENTS.md的Agent应能在此处正确开展工作。同时读取
.context/
的Agent应能安全地进行变更。

Writing .context/CONTEXT.md

撰写.context/CONTEXT.md

Reference depth, co-located with the code it describes. Where an agent goes when it needs contracts, architecture, or rationale in detail.
Sections (use only those with substance):
  • Contracts: interfaces, invariants, what breaks if violated
  • Architecture: component relationships, data flow, dependency direction
  • Rationale: why X over Y, rejected alternatives
  • Patterns: how to work here, concrete pitfalls
The 
.context/
directory is extensible: additional files alongside CONTEXT.md for specialized concerns.
提供深度参考内容，与所描述的代码存放在同一位置。当Agent需要详细了解契约、架构或设计理由时，会访问此文件。
仅保留有实质内容的章节：
  • 契约：接口、不变量，违反会导致的问题
  • 架构：组件关系、数据流、依赖方向
  • 设计理由：选择方案X而非Y的原因，被否决的替代方案
  • 模式：在此处工作的方法，具体陷阱
.context/
目录可扩展：可在CONTEXT.md旁添加其他文件以处理特定问题。

What Does NOT Belong in AGENTS.md

AGENTS.md不应包含的内容

Apply the every-session test: root AGENTS.md loads on every session. If knowledge is only relevant when working in a specific domain, it belongs in that domain's AGENTS.md or .context/, not root.
Apply the think-vs-lookup test: text whose removal would cause a wrong decision belongs in AGENTS.md. Text an agent would merely have to look up belongs in .context/. Text that changes no behavior gets deleted — agents already know how to code and follow common conventions.
Specific failure modes:
  • Session bleed: LLM working notes that calcified into the instruction file. Tells: status-update language ("deleted", "shipped", "deferred"), implementation terms packed without framing, history narration.
  • Reference material posing as intent: tables, command blocks, full scheme vocabularies, implementation specifics.
  • Redundant guards: prose warnings for invariants already enforced by tests or types. The code is the real guard; prose rots faster.
  • Duplicated knowledge: restating what lives in a skill, a domain .context/, or a KB page. Point, don't duplicate.
  • Domain-specific detail at root: URI scheme tables, gateway pricing internals, auth implementation details. These belong in their domain's AGENTS.md, not root.
应用每次会话测试：根节点的AGENTS.md会在每次会话时加载。如果知识仅在处理特定领域时才相关，应放在该领域的AGENTS.md或.context/中，而非根节点。
应用思考vs查找测试：删除后会导致Agent做出错误决策的内容属于AGENTS.md。Agent仅需查找参考的内容属于.context/。不影响行为的内容应删除——Agent已掌握编码技能和通用规范。
典型错误模式：
  • 会话残留：固化为指令文件的LLM工作笔记。特征：状态更新类语言（"已删除"、"已发布"、"已推迟"）、无框架的实现术语、历史叙述。
  • 伪装成意图的参考资料：表格、命令块、完整的方案词汇表、实现细节。
  • 冗余防护：针对已由测试或类型系统保障的不变量的文字警告。代码才是真正的防护，文字内容更容易过时。
  • 重复知识：重述已存在于skill、领域.context/或知识库页面中的内容。应链接而非重复。
  • 根节点中的领域特定细节：URI方案表格、网关定价内部逻辑、认证实现细节。这些应放在对应领域的AGENTS.md中，而非根节点。

Structural Rules

结构规则

  • Relative paths for all links
  • AGENTS.md and .context/ at the same directory level (siblings)
  • Link to files, not headings (headings change more often)
  • Lateral links between 
    .context/
    directories with contracts between them
  • LCA deduplication: if two siblings share context, put it in the parent
  • 所有链接使用相对路径
  • AGENTS.md与.context/处于同一目录层级（同级）
  • 链接指向文件而非标题（标题更易变更）
  • 存在契约关系的
    .context/
    目录间可横向链接
  • 最近公共祖先去重：如果两个兄弟节点共享上下文，将其放在父节点中

CLAUDE.md Mirrors

CLAUDE.md镜像文件

Claude harnesses read CLAUDE.md, not AGENTS.md. Give every AGENTS.md a sibling CLAUDE.md whose first line is 
@AGENTS.md
— normally the whole file. Run 
meridian qi claude-md-fix <target-root>
on the containing tree after creating or moving AGENTS.md files: it creates missing mirrors, skips exact ones, and reports anything else as a conflict.
Never write shared instructions into CLAUDE.md. Claude-only knowledge is rare; when it exists, put it below the 
@AGENTS.md
import and expect 
claude-md-fix
to keep flagging the file, so the divergence stays visible.
Loading differs by level. At the root, each harness auto-loads its own file every session: Claude reads CLAUDE.md, others read AGENTS.md. In subdirectories, Claude auto-injects CLAUDE.md when it touches files there; other agents see nested AGENTS.md only by reading it on entry. Don't lean on Claude's auto-injection: a nested AGENTS.md carries the local additions an agent needs on entry, with everything else inherited from ancestors.
Claude工具会读取CLAUDE.md而非AGENTS.md。应为每个AGENTS.md创建同级的CLAUDE.md，其第一行内容为
@AGENTS.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；其他Agent仅在进入目录时才会读取嵌套的AGENTS.md。不要依赖Claude的自动注入机制：嵌套的AGENTS.md应包含Agent进入目录时所需的本地补充内容，其他内容从父节点继承。