claude-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create or Improve a CLAUDE.md

创建或优化CLAUDE.md

FIRST: Explore the Codebase

第一步：探索代码库

Before doing ANYTHING else, use the Task tool with these exact parameters:

```
subagent_type
```
:
```
Explore
```
```
thoroughness
```
:
```
very thorough
```
```
prompt
```
: Include the WHAT/WHY/HOW questions listed below

Do NOT proceed until exploration is complete.

在进行任何操作之前，请使用Task工具并设置以下精确参数：

```
subagent_type
```
:
```
Explore
```
```
thoroughness
```
:
```
very thorough
```
```
prompt
```
: 包含以下列出的WHAT/WHY/HOW问题

探索完成前请勿继续。

Overview

概述

You are creating or improving a

CLAUDE.md

file for a codebase. This file is the only content guaranteed to appear in every Claude conversation, making it critical infrastructure for agent effectiveness.

你正在为某个代码库创建或优化

CLAUDE.md

文件。该文件是唯一能确保在每一次Claude对话中都展示的内容，因此它是提升Agent效能的关键基础配置。

Key Principles (from HumanLayer research)

核心原则（来自HumanLayer研究）

Under 300 lines (ideally <100). Shorter = better followed.
Only universally applicable directives. Claude's system prompt uses ~50 of ~150-200 available instruction slots.
Progressive disclosure: Reference separate docs, don't inline everything.
Never use as linter: Use actual linters/formatters, not LLM instructions for code style.
No commands, skills, hooks, or automations: These are discoverable via
```
/help
```
,
```
.claude/commands/
```
,
```
.claude/skills/
```
,
```
.claude/settings.json
```
, and
```
.claude/automations/
```
. Don't inventory them in CLAUDE.md — they change frequently and become stale.
Use
file:line
pointers instead of code snippets (prevents outdated info).

篇幅控制在300行以内（理想情况是少于100行）。越简短，越容易被遵循。
仅包含通用适用的指令。Claude的系统提示词在约150-200个可用指令槽中仅使用约50个。
渐进式披露：引用独立文档，不要将所有内容内联在文件中。
切勿用作代码检查工具：使用实际的代码检查器/格式化工具，而非用大语言模型指令来规范代码风格。
不包含命令、技能、钩子或自动化内容：这些内容可通过
```
/help
```
、
```
.claude/commands/
```
、
```
.claude/skills/
```
、
```
.claude/settings.json
```
和
```
.claude/automations/
```
查看。不要在CLAUDE.md中罗列这些内容——它们会频繁变更，很快就会过时。
使用
file:line
指针替代代码片段（避免信息过时）。

What "Universally Applicable" Means

“通用适用”的定义

A rule is universally applicable if it applies to every single task in this codebase. Ask yourself:

Would this rule apply when fixing a bug? Adding a feature? Writing tests? Refactoring?
If the answer is "only sometimes", it does NOT belong in CLAUDE.md.

Examples of universally applicable rules:

"Use
```
uv add
```
instead of
```
pip install
```
" (applies to every Python task)
"Run
```
make check
```
before committing" (applies to every change)
"All API endpoints require authentication except
```
/health
```
" (applies to every API task)

Examples of NOT universally applicable (don't include):

"Use React Query for data fetching" (only applies when adding data fetching)
"Add migration files for schema changes" (only applies when changing schema)
Code style rules (use linters instead)
Commands, skills, hooks, and automations (discoverable via tools, not LLM guidance)

如果一条规则适用于代码库中的每一项任务，那么它就是通用适用的。请自问：

这条规则在修复bug、添加功能、编写测试、重构代码时都适用吗？
如果答案是“仅有时适用”，那么它就不属于CLAUDE.md的内容。

通用适用规则示例：

“使用
```
uv add
```
而非
```
pip install
```
”（适用于所有Python任务）
“提交前运行
```
make check
```
”（适用于所有变更操作）
“除
```
/health
```
外，所有API端点都需要身份验证”（适用于所有API相关任务）

非通用适用示例（请勿包含）：

“使用React Query进行数据获取”（仅在添加数据获取功能时适用）
“为 schema 变更添加迁移文件”（仅在修改schema时适用）
代码风格规则（改用代码检查器）
命令、技能、钩子和自动化内容（可通过工具查看，无需大语言模型指导）

Your Process

操作流程

Step 1: Explore (ALREADY DONE ABOVE)

步骤1：探索（已在上方完成）

Your Explore agent should have discovered:

WHAT (Technology & Structure):

Primary language(s) and frameworks
Project structure (especially monorepo layouts)
Key directories and their purposes
Configuration files (package.json, pyproject.toml, Cargo.toml, etc.)
Build/CI configuration

WHY (Purpose & Architecture):

What the project does
How different components relate
Key abstractions and patterns used

HOW (Commands & Workflows):

Build commands
Test commands (unit, integration, e2e)
Lint/format commands
Run/dev commands
Deployment patterns

你的Explore Agent应已发现以下信息：

WHAT（技术与结构）：

主要编程语言及框架
项目结构（尤其是单仓布局）
关键目录及其用途
配置文件（package.json、pyproject.toml、Cargo.toml等）
构建/CI配置

WHY（目的与架构）：

项目功能
不同组件之间的关联方式
使用的核心抽象和模式

HOW（命令与工作流）：

构建命令
测试命令（单元测试、集成测试、端到端测试）
代码检查/格式化命令
运行/开发命令
部署模式

Step 2: Check Existing Documentation

步骤2：检查现有文档

Search for:

Existing README.md, CONTRIBUTING.md, docs/
Existing CLAUDE.md — if one exists, read it carefully and propose targeted edits rather than rewriting from scratch. Preserve what's already working.
Architecture decision records (ADRs)
Code conventions documentation

搜索以下内容：

现有的README.md、CONTRIBUTING.md、docs/目录
现有的CLAUDE.md——如果存在，请仔细阅读并提出针对性修改建议，而非从头重写。保留已生效的内容。
架构决策记录（ADRs）
代码规范文档

Step 3: Create Progressive Disclosure Structure

步骤3：创建渐进式披露结构

If complex docs are needed, create an

agent-docs/

directory at the repo root with focused files:

agent-docs/
├── architecture.md       # System design, component relationships
├── build-and-test.md     # How to build, test, verify changes
├── conventions.md        # Code patterns specific to this project
├── database.md           # Schema, migrations, data patterns
├── api-patterns.md       # API design, authentication, etc.
└── glossary.md           # User-specific vocabulary Claude can't infer

Only create files that add real value. Don't create empty templates.

如果需要复杂文档，请在仓库根目录创建

agent-docs/

目录，并添加针对性文件：

agent-docs/
├── architecture.md       # 系统设计、组件关系
├── build-and-test.md     # 构建、测试、验证变更的方法
├── conventions.md        # 项目特有的代码模式
├── database.md           # 数据库schema、迁移、数据模式
├── api-patterns.md       # API设计、身份验证等
└── glossary.md           # Claude无法推断的用户特定词汇表

仅创建具有实际价值的文件，不要创建空模板。

Step 4: Write the CLAUDE.md

步骤4：编写CLAUDE.md

Structure the file as:

markdown

undefined

文件结构如下：

markdown

undefined

Project Name

项目名称

[One sentence describing what this project is]

[一句话描述该项目的功能]

Quick Reference

快速参考

Build:
```
[command]
```
Test:
```
[command]
```
Lint:
```
[command]
```
Dev server:
```
[command]
```

构建:
```
[命令]
```
测试:
```
[命令]
```
代码检查:
```
[命令]
```
开发服务器:
```
[命令]
```

Non-Obvious Structure

非直观结构

[Don't list directories — Claude can discover those via tools] [Instead, document things that AREN'T discoverable from file names alone:] [- Generated code paths (so Claude doesn't edit them)] [- Monorepo package relationships and dependency direction] [- Naming conventions that imply behavior (e.g. *.server.ts = server-only)] [- Co-location patterns (e.g. each feature owns its routes/, models/, services/)]

[不要罗列目录——Claude可通过工具发现这些内容] [相反，记录无法从文件名直接看出的信息：] [- 生成代码的路径（避免Claude编辑这些文件）] [- 单仓包之间的关系及依赖方向] [- 隐含行为的命名规范（例如*.server.ts = 仅服务器端使用）] [- 代码共置模式（例如每个功能模块拥有自己的routes/、models/、services/目录）]

Key Patterns

核心模式

[2-3 critical patterns or conventions unique to this codebase] [Use file:line references, not code snippets]

[2-3个代码库特有的关键模式或规范] [使用file:line引用，而非代码片段]

Documentation

文档

```
agent-docs/architecture.md
```
- System design and component relationships
```
agent-docs/build-and-test.md
```
- Detailed build and test instructions [Only list files that exist]

```
agent-docs/architecture.md
```
- 系统设计与组件关系
```
agent-docs/build-and-test.md
```
- 详细的构建和测试说明 [仅列出已存在的文件]

Critical Rules

关键规则

[Only include rules that are UNIVERSALLY applicable across ALL tasks] [Max 5-10 rules] [If it can be enforced by a linter, don't include it here]

undefined

[仅包含适用于所有任务的通用规则] [最多5-10条规则] [如果可通过代码检查器强制执行，则不要在此处列出]

undefined

Step 5: Validate Against Checklist

步骤5：对照检查清单验证

Output

输出要求

First: Summarize what you discovered about the codebase
Second: Directly create or edit the
```
CLAUDE.md
```
file. If one exists, make targeted edits. If not, create it.
Third: Create any
```
agent-docs/
```
files that add real value
Fourth: List unresolved questions (e.g., "Is there a staging environment?")

首先：总结你对代码库的发现
其次：直接创建或编辑
```
CLAUDE.md
```
文件。如果已存在，请进行针对性修改；如果不存在，则创建新文件。
第三：创建任何具有实际价值的
```
agent-docs/
```
文件
第四：列出未解决的问题（例如：“是否存在预发布环境？”）

Important Notes

重要提示

If a CLAUDE.md already exists, default to targeted edits — don't rewrite from scratch. Only do a full replacement if the existing file is fundamentally broken.
Ask clarifying questions if the codebase purpose is unclear.
Don't guess at commands—verify they exist in package.json/Makefile/etc.
Don't include commands, skills, hooks, automations, or other discoverable/deterministic config. These belong in
```
.claude/commands/
```
,
```
.claude/skills/
```
,
```
.claude/settings.json
```
, and
```
.claude/automations/
```
— not CLAUDE.md.

如果CLAUDE.md已存在，优先进行针对性修改——不要从头重写。仅当现有文件存在根本性问题时，才进行完全替换。
如果代码库的用途不明确，请提出澄清问题。
不要猜测命令——需在package.json/Makefile等文件中验证其存在。
不要包含命令、技能、钩子、自动化或其他可发现/确定性配置。这些内容应放在
```
.claude/commands/
```
、
```
.claude/skills/
```
、
```
.claude/settings.json
```
和
```
.claude/automations/
```
中，而非CLAUDE.md。

Additional information provided by User

用户提供的额外信息

$ARGUMENTS