CLAUDE.md 绝对应该根据项目阶段不断更新。根据最佳实践，它不是”一次性设置就忘记”的文档，而是需要像代码一样持续维护的活文档。
为什么需要随项目阶段更新？
1. 项目演进带来的必然变化
- 初期：可能只有基础架构和简单规范
- 成长期：新增模块、技术栈扩展、团队规模变化
- 成熟期：复杂的业务规则、性能优化要求、安全规范
- 维护期：遗留代码处理、重构策略、迁移指南
2. 防止文档”腐烂”（Documentation Rot）
根据社区实践，CLAUDE.md 如果不更新会出现：
- 引用的文件路径已不存在
- 命令无法运行（依赖或配置已变更）
- 版本号不匹配
- 已弃用的功能仍被记录
推荐的更新策略
阶段性更新时机
| 阶段 | 更新重点 | 频率建议 |
|---|---|---|
| 项目启动 | 建立基础架构、技术栈、核心约定 | 每周1-2次，快速迭代 |
| 功能开发 | 新增模块规范、API模式、错误处理 | 每个功能完成后更新 |
| 代码审查 | 从 PR 中发现未记录的约定 | 每次审查后补充 |
| 问题修复 | 记录 Claude 反复犯错的地方 | 发现问题立即添加 |
| 定期维护 | 清理冗余、整合重复、优化结构 | 每2-4周回顾一次 |
具体的维护方法
1. 有机增长（Organic Growth）
当 Claude 做出错误假设时，不要只纠正一次，而是说：”把这个规则添加到 CLAUDE.md”。这样文档会从实际使用中自然演化 。
2. 触发式更新
- 重大架构变更后立即更新
- 新团队成员加入时补充 onboarding 信息
- 引入新工具或依赖时添加使用说明
3. 分层管理
对于大型项目，可以采用分层结构：
CLAUDE.md (根目录 - 全局约定)
├── api/CLAUDE.md (API 模块特定规则)
├── frontend/CLAUDE.md (前端特定规则)
└── .claude/rules/ (细分规则文件) 更新时的检查清单
- [ ] 项目概述是否仍准确？
- [ ] 构建/测试命令是否有效？
- [ ] 关键文件路径是否正确？
- [ ] 新引入的依赖是否已记录？
- [ ] 是否有新的”常见陷阱”需要记录？
- [ ] 代码风格约定是否需要调整？
一个实用的信号
CLAUDE.md 的 Git 提交历史是团队采用 AI 辅助开发的健康指标：
- ✅ 健康信号：定期有更新提交，工程师在聊天中分享命令和技巧
- ❌ 问题信号：几个月无变更，同样的问题被反复询问
总结
CLAUDE.md 应该被视为项目的”外部记忆”，随着项目认知的深化而持续进化。最佳实践是：小步快跑、及时记录、定期清理——让它成为捕捉团队集体智慧的活文档，而不是尘封的静态文件。
