Claude Code 规则：如何编写 CLAUDE.md 并管理智能编码上下文

Claude Code 的规则存放在 CLAUDE.md 文件中——这些 Markdown 文件可以放在项目仓库、主目录或组织配置中，Claude 会在每次会话开始时读取它们。结合 .claude/rules/ 中的路径范围规则、用于权限管理的 settings.json 以及用于学习偏好的自动记忆，规则系统为你提供了精确、持久的控制能力，让编码代理在任何任务中都能按预期行事。

什么是 Claude Code 规则？

每个 Claude Code 会话都是从空白上下文窗口开始的。规则的作用是预先加载 Claude 所需的上下文，这样它就不必从零开始——也不会重复犯同样的错误。

两个互补的系统负责处理这一点：

CLAUDE.md 文件 是你编写的 Markdown 文件，Claude 会在每次会话开始时读取它们。用于那些始终需要应用的指令：构建命令、代码约定、架构决策、硬性约束。

自动记忆 是 Claude 根据你在会话中给出的纠正和偏好自行记录的笔记。这些笔记会自动累积；Claude 会判断哪些值得保存，并在未来的会话中读取这些笔记。

两者都会在会话开始时加载到上下文中，但它们并非强制性的配置。它们只是 Claude 作为上下文遵循的指令。要实现硬性强制执行——无论 Claude 决定做什么，都阻止某个特定命令——你需要使用 PreToolUse 钩子或 settings.json 中的 deny 规则。这种区别在自主运行中很重要，因为你希望行为可预测，而不是概率性合规。

CLAUDE.md 文件位置与范围

Claude Code 会从多个位置加载 CLAUDE.md 文件，每个位置覆盖不同的范围。它们按从最宽泛到最具体的顺序加载：

位置	范围	用途
~/.claude/CLAUDE.md	你机器上的所有项目	个人偏好、全局工作流程习惯
./CLAUDE.md（仓库根目录）	该项目的所有会话	项目约定、构建命令、团队共享规则
./CLAUDE.local.md（仓库根目录）	仅你的本地会话	开发者个人偏好；需添加到 .gitignore
./src/CLAUDE.md（子目录）	涉及该目录中文件的会话	模块特定规则，不适用于整个项目

所有发现的文件会被拼接在一起放入上下文——它们不会互相覆盖。在拼接后的内容中，从文件系统根目录到你的工作目录的内容按“最具体最后”的顺序排列，因此项目指令会出现在用户指令之后。这自然带来了特异性：当项目规则与用户级规则冲突时，项目规则获胜。

你可以在任何 CLAUDE.md 内部使用 @path 引用导入其他文件：

@./docs/architecture.md
@./CONTRIBUTING.md

导入的文件会在会话开始时加载，与 CLAUDE.md 本身一样。导入有助于组织内容，但不会节省上下文——导入的内容会计入你的 Token 预算。

对于团队：将项目 CLAUDE.md 提交到源代码管理。这确保每个开发者的 Claude 会话——以及任何基于 CI 的代理运行——都以相同的共享上下文开始。请将其视为 .eslintrc 或 pyproject.toml。

在 CLAUDE.md 中放置什么内容

最有用的内容是你否则每次会话都需要重新解释的内容，或者新团队成员在第一个小时内需要了解的内容。

好的候选内容：

• 与明显默认值不同的构建和测试命令（./scripts/test.sh --ci，而非仅仅 npm test）
• 代码约定中未被 linter 捕获的部分（“我们在所有地方使用具名导出；共享工具中不使用默认导出”）
• 从代码中不易看出的架构决策（“lib/ 目录跨服务共享——请勿在此添加特定服务的逻辑”）
• 已知的陷阱（“config.ts 文件在构建时生成；请勿手动编辑”）
• 工作流程约束（“在做出更改前始终创建分支；在打开 PR 前推送到远程”）

需要省略的内容：

• 目录列表和文件树——Claude 会从仓库中读取
• 依赖列表——可从 package.json、pyproject.toml 等获取
• 对现有代码功能的长篇描述——Claude 直接读取源代码
• 最近的更改——Claude 在需要历史时会使用 git log 和 git diff

保持 CLAUDE.md 专注于那些无法通过阅读代码库推导出来的内容。超过 200 行的文件会消耗更多上下文，并降低遵守的可靠性。Claude Code 中的 /doctor 命令会审计已提交的 CLAUDE.md，并建议删除那些可以从代码中推导出来的内容——这是修剪臃肿文件的有效方法。

编写有效的规则

具体性至关重要。比较以下两种写法：

# 模糊——一致性较差
遵循项目编码标准。

# 具体——一致性更强
- 使用 pnpm，而不是 npm 或 yarn
- 每次提交前运行 pnpm test；如果测试失败，不得提交
- 从 src/types/index.ts 导出所有共享类型——不要在组件文件中内联定义类型
- 在测试中，data/ 目录是只读的；请使用 tests/fixtures/ 中的测试夹具

每条规则都应该是可操作的，无需进一步解释。如果你需要向某人解释某条规则的理由，请将理由内联添加——这有助于 Claude 在边界情况下正确应用规则。

使用 .claude/rules/ 的路径范围规则

.claude/rules/ 目录允许你将规则附加到特定的文件模式，而无需在每次会话中都加载它们。Claude 会发现在 .claude/rules/ 中的文件，并在你处理匹配的文件时加载它们。

一个 TypeScript 单体仓库的典型结构：

.claude/rules/
  api.md             # 用于 src/api/** 的规则——请求验证、错误格式
  components.md      # 用于 src/components/** 的规则——属性类型、样式约定
  tests.md           # 用于 tests/** 的规则——夹具模式、模拟设置
  database.md        # 用于 migrations/ 和 models/ 的规则——迁移命名、查询模式

每个规则文件使用 YAML 前置元数据，并通过 paths 字段控制何时加载：

---
paths:
  - "src/api/**/*.ts"
  - "src/api/**/*.test.ts"
---

# API 开发规则

- 所有路由处理程序必须在任何业务逻辑之前使用 zod 验证输入
- 错误以 `{ error: string; code: string }` 的形式返回——切勿使用纯字符串
- 限流在网关层应用；请勿在处理器内部添加

没有 paths 字段的规则会在会话开始时无条件加载，与项目 CLAUDE.md 中的内容相同。带有 paths 的规则仅在 Claude 打开匹配这些模式的文件时加载。

这使项目根目录的 CLAUDE.md 保持简洁，并确保某个技术栈层的详细约定不会在专注于其他区域的会话期间填满上下文。

settings.json 与 CLAUDE.md 的区别

CLAUDE.md 控制 Claude 知道并打算做什么。settings.json 控制 Claude 实际被允许做什么。

	CLAUDE.md	settings.json
目的	指令和上下文	权限和配置
是否强制执行？	否——Claude 将其作为指导来执行	是——deny 规则无条件阻止工具调用
格式	自由格式的 Markdown	结构化 JSON
存放位置	./CLAUDE.md、~/.claude/CLAUDE.md	.claude/settings.json、~/.claude/settings.json

项目中的 settings.json 位于 .claude/settings.json：

{
  "permissions": {
    "allow": [
      "Bash(pnpm test)",
      "Bash(pnpm build)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)"
    ]
  }
}

allow 列表预先批准了特定命令，因此 Claude 可以在无需提示的情况下运行它们。这可以加速你信任的操作的交互式会话。deny 列表无条件阻止命令——无论 Claude 决定做什么，无论 CLAUDE.md 怎么说。对于生产数据或基础设施上的不可逆操作，请使用 deny。

用户级设置位于 ~/.claude/settings.json，适用于所有项目。项目设置位于 .claude/settings.json，仅适用于该仓库。当两者重叠时，项目设置优先于用户设置。

自动记忆：Claude 的笔记

自动记忆是 CLAUDE.md 的对应物。CLAUDE.md 是你编写的指令，而自动记忆是 Claude 根据在会话中学到的内容自行记录的笔记。

当你在会话中纠正 Claude 时——比如“这个项目我们使用 Vitest，而不是 Jest”——它可以将其保存为 ~/.claude/projects/<repo>/memory/ 中的一条笔记。下次会话时，Claude 会读取该笔记并应用纠正，无需再次告知。

记忆目录包含：

~/.claude/projects/<repo>/memory/
  MEMORY.md          # Claude 用于查找其他文件的索引；每次会话前 200 行加载
  debugging.md       # Claude 在该仓库中解决问题时发现的模式
  conventions.md     # Claude 从你的纠正中学到的约定

这是机器本地的，且每个仓库独立。自动记忆是 CLAUDE.md 的补充，而非替代：CLAUDE.md 用于团队共享的项目规则；自动记忆用于 Claude 在与你的合作中学到的个人模式。

自动记忆是可读的 Markdown 文件，你可以随时编辑或删除。在会话中运行 /memory 即可浏览和编辑这些文件。如果某些内容过时或错误，请删除它——Claude 将不再应用过时的规则。

智能编码的最佳实践

自主运行 Claude Code——通过 claude -p、Agent SDK 或 CI 流水线——会提高规则设置的重要性。代理可能在不暂停的情况下完成数十次工具调用，并且没有交互式的来回沟通来在运行中途捕捉误解。

编写明确的约束，而不仅仅是偏好。 交互式的 Claude 可以请求你澄清。自主运行会使用上下文中已有的内容。如果“未经创建数据库快照不得修改迁移文件”很重要，它必须出现在 CLAUDE.md 中。不要假设 Claude 会从代码库结构中推断出该约束。

对任何难以撤销的操作使用 deny 规则。 预先批准 Bash(pnpm build) 可以加速交互式会话，且风险较低。但对于自主运行，deny 列表是你的安全网，用于那些触及生产基础设施、永久提交到 Git 历史或删除数据的操作。

将项目 CLAUDE.md 放在版本控制中。 提交到仓库根目录的 CLAUDE.md 一致地适用于交互式会话、CI 运行以及任何团队成员的本地代理。这里是定义代码库“正确”含义的规则的正确位置。

对领域特定内容使用 .claude/rules/。 如果你的项目有多个不同的层次——前端组件、后端 API、数据库模式、基础设施脚本——请将每层的规则放在 .claude/rules/ 中，并设置路径范围。一个包含所有内容、长达 400 行的 CLAUDE.md 会让 Claude 更难导航，并且每次会话会消耗更多上下文。

将参考资料移至技能。 技能（.claude/skills/）按需加载，而非在会话开始时加载。冗长的 API 文档、多步骤部署流程和故障排除指南应属于你通过 /deploy 或 /debug 调用的技能——而不是放在 CLAUDE.md 中，在无关时仍消耗上下文。

定期审查自动记忆。 自动记忆会随时间累积。构建命令会改变，约定会被重构，测试模式会变化。一条过时的记忆笔记说“使用 v1 API 客户端”，而你已经迁移到 v2，这会在自主运行中导致微妙的错误。当你对项目结构做出重大更改时，请审计 ~/.claude/projects/<repo>/memory/。

将你的规则设置与开源模型结合使用

你构建的 CLAUDE.md 上下文和 .claude/rules/ 无论使用哪个模型进行推理，都以相同方式工作。一旦规则编写完成，切换模型后端可以保留所有设置——而通过 Novita AI 的 LLM API 使用开源模型是大规模智能编码工作的实用选择。

配置只需一个环境变量：

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_AUTH_TOKEN="<your-novita-api-key>"
export ANTHROPIC_MODEL="qwen/qwen3-coder-480b-a35b-instruct"

将 ANTHROPIC_BASE_URL 指向 Novita AI 后，Claude Code 会将所有推理请求发送到 Novita 的 Anthropic 兼容端点，而不是 api.anthropic.com。你的 CLAUDE.md、路径范围规则和 settings.json 都像之前一样应用——规则层位于模型选择的上游。

Novita AI 托管了专注于编码的开源模型，包括 Qwen3-Coder、GLM-4.7、MiniMax M2.5 和 DeepSeek V4。这些模型针对多步骤工具使用和函数调用进行了优化，这与 Claude Code 内部用于文件编辑、Shell 命令和仓库导航的工具调用模式非常匹配。

对于大规模运行智能编码任务的团队——代码审查流水线、跨大型仓库的自动重构、测试生成——Novita 上的开源模型通常每百万 Token 的成本远低于闭源替代方案，同时仍然能有效读取和应用你的项目规则。

如果你在针对生产代码库运行代理，并且希望获得超出 deny 规则的额外安全层，可以考虑将 Novita 的 LLM API 与 Novita 的 Agent Sandbox 搭配使用。沙箱为代理提供完整的 Linux 环境，用于文件操作和命令执行，与你的主机系统隔离。你的 CLAUDE.md 上下文随任务一起携带；执行风险被隔离。

常见问题解答

Claude Code 中的 CLAUDE.md 是什么？

CLAUDE.md 是一个 Markdown 文件，为 Claude Code 提供跨会话的持久指令。它在会话开始时加载，因此 Claude 无需每次都被重新教导你的项目约定。你可以在多个范围内拥有 CLAUDE.md 文件：用户级（~/.claude/CLAUDE.md）用于适用于所有地方的个人偏好，项目级（仓库根目录）用于提交到版本控制的团队共享规则，以及子目录级用于模块特定规则。

我应该在 claude rules md 文件中放置什么内容？

写下你每次会话都需要重新解释的内容：构建和测试命令、与框架默认值不同的编码约定、架构约束以及已知的代码库陷阱。省略 Claude 可以从代码库本身推导出的内容——文件树、依赖列表以及对现有代码功能的描述。保持文件在 200 行以下，以获得一致的遵守效果。

Claude Code 中 CLAUDE.md 和 settings.json 有什么区别？

CLAUDE.md 是 Claude 作为指导遵循的指令。settings.json 是 Claude Code 在系统级别强制执行的配置。CLAUDE.md 中的规则塑造了 Claude 打算做什么；settings.json 中的 deny 条目则无条件阻止工具调用。对于无论 Claude 如何决定都不能发生的事情——不可逆的删除、强制推送、生产环境操作——请使用 settings.json，而不是 CLAUDE.md。

.claude/rules/ 目录是什么？

.claude/rules/ 包含路径范围规则文件，仅在 Claude 处理与规则范围匹配的文件时加载。这允许你编写详细的领域特定规则，而无需在每次会话中都加载它们。规则文件是 Markdown 文件，带有可选的 YAML 前置元数据，指定 paths 的 glob 模式。没有 paths 前置元数据的规则会在会话开始时无条件加载，就像额外的 CLAUDE.md 内容一样。

CLAUDE.md 在 CI 和自动化 claude code 任务中有效吗？

是的。任何在仓库目录中运行的 claude -p 调用、Agent SDK 调用或 CI 流水线都会加载项目的 CLAUDE.md。这使得 CLAUDE.md 能够在交互式和自动化上下文中一致地强制执行行为。将其提交到版本控制可以确保每次运行——无论是本地还是 CI——都以相同的共享上下文开始。

claude code 上下文如何工作？我该如何管理它？

上下文是当前会话的 Token 预算。CLAUDE.md 文件、导入的引用、自动记忆以及对话历史都会计入其中。通过保持 CLAUDE.md 简洁、使用 .claude/rules/ 仅在相关时加载领域内容、以及使用 /compact 来总结长会话而不丢失连续性来管理它。在 /compact 之后，Claude 会从磁盘重新读取项目根目录的 CLAUDE.md，并自动将其重新注入到会话中。

如何在团队中进行智能编码时使用 claude code 最佳实践？

将项目 CLAUDE.md 提交到你的仓库，以便所有团队成员和 CI 代理共享相同的规则。对领域特定内容使用带路径范围的 .claude/rules/。在 .claude/settings.json 中添加 deny 规则，用于那些永远不应在自动化上下文中运行的操作。让自动记忆远离 CI——它是机器本地的且针对每个开发者；提交的 CLAUDE.md 才是共享行为的真相来源。

Novita AI 是一个 AI 云平台，为开发者提供通过简单 API 部署 AI 模型的便捷方式，同时提供价格实惠且可靠的 GPU 云用于构建和扩展。

推荐文章

• Claude Code CLI 文档：设置、斜杠命令和 LLM API 集成
• Claude Code SDK：使用 Python 和 TypeScript 构建自主代理
• 使用 Novita 的 Agent Sandbox 构建编码代理

---

来源检查日期：2026 年 7 月 21 日：Claude Code 记忆文档、Claude Code 功能概述、Novita AI LLM API