distill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

description: Rewrite repo CLAUDE.md into the best onboarding guide for this project

description: 将仓库的CLAUDE.md重写为该项目的最佳入职指南

DISTILL

提炼

Distill this repo's knowledge into a single, sharp

CLAUDE.md

将本仓库的知识浓缩为一份精准的

CLAUDE.md

文件。

Purpose

目标

Rewrite the current repository's
```
CLAUDE.md
```
into the best possible onboarding + operating guide for this project.
Output must let a new contributor start useful work in minutes, without asking questions.
Scope is this repo only; global philosophy lives in
```
~/.claude/CLAUDE.md
```
.

将当前仓库的
```
CLAUDE.md
```
重写为该项目的最佳入职+操作指南。
输出内容必须让新贡献者在几分钟内就能开展有意义的工作，无需提问。
范围仅限本仓库；全局理念请参考
```
~/.claude/CLAUDE.md
```
。

The Kill Test

淘汰测试

Every line in CLAUDE.md must survive three questions:

Discoverable? Would Claude figure this out from
```
ls
```
,
```
cat package.json
```
, or reading code? → DELETE
Surprising? Does this describe something counter-intuitive or unexpected? If not → DELETE
Earned by pain? Did this instruction come from something going wrong? → KEEP

Start with nothing. Wait for Claude to do something wrong. Write THAT down.

CLAUDE.md中的每一行都必须通过以下三个问题的检验：

可发现？ Claude能否通过
```
ls
```
、
```
cat package.json
```
或阅读代码得知这些信息？→ 删除
有意外性？ 内容是否描述了违反直觉或出乎意料的情况？如果没有→ 删除
源于痛点？ 这条指令是否是从出错的经历中总结出来的？→ 保留

从零开始。等Claude出错了，再把那个问题记录下来。

What to kill

需淘汰的内容

File trees (Claude can
```
ls
```
)
"This project uses React with TypeScript" (Claude can see tsconfig.json)
Architecture descriptions that restate what code shows
Technology stack versions (in package.json)
Module lists (in imports)
Development philosophy restating linter/type config
Sprint plans, roadmaps, marketing copy, performance metrics
Build system descriptions (in build config)
Testing framework choice (in test config)

文件目录树（Claude可以执行
```
ls
```
查看）
"本项目使用React和TypeScript"（Claude可以查看tsconfig.json）
重复代码所展示内容的架构描述
技术栈版本（在package.json中）
模块列表（在导入语句中）
重复代码检查/类型配置的开发理念
冲刺计划、路线图、营销文案、性能指标
构建系统描述（在构建配置中）
测试框架选择（在测试配置中）

What survives

需保留的内容

"Run
```
yarn test:unit
```
not
```
npm test
```
" — weird, not discoverable
"Don't touch src/legacy/ — three enterprise clients depend on it" — earned by pain
"The auth middleware is load-bearing, all of it, don't be a hero" — counter-intuitive
"DATABASE_URL not POSTGRES_URL — Prisma's Rust engine reads it before Node" — painful gotcha
"e2e tests can't run headless due to extension limitations" — surprising constraint

"执行
```
yarn test:unit
```
而非
```
npm test
```
" —— 不符合常规，无法直接发现
"不要修改src/legacy/ —— 有三个企业客户依赖该目录" —— 源于实际痛点
"认证中间件至关重要，所有代码都不能改动，别逞能" —— 违反直觉
"DATABASE_URL not POSTGRES_URL —— Prisma的Rust引擎会在Node启动前读取该变量" —— 令人头疼的陷阱
"e2e tests can't run headless due to extension limitations" —— 出乎意料的约束

Inputs

输入信息

Always read, if present:
- Repo
```
AGENTS.md
```
  .
- Existing repo
```
CLAUDE.md
```
  .
- Root
```
README
```
  and any high-signal docs in
```
docs/
```
  .
- Key config / entry files (e.g.
```
package.json
```
  ,
```
pyproject.toml
```
  ,
```
docker-compose.yml
```
  , main entrypoints).

若存在，务必阅读：
- 仓库中的
```
AGENTS.md
```
- 现有仓库的
```
CLAUDE.md
```
- 根目录的
```
README
```
  以及
```
docs/
```
  目录下的高价值文档
- 关键配置/入口文件（如
```
package.json
```
  、
```
pyproject.toml
```
  、
```
docker-compose.yml
```
  、主入口文件）

Target Shape for

CLAUDE.md

CLAUDE.md

的目标格式

markdown

undefined

markdown

undefined

CLAUDE

Purpose

目标

What this repo is and why it exists.

本仓库的定位与存在意义。

Architecture Map

架构概览

Main domains / services and how they fit.
Where to start reading code (file:line).

主要领域/服务及其关联方式。
代码阅读的起始位置（文件:行号）。

Run & Test

运行与测试

Commands to run app, tests, lint, typecheck.
Required env, secrets, or services.

运行应用、测试、代码检查、类型检查的命令。
所需的环境变量、密钥或服务。

Quality & Pitfalls

质量与陷阱

Definition of done, PR expectations, review norms.
Non-obvious invariants, footguns, "never do X".

完成标准、PR要求、评审规范。
非显而易见的不变规则、陷阱、"绝对不要做X"的警告。

References

参考资料

Key docs / ADRs / diagrams (paths).
External systems / dashboards / runbooks.

undefined

关键文档/架构决策记录(ADR)/图表（路径）。
外部系统/仪表盘/运行手册。

undefined

The Codex First-Draft Pattern

Codex初稿模式

Codex drafts the new CLAUDE.md. You review and refine.

bash

codex exec "DISTILL: Rewrite CLAUDE.md for this repo. Read README, ARCHITECTURE.md, docs/, and key code. Follow target shape below. Output to /tmp/claude-draft.md" \
  --output-last-message /tmp/codex-distill.md 2>/dev/null

Review Codex's draft. Refine for accuracy and compression.

由Codex生成新的CLAUDE.md初稿，你负责审核和优化。

bash

codex exec "DISTILL: Rewrite CLAUDE.md for this repo. Read README, ARCHITECTURE.md, docs/, and key code. Follow target shape below. Output to /tmp/claude-draft.md" \
  --output-last-message /tmp/codex-distill.md 2>/dev/null

审核Codex生成的初稿，优化内容的准确性和简洁性。

Algorithm

流程步骤

Gather (Codex does this)
- Read inputs; understand what the repo does, how it runs, and how it fits into the wider system.
Kill Test every line
- For each line, ask three questions:
  - Discoverable? Would Claude figure this out from
```
ls
```
    ,
```
cat package.json
```
    , or reading code? → DELETE
  - Surprising? Does this describe something counter-intuitive? If behavior is what you'd expect → DELETE
  - Earned by pain? Did this come from something going wrong? → KEEP
- Also classify:
  - General / global → belongs in
```
~/.claude/CLAUDE.md
```
    , do not restate here.
  - Marketing copy / roadmaps / sprint plans → DROP (not instructions)
Draft new
CLAUDE.md
(Codex produces first draft)
- Fill the target shape above with tight, repo-specific bullets.
- Prefer bullets over paragraphs; every line must earn its place.
- Link to existing docs instead of duplicating them.
Compress
- Apply the 3-2-1 test:
  - 3 key decisions or invariants newcomers must know.
  - 2 critical insights about architecture or workflow.
  - 1 clear starting point in the codebase.
- Rewrite soft prose into sharp, actionable lines.
Validate
- Run the checklist below.
- Only propose the new
```
CLAUDE.md
```
  once all checks pass.

收集信息（由Codex完成）
- 读取输入信息；理解仓库的功能、运行方式及其在更大系统中的定位。
逐行执行淘汰测试
- 对每一行内容，提出三个问题：
  - 可发现？ Claude能否通过
```
ls
```
    、
```
cat package.json
```
    或阅读代码得知这些信息？→ 删除
  - 有意外性？ 内容是否描述了违反直觉的情况？如果是预期内的行为→ 删除
  - 源于痛点？ 这条指令是否是从出错的经历中总结出来的？→ 保留
- 同时进行分类：
  - 通用/全局内容 → 属于
```
~/.claude/CLAUDE.md
```
    ，请勿在此重复。
  - 营销文案/路线图/冲刺计划 → 舍弃（不属于操作指令）
生成新的
CLAUDE.md
初稿（由Codex完成）
- 用简洁的、仓库专属的项目符号填充上述目标格式。
- 优先使用项目符号而非段落；每一行内容都必须有存在的价值。
- 链接到现有文档，而非重复内容。
压缩内容
- 应用3-2-1测试：
  - 3个新成员必须了解的关键决策或不变规则。
  - 2个关于架构或工作流程的核心见解。
  - 1个明确的代码库起始阅读点。
- 将模糊的描述改写为清晰、可执行的内容。
验证
- 执行下方的检查清单。
- 只有通过所有检查后，才提交新的
```
CLAUDE.md
```
  。

Checklist (must pass)

检查清单（必须全部通过）

Readable in ≤3 minutes; roughly ≤80 lines.
Every line fails the Kill Test (not discoverable from code/config/ls).
Run commands included (only if non-obvious — skip if standard
```
pnpm dev/test/build
```
).
Captures footguns, gotchas, and "don't touch X" warnings.
No file trees (Claude can
```
ls
```
).
No technology stack listings (Claude can read package.json).
No architecture descriptions that restate what code shows.
No marketing copy, roadmaps, or sprint plans.
Links to deeper docs / ADRs instead of copying them.
Does not restate global behavior or philosophy from
```
~/.claude/CLAUDE.md
```
.

阅读时间≤3分钟；内容约≤80行。
每一行内容都未通过淘汰测试（无法从代码/配置/ls命令中发现）。
包含运行命令（仅针对非标准命令——如果是标准的
```
pnpm dev/test/build
```
则可省略）。
记录了陷阱、易犯错误和"不要修改X"的警告。
无文件目录树（Claude可以执行
```
ls
```
查看）。
无技术栈列表（Claude可以读取package.json）。
无重复代码所展示内容的架构描述。
无营销文案、路线图或冲刺计划。
链接到更深层次的文档/ADR，而非复制内容。
未重复
```
~/.claude/CLAUDE.md
```
中的全局行为或理念。

Compression Examples

压缩示例

Kill (discoverable): "The project uses Turborepo with pnpm workspaces, Next.js 15, React 19, Tailwind CSS, and TypeScript strict mode." → Claude can read

package.json

and

tsconfig.json

Kill (not surprising): "Content scripts inject into web pages. Background scripts handle lifecycle. Core modules have specific responsibilities." → This is what every browser extension does.

Kill (file tree):

├── apps/web/       # Next.js app
├── packages/common/ # Shared types
└── turbo.json      # Turborepo config

→ Claude can

ls

Keep (earned by pain): "DATABASE_URL not POSTGRES_URL — Prisma's Rust engine reads it before Node.js starts. Runtime env modifications are too late in serverless."

Keep (surprising): "e2e tests can't run headless due to browser extension limitations."

Keep (load-bearing): "Don't touch src/legacy/ — three enterprise clients depend on it, and there are no tests."

淘汰（可发现）："本项目使用Turborepo、pnpm工作区、Next.js 15、React 19、Tailwind CSS和严格模式的TypeScript。" → Claude可以读取

package.json

和

tsconfig.json

。

淘汰（无意外性）："内容脚本注入到网页中。后台脚本处理生命周期。核心模块有特定的职责。" → 这是所有浏览器扩展的常规行为。

淘汰（文件目录树）：

├── apps/web/       # Next.js应用
├── packages/common/ # 共享类型
└── turbo.json      # Turborepo配置

→ Claude可以执行

ls

查看。

保留（源于痛点）："DATABASE_URL not POSTGRES_URL —— Prisma的Rust引擎会在Node.js启动前读取该变量。在无服务器环境中，运行时修改环境变量为时已晚。"

保留（有意外性）："e2e tests can't run headless due to browser extension limitations" —— 出乎意料的约束

保留（至关重要）："不要修改src/legacy/ —— 有三个企业客户依赖该目录，且该目录没有测试用例。"

Philosophy

理念

Maximum signal per word.
Document what is not obvious from code or README.
If you can't find 3 decisions, 2 insights, and 1 starting point, read more code before writing.

每一个字都要传递最大的信息量。
记录代码或README中未体现的非显而易见的内容。
如果找不到3个关键决策、2个核心见解和1个起始阅读点，请先阅读更多代码再开始编写。

Graduation Rules

升级规则

CLAUDE.md is a staging area for learnings. When sections grow, graduate them:

Patterns section > 10 lines → extract to a skill
Rules section > 5 items → extract to an agent
Workflow section > 3 steps → extract to a command

Keep CLAUDE.md lean. Knowledge graduates to executable artifacts.

CLAUDE.md是知识积累的临时区域。当内容增长到一定程度时，需进行升级：

模式部分超过10行 → 提炼为一个skill
规则部分超过5条 → 提炼为一个agent
工作流程部分超过3个步骤 → 提炼为一个命令

保持CLAUDE.md简洁。知识需升级为可执行的工件。

distill

Original

Translation

description: Rewrite repo CLAUDE.md into the best onboarding guide for this project

description: 将仓库的CLAUDE.md重写为该项目的最佳入职指南

DISTILL

提炼

Purpose

目标

The Kill Test

淘汰测试

What to kill

需淘汰的内容

What survives

需保留的内容

Inputs

输入信息

Target Shape for CLAUDE.md

CLAUDE.md的目标格式

CLAUDE

CLAUDE

Purpose

目标

Architecture Map

架构概览

Run & Test

运行与测试

Quality & Pitfalls

质量与陷阱

References

参考资料

The Codex First-Draft Pattern

Codex初稿模式

Algorithm

流程步骤

Checklist (must pass)

检查清单（必须全部通过）

Compression Examples

压缩示例

Philosophy

理念

Graduation Rules

升级规则

Target Shape for
`CLAUDE.md`

`CLAUDE.md`
的目标格式