CLAUDE.md 是 Claude Code 的"系统提示词"，直接影响 AI 对项目上下文的理解质量。以下是经过实战验证的编写建议：
1. 黄金结构（从上到下）
项目一句话定义 → 技术栈版本 → 目录地图 → 必遵守规则 → 常用命令 → 踩坑记录不要写成技术文档，要写成给新同事看的"入职速查表"。
2. 内容编写原则
- 具体路径：写
src/components而非 "组件目录"，写npm run dev:local而非 "启动开发服务器" - 正反示例：不仅说"用 async/await"，还要写"避免
.then()链式调用" - 优先级标记：用
【强制】、【建议】、【参考】区分重要性，AI 会优先执行强制项
3. 动态维护技巧
- 200 行红线：超过则拆分为
CLAUDE.md+docs/ai-context.md，主文件只保留高频规则 - 版本锁定：技术栈变更时（如 Vue2 升 3）立即更新，避免 AI 给出过时建议
- 错题本机制：每次 AI 犯错后，把纠正要点写成 "常见错误" 段落追加进去
4. 高阶优化
- 条件指令：使用 "如果是修复 Bug，先写测试复现；如果是新功能，先更新文档" 这类分支逻辑
- 工具链绑定：明确指定 "使用 pnpm 而非 npm"、"ESLint 必过才能提交"，减少 AI 的猜测成本
- 负向约束：明确列出 "不要修改 .env.example"、"不要直接提交到 main 分支"，比正向指令更有效
5. 避坑 checklist
- [ ] 检查是否有矛盾规则（如前面说用单引号，后面说用双引号）
- [ ] 删除临时性内容（如 "下周要重构" 这类过期信息）
- [ ] 确保文件被 Git 跟踪，但
.gitignore中排除敏感配置（如内网 API 地址）
实战建议：先用 50 行写出核心规则，使用一周后再根据实际交互补充细节，避免一开始就写得过于冗长导致 AI 抓不住重点。