用途:创建与维护 CLAUDE.md 项目记忆文件,为 AI 编码智能体提供代码库中不易推断的上下文。仅用于非显而易见的约定、架构模式与陷阱、已确认的重复问题解决方案;不用于显而易见的模式、重复文档或通用编码建议。
主要原则:信噪比优先,能从代码推断的内容省略;写可行动的上下文,关注做什么与为何重要;只记录实际遇到的问题,未遇到的不预防性解决。
结构:使用 XML 风格标签组织,常用 <ARCHITECTURE>、<CONVENTIONS>、<GOTCHAS>、<TESTING>,用 2-4 个章节,只保留有价值内容。
应包含:架构决策、非显而易见的约定、重复出现的问题、项目模式(错误处理、日志、API 版本、迁移)。
应排除:行号(用描述性路径如 src/auth/middleware.ts)、显而易见信息、安装步骤、通用建议、临时笔记、与 README 重复内容。
反模式:不要写代码风格规则(交给 ESLint、Prettier、Black、golangci-lint 等);任务细节(数据库 schema、API 规格、部署流程)应链接到各自文档而非复制;不要什么都写,只问是否为多数编码会话相关。
链接现有文档:指向现有文档并说明何时阅读,不重复内容;指定代码用 file:line 引用。
写作风格:具体、简洁、主动语态。更新时机:探索代码库后发现的非显而易见模式、花费大量调查且会再次遇到的问题、不明显的陷阱。不要加一次性修复、易找到的信息、临时方案。
拼写约定:始终使用澳式英语拼写。
示例结构:<ARCHITECTURE> 事件驱动架构、Auth 与数据库文档链接;<CONVENTIONS> API 路由用复数名词、错误码 4 位格式、特性开关在中间件检查、日期统一 UTC;<GOTCHAS> 缓存竞态条件需先加锁、后台任务令牌 1 小时过期用 refreshToken() 刷新;<TESTING> 提交前运行 make test,集成测试需 Docker。
Token 预算:目标 1k-4k tokens,多数项目 100-300 行。超出时精简措辞、删通用建议、去重、检查 token 数。
最终检查清单:措辞简洁不重复;各章节只增加非显而易见价值;无代码风格指南;链接而非复制文档;无模糊冗长指导;无临时笔记或 TODO(除非用户要求);文件引用不含行号;聚焦稳定长期模式。