Claude Code 项目记忆怎么写？CLAUDE.md 实战模板与避坑清单

Claude Code 用得久了，你会发现一个很真实的问题：它不是每次都从同一个状态开始理解项目。今天你提醒它“不要改这个目录”，明天它可能又要重新问；这次你告诉它测试命令，下次换个会话又要再解释一遍。

这就是项目记忆要解决的事。按照 Claude Code 官方文档，Claude Code 会读取 CLAUDE.md 这类文件，把其中的项目约定、构建命令、工作流程和注意事项带进会话上下文。它不是硬性权限系统，而是给 AI 编程助手看的长期说明书。

如果你已经看过站内的 Claude Code 新手工作流、Claude Code Hooks 教程，再配合 Claude专题 和 AI编程工具专题，这篇可以作为下一步：把“每次口头提醒”变成项目级规则。

CLAUDE.md 适合写什么

CLAUDE.md 最适合写那些你不想每次重复解释、并且大多数任务都会用到的信息。比如：

• 项目是做什么的，核心目录怎么分；
• 常用启动、测试、构建命令；
• 代码风格和命名约定；
• 哪些文件不能随便改；
• 发布、检查、回滚前需要注意什么；
• 团队已经踩过的坑。

不要把 CLAUDE.md 写成百科全书。官方文档也强调，规则越具体、越简洁，Claude 越容易稳定遵守。太长的文件会占用上下文，还会让真正重要的规则被淹没。

一个适合中小项目的 CLAUDE.md 模板

下面这份模板可以直接改。它不是越复杂越好，重点是让 Claude Code 快速知道项目边界和验证方式。

# Project Guide

## What This Project Is
- This repository powers a WordPress content workflow for an AI practice blog.
- The goal is stable publishing, SEO hygiene, and maintainable scripts.

## Commands
- Install dependencies: `npm install`
- Run checks: `npm test`
- Lint changed files: `npm run lint`
- Publish posts only through the project publisher script.

## Editing Rules
- Keep changes scoped to the requested task.
- Do not commit credentials, generated secrets, or real API keys.
- Do not add an h1 inside WordPress post bodies.
- Prefer existing helper scripts before creating new workflows.

## Verification
- After code changes, run the narrowest relevant test first.
- For publishing changes, verify title, excerpt, featured image alt, and internal links.
- If a check cannot be run, say exactly why.

## Content Rules
- Use topic-specific featured images.
- Reuse established tags when possible.
- Avoid creating thin tag pages for one-off topics.

这类模板的价值不在“写得漂亮”，而在“可执行”。比如“保持代码整洁”太虚；“优先运行 npm test，不能运行时说明原因”就具体得多。

CLAUDE.md、CLAUDE.local.md 和 AGENTS.md 怎么分工

很多人会把所有规则都塞进一个文件，最后越写越乱。更合理的拆法是：

• CLAUDE.md：项目级规则，适合提交到仓库，团队共享。
• CLAUDE.local.md：个人本地偏好，比如本机测试地址、临时路径、个人脚本，建议加入 .gitignore。
• AGENTS.md：如果项目同时给 Codex、其他 coding agent 使用，可以保留 AGENTS.md，再让 CLAUDE.md 导入它。

官方文档明确提到，Claude Code 读取的是 CLAUDE.md，不是 AGENTS.md。如果你的项目已经有 AGENTS.md，可以在 CLAUDE.md 里这样写：

@AGENTS.md

## Claude Code
- Before editing shared payment code, explain the plan first.
- Use path-specific rules for frontend-only changes.

这样做的好处是不用维护两份重复规则。AGENTS.md 放通用约定，CLAUDE.md 补 Claude Code 相关的行为要求。

什么时候该拆到 .claude/rules/

当项目变大后，不建议把所有规则继续塞进 CLAUDE.md。比如前端、后端、数据库迁移、内容发布各有一套要求，硬塞在一起会让上下文变重。

这时可以考虑 `.claude/rules/`。思路是把规则按场景拆开：

.claude/
  CLAUDE.md
  rules/
    frontend.md
    testing.md
    wordpress-content.md
    security.md

更进一步，还可以给规则加路径范围。比如只有处理 `src/api/` 下的文件时，才加载 API 规则；只有编辑文章草稿时，才加载内容发布规则。这样既能保留细节，又不会让每次会话都背上全部规则。

项目记忆不是权限系统

这一点很重要。CLAUDE.md 能影响 Claude Code 的行为，但它不是强制执行层。如果你写“不要删除数据库”，Claude 仍然需要配合权限设置、代码审查、备份和命令限制来真正降低风险。

我建议把风险控制分成三层：

• CLAUDE.md 写清楚行为规则和流程；
• Hooks 或脚本做自动检查，比如格式化、测试、敏感词扫描；
• 真实高风险操作交给权限、备份、人工确认来兜底。

这也能和 MCP 实战工作流、AI编程工具选择指南 形成互补：记忆负责“让 AI 知道怎么做”，工具和流程负责“让结果可验证”。

常见错误：把规则写得像愿望清单

下面这些写法看似有道理，其实效果通常不好：

• “写高质量代码”：太泛，无法验证。
• “像资深工程师一样思考”：没有项目上下文。
• “尽量不要出错”：没有操作边界。
• “所有情况都先问我”：会让小改动也变慢。
• “永远不要改某目录”：如果没有解释原因，后续任务容易冲突。

更好的写法是：

• “修改数据库迁移前，先列出影响表和回滚方式。”
• “文章正文不得包含 h1，标题由 WordPress 主题输出。”
• “只编辑与当前任务相关的文件；遇到无关脏改动时不要回滚。”
• “发布后运行指定检查脚本，并报告摘要、关键词、特色图 alt 和内链数量。”

你会发现，好的项目记忆通常像一份简短的工作协议，而不是一句泛泛的价值观。

老达点评

CLAUDE.md 的价值，不是让 Claude Code 瞬间变聪明，而是减少重复沟通和低级跑偏。对个人开发者来说，它能保存项目习惯；对小团队来说，它能让 AI 编程工具更接近一个遵守项目规矩的新同事。

我的建议是先写 50 行以内的版本，只放最常用、最容易出错、最值得每次加载的规则。等你连续遇到同一个问题两次，再把它补进去。项目记忆不是越多越好，而是越准越好。