knowledge-layers

知识层级

编写或编辑 AGENTS.md 或 .context/ 文件时，加载 /creative-writing-skills:qi-layer：它负责写作规范（四项原则、内容指南，以及哪些内容不应包含）。 如果尚未加载，请加载 /creative-writing-skills:information-hierarchy，以了解信息披露层级。 如果尚未加载，请加载 /creative-writing-skills:llm-writing。

五个层级

层级	内容	使用时机
AGENTS.md	目录的意图和心智模型	Agent 进入目录时首先阅读；在此处开始工作前需要了解的内容
.context/	契约、架构、理由（CONTEXT.md）；延后处理的工作（TODO、FUTURE）	作为参考资料，以及有记录的延后事项；与所描述的内容放在一起
KB	跨领域决策、领域概念、模式	涉及多个目录；可跨会话延续；不归任何单一目录所有
docs/	面向用户的文档	受众不同，更新节奏也不同
工作目录	临时设计决策和草稿	不与长期内容放在一起；范围限于当前工作事项

放置规则

如果内容是某个目录的意图或心智模型 → AGENTS.md。 如果是 Agent 会查阅的目录级深度信息 → .context/。 如果是范围限于此目录的延后工作 → .context/TODO（必须做） 或 .context/FUTURE（可选做）。使用扁平的 Markdown 列表——每个条目都要注明受影响的路径和具体后续工作。跨领域事项或需要对外公开的事项，应提交到项目的问题跟踪系统。 如果是全局概览——跨领域决策、领域概念、更高层次的系统架构 → KB。 如果面向最终用户 → docs/。 如果是人类对 Agent 的纠正 → KB 纠正登记表 （resources/corrections/register.md；代码项目还应在其旁边放置 code.md）。 /creative-writing-skills:correct 会修复反复出现的问题类别。 如果是临时工作产物 → 工作目录。

如有疑问，优先放在相关内容旁边。依赖某个子系统的知识应放在该子系统的 AGENTS.md 或 .context/ 中，即使它读起来像一个概念；KB 则不依赖任何单一实现，只保留在实现变更后仍然成立的内容。与所描述对象相距甚远的知识更容易过时：对象发生变化时，人们不会因此意识到还需要更新远处的文档。

KB 应链接到该工作的自有文档。 在 KB 中撰写某项工作的内容前，先阅读其文档、AGENTS.md、.context/ 以及该工作更新过的注释。链接到这些内容所描述的文档，只写它们未提及的内容：已确定的意图、原因、被否决的替代方案，以及它与项目其他部分的关系。如果这些文档已涵盖全部内容，KB 只需添加链接，或者不添加任何内容。将复述这些文档的 KB 章节精简为链接和它们未提及的部分；否则，下次文档变更时，副本就会与原文不一致。

当前事实优先于历史

每个持久层——AGENTS.md、.context/、KB、docs/——都保存着最准确的当前认知；工作目录可在工作项进行期间保留中间推理。当持久内容被取代时，应将其删除，或（对于 KB 页面）移至 archive/（标记为 .kgignore，不纳入知识图谱）。当前内容绝不引用归档内容。页面应呈现当前事实，绝不叙述自身的演变过程。

删除无需替代内容。 如果页面所述主题已不存在，或描述的行为已不再属于系统，应立即删除——即使没有新的内容可供替换。过时知识比空缺更糟：Agent 会加载它，并据此进行推理。是否删除由内容事实负责人决定；结构角色只负责提出提醒。

历史由归档保存。 在使用版本控制的目录树中，删除未跟踪文件前先提交，以便删除操作留在历史记录中，并在提交信息中说明删除了什么以及原因。在其他地方，应先在项目归档中保留仍有价值的内容，再进行删除。删除成本很低，因为保留下来的内容并未真正丢失。

每一层的事实都有其锚点。 AGENTS.md 和 .context/ 描述的是包含它们的目录树：更改所描述的内容时，应同时更新它们。KB 记录当前已确定的意图——项目应该是什么样；一旦人类确定某项不变量，无论是否已实现，它就成为 KB 中的事实。尚未确定的意图不属于 KB 内容，应留在工作目录中。docs/ 描述已向读者发布的内容。在代码项目中，加载 resources/code.md，了解这些规则如何对应分支、合并和已发布代码。

决策记录是例外：当被取代的决策有助于解释系统为何发生变化时，应保留原记录。将旧决策标记为已取代，并链接到替代决策。

不变量与当前选择

将每个已确定的事项记录为以下两种类型之一。不论工作如何开展，都必须成立的事项是不变量。项目当前正在采取或尝试的做法是当前选择。判断标准是：如果 Agent 找到一种更好的方法，但会破坏该事项，它是否应停下来先询问项目负责人？如果是，则为不变量；如果不是，Agent 可以更改它并更新文档。

默认视为当前选择。人类的保留措辞（“暂时如此”“试试看”“我觉得”“怎么省事怎么来”）表示这是一次尝试；人类同意 Agent 提出的方案也一样。Agent 自行作出的决定在得到人类确认成为不变量之前，始终是当前选择。引用人类的话时，应保留其中的保留措辞，绝不要把一次尝试记录成他们的定论。

将不变量写成规则，记录在决策记录或 AGENTS.md 中。将当前选择写成当前状况，放在所描述工作的旁边。测量数据及问题经过应放在所测量或所解释内容的旁边，不要写进规则。状态行只说明事项已完成、部分完成、尚未完成或已被取代；它如何发展到当前状态，应由版本控制或归档记录。

KB 约定

结构

KB 与其他目录树一样：它有自己的 AGENTS.md 和 .context/ 配套文件，应按照 /creative-writing-skills:qi-layer 编写——在 AGENTS.md 中写明意图，在 .context/ 中写治理细节（写作约定、结构、验证）。写入前先阅读 KB 自身的 AGENTS.md。将此技能视为跨项目默认规范；对于特定 KB，应以其本地指南为准。建议的起始布局见 resources/bootstrap.md。

Wiki 页面约定

遵循 /creative-writing-skills:information-hierarchy。每份文档只讲一个概念；文件名应描述其内容（token-validation.md），而非记录时间（auth-redesign-notes.md）。通过交叉引用代替重复解释。加载 /creative-writing-skills:shared-dao，了解词汇方法论。涉及空间关系的内容使用 mermaid；记录仅凭文件本身难以传达的信息。

运维

摄取：新信息进入知识库。阅读来源，提取关键知识，编写或更新 Wiki 页面，并更新此次变更涉及的索引和交叉链接。

维护：按照上文“当前事实优先于历史”原则，保持 Wiki 内容最新。

检查：检查 Wiki 的健康状况。查找矛盾、过时的说法、孤立页面或缺失的交叉引用。使用 /creative-writing-skills:md-validation 检查链接和图表。

对于需要人工处理的内容，使用 > [!FLAG] **需要人工审核** 标记。