Shashank Trivedi

在项目中配置 Claude Code（或 Claude 驱动的 AI 编程助手）时，高效地组织指令是获得准确代码生成并保持低 token 消耗的关键。

理解何时使用单个 CLAUDE.md 以及何时使用模块化的 .claude/rules/ 文件，将有助于让你的 AI 助手保持敏锐、专注且可预测。

核心层级与作用域

Claude Code 会在多个层级中查找配置：

├── ~/.claude/                      # 用户/全局级别（适用于所有项目）
└── project-root/
    ├── CLAUDE.md                   # 项目全局级别（在每个会话中加载）
    ├── .claude/rules/              # 模块化且有作用域的规则（按需加载）
    └── sub-app/
        └── CLAUDE.md               # 子目录/单体仓库作用域

Enter fullscreen mode Exit fullscreen mode

  1. CLAUDE.md（全局速查表）将 CLAUDE.md 视为 AI 的主 ReadMe。它提供高层次上下文和项目核心记忆。 使用 CLAUDE.md 的场景：常用 CLI 命令：构建、测试、lint 和运行脚本（npm test、docker compose up）。 核心架构：技术栈摘要、整体文件夹结构和设计原则。 全局规则：适用于整个项目的不可变指南（例如，“严格 TypeScript，禁用 any”）。

项目上下文：电商 Web 应用

构建与测试命令

  • 构建：npm run build
  • 测试单个文件：npx jest src/components/Button.test.tsx
  • Lint：npm run lint

高层次指南

  • 所有 UI 组件必须使用 React 19 函数式语法。
  • 切勿硬编码密钥或环境变量。
  1. .claude/rules/（模块化且路径作用域的规则）随着项目增长，将所有指南塞进 CLAUDE.md 会使提示上下文膨胀并降低整体合规性。 .claude/rules/ 目录允许你创建模块化、主题特定或路径作用域的规则（使用 .yml 或 .md）。 使用 .claude/rules/ 的场景：路径特定规则（globs）：仅适用于某些文件的指南（例如，API 路由 vs. React 组件）。 领域分离：将规则拆分为专用文件（testing.yml、security.yml、db-migrations.yml）。 Token 优化：编辑 CSS/React 组件时，避免将后端迁移规则加载到上下文中。

.claude/rules/api-routes.yml

name: API & Endpoint Rules
globs:

  • "src/api/*/.ts"
  • "src/controllers/*/.ts"

rules:

  • id: input-validation description: 使用 Zod schemas 验证所有传入负载。
  • id: error-handling description: 切勿在 API 响应中暴露内部数据库错误堆栈。

专业提示与最佳实践

  • 保持 CLAUDE.md 简洁：目标在 100–150 行以内。将特定领域细节移至 .claude/rules/。
  • 结合两种策略： 将命令与核心支柱放在 CLAUDE.md 中[cite: 1]。将框架/目录特定内容放在 .claude/rules/ 中[cite: 1]。
  • 在单体仓库中使用子目录 CLAUDE.md：将本地化的 CLAUDE.md 文件放在特定包/应用中（例如，apps/web/CLAUDE.md 和 services/auth/CLAUDE.md），以便子团队维护隔离的上下文[cite: 1]。