CLAUDE.md 两层知识架构设计

在多项目开发中，如何让 AI 助手既掌握通用规则，又能精准理解每个项目的独特上下文，是一个核心挑战。CLAUDE.md 的两层知识架构提供了一种优雅的解决方案。

全局知识层：统一管理，跨项目复用

第一层是全局知识，位于 ~/.claude/CLAUDE.md。这一层存放所有项目共享的通用经验和工作规范，包括 Git 工作流、代码审查标准、编码规范、以及 OMC Skill 系统的使用方法。全局层的设计原则是「通用但不冗余」——所有放在这一层的知识必须是真正跨项目通用的，而不是某个项目的特定经验。例如，TypeScript 的类型检查规范放在全局层，因为无论项目用 Next.js 还是 Astro，都需要遵循同样的类型安全原则。但某个 Astro 项目的 tailwind.config.mjs 迁移注意事项则应放在项目层，因为它只对那个特定项目有意义。

全局层的另一个重要内容是行为规则（behavioral rules）。这些规则定义了与 AI 协作时的基本约定，比如「禁止空道歉必须给方案」、「修复前后必须验证」、「模糊指令必须先确认意图」等。这些规则经过多次实际协作中的教训总结而成，是保证协作效率的关键。

项目专属层：精确上下文，跟随项目

第二层是项目专属知识，位于各项目根目录的 CLAUDE.md。项目层只引用全局层（请先阅读 ~/.claude/CLAUDE.md 获得通用知识），然后补充该项目的独特经验。判断一条知识应该放在哪一层的标准很简单：如果是所有项目通用的放全局，如果只有这个项目特殊的放项目层。技术栈、依赖版本、目录结构这些属于项目层；而工作流程、验证标准、编码规范这些属于全局层。

项目层还有一个关键原则是不重复全局层已有的内容。如果一条规则已经在全局层存在，项目层的 CLAUDE.md 只需要引用而不需要重新描述。例如，全局层已经规定了 Git commit 的格式规范，项目层就不需要再写一遍「commit message 应该怎么写」，只需要写这个项目特有的 Git 分支策略（如「main 分支是发布分支，dev 分支是开发分支」）。

引用机制与知识归属

两层架构的核心是引用机制而非复制机制。全局层的规则覆盖所有项目，项目层的规则补充但不重复全局层。这种设计的优势在于维护成本极低：当一条通用规则需要更新时，只需要改一处，全局层更新后所有项目自动生效。这与「复制粘贴」模式形成鲜明对比——后者的维护是 O(n) 的，n 是项目数量，当规则更新时需要逐个项目修改，极易遗漏。

在实际协作中，两层架构的价值体现在多个维度。首先，新项目初始化时有了标准模板，只需要创建项目 CLAUDE.md 并引用全局层即可。其次，当在某个项目中遇到新问题并找到解决方案时，可以先问自己「这个经验对其他项目也有用吗」，如果答案是肯定的，就把它沉淀到全局层，否则就放在项目层。最后，当团队成员加入新项目时，可以通过阅读项目层的 CLAUDE.md 快速了解该项目的独特约束和技术选型，而无需从头理解所有通用规范。

实践中的知识流转

两层架构并非一成不变，而是一个动态的知识管理系统。当一个项目经验经过验证具有普适性时，它会从项目层「晋升」到全局层；当一条全局规则在某个特定场景不适用时，项目层可以进行覆盖。例如，Tailwind CSS v4 的迁移经验最初来自 sprites-gallery 项目，后来被总结为全局规则，因为后续的 gdkvm 项目和其他 Astro 项目都需要这个知识。而某个项目特有的第三方 API 集成经验则保持在项目层，不会污染全局知识库。

这种晋升机制保证了知识库的健康演进：新知识先在小范围验证，验证通过后推广到全局；全局知识在特定项目中遇到挑战时，也会被重新审视是否需要调整为更通用的形式。