project-knowledge

项目知识

解决不明确的项目术语，并保留已确定的决策，让后续工作使用一致的语言，避免反复讨论相同的权衡。

解决术语

如果 GLOSSARY.md 存在，请阅读。

• 与用户一起明确含糊、多义或相互冲突的项目术语。
• 用具体的边界情况检验领域概念之间不明确的关系。
• 术语明确后，如有需要，创建 GLOSSARY.md，并立即使用术语表模板更新。
• GLOSSARY.md 中仅保留项目术语及其当前定义。

保留决策

如果 docs/decisions/README.md 存在，请阅读，并仅加载与当前工作相关的主题文件。

仅当项目决策同时满足以下所有条件时，才记录该决策：

1. 已确定：该选择不再是提案。用户已确认结果，或该选择是在用户明确委托的此类决策权限下作出的。
2. 可复用：未来工作很可能会遇到相同的问题，除非满足重新考虑的条件，否则应沿用这一答案。
3. 非显而易见：如果没有相关理由，未来工作可能会合理地重新讨论该问题或作出不同选择。
4. 确有权衡：存在合理的替代方案，记录被否决方案的理由可以避免重复评估。

在将选择视为已确定之前，必须有证据表明该选择是有意作出的。仅凭实现结果或无人反对，并不足以证明这一点。

对于每项符合条件的决策，请使用决策约定模板，在 docs/decisions/ 中创建或更新唯一对应的主题文件。仅保留未来工作在无需重复原始分析的情况下应用该决策所需的背景信息。

保持设计索引最新

根目录中的 DESIGN.md 是设计工作的起点：项目价值观、正在使用的共享组件、被拒绝的 UI 模式，以及每个可见元素与负责它的决策契约之间的映射。契约始终是所有规则的来源；DESIGN.md 只指向这些契约，因此不要将任何规则文本、理由或阈值复制到其中。

屏幕契约决定某项内容在屏幕上的外观或行为：颜色、文本角色、间距、图标、组件、文案、加载、禁用或错误状态，或弹层、提示消息或页眉行为。有关代码仓库机制、数据所有权、评审流程或部署的契约不是屏幕契约，不应写入 DESIGN.md。设定 UI 评审标准的契约可以作为被拒绝模式的链接目标，但不是映射元素。

创建屏幕契约、更改某个契约所涵盖的元素，或新增或移除某个屏幕契约或 UI 评审标准契约所拒绝的 UI 模式时，请在同一次变更中使用设计索引模板更新 DESIGN.md：

• 为契约负责的每个元素新增、更正或移除一行映射。
• 对于契约拒绝且 Agent 原本可能在 UI 代码中编写的每种模式，新增或移除一行被拒绝模式。通过 lint 强制执行规则等流程替代方案，只保留在契约中。
• 确保两个 Agent 客户端都获知：构建或评审屏幕的工作应先阅读 DESIGN.md。将此说明写入 AGENTS.md；如果文件不存在，则创建该文件。如果 CLAUDE.md 存在且尚未加载 AGENTS.md，也将此说明写入其中。已有含义相同说明的文件无需修改。

如果 DESIGN.md 尚不存在，请立即创建：

• 映射决策索引中的所有现有屏幕契约，而不只是当前契约，并列出它们拒绝的 UI 模式。
• 从项目的令牌来源和共享组件目录中各复制一次价值观和共享组件，并在相应章节中注明每个来源路径。如果来源不存在，则省略相应章节。

创建后，只有在相关工作更改了价值观和组件章节中注明的来源时，才更新这些章节。如果现有 DESIGN.md 使用了其他布局，请在原有位置添加行，不要重新排版。没有屏幕契约的项目不应有 DESIGN.md。

记录后续事项

如果本次会话中采用的临时变通方案的根本原因仍未解决，或者发现了范围外的缺陷或有证据支持的疑似原因，请记录后续事项。本次会话内已解决的工作、没有证据的猜测，以及当前变更中已修复的缺陷，均不符合记录条件。

发现符合条件的事项时，立即按照后续事项模板，将其单独写入 docs/follow-ups/<slug>.md，并根据症状命名 slug。记录内容必须让后续会话无需依赖本次对话也能采取行动。在对话中提及该发现并不能留存它。

后续事项记录的是待解决的问题，而非已确定的决策，因此在问题按自身条件得到解决之前，不应将其纳入 GLOSSARY.md 或决策契约。相关工作发布或该事项被提升到规范文件夹时，请删除该文件。

维护项目事实

• 如果代码与用户的陈述、GLOSSARY.md 或相关决策契约冲突，请指出不一致之处，不要默默自行取舍。代码展示的是当前行为，但不能说明该行为是否出于有意设计。
• 要求文档与代码保持一致，并不代表用户确认了代码所暗示的决策。
• 如果相关来源对已确定的决策存在分歧，在明确澄清意图之前，保持项目知识不变。
• 只有更新目标文件后，才视为术语或决策已得到保留。