大型代码库的 Claude Code 最佳实践：构建层级化知识库
摘要：在大型代码库中高效使用 Claude Code 的核心在于"渐进式披露"原则。通过构建三级层级化知识库，让 AI 在需要时获取恰到好处的上下文，避免 token 浪费和上下文混淆。
引言
AI 辅助编程工具日益普及，开发者面临新挑战：如何在大型代码库中高效使用 Claude Code。在根目录放一个庞大的 README 并非良策——token 浪费、上下文混淆、维护困难。
本文介绍一种层级化知识库最佳实践，通过三级文档结构，让 Claude Code 在正确时机获取正确信息。
核心原则：渐进式披露
渐进式披露（Progressive Disclosure）：在根目录提供高层规则，随着 AI 深入子目录，逐步提供更具体的"为什么"和"怎么做"。
Claude Code 原生识别 CLAUDE.md 文件。我们将此模式扩展为层级化方法，让文档结构与目录树对齐。
三级层级结构
第一层：项目根目录（全局上下文）
文件位置：/CLAUDE.md
定位：项目"宪法"，定义技术栈、核心命令、不可违背的标准。
示例内容：
## 构建命令
- 生产构建：pnpm build
- 开发模式：pnpm dev
## 测试命令
- 单元测试：pnpm test:unit <文件>
- E2E 测试：pnpm test:e2e
## 代码规范
- 仅使用函数式组件
- 禁止 default exports
- 样式使用 Tailwind CSS
## 架构概述
- Next.js 单体仓库
- 共享逻辑位于 /packages/shared
第二层：模块/领域（战略上下文）
文件位置：/src/features/billing/CONTEXT.md
定位：解释代码无法揭示的业务逻辑和隐性数据流。
示例内容：
## 领域逻辑
本模块处理 Stripe 支付集成。
## 数据流
所有支付必须先触发 webhook-handler，再更新数据库。
## 安全要求
- 禁止在前端暴露 Secret_Key
- 使用 /api/stripe 中的代理进行后端调用
## 依赖关系
- 依赖 UserStore 进行税费计算
- 与 OrderService 双向同步
第三层：叶子节点/组件（战术上下文）
文件位置：/src/components/DataGrid/NOTES.md
定位：解释"陷阱"和技术债务。
示例内容：
## 性能注意事项
- 使用 react-virtualized 进行虚拟滚动
- 禁止移除 rowHeight 属性，否则在 Safari 上会崩溃
## 已知问题
- 排序切换与 API 存在竞态条件
- 解决方案：使用 isLoading ref 进行防抖
## 待重构
- [ ] 将排序逻辑提取为独立 Hook
- [ ] 替换已废弃的 componentWillReceiveProps
AI 友好内容的编写规范
1. 明确而非习惯用语
❌ 错误：Just run the tests
✅ 正确：Use npm run test
AI 对明确指令响应更好，避免开发者"行话"。
2. 使用"要/不要"列表
AI 对否定约束响应极佳：
## 类型规范
- ❌ 不要使用 'any' 类型
- ✅ 类型 truly 不明确时使用 'unknown'
- ✅ 优先使用 TypeScript 严格模式
3. 引用具体文件路径
让 AI 知道"真相"在哪里：
## 数据模型
- 主 Schema 定义在 /src/db/schema.ts
- 类型导出在 /src/types/index.ts
4. 保持精简
单个上下文文件不超过 50 行高密度信息。超过 10KB，AI 可能浪费过多 token。
层级化 vs 扁平化：对比
| 特性 | 扁平化（单一 README） | 层级化（多级结构） |
|---|---|---|
| Token 使用 | 高（AI 每次读取全部内容） | 低（仅读取相关目录笔记） |
| 精确度 | 低（可能混淆 Webhook 规则与 UI 规则） | 高（特定文件夹的特定规则） |
| 可维护性 | 难（单一文件变成"杂物抽屉"） | 易（小文件贴近所描述的代码） |
| 扩展性 | 差（随项目增长迅速膨胀） | 好（新增模块只需添加对应文件） |
实施步骤
无需一次性完成。采用渐进式方法：
第一阶段：根目录
- 创建
/CLAUDE.md - 定义技术栈、构建命令、代码规范
第二阶段：核心模块
- 识别 3-5 个核心业务模块
- 为每个模块创建
CONTEXT.md - 描述数据流、安全要求、依赖关系
第三阶段：复杂组件
- 识别存在技术债务或"陷阱"的组件
- 创建
NOTES.md记录已知问题和解决方案
第四阶段：让 Claude 协助
使用 Claude Code 本身帮助生成文档：
# 让 Claude 分析模块并生成 CONTEXT.md
claude "Analyze the billing module and create a CONTEXT.md
that explains the data flow and security requirements"
总结
层级化知识库的核心价值：
- 节省 token：AI 仅读取相关上下文
- 提高精确度：特定规则作用于特定范围
- 易于维护：小文件贴近代码，更新成本低
- 可扩展：随项目增长自然扩展
实施时从根目录 /CLAUDE.md 入手，逐步向下扩展。记住：文档的价值在于被使用，而非被写完。
参考资料
