Back to Details

claude-memory-files

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CLAUDE.md Authoring

CLAUDE.md 编写指南

Write effective project memory files that give Claude Code the context it needs without wasting tokens.
编写高效的项目记忆文件，为Claude Code提供所需的上下文信息，同时避免浪费tokens。

Core Principles

核心原则

Be specific and actionable. "Use 2-space indentation in TypeScript" beats "format code properly."
Progressive disclosure. Keep root CLAUDE.md minimal. Split detailed guidance into 
.claude/rules/
files or use 
@imports
.
Challenge every line. Claude is already smart—only add context it doesn't have. Ask: "Does this justify its token cost?"
Avoid redundancy. Don't repeat what's in README, package.json, or inferable from code.
Living document. After significant exploration, update with discoveries to prevent re-crawling.
具体且可执行。例如“TypeScript中使用2空格缩进”要优于“正确格式化代码”。
渐进式披露。保持根目录的CLAUDE.md简洁。将详细说明拆分到
.claude/rules/
文件中，或使用
@imports
导入。
质疑每一行内容。Claude本身已具备丰富知识——仅添加它不知道的上下文信息。自问：“这部分内容是否值得消耗对应的tokens？”
避免冗余。不要重复README、package.json中已有的内容，或可从代码中推断出的信息。
动态更新的文档。在深度探索代码库后，更新文件记录新发现，防止后续重复爬取。

Degrees of Freedom

自由度等级

Match instruction specificity to the task's fragility:
  • High freedom (guidance): Multiple valid approaches, context-dependent decisions
  • Medium freedom (patterns): Preferred approach exists, some variation acceptable
  • Low freedom (strict rules): Operations are fragile, consistency critical, specific sequence required
When unsure, opt for lowest freedom. Rules can be loosened later, but damage from under-specified guidance can't always be undone. Treat CLAUDE.md as a least-privilege system.
根据任务的脆弱性匹配指令的具体程度：
  • 高自由度（指导型）：存在多种有效实现方式，需根据上下文做决策
  • 中等自由度（模式型）：有首选实现方案，允许一定程度的变体
  • 低自由度（严格规则型）：操作容错性低，一致性至关重要，需遵循特定步骤
不确定时，优先选择最低自由度。规则可后续放宽，但指导说明不够明确造成的影响有时无法挽回。将CLAUDE.md视为最小权限系统。

File Locations

文件位置

LocationPurposeShared With
./CLAUDE.md
or 
./.claude/CLAUDE.md
Team project instructionsTeam (via git)
./.claude/rules/*.md
Modular topic rulesTeam (via git)
./CLAUDE.local.md
Personal project prefsJust you
~/.claude/CLAUDE.md
Personal global prefsJust you (all projects)
~/.claude/rules/*.md
Personal global rulesJust you (all projects)
位置用途共享对象
./CLAUDE.md
或 
./.claude/CLAUDE.md
团队项目指令团队成员（通过git共享）
./.claude/rules/*.md
模块化主题规则团队成员（通过git共享）
./CLAUDE.local.md
个人项目偏好设置仅自己可见
~/.claude/CLAUDE.md
个人全局偏好设置仅自己可见（适用于所有项目）
~/.claude/rules/*.md
个人全局规则仅自己可见（适用于所有项目）

Creating a New CLAUDE.md

创建新的CLAUDE.md

Quick Start

快速开始

Run 
/init
in Claude Code to bootstrap, then refine.
在Claude Code中运行
/init
命令初始化文件，之后再进行细化。

Essential Sections

必备章节

A good CLAUDE.md typically includes:
markdown
undefined
一份优质的CLAUDE.md通常包含以下内容：
markdown
undefined

Project Name

项目名称

Brief context (1-2 sentences): what this is, primary language/framework.
简要上下文（1-2句话）：项目定位、主要使用的语言/框架。

Before Starting Work

开始工作前

Before exploring the codebase via file reads or bash commands, ask the user for:
  • Existing architecture diagrams or documentation
  • File tree documentation or codebase maps
  • Relevant context from previous sessions
  • Links to design docs, ADRs, or wikis
This avoids redundant exploration. After any significant discovery, update this CLAUDE.md.
在通过读取文件或bash命令探索代码库前，请向用户询问：
  • 现有的架构图或文档
  • 文件树文档或代码库地图
  • 之前会话的相关上下文
  • 设计文档、ADR或维基链接
这可避免重复探索。在有重要发现后，更新此CLAUDE.md文件。

Project Structure

项目结构

[Key directories and their purposes - avoids repeated 
find
and 
ls
commands]
  • src/api/
    - REST endpoints, organized by resource
  • src/services/
    - Business logic, one service per domain
  • src/models/
    - Database models (Prisma)
  • tests/
    - Mirrors src/ structure
[关键目录及其用途 - 避免重复执行
find
和
ls
命令]
  • src/api/
    - REST接口，按资源分类
  • src/services/
    - 业务逻辑，每个领域对应一个服务
  • src/models/
    - 数据库模型（Prisma）
  • tests/
    - 与src/结构镜像对应

Commands

命令

  • Build: 
    pnpm run build
  • Test: 
    pnpm run test
  • Lint: 
    pnpm run lint
  • 构建：
    pnpm run build
  • 测试：
    pnpm run test
  • 代码检查：
    pnpm run lint

Architecture

架构

[Non-obvious patterns, key abstractions, data flow]
[非显性模式、关键抽象、数据流]

Conventions

约定

  • [Specific, actionable rules]
  • [Things Claude wouldn't know from reading code]
undefined
  • [具体、可执行的规则]
  • [Claude无法通过读取代码得知的内容]
undefined

What to Include

应包含的内容

  • Before Starting Work section - instruct agent to ask for existing context before exploring
  • Project structure map - key directories and purposes (avoids repeated file tree crawling)
  • Frequent commands - build, test, lint, deploy (avoid repeated discovery)
  • Architecture overview - key patterns, data flow, module boundaries
  • Non-obvious conventions - naming patterns, file organization choices, commit style
  • Critical warnings - "never modify X directly", "requires Y before Z"
  • 开始工作前章节 - 指导Agent在探索前先询问现有上下文
  • 项目结构地图 - 关键目录及其用途（避免重复爬取文件树）
  • 常用命令 - 构建、测试、代码检查、部署（避免重复探索）
  • 架构概述 - 关键模式、数据流、模块边界
  • 非显性约定 - 命名模式、文件组织方式、提交风格
  • 重要警告 - “切勿直接修改X”、“执行Z前需先完成Y”

What to Exclude

应排除的内容

  • Claude's existing knowledge: Generic language idioms, standard library usage, common patterns
  • Redundant content: Already in README.md, package.json, or inferable from code
  • Vague directives: "Write clean code", "follow best practices", "be thorough"
  • Claude已有的知识：通用语言习语、标准库用法、常见模式
  • 冗余内容：已在README.md、package.json中存在，或可从代码中推断出的信息
  • 模糊指令：“编写整洁代码”、“遵循最佳实践”、“确保全面”

The Living Document Workflow

动态文档工作流

Ideal workflow after significant work:
  1. Request comes in
  2. Read files, explore codebase, do the work
  3. Before ending session: update CLAUDE.md with what was learned or changed
What to capture after exploration:
  • Directory structures discovered (so future sessions don't re-crawl)
  • Key files and their purposes
  • Patterns identified in the codebase
  • Gotchas or non-obvious behaviors
  • New conventions established during the work
Example update after exploration:
markdown
undefined
完成重要工作后的理想流程：
  1. 收到需求
  2. 读取文件、探索代码库、完成工作
  3. 会话结束前：更新CLAUDE.md记录所学内容或变更
探索后需记录的内容：
  • 发现的目录结构（避免后续会话重复爬取）
  • 关键文件及其用途
  • 代码库中识别出的模式
  • 陷阱或非显性行为
  • 工作过程中确立的新约定
探索后的更新示例：
markdown
undefined

Project Structure (updated 2024-01)

项目结构（2024-01更新）

After exploring the codebase:
  • src/handlers/
    - Lambda handlers, one per API route
  • src/lib/
    - Shared utilities 
    • src/lib/db.ts
      - Database connection singleton
    • src/lib/auth.ts
      - JWT validation middleware
  • infrastructure/
    - CDK stacks (not Terraform as README suggests)

**Trigger phrases for updating CLAUDE.md:**

- "Let me update CLAUDE.md with what we learned"
- "I should document this discovery"
- "Future sessions will benefit from knowing..."
探索代码库后补充：
  • src/handlers/
    - Lambda处理器，每个API路由对应一个处理器
  • src/lib/
    - 共享工具库 
    • src/lib/db.ts
      - 数据库连接单例
    • src/lib/auth.ts
      - JWT验证中间件
  • infrastructure/
    - CDK栈（并非README中提到的Terraform）

**触发更新CLAUDE.md的常用表述：**

- “让我更新CLAUDE.md记录我们的发现”
- “我应该记录这个发现”
- “后续会话会受益于了解这些内容...”

Using Imports

使用导入功能

Import files with 
@path/to/file
syntax:
markdown
See @README.md for project overview.
Standard commands in @package.json.
使用
@path/to/file
语法导入文件：
markdown
项目概述请参考@README.md。
标准命令请查看@package.json。

Team Conventions

团队约定

  • Git workflow: @docs/git-workflow.md
  • API patterns: @docs/api-standards.md
  • Git工作流：@docs/git-workflow.md
  • API模式：@docs/api-standards.md

Individual Setup

个人设置

@~/.claude/personal-prefs.md

Imports work recursively (max depth 5). Not evaluated inside code blocks.
@~/.claude/personal-prefs.md

导入支持递归（最大深度为5）。代码块内的导入不会被解析。

Modular Rules with .claude/rules/

使用.claude/rules/实现模块化规则

For larger projects, split instructions by topic:
text
.claude/
├── CLAUDE.md              # Minimal root
└── rules/
    ├── typescript.md      # Language conventions
    ├── testing.md         # Test patterns
    ├── api.md             # API design rules
    └── frontend/
        ├── react.md
        └── styles.md
对于大型项目，可按主题拆分指令：
text
.claude/
├── CLAUDE.md              # 精简的根文件
└── rules/
    ├── typescript.md      # 语言约定
    ├── testing.md         # 测试模式
    ├── api.md             # API设计规则
    └── frontend/
        ├── react.md
        └── styles.md

Path-Scoped Rules

路径范围规则

Use YAML frontmatter to scope rules to specific files:
markdown
---
paths:
  - "src/api/**/*.ts"
  - "src/services/**/*.ts"
---
使用YAML前置元数据将规则限定到特定文件：
markdown
---
paths:
  - "src/api/**/*.ts"
  - "src/services/**/*.ts"
---

API Layer Rules

API层规则

  • All endpoints require input validation
  • Use standard error response format from @docs/errors.md

Glob patterns: `**/*.ts`, `src/**/*`, `*.{ts,tsx}`, `{src,lib}/**/*.ts`
  • 所有接口都需要输入验证
  • 使用@docs/errors.md中定义的标准错误响应格式

通配符模式：`**/*.ts`, `src/**/*`, `*.{ts,tsx}`, `{src,lib}/**/*.ts`

Refactoring a Bloated CLAUDE.md

重构臃肿的CLAUDE.md

If CLAUDE.md exceeds ~50 lines, consider restructuring:
  1. Analyze: Identify conflicting or redundant instructions
  2. Extract: Keep only universal content in root (description, critical commands, overrides)
  3. Categorize: Group remaining content by topic
  4. Split: Move to 
    .claude/rules/
    or imported files
  5. Prune: Remove vague directives, defaults Claude already knows, outdated refs
See refactoring checklist for detailed guidance.
如果CLAUDE.md超过约50行，可考虑重构：
  1. 分析：识别冲突或冗余的指令
  2. 提取：根文件仅保留通用内容（描述、关键命令、覆盖规则）
  3. 分类：将剩余内容按主题分组
  4. 拆分：移动到
    .claude/rules/
    或导入文件中
  5. 精简：移除模糊指令、Claude已默认知晓的内容、过时引用
详细指导请查看重构检查清单。

Markdown Formatting

Markdown格式规范

CLAUDE.md files should follow standard markdownlint rules. Detailed guidance is available in user-level rules (
~/.claude/rules/
):
  • Code blocks: Always specify a language. Use 
    text
    for file trees and non-code content.
  • Tables: Use spaces around inner pipe edges (
    | cell | cell |
    not 
    |cell|cell|
    ).
CLAUDE.md文件应遵循标准markdownlint规则。详细格式指导可在用户级规则目录中查看（
~/.claude/rules/
）：
  • 代码块：始终指定语言类型。文件树和非代码内容使用
    text
    类型。
  • 表格：单元格内的管道符两侧需添加空格（
    | cell | cell |
    而非 
    |cell|cell|
    ）。

Quality Checklist

质量检查清单

Before committing CLAUDE.md changes:
  • Every instruction is specific and actionable
  • No duplication with README or other docs
  • Root file under 50 lines (for larger projects)
  • No generic advice Claude already knows
  • Commands are accurate and tested
  • Path-scoped rules use correct glob patterns
  • Imports resolve to existing files
  • Recent explorations/discoveries have been captured
提交CLAUDE.md变更前，请检查：
  • 每条指令都具体且可执行
  • 与README或其他文档无重复内容
  • 根文件行数不超过50行（大型项目）
  • 无Claude已默认知晓的通用建议
  • 命令准确且经过测试
  • 路径范围规则使用正确的通配符模式
  • 导入的文件路径有效
  • 近期的探索/发现已被记录