9. 用CLAUDE-md教会Claude理解项目

来源：Claude Code

预计用时：35～50 分钟
本篇目标：加入一份简短的项目说明和一份路径 Rules，并用静态检查、/context 和全新会话证明它们在正确时机加载；同时分清 Auto Memory 与安全规则。

前几篇反复说明“不安装依赖、源菜谱只读、测试要跑完整套件”。这些是每次会话都应知道的项目事实，适合进入 CLAUDE.md。只有处理菜谱 JSON 时才需要的字段约束，则放进按路径加载的 Rules，避免每轮占用上下文。

开始状态

从第 8 篇的主 MealCraft 项目开始：

macOS、Linux 或 WSL2：

cd ~/claude-code-course/mealcraft
git status --short
python3 scripts/verify_security_lab.py --after

Windows PowerShell：

Set-Location "$HOME\claude-code-course\mealcraft"
git status --short
py scripts/verify_security_lab.py --after

如果你没有保留 output/security-probe.txt，安全检查器的 --after 会失败；这不影响本篇，可先只确认 .claude/settings.json 存在、测试通过且 data/recipes 没有 Diff。

开始复制前，退出当前 Claude Code 会话。CLAUDE.md 在新会话启动时加载，使用旧会话会让验证结果含糊。

一、三种机制各自保存什么

机制	谁写	适合内容	加载方式
CLAUDE.md	你	每次都要知道的命令、架构、项目约束	新会话启动时加载
.claude/rules/*.md	你	某类路径或主题的细节	无 paths 时总是加载；有 paths 时匹配文件被读取后加载
Auto Memory	Claude	从纠正中形成的项目经验和个人偏好	每个仓库自动维护并在会话中加载

三者都是给模型看的上下文，不是强制访问控制。第 8 篇的 permissions.deny 和 Sandbox 才负责硬边界。即使 CLAUDE.md 写着“不要改菜谱”，也不能因此删除 Edit(/data/recipes/**)。

二、复制课程提供的简短说明

设置教程根目录变量；占位符必须替换。

macOS、Linux 或 WSL2：

export COURSE_SOURCE="/替换为实际路径/claude-code-tutorial-v0.2"
test -f "$COURSE_SOURCE/exercise-assets/mealcraft/memory-kit/CLAUDE.md"
test ! -e CLAUDE.md
test ! -e .claude/rules/recipe-data.md
cp -R "$COURSE_SOURCE/exercise-assets/mealcraft/memory-kit/." .

Windows PowerShell：

$CourseSource = "C:\替换为实际路径\claude-code-tutorial-v0.2"
if (-not (Test-Path "$CourseSource\exercise-assets\mealcraft\memory-kit\CLAUDE.md")) { throw "上下文素材路径错误" }
if (Test-Path CLAUDE.md) { throw "项目已有 CLAUDE.md，请先人工比较" }
if (Test-Path ".claude\rules\recipe-data.md") { throw "项目已有同名 Rules，请先人工比较" }
Copy-Item "$CourseSource\exercise-assets\mealcraft\memory-kit\*" -Destination . -Recurse
New-Item -ItemType Directory -Force ".claude\rules" | Out-Null
Copy-Item "$CourseSource\exercise-assets\mealcraft\memory-kit\.claude\rules\recipe-data.md" -Destination ".claude\rules\recipe-data.md"

如果已有说明文件，停止复制并人工合并，不要覆盖。重复或矛盾的指令会降低遵循度。

新增文件：

CLAUDE.md
.claude/rules/recipe-data.md
scripts/verify_project_instructions.py

三、先自己读，不让 Claude 替你背书

CLAUDE.md 只保留每次都会用到的内容：

• MealCraft 的个人、本地项目定位与技术栈；
• 重要路径的职责；
• macOS/Linux/WSL2 与 Windows 测试、运行命令；
• 源菜谱只读、临时测试、UTF-8 和结构化错误等约束；
• “完成”必须包含哪些验证和 Diff 审查。

recipe-data.md 的开头是：

---
paths:
  - "data/recipes/**/*.json"
  - "tests/fixtures/**/*.json"
---

paths 是 Rules frontmatter 当前读取的唯一字段。它使这份规则只在 Claude 处理匹配的 JSON 时进入上下文；若 YAML 无法解析，规则可能退化为无条件加载，因此要验证语法和行为。

四、用静态检查器验证文件结构

macOS、Linux 或 WSL2：

python3 scripts/verify_project_instructions.py

Windows PowerShell：

py scripts/verify_project_instructions.py

预期输出：

PASS: MealCraft 项目说明简洁，路径 Rules 结构完整

检查器会验证：

• CLAUDE.md 不超过本课程设定的 80 行；
• 真实命令、路径、Windows 分支和完成标准存在；
• Rules 的 frontmatter 位于文件第一行且包含两个固定 glob；
• 第 8 篇共享安全设置仍存在；
• 项目说明没有密钥变量或演示密钥内容。

再运行：

git diff --check
git status --short

预期只多出这三个课程文件，没有菜谱或安全配置被改写。

五、用 /context 证明启动说明已加载

从 MealCraft 根目录启动一个全新会话：

claude

输入：

/context

在 Memory files 区域确认项目 CLAUDE.md 已加载。界面布局可能随版本变化，稳定判断标准是能看到当前项目的文件路径，而不是某个固定颜色或位置。

此时先不要读取菜谱，发送：

不要调用工具。仅根据启动时已经加载的项目说明，告诉我完整测试命令、源菜谱目录和“完成”的三个证据。

预期回答包含完整 unittest 命令、data/recipes、完整测试/发布检查或人工验证、Git Diff。它不应建议安装框架或访问外部 API。

如果答不出来，先检查启动目录和 /context，不要立即把同样内容追加十遍。

六、触发并验证路径 Rules

发送一个明确的只读任务：

只读 data/recipes/tomato-eggs.json。列出这份菜谱必须遵守的数据规则，并标明规则来自哪个项目文件。不要修改任何文件。

Claude 读取匹配文件后，recipe-data.md 应进入上下文。再次运行：

/context

确认 Memory files 中出现 .claude/rules/recipe-data.md，或当前界面明确显示该 Rules 已加载。然后核对 Claude 的回答至少包含：文件名与 id 一致、amount 保持字符串、UTF-8、源菜谱不被浏览或换算改写。

独立磁盘检查：

git diff -- data/recipes

应无输出。/context 证明规则进入模型上下文，Git 则证明只读任务没有产生副作用。

七、用 Plan Mode 检查规则是否指导决策

输入：

/plan 为 MealCraft 增加一份名为“紫菜蛋花汤”的本地菜谱

补充：

只给出计划和需要确认的信息，不要创建或修改文件。

计划应自然引用现有契约，例如 kebab-case id、UTF-8、amount 字符串、固定字段、数据检查和完整 unittest，而不是重新发明 schema。

若计划遗漏规则，先问 Claude 它实际加载了哪些 Memory files。仍然遗漏时，改写一条更具体的说明，而不是把整份 REQUIREMENTS.md 复制进 CLAUDE.md。

退出 Plan 后运行 git status --short，确认没有新菜谱。

八、用全新会话验证跨会话持久性

输入 /exit，然后仍从 MealCraft 根目录重新运行：

claude

不要恢复旧会话。直接发送：

不要调用工具。只根据新会话启动上下文，用不超过 8 条说明 MealCraft 的技术边界、测试命令和完成标准。

如果回答仍符合 CLAUDE.md，说明持久性来自磁盘文件，而不是上一段聊天记忆。会话内容可以丢失，项目说明仍会在新会话加载。

九、检查 Auto Memory，但不把它当项目文档

输入：

/memory

当前命令会列出项目与用户范围的 CLAUDE 文件、Rules、Auto Memory 开关和存放位置。只浏览，不需要为了本篇强制开启或关闭。

Auto Memory 适合保存 Claude 从纠正中学到、又无法直接从代码推导的经验。它不适合保存：

• API Key、账号、个人路径或私人数据；
• 必须由所有读者共享的构建和测试契约；
• 应该由测试、权限或 Sandbox 强制的安全边界；
• 只对当前一次任务有用的临时状态。

Auto Memory 按仓库维护并跨 worktree 共享；它由 Claude 写，不进入你的 Git 项目历史。需要所有人看到的事实应写入项目 CLAUDE.md、Rules、README 或测试。

十、/init、AGENTS.md 与审计边界

在一个没有项目说明的新仓库中，/init 可以分析代码并生成 CLAUDE.md 起点。如果文件已经存在，当前行为是提出改进而不是静默覆盖。本课程已经提供并验证了短文件，不需要再运行 /init。

当前 Claude Code 也能读取 AGENTS.md，但默认情况下，工作目录或上级目录已经有 CLAUDE.md 时，不会同时自动加载项目 AGENTS.md。已有多 Agent 说明的仓库应先核对 Project instructions 设置或显式导入，不要假设两份文件都会生效。

如果你的 /help 中存在 /doctor prompt-audit，可选运行它审计过时、冲突或找不到目标的项目说明。它先给报告，不应在未经确认时修改文件。无此命令时，静态检查器、/context 和人工 Diff 已足够完成本篇。

十一、提交共享上下文

在 Claude Code 中运行 /diff，外部终端执行：

git status --short
git diff --check
git diff -- data/recipes .claude/settings.json

最后一条命令应无输出。提交共享文件：

git add CLAUDE.md .claude/rules/recipe-data.md scripts/verify_project_instructions.py
git diff --cached --check
git commit -m "document MealCraft project context"

不要把 Auto Memory 目录、个人 CLAUDE.local.md 或用户级 ~/.claude/CLAUDE.md 加入项目提交。

本篇验收清单

• 能解释 CLAUDE.md、路径 Rules 与 Auto Memory 的作者、范围和加载时机；
• 静态检查器输出 PASS；
• 新会话 /context 显示项目 CLAUDE.md；
• 读取菜谱 JSON 后，路径 Rules 出现在已加载上下文中；
• Plan Mode 的菜谱计划引用固定 schema 与验证，而磁盘没有变化；
• 第二个全新会话仍能根据启动上下文回答项目边界；
• /memory 已检查，但未写入密钥或把 Auto Memory 当安全策略；
• Git 提交只包含共享项目说明、Rules 和检查脚本。

关键排错

/context 看不到 CLAUDE.md：确认从 MealCraft 根目录启动、文件名大小写正确且不是只在旧会话中新增。退出后新建会话再查。

路径 Rules 一开始就无条件出现：检查 frontmatter 是否从文件第一行开始、两个 --- 是否闭合、paths 缩进是否有效。无效 YAML 会让规则失去条件范围。

读取菜谱后仍看不到 Rules：确认读取路径实际匹配 data/recipes/**/*.json，再用 /context 查看。不要用只讨论文件名、但从未让 Read 工具打开文件的提示代替触发。

说明越来越长：把只适用于特定文件的内容移入 Rules，把多步骤流程留给后面的 Skill。CLAUDE.md 应保存每次都需要的最小事实，而不是复制整份手册。

本篇小结

MealCraft 现在有两层可维护上下文：短 CLAUDE.md 提供每次会话都需要的项目事实，路径 Rules 只在处理菜谱数据时加入细节。/context 和全新会话证明加载行为，权限与 Sandbox 继续负责强制边界。

下一篇会用 MealCraft 2.0 的分阶段升级学习会话恢复、分支、压缩、/fork 与后台 Agent；项目事实仍以文件、Git 和测试为准。

官方参考：

• How Claude remembers your project
• Commands
• Settings files and precedence