Back to Details

create-or-audit-claude-md

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create or audit a CLAUDE.md

创建或审核CLAUDE.md

Two modes, same skill: Mode 1 writes a new 
CLAUDE.md
by reading the codebase and distilling ambient context an agent needs. Mode 2 audits an existing one against the quality gates.
同一技能包含两种模式：模式1通过读取代码库并提炼Agent所需的环境上下文来编写新的
CLAUDE.md
。模式2根据质量标准审核现有的
CLAUDE.md
。

Before You Start

开始之前

  • principles/02-dense-not-brief.md
    — the rule that drives 
    CLAUDE.md
    length. Load-bearing, not pad.
  • skills/meta/create-or-audit-claude-md/templates/CLAUDE.md
    — the annotated root skeleton with required sections.
  • skills/meta/create-or-audit-claude-md/templates/CLAUDE.subdir.md
    — the subdir skeleton + the four trigger criteria.
  • skills/meta/create-or-audit-claude-md/lib/validate.sh
    — the mechanical gate.
  • principles/02-dense-not-brief.md
    — 决定
    CLAUDE.md
    篇幅的规则。内容需核心有用，而非冗余填充。
  • skills/meta/create-or-audit-claude-md/templates/CLAUDE.md
    — 带注释的基础框架模板，包含必填章节。
  • skills/meta/create-or-audit-claude-md/templates/CLAUDE.subdir.md
    — 子目录框架模板 + 四个触发条件。
  • skills/meta/create-or-audit-claude-md/lib/validate.sh
    — 自动化校验工具。

Mode 1 — create a CLAUDE.md

模式1 — 创建CLAUDE.md

Step 1: discover the codebase

步骤1：探索代码库

bash
undefined
bash
undefined

Top-level shape

Top-level shape

ls -la find . -maxdepth 2 -type d -not -path '/node_modules' -not -path '/.git'
ls -la find . -maxdepth 2 -type d -not -path '/node_modules' -not -path '/.git'

Build/test/lint commands (look in all the usual places)

Build/test/lint commands (look in all the usual places)

cat package.json 2>/dev/null | jq '.scripts // {}' cat pyproject.toml 2>/dev/null | grep -A 20 '[tool.' | head -40 cat Makefile 2>/dev/null | grep -E '^[a-zA-Z_-]+:' cat justfile .justfile 2>/dev/null ls .github/workflows/ 2>/dev/null
cat package.json 2>/dev/null | jq '.scripts // {}' cat pyproject.toml 2>/dev/null | grep -A 20 '[tool.' | head -40 cat Makefile 2>/dev/null | grep -E '^[a-zA-Z_-]+:' cat justfile .justfile 2>/dev/null ls .github/workflows/ 2>/dev/null

Entry points

Entry points

git log --pretty=format: --name-only -200 | sort | uniq -c | sort -rn | head -30
undefined
git log --pretty=format: --name-only -200 | sort | uniq -c | sort -rn | head -30
undefined

Step 2: identify subsystems

步骤2：识别子系统

Look at the top-level source tree. For each major directory (likely candidates: 
src/
, 
apps/
, 
packages/
, 
services/
, 
lib/
), ask:
  • What does it own?
  • How does it communicate with siblings?
  • What language/framework does it use?
查看顶级源码目录。针对每个主要目录（典型候选：
src/
、
apps/
、
packages/
、
services/
、
lib/
），思考：
  • 它负责什么功能？
  • 它如何与其他子系统交互？
  • 使用了哪种语言/框架？

Step 3: extract the "things to know"

步骤3：提炼“必备知识”

The most valuable section of a 
CLAUDE.md
. These are the hidden invariants and gotchas — the things not obvious from the code but known by every veteran.
Mine them from:
bash
undefined
这是
CLAUDE.md
中最有价值的章节。内容包括隐藏的约束条件和常见陷阱——这些信息无法从代码中直接看出，但每个资深开发者都知晓。
可通过以下方式收集：
bash
undefined

Recent bug fixes reveal invariants

Recent bug fixes reveal invariants

git log --oneline --all | grep -iE 'fix|bug' | head -30
git log --oneline --all | grep -iE 'fix|bug' | head -30

ADRs if they exist

ADRs if they exist

ls docs/adr docs/decisions docs/arc42/decisions 2>/dev/null
ls docs/adr docs/decisions docs/arc42/decisions 2>/dev/null

"Do not edit this" and "DANGER" comments in the code

"Do not edit this" and "DANGER" comments in the code

grep -rniE 'DO NOT|DANGER|CAREFUL|WARNING|HACK|FIXME|TODO' --include='.py' --include='.ts' --include='.js' --include='.go' --include='*.rs' | head -30
undefined
grep -rniE 'DO NOT|DANGER|CAREFUL|WARNING|HACK|FIXME|TODO' --include='.py' --include='.ts' --include='.js' --include='.go' --include='*.rs' | head -30
undefined

Step 4: write the file using 
root.md.template

步骤4：使用
root.md.template
编写文件

Copy 
skills/meta/create-or-audit-claude-md/templates/CLAUDE.md
and fill in every section. Keep the section order from the template — agents rely on it.
Special discipline for each section:
  • Quick Reference — real commands that actually run. If 
    pnpm test
    doesn't exist, don't list it.
  • Architecture — the longest section. 2–3 paragraphs overview + directory tree + per-subsystem deep-dives.
  • Patterns and Conventions — only things a linter doesn't catch (principle 03).
  • Things to Know — gotchas with structure: what happens → why → what to do. These are pure value for the agent.
  • Security-Critical Areas — a short, honest list. Lying here will erode trust.
复制
skills/meta/create-or-audit-claude-md/templates/CLAUDE.md
并填充所有章节。保持模板中的章节顺序——Agent依赖该顺序读取信息。
各章节编写规范：
  • 快速参考 — 列出实际可运行的命令。如果
    pnpm test
    不存在，请勿列出。
  • 架构 — 篇幅最长的章节。2-3段概述 + 目录树 + 每个子系统的详细说明。
  • 模式与约定 — 仅记录代码检查工具无法捕获的内容（原则03）。
  • 必备知识 — 陷阱需按以下结构描述：现象 → 原因 → 解决方案。这对Agent来说是核心价值。
  • 安全关键区域 — 简短、真实的列表。此处不实会破坏信任。

Step 5: create subdirectory CLAUDE.md files

步骤5：创建子目录CLAUDE.md文件

A subdirectory gets its own 
CLAUDE.md
when ANY of the four criteria holds (
skills/meta/create-or-audit-claude-md/SKILL.md
enumerates them): different language/framework, 3+ divergent patterns, own build commands, 10+ files with distinct conventions.
Each must be self-contained — a developer working in that directory should not need to flip back to root.
当满足以下四个条件中的任意一个时，子目录需要单独的
CLAUDE.md
（
skills/meta/create-or-audit-claude-md/SKILL.md
列出了具体条件）：使用不同语言/框架、存在3种以上差异化模式、拥有独立构建命令、包含10个以上遵循独特约定的文件。
每个子目录的
CLAUDE.md
必须独立完整——在该目录工作的开发者无需返回根目录查看文档。

Mode 2 — audit an existing CLAUDE.md

模式2 — 审核现有CLAUDE.md

Step 1: run the validator

步骤1：运行校验工具

bash
bash skills/meta/create-or-audit-claude-md/lib/validate.sh CLAUDE.md
Fix errors before continuing.
bash
bash skills/meta/create-or-audit-claude-md/lib/validate.sh CLAUDE.md
在继续下一步前修复所有错误。

Step 2: five quality gates

步骤2：五项质量标准

Gate 1 — density. Is every line load-bearing? Cut transitional prose ("In summary...", "As mentioned above..."), cut sections that have shrunk to a single sentence.
Gate 2 — evidence. Every declarative statement cites a file or a command. Run:
bash
grep -oE '`[a-zA-Z_./-]+/[a-zA-Z_.-]+`' CLAUDE.md | sort -u | while read p; do
  path=$(echo "$p" | tr -d '`')
  [ ! -e "$path" ] && echo "STALE: $p"
done
Gate 3 — duplication. Scan for rules already enforced by tooling (linter rules, formatter rules, CI checks). Remove them; point at the tool instead.
Gate 4 — alternatives. Every prohibition (
never
, 
don't
, 
do not
) must have a nearby alternative (
instead
, 
use X instead
, 
prefer
). Validator enforces.
Gate 5 — Things to Know. This section's presence is a strong signal the 
CLAUDE.md
has earned its keep. If it's empty or trivial, interview the team: "What's the most surprising thing about this codebase?"
标准1 — 内容密度。每一行是否都有核心价值？删除过渡性文字（如“综上所述...”、“如前所述...”），删除已缩减为单句的章节。
标准2 — 依据充分。每个陈述性内容都需引用文件或命令。运行以下命令：
bash
grep -oE '`[a-zA-Z_./-]+/[a-zA-Z_.-]+`' CLAUDE.md | sort -u | while read p; do
  path=$(echo "$p" | tr -d '`')
  [ ! -e "$path" ] && echo "STALE: $p"
done
标准3 — 无重复。检查是否存在已由工具（代码检查规则、格式化规则、CI检查）强制执行的规则。删除这些内容，改为指向对应工具。
标准4 — 替代方案。每个禁止性表述（
never
、
don't
、
do not
）必须附带附近的替代方案（
instead
、
请改用X
、
推荐
）。校验工具会强制要求这一点。
标准5 — 必备知识。该章节的存在是
CLAUDE.md
具备价值的重要标志。如果该章节为空或内容无关紧要，请询问团队：“这个代码库最令人意外的地方是什么？”

Step 3: report

步骤3：生成审核报告

markdown
undefined
markdown
undefined

CLAUDE.md Audit: {path}

CLAUDE.md审核报告: {path}

Verdict: APPROVE | REVISE | REJECT

结论: 通过 | 需要修订 | 拒绝

Gate results

质量标准检查结果

...
...

Stale references (must fix)

失效引用（必须修复）

{List of paths that no longer exist}
{不再存在的路径列表}

Duplicated tooling rules (remove these — point at the tool)

重复的工具规则（删除这些内容，改为指向工具）

...
...

Missing sections

缺失章节

...
...

Proposed additions to "Things to Know"

“必备知识”章节建议补充内容

{From your discovery in step 2}
undefined
{来自步骤2的发现}
undefined

Verify

验证

bash
undefined
bash
undefined

Validator passes

Validator passes

bash skills/meta/create-or-audit-claude-md/lib/validate.sh CLAUDE.md
bash skills/meta/create-or-audit-claude-md/lib/validate.sh CLAUDE.md

Expected: VERDICT: PASS

Expected: VERDICT: PASS

No stale file references

No stale file references

grep -oE '
[a-zA-Z_./-]+/[a-zA-Z_.-]+
' CLAUDE.md | tr -d '`' | while read p; do [ ! -e "$p" ] && echo "STALE: $p" done
grep -oE '
[a-zA-Z_./-]+/[a-zA-Z_.-]+
' CLAUDE.md | tr -d '`' | while read p; do [ ! -e "$p" ] && echo "STALE: $p" done

Expected: empty output

Expected: empty output

undefined
undefined

Common Mistakes

常见错误

MistakeCorrection
Padding to reach a line countDense, not bulky. A 150-line file with every line load-bearing beats a 400-line mix.
Embedding a 30-line code snippetReference the file (principle 04): 
`src/api/routes.ts` — see this for the pattern.
Restating every linter rulePoint at the tool (
.eslintrc.json
, 
ruff.toml
) and document only the non-obvious rules.
"Don't use 
x
" with no alternative		Pair with "Use 
y
instead, defined in 
src/lib/y.ts
." Validator errors without this.
错误修正方案
为达到行数要求填充冗余内容内容需精炼而非冗长。每行都有核心价值的150行文件优于400行的冗余文件。
嵌入30行代码片段引用文件（原则04）：
`src/api/routes.ts` — 相关模式请查看此文件。
重复列出所有代码检查规则指向对应工具（
.eslintrc.json
、
ruff.toml
），仅记录非显而易见的规则。
只说“不要使用
x
”而不提供替代方案		搭配说明“请改用
y
，定义于
src/lib/y.ts
”。校验工具会因缺少替代方案报错。

What doesn't belong in CLAUDE.md

CLAUDE.md不应包含的内容

  • Rules already enforced by tooling. If ESLint catches it, don't restate it (principle 03).
  • Temporary state. Current sprint goals, "in-progress" features. That's issue-tracker territory.
  • Long tutorials. If a walkthrough is >20 lines, it's a skill, not ambient context.
  • Embedded code snippets over 10 lines. They rot. Reference the file instead (principle 04).
  • 已由工具强制执行的规则。如果ESLint能捕获该问题，无需重复记录（原则03）。
  • 临时状态。当前冲刺目标、“开发中”的功能。这些内容属于问题跟踪工具的范畴。
  • 长篇教程。如果操作指南超过20行，应作为独立技能，而非环境上下文。
  • 超过10行的嵌入代码片段。这类内容容易过时。请改为引用文件（原则04）。