Back to Details

improve-claude-md

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
When the user provides a CLAUDE.md file (or asks you to improve one), rewrite it following the principles and structure below.
当用户提供CLAUDE.md文件（或要求你优化现有文件）时，请按照以下原则和结构重写它。

Core Problem

核心问题

Claude Code injects a system reminder with every CLAUDE.md that says:
"this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task."
This means Claude will ignore parts of your CLAUDE.md it deems irrelevant. The more content that isn't applicable to the current task, the more likely Claude is to ignore everything — including the parts that matter.
Claude Code会在每个CLAUDE.md文件中注入一条系统提示：
"此上下文可能与你的任务相关，也可能不相关。只有当它与你的任务高度相关时，你才需要响应此上下文。"
这意味着Claude会忽略它认为不相关的CLAUDE.md内容。与当前任务不适用的内容越多，Claude就越有可能忽略所有内容——包括重要的部分。

Solution: 
<important if="condition">
Blocks

解决方案：
<important if="condition">
块

Wrap conditionally-relevant sections of the CLAUDE.md in 
<important if="condition">
XML tags. This exploits the same XML tag pattern used in Claude Code's own system prompt, giving the model an explicit relevance signal that cuts through the "may or may not be relevant" framing.
将CLAUDE.md中与条件相关的部分用
<important if="condition">
XML标签包裹。这利用了Claude Code自身系统提示中使用的XML标签模式，为模型提供明确的相关性信号，打破“可能相关也可能不相关”的框架。

Principles

原则

1. Foundational context stays bare, domain guidance gets wrapped

1. 基础上下文保持原样，领域指导内容包裹标签

Not everything should be in an 
<important if>
block. Context that is relevant to virtually every task — project identity, project map, tech stack — should be left as plain markdown at the top of the file. This is onboarding context the agent always needs.
Domain-specific guidance that only matters for certain tasks — testing patterns, API conventions, state management, i18n — gets wrapped in 
<important if>
blocks with targeted conditions.
The rule of thumb: if it's relevant to 90%+ of tasks, leave it bare. If it's relevant to a specific kind of work, wrap it.
并非所有内容都需要放在
<important if>
块中。几乎与所有任务相关的上下文——项目标识、项目地图、技术栈——应作为纯Markdown放在文件顶部。这是Agent始终需要的入门上下文。
仅与特定任务相关的领域特定指导——测试模式、API约定、状态管理、国际化（i18n）——需要用带有针对性条件的
<important if>
块包裹。
经验法则：如果与90%以上的任务相关，就保持原样；如果仅与特定类型的工作相关，就包裹起来。

2. Conditions must be specific and targeted

2. 条件必须具体且有针对性

Bad — overly broad conditions that match everything:
<important if="you are writing or modifying any code">
- Use absolute imports
- Use functional components
- Use camelCase filenames
</important>
Good — each rule has its own narrow trigger:
<important if="you are adding or modifying imports">
- Use `@/` absolute imports (see tsconfig.json for path aliases)
- Avoid default exports except in route files
</important>

<important if="you are creating new components">
- Use functional components with explicit prop interfaces
</important>

<important if="you are creating new files or directories">
- Use camelCase for file and directory names
</important>
反面示例——过于宽泛的条件（匹配所有场景）：
<important if="you are writing or modifying any code">
- Use absolute imports
- Use functional components
- Use camelCase filenames
</important>
正面示例——每个规则都有其狭窄的触发条件：
<important if="you are adding or modifying imports">
- Use `@/` absolute imports (see tsconfig.json for path aliases)
- Avoid default exports except in route files
</important>

<important if="you are creating new components">
- Use functional components with explicit prop interfaces
</important>

<important if="you are creating new files or directories">
- Use camelCase for file and directory names
</important>

3. Keep it short, use progressive disclosure sparingly

3. 保持简洁，谨慎使用渐进式披露

Do not shard into separate files that require the agent to make tool calls to discover, unless the extra context is incredibly verbose or complex.
The whole point of 
<important if>
blocks is that everything is inline but conditionally weighted — the agent sees it all but only attends to what matches.
Prefer to keep the file concise.
除非额外上下文异常冗长或复杂，否则不要将内容拆分为需要Agent调用工具才能发现的单独文件。
<important if>
块的核心价值在于所有内容都内联但有条件加权——Agent能看到全部内容，但只会关注匹配当前场景的部分。
尽量保持文件简洁。

4. Less is more

4. 少即是多

  • Frontier models can reliably follow a few hundred. Claude Code's system prompt and tools already use ~50 of those. Your CLAUDE.md should be as lean as possible.
  • Cut any instruction that a linter, formatter, or pre-commit hook can enforce
  • Cut any instruction the agent can discover from existing code patterns. LLMs are in-context learners — if your codebase consistently uses a pattern, the agent will follow it after a few searches.
  • Cut code snippets. They go stale and bloat the file. Use file path references instead (e.g., "see 
    src/utils/example.ts
    for the pattern").
  • 前沿模型可以可靠遵循数百条指令，但Claude Code的系统提示和工具已经占用了约50条。你的CLAUDE.md应尽可能精简。
  • 删除任何可以通过linter、格式化工具或预提交钩子强制执行的指令。
  • 删除任何Agent可以从现有代码模式中发现的指令。大语言模型具备上下文学习能力——如果你的代码库始终使用某种模式，Agent在几次搜索后就会遵循它。
  • 删除代码片段。它们会过时并使文件膨胀，改用文件路径引用（例如：“查看
    src/utils/example.ts
    了解模式”）。

5. Keep all commands

5. 保留所有命令

Do not drop commands from the original file. The commands table is foundational reference — the agent needs to know what's available even if some commands are used less frequently.
不要删除原始文件中的命令。命令表是基础参考——即使某些命令不常用，Agent也需要知道它们的存在。

Output Structure

输出结构

When rewriting a CLAUDE.md, produce this structure:
undefined
重写CLAUDE.md时，请遵循以下结构：
undefined

CLAUDE.md

CLAUDE.md

[one-line project identity — what it is, what it's built with]
[单行项目标识——项目内容、技术栈]

Project map

Project map

[directory listing with brief descriptions]
<important if="you need to run commands to build, test, lint, or generate code"> [commands table — all commands from the original] </important> <important if="<specific trigger for rule 1>"> [rule 1] </important> <important if="<specific trigger for rule 2>"> [rule 2] </important>
... more rules, each with their own block ...
<important if="<specific trigger for domain area 1>">
[guidance]
</important>
... more domain sections ...
undefined
[目录列表及简要说明]
<important if="you need to run commands to build, test, lint, or generate code"> [命令表——保留原始文件中的所有命令] </important> <important if="<specific trigger for rule 1>"> [规则1] </important> <important if="<specific trigger for rule 2>"> [规则2] </important>
... 更多规则，每个规则对应独立块 ...
<important if="<specific trigger for domain area 1>">
[领域指导]
</important>
... 更多领域部分 ...
undefined

How to Apply

实施步骤

When given an existing CLAUDE.md to improve:
  1. Identify the project identity — extract a single sentence describing what this is. Leave it bare at the top.
  2. Extract the directory map — keep it bare (no 
    <important if>
    wrapper). This is foundational context.
  3. Extract the tech stack — if present, keep it bare near the top. Condense to one or two lines.
  4. Extract commands — keep ALL commands from the original. Wrap in a single 
    <important if>
    block.
  5. Break apart rules — split any list of rules into individual 
    <important if>
    blocks with specific conditions. You can group rules, but never group unrelated rules under one broad condition.
  6. Wrap domain sections — testing, API patterns, state management, i18n, etc. each get their own block with a condition describing when that knowledge matters.
  7. Delete linter territory — remove style guidelines, formatting rules, and anything enforceable by tooling. Suggest replacing with pre-push or pre-commit hooks.
  8. Delete code snippets — replace with file path references.
  9. Delete vague instructions — remove anything like "leverage the X agent" or "follow best practices" that isn't concrete and actionable.
当收到需要优化的现有CLAUDE.md文件时：
  1. 确定项目标识——提取描述项目的单句，放在文件顶部，保持原样。
  2. 提取目录地图——保持原样（不使用
    <important if>
    包裹），这是基础上下文。
  3. 提取技术栈——如果存在，放在顶部附近，保持原样，浓缩为1-2行。
  4. 提取命令——保留原始文件中的所有命令，用单个
    <important if>
    块包裹。
  5. 拆分规则——将任何规则列表拆分为带有特定条件的独立
    <important if>
    块。可以对相关规则进行分组，但绝不能将不相关规则放在同一个宽泛条件下。
  6. 包裹领域部分——测试、API模式、状态管理、国际化（i18n）等内容，每个部分用独立块包裹，并添加描述该知识适用场景的条件。
  7. 删除linter管辖内容——删除样式指南、格式化规则及任何可通过工具强制执行的内容，建议替换为预推送或预提交钩子。
  8. 删除代码片段——改用文件路径引用。
  9. 删除模糊指令——删除诸如“利用X agent”或“遵循最佳实践”等不具体、不可执行的内容。

Example

示例

Input:
markdown
undefined
输入：
markdown
undefined

CLAUDE.md

CLAUDE.md

This is an Express API with a React frontend in a Turborepo monorepo.
This is an Express API with a React frontend in a Turborepo monorepo.

Commands

Commands

CommandDescription
turbo build
Build all packages
turbo test
Run all tests
turbo lint
Lint all packages
turbo dev
Start dev server
turbo storybook
Start Storybook
turbo db:generate
Generate Prisma client
turbo db:migrate
Run database migrations
turbo analyze
Bundle analyzer
CommandDescription
turbo build
Build all packages
turbo test
Run all tests
turbo lint
Lint all packages
turbo dev
Start dev server
turbo storybook
Start Storybook
turbo db:generate
Generate Prisma client
turbo db:migrate
Run database migrations
turbo analyze
Bundle analyzer

Project Structure

Project Structure

  • apps/api/
    - Express REST API
  • apps/web/
    - React SPA
  • packages/db/
    - Prisma schema and client
  • packages/ui/
    - Shared component library
  • packages/config/
    - Shared configuration
  • apps/api/
    - Express REST API
  • apps/web/
    - React SPA
  • packages/db/
    - Prisma schema and client
  • packages/ui/
    - Shared component library
  • packages/config/
    - Shared configuration

Coding Standards

Coding Standards

  • Use named exports
  • Use functional components with TypeScript interfaces for props
  • Use camelCase for variables, PascalCase for components
  • Prefer 
    const
    over 
    let
  • Always use strict equality (
    ===
    )
  • Use template literals instead of string concatenation
  • Write JSDoc comments for all public functions
  • Use barrel exports in index.ts files
  • Use named exports
  • Use functional components with TypeScript interfaces for props
  • Use camelCase for variables, PascalCase for components
  • Prefer 
    const
    over 
    let
  • Always use strict equality (
    ===
    )
  • Use template literals instead of string concatenation
  • Write JSDoc comments for all public functions
  • Use barrel exports in index.ts files

API Development

API Development

  • All routes go in 
    apps/api/src/routes/
  • Use Zod for request validation
  • Use Prisma for database access
  • Error responses follow RFC 7807 format
  • Authentication via JWT middleware
  • All routes go in 
    apps/api/src/routes/
  • Use Zod for request validation
  • Use Prisma for database access
  • Error responses follow RFC 7807 format
  • Authentication via JWT middleware

Testing

Testing

  • Jest + Supertest for API tests
  • Vitest + Testing Library for frontend
  • Test fixtures in 
    __fixtures__/
    directories
  • Use 
    createTestClient()
    helper for API integration tests
  • Mock database with 
    prismaMock
    from 
    packages/db/test
  • Jest + Supertest for API tests
  • Vitest + Testing Library for frontend
  • Test fixtures in 
    __fixtures__/
    directories
  • Use 
    createTestClient()
    helper for API integration tests
  • Mock database with 
    prismaMock
    from 
    packages/db/test

State Management

State Management

  • Zustand for global client state
  • React Query for server state
  • URL state via 
    nuqs

Output:
```markdown
  • Zustand for global client state
  • React Query for server state
  • URL state via 
    nuqs

输出：
```markdown

CLAUDE.md

CLAUDE.md

Express API + React frontend in a Turborepo monorepo.
Express API + React frontend in a Turborepo monorepo.

Project map

Project map

  • apps/api/
    - Express REST API
  • apps/web/
    - React SPA
  • packages/db/
    - Prisma schema and client
  • packages/ui/
    - Shared component library
  • packages/config/
    - Shared configuration
<important if="you need to run commands to build, test, lint, or generate code">
Run with 
turbo
from the repo root.
CommandWhat it does
turbo build
Build all packages
turbo test
Run all tests
turbo lint
Lint all packages
turbo dev
Start dev server
turbo storybook
Start Storybook
turbo db:generate
Regenerate Prisma client after schema changes
turbo db:migrate
Run database migrations
turbo analyze
Bundle analyzer
</important> <important if="you are adding or modifying imports or exports"> - Use named exports (no default exports) </important> <important if="you are creating new components"> - Use functional components with TypeScript interfaces for props </important> <important if="you are adding or modifying API routes">
  • All routes go in 
    apps/api/src/routes/
  • Use Zod for request validation
  • Use Prisma for database access
  • Error responses follow RFC 7807 format
  • Authentication via JWT middleware </important>
<important if="you are writing or modifying tests">
  • API: Jest + Supertest
  • Frontend: Vitest + Testing Library
  • Test fixtures in 
    __fixtures__/
    directories
  • Use 
    createTestClient()
    helper for API integration tests
  • Mock database with 
    prismaMock
    from 
    packages/db/test
    </important>
<important if="you are working with state management, stores, or URL parameters">
  • Zustand for global client state
  • React Query for server state
  • URL state via 
    nuqs
    </important> 

What was removed and why:
- camelCase/PascalCase, const vs let, strict equality, template literals, JSDoc, barrel exports — linter and formatter territory, or discoverable from existing code patterns
- Coding Standards as a grouped section — split into targeted blocks by trigger condition

What was NOT removed:
- All commands kept (including dev, storybook, analyze)
- Project map left bare (foundational context, relevant to every task)
  • apps/api/
    - Express REST API
  • apps/web/
    - React SPA
  • packages/db/
    - Prisma schema and client
  • packages/ui/
    - Shared component library
  • packages/config/
    - Shared configuration
<important if="you need to run commands to build, test, lint, or generate code">
Run with 
turbo
from the repo root.
CommandWhat it does
turbo build
Build all packages
turbo test
Run all tests
turbo lint
Lint all packages
turbo dev
Start dev server
turbo storybook
Start Storybook
turbo db:generate
Regenerate Prisma client after schema changes
turbo db:migrate
Run database migrations
turbo analyze
Bundle analyzer
</important> <important if="you are adding or modifying imports or exports"> - Use named exports (no default exports) </important> <important if="you are creating new components"> - Use functional components with TypeScript interfaces for props </important> <important if="you are adding or modifying API routes">
  • All routes go in 
    apps/api/src/routes/
  • Use Zod for request validation
  • Use Prisma for database access
  • Error responses follow RFC 7807 format
  • Authentication via JWT middleware </important>
<important if="you are writing or modifying tests">
  • API: Jest + Supertest
  • Frontend: Vitest + Testing Library
  • Test fixtures in 
    __fixtures__/
    directories
  • Use 
    createTestClient()
    helper for API integration tests
  • Mock database with 
    prismaMock
    from 
    packages/db/test
    </important>
<important if="you are working with state management, stores, or URL parameters">
  • Zustand for global client state
  • React Query for server state
  • URL state via 
    nuqs
    </important> 

删除内容及原因：
- camelCase/PascalCase命名、const与let选择、严格相等、模板字符串、JSDoc、桶导出——这些属于linter和格式化工具的管辖范围，或可从现有代码模式中发现。
- 作为分组部分的“编码标准”——按触发条件拆分为针对性块。

未删除内容：
- 保留所有命令（包括dev、storybook、analyze）。
- 项目地图保持原样（基础上下文，与所有任务相关）。