用途
Knowledge Layers 用于回答一个核心问题：某条知识应该放在哪里。它适用于编写或编辑 AGENTS.md、.context/ 文件，也适用于阅读和撰写持久化文档，包括 AGENTS.md、.context/、KB、docs/ 以及工作目录。
在编写或编辑 AGENTS.md 或 .context/ 文件时，应加载 /qi-layer，它负责具体写法（四项原则、内容指南、什么不该放）。若尚未加载，还应加载 /information-hierarchy 以了解披露层级，并加载 /llm-writing。
五个层级
- AGENTS.md：承载一个目录的意图与心智模型。这是智能体进入时首先阅读的内容，用于理解在此工作之前需要知道什么。
- .context/：存放契约、架构、理由（CONTEXT.md）；延后工作（TODO、FUTURE）。提供参考深度和受跟踪的延后事项，与所描述的代码放在一起。
- KB：跨领域的决策、领域概念、模式。跨越多个目录，生命周期长于会话，没有单一目录拥有它。
- docs/：面向用户的文档。受众不同，更新节奏不同。
- 工作目录：临时的设计决策与草稿。不与持久内容放在一起，作用域限定于当前活跃的工作项。
放置规则
- 如果是某个目录的意图/心智模型 → AGENTS.md。
- 如果是目录范围内、供智能体查阅的深度内容 → .context/。
- 如果是限定于该目录的延后工作 → .context/TODO（必须做）或 .context/FUTURE（锦上添花）。采用扁平 markdown 列表，每条注明受影响的路径和具体的后续动作。跨领域事项或需要外部可见性的事项，改记入项目的问题跟踪器。
- 如果是全局图景——跨领域决策、领域概念、更高层的系统架构 → KB。
- 如果是面向最终用户 → docs/。
- 如果是临时工作产物 → 工作目录。
拿不准时，就近放置。依赖某个子系统的知识，即使读起来像概念，也应放在该子系统的 AGENTS.md 或 .context/ 中；KB 保持与代码无关，只保留在实现变化后仍然成立的内容。知识离它所描述的对象越远，腐化越快：代码变更不会触发“远处文档需要更新”的意识。
当前事实优先于历史
每个持久层——AGENTS.md、.context/、KB、docs/——都保存当前最佳理解；工作目录可以在其工作项活跃期间保留中间推理。当持久内容被取代时，删除它，或（对 KB 页面）将其移入 archive/（被 .kgignore 忽略，排除在知识图谱之外）。活跃内容永不引用已归档内容。页面读起来应是当前事实，绝不叙述自身的演变。
删除不需要替代物。一个主题已消失的页面，或描述系统已不再具有的行为的页面，一经发现即删除——即使没有新内容可写。过时知识比空白更糟：智能体会加载它并据此推理。删除是内容真相所有者的决定；结构性角色只做标记。
Git 历史就是归档。删除未跟踪文件前先提交，使删除进入历史，并在提交信息中说明删除了什么及原因。删除成本很低，因为已跟踪的内容永远不会真正丢失。
真相按层锚定。AGENTS.md 和 .context/ 描述包含它们的检出：在代码变更的同一分支中更新它们，让合并同时携带两者——在并行 PR 进行时，每个分支记录自身。KB 与代码无关：它记录当前已确定的意图——系统应该是什么样——一个已确定的决策在做出那一刻就是 KB 真相，无论是否合并。未确定的意图不是 KB 材料，留在工作目录。docs/ 描述已发布的行为。
决策记录是例外：当被取代的决策能解释系统为何变化时，就地保留它。将旧决策标记为已取代，并链接到替代项。
KB 约定
结构
KB 是与其他目录一样的目录树：它自带 AGENTS.md 与 .context/ 配对，按 /qi-layer 编写——意图在 AGENTS.md，治理深度（写作约定、结构、校验）在 .context/。写入前先阅读 KB 自己的 AGENTS.md。将此技能视为跨项目默认值；该 KB 的本地指南优先。建议的起始布局见 resources/bootstrap.md。
Wiki 页面约定
遵循 /information-hierarchy。一个文档一个概念；按描述内容命名文件（token-validation.md），而非按时间（auth-redesign-notes.md）。用交叉引用代替重复解释。加载 /shared-dao 了解词汇方法论。任何空间性内容使用 mermaid；捕捉代码不易表达的信息。
操作
- 摄取（Ingest）：新信息进入 KB。阅读来源，提取关键知识，编写或更新 wiki 页面，并更新受该变更影响的索引/交叉链接。
- 维护（Maintain）：按上文“当前事实优先于历史”保持 wiki 最新。
- 检查（Lint）：对 wiki 做健康检查。查找矛盾、过时断言、孤立页面、缺失的交叉引用。使用 /md-validation 做链接检查和图表校验。
用 > [!FLAG] **Needs human review** 标记需要人工关注的内容。