review-structure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Review Structure

仓库结构审核

You are auditing the user's repo so that you (Claude) can navigate it cold and operate inside it effectively. The user is non-technical — they don't search this repo, you do. Every principle below comes from how your own search tools actually work.

你正在审核用户的仓库，以便你（Claude）能够直接导航并在其中高效操作。用户是非技术人员——他们不会搜索这个仓库，搜索的人是你。以下每一条原则都基于你自身搜索工具的实际工作机制。

How you search a repo

你如何搜索仓库

Internalize this before auditing — every principle downstream is a consequence of these mechanics.

Read
— load a known file by path. First move on entry: read root
```
CLAUDE.md
```
or
```
README.md
```
.
Glob
— pattern-match file paths. Case-sensitive, literal. e.g.
```
**/CLAUDE.md
```
,
```
clients/*/profile.md
```
.
Grep
— search file contents, usually scoped with
```
--glob
```
.
Bash: ls / find
— see directory shape, not content. e.g.
```
find . -type d -maxdepth 2
```
.
CLAUDE.md
auto-loading:
- Ancestor
```
CLAUDE.md
```
  files (root + dirs above cwd) load at session start.
- Subdirectory
```
CLAUDE.md
```
  files load lazily, only when you
  Read
  /
  Edit
  a file in that subtree. They do not fire on
```
Glob
```
  ,
```
Grep
```
  , or
```
ls
```
  .

The corollary: a subdirectory
CLAUDE.md
cannot rescue bad names. Naming carries navigation;

CLAUDE.md

only carries non-obvious context once you've already decided to open a file.

在开始审核前请先理解这些内容——后续的每一条原则都是这些机制的结果。

Read
— 通过路径加载已知文件。进入仓库后的第一步：读取根目录的
```
CLAUDE.md
```
或
```
README.md
```
。
Glob
— 模式匹配文件路径。区分大小写，完全字面匹配。例如：
```
**/CLAUDE.md
```
、
```
clients/*/profile.md
```
。
Grep
— 搜索文件内容，通常通过
```
--glob
```
限定范围。
Bash: ls / find
— 查看目录结构，不读取内容。例如：
```
find . -type d -maxdepth 2
```
。
CLAUDE.md
自动加载规则：
- 祖先目录的
```
CLAUDE.md
```
  文件（根目录+当前工作目录之上的目录）会在会话开始时加载。
- 子目录的
```
CLAUDE.md
```
  文件采用懒加载，仅当你在该子树中
```
Read
```
  /
```
Edit
```
  文件时才会加载。它们不会在
```
Glob
```
  、
```
Grep
```
  或
```
ls
```
  操作时触发加载。

推论：子目录的
CLAUDE.md
无法挽救糟糕的命名。命名是导航的核心；

CLAUDE.md

仅在你已经决定打开某个文件后，提供非显而易见的上下文信息。

Principles (the audit checklist)

审核原则（检查清单）

Self-describing names. A cold reader (you) should infer content from the path alone.
```
data/
```
says nothing;
```
sales/pipeline.csv
```
says everything. Naming is your primary navigation aid because Glob/Grep see paths, not CLAUDE.md.
Lowercase kebab-case —
```
acme-corp/
```
, not
```
Acme Corp/
```
or
```
AcmeCorp/
```
. This is mechanical, not aesthetic: spaces break shell commands, casing breaks Glob patterns.
Group by domain, not by file type. Folders are business areas (
```
sales/
```
,
```
clients/
```
,
```
operations/
```
), not file kinds (
```
templates/
```
,
```
data/
```
,
```
scripts/
```
). Domain grouping lets you ignore irrelevant subtrees entirely; file-type grouping forces you to load everything.
Sibling folders mirror each other's shape. If every client folder has
```
profile.md
```
,
```
contacts.md
```
,
```
updates.md
```
, then
```
Glob clients/*/profile.md
```
pulls all profiles in one call. If shapes vary, you have to
```
Read
```
each folder to discover what's there.
Shallow + wide over deep + narrow. Three levels (root → domain → leaf) is comfortable. Five-deep generic nesting (
```
stuff/items/things/2024/q1/
```
) gets lost.
Glossary for user-specific vocabulary. Keep an
```
agent-docs/glossary.md
```
file (in an
```
agent-docs/
```
directory at the repo root, alongside other progressive-disclosure docs like
```
architecture.md
```
,
```
conventions.md
```
, etc.) for terms specific to the user's world that Claude can't infer — internal client codenames, industry acronyms, custom workflow names ("V2 brief", "the rolodex"), team shorthand. The root
```
CLAUDE.md
```
must include this self-perpetuating rule:
"When the user uses a term you don't understand, check
agent-docs/glossary.md
first. If the term isn't there, ask the user to clarify, then add the definition there."
Why a separate file (not inline in
```
CLAUDE.md
```
): the glossary keeps growing as the user works; a dedicated file stays manageable and only loads when needed. Why the rule lives in root
```
CLAUDE.md
```
: that file auto-loads at session start, so Claude always knows where to check and how to maintain the glossary — even though the glossary itself is read lazily, only when an unfamiliar term appears. Why
```
agent-docs/
```
: the convention from the
```
claude-md
```
skill — all progressive-disclosure docs live there, keeping the root tidy.
Root
CLAUDE.md
always. It's the entry interface — what the repo is, how the domains connect, where to go for what.
Subdirectory
CLAUDE.md
: default is none. Only add one when the folder carries implicit context that names can't convey. Conditions that justify one:
- Behavioral rules that apply to every file in the subtree — e.g. brand voice in
```
marketing/
```
  , citation style in
```
research/
```
  . Auto-loading the rule means Claude can't forget it when editing files inside.
- Per-instance context that varies — e.g. each client folder has its own engagement history, contacts, recent decisions.
- Domain rules Claude can't infer from file names — pricing logic, pipeline stages, judgment calls, things-to-watch-for.
- Naming conventions that operate inside the folder — e.g. "files prefixed
```
draft-
```
  are not yet reviewed."
Skip when the folder's shape and names already explain themselves. An empty-restating
```
CLAUDE.md
```
is dead weight and trains Claude to skim past them.
No orphaned business content. Business files (proposals, client notes, pricing data, templates, scripts that operate on your data) belong inside a domain folder. Conventional root-level files —
```
README.md
```
,
```
CLAUDE.md
```
,
```
.gitignore
```
,
```
.env
```
,
```
package.json
```
,
```
pyproject.toml
```
,
```
LICENSE
```
, plus Claude-infrastructure dirs (
```
.claude/
```
,
```
agent-docs/
```
) and other hidden config dirs (
```
.github/
```
) — are expected at root and don't count as orphans.

自描述命名。初次接触的人（你）应该仅通过路径就能推断内容。
```
data/
```
毫无意义；
```
sales/pipeline.csv
```
则一目了然。命名是你主要的导航工具，因为Glob/Grep只能看到路径，看不到
```
CLAUDE.md
```
。
小写短横线命名法——
```
acme-corp/
```
，而非
```
Acme Corp/
```
或
```
AcmeCorp/
```
。这是出于技术原因而非美观：空格会破坏shell命令，大小写会导致Glob模式失效。
按业务领域分组，而非文件类型。文件夹对应业务领域（
```
sales/
```
、
```
clients/
```
、
```
operations/
```
），而非文件种类（
```
templates/
```
、
```
data/
```
、
```
scripts/
```
）。按领域分组让你可以完全忽略不相关的子树；按文件类型分组则迫使你加载所有内容。
同级文件夹结构保持一致。如果每个客户文件夹都包含
```
profile.md
```
、
```
contacts.md
```
、
```
updates.md
```
，那么
```
Glob clients/*/profile.md
```
可以一次性获取所有客户资料。如果结构不一致，你就必须逐个
```
Read
```
文件夹来发现其中的内容。
宁浅勿深，宁宽勿窄。三级目录结构（根目录 → 业务领域 → 叶子文件）是比较舒适的。五级通用嵌套（
```
stuff/items/things/2024/q1/
```
）会导致内容难以查找。
用户特定词汇术语表。在仓库根目录的
```
agent-docs/
```
目录下保留一个
```
agent-docs/glossary.md
```
文件（与
```
architecture.md
```
、
```
conventions.md
```
等渐进式披露文档放在一起），用于存放Claude无法推断的用户特定术语——内部客户代号、行业缩写、自定义工作流名称（如“V2 brief”、“the rolodex”）、团队简写。根目录的
```
CLAUDE.md
```
必须包含这条自维护规则：
“当用户使用你不理解的术语时，先查看
agent-docs/glossary.md
。如果术语不在其中，请询问用户澄清，然后将定义添加到该文件中。”
为什么使用单独文件（而非内联在
```
CLAUDE.md
```
中）：术语表会随着用户的使用不断增长；专用文件更易于管理，且仅在需要时才会加载。为什么规则放在根目录
```
CLAUDE.md
```
中：该文件会在会话开始时自动加载，因此Claude始终知道去哪里查询以及如何维护术语表——尽管术语表本身是懒加载的，仅当出现不熟悉的术语时才会读取。为什么放在
```
agent-docs/
```
中：这是
```
claude-md
```
技能的约定——所有渐进式披露文档都放在这里，保持根目录整洁。
必须有根目录
CLAUDE.md
。它是入口界面——说明仓库是什么、各业务领域如何关联、不同内容的存放位置。
子目录
CLAUDE.md
：默认不添加。仅当文件夹包含无法通过名称传达的隐含上下文时才添加。符合以下条件时才需要添加：
- 适用于子树中所有文件的行为规则——例如
```
marketing/
```
  中的品牌语气、
```
research/
```
  中的引用格式。自动加载规则意味着Claude在编辑该子树内的文件时不会忘记这些规则。
- 每个实例各不相同的上下文信息——例如每个客户文件夹都有自己的合作历史、联系人、近期决策。
- Claude无法从文件名推断的领域规则——定价逻辑、销售流程阶段、判断标准、需要注意的事项。
- 文件夹内部的命名约定——例如“以
```
draft-
```
  为前缀的文件尚未审核”。
如果文件夹的结构和名称已经能清晰说明内容，则无需添加。重复说明内容的
```
CLAUDE.md
```
是无用的，会让Claude养成跳过它们的习惯。
无孤立业务内容。业务文件（提案、客户笔记、定价数据、模板、处理数据的脚本）应放在对应的业务领域文件夹中。常规的根目录文件——
```
README.md
```
、
```
CLAUDE.md
```
、
```
.gitignore
```
、
```
.env
```
、
```
package.json
```
、
```
pyproject.toml
```
、
```
LICENSE
```
，以及Claude基础设施目录（
```
.claude/
```
、
```
agent-docs/
```
）和其他隐藏配置目录（
```
.github/
```
）——属于根目录的预期文件，不算孤立内容。

Teaching example

教学示例

The same business, organized two ways:

Wrong — grouped by file type:

my-business/
├── CLAUDE.md
├── templates/
│   ├── proposal-template.md
│   ├── invoice-template.md
│   └── campaign-brief.md
├── data/
│   ├── client-list.csv
│   └── pipeline.csv
├── docs/
│   ├── sales-process.md
│   ├── brand-guidelines.md
│   └── pricing.md
└── scripts/
    ├── generate-invoice.py
    └── send-proposal.py

Asked to "draft a proposal for Acme Corp," you have to hunt across

templates/

docs/

data/

, and

scripts/

and load it all to figure out what's relevant. No domain boundaries. No place to put domain context that auto-loads when you open a sales file.

Right — grouped by domain:

Note: not every folder needs a

CLAUDE.md

— only the ones with implicit context that names can't carry (see Principle 8). Folders whose shape and names speak for themselves get none.

my-business/
├── CLAUDE.md                  ← what this repo is, how domains connect; rule: ask + add to agent-docs/glossary.md
├── agent-docs/
│   └── glossary.md            ← user-specific vocab, grows over time, read lazily
├── sales/
│   ├── CLAUDE.md              ← pricing rules, pipeline stages (domain rules Claude can't infer)
│   ├── templates/
│   ├── pipeline.csv
│   └── scripts/
├── clients/                   ← no CLAUDE.md: every client folder mirrors the same shape, Glob discovers it
│   ├── acme-corp/
│   │   ├── CLAUDE.md          ← per-client engagement context, contacts (varies per instance)
│   │   ├── profile.md
│   │   ├── contacts.md
│   │   └── updates.md
│   └── beta-inc/
│       ├── CLAUDE.md
│       ├── profile.md
│       ├── contacts.md
│       └── updates.md
├── operations/                ← no CLAUDE.md: `sops/` and `templates/` are self-explanatory
│   ├── sops/
│   └── templates/
└── marketing/
    ├── CLAUDE.md              ← brand voice (behavioral rule that applies to every file written here)
    ├── brand-voice.md
    └── templates/

Same task: read root

CLAUDE.md

→

sales/CLAUDE.md

→

clients/acme-corp/CLAUDE.md

. You never touch

operations/

marketing/

. Each domain

CLAUDE.md

auto-loads when you open files in its subtree, so domain rules ride along with the work — and folders without one stay out of the way.

同一业务的两种组织方式：

错误示例——按文件类型分组：

my-business/
├── CLAUDE.md
├── templates/
│   ├── proposal-template.md
│   ├── invoice-template.md
│   └── campaign-brief.md
├── data/
│   ├── client-list.csv
│   └── pipeline.csv
├── docs/
│   ├── sales-process.md
│   ├── brand-guidelines.md
│   └── pricing.md
└── scripts/
    ├── generate-invoice.py
    └── send-proposal.py

当要求“为Acme Corp起草一份提案”时，你需要在

templates/

、

docs/

、

data/

和

scripts/

中查找，并加载所有内容才能确定哪些是相关的。没有业务领域边界，也没有地方存放能在打开销售文件时自动加载的领域上下文。

正确示例——按业务领域分组：

注意：并非每个文件夹都需要

CLAUDE.md

——仅当存在无法通过名称传达的隐含上下文时才需要（参见原则8）。结构和名称已能清晰说明内容的文件夹无需添加。

my-business/
├── CLAUDE.md                  ← 说明仓库用途、业务领域关联；规则：询问并添加到agent-docs/glossary.md
├── agent-docs/
│   └── glossary.md            ← 用户特定词汇，随时间增长，懒加载
├── sales/
│   ├── CLAUDE.md              ← 定价规则、销售流程阶段（Claude无法推断的领域规则）
│   ├── templates/
│   ├── pipeline.csv
│   └── scripts/
├── clients/                   ← 无需CLAUDE.md：每个客户文件夹结构一致，可通过Glob发现
│   ├── acme-corp/
│   │   ├── CLAUDE.md          ← 客户专属合作上下文、联系人（每个实例各不相同）
│   │   ├── profile.md
│   │   ├── contacts.md
│   │   └── updates.md
│   └── beta-inc/
│       ├── CLAUDE.md
│       ├── profile.md
│       ├── contacts.md
│       └── updates.md
├── operations/                ← 无需CLAUDE.md：`sops/`和`templates/`含义明确
│   ├── sops/
│   └── templates/
└── marketing/
    ├── CLAUDE.md              ← 品牌语气（适用于该文件夹内所有文件的行为规则）
    ├── brand-voice.md
    └── templates/

同样的任务：读取根目录

CLAUDE.md

→

sales/CLAUDE.md

→

clients/acme-corp/CLAUDE.md

。你完全不需要接触

operations/

或

marketing/

。每个业务领域的

CLAUDE.md

会在你打开该子树内的文件时自动加载，因此领域规则会伴随工作过程——而不需要

CLAUDE.md

的文件夹则不会干扰你。

Workflow

工作流程

Map the repo.

bash

ls
find . -type d -maxdepth 3 -not -path '*/.*' -not -path '*/node_modules/*'

Then

Glob **/CLAUDE.md

and

Read

the root

CLAUDE.md

Clarify before auditing — one question at a time. After mapping, you'll have inferences but also gaps. Fill them through
```
AskUserQuestion
```
. Ask one question, propose a recommended answer with a one-line reason, wait for the response before asking the next. Each answer informs the next question — never batch. The user is non-technical; foreign-looking folder names may be meaningful domain terms to them, and only they can tell you which.
Common questions to walk in this order (skip any that are already obvious from the repo):
1. Domain confirmation — "I see [list]. Are these your main business areas?" Recommend the inferred list with a one-line reason; let user correct, add, or merge.
2. Ambiguous folders — for any folder whose purpose isn't clear from the name, ask what lives in it and whether it belongs inside one of the confirmed domains.
3. Sibling-shape intent — when sibling folders look inconsistent (e.g. some clients have
```
profile.md
```
  , others don't), ask whether they should mirror each other or whether the variation is intentional.
4. CLAUDE.md
  necessity — for any subdirectory
```
CLAUDE.md
```
  that just restates what names already say, ask whether there's implicit context worth keeping or whether it can be removed.
5. Glossary check — list any terms you spotted in the repo or in the user's recent prompts that look user-specific and aren't in
```
agent-docs/glossary.md
```
  . Ask: "Are these worth adding so a future session can look them up when they appear?" Recommend adding the obvious ones; let user accept, edit, or skip.
Stop asking once you have what you need to audit confidently. Don't over-interview.
Audit against the principles. Walk the checklist. Note what's working and what isn't. Flag specifically:
- Folders grouped by file type (templates/, docs/, data/, scripts/ at root)
- Names with spaces, capitals, or that don't describe content
- Sibling folders with inconsistent shapes
- Subdirectory
```
CLAUDE.md
```
  files that don't meet any of Principle 8's four conditions (dead weight — restates what names already say)
- Domain folders missing a
```
CLAUDE.md
```
  where Principle 8's conditions clearly apply (e.g. behavioral rules like brand voice, per-instance context that varies)
- Missing
```
agent-docs/glossary.md
```
  , or root
```
CLAUDE.md
```
  doesn't include the "ask + add to glossary" rule
- Loose business content at the root (not config/metadata files like
```
.gitignore
```
  ,
```
package.json
```
  , etc.)
- Generic nesting more than 3 levels deep
Produce the report (template below). Include a proposed before/after tree and a plain-English list of changes — no shell commands, the user is non-technical.
Wait for explicit user confirmation before any file moves. Even if the user invoked the skill, do not move files until they approve the specific plan. Then execute the moves yourself (you know the commands) and re-run step 1 to confirm.

映射仓库结构。

bash

ls
find . -type d -maxdepth 3 -not -path '*/.*' -not -path '*/node_modules/*'

然后使用

Glob **/CLAUDE.md

并

Read

根目录的

CLAUDE.md

。

审核前澄清——一次一个问题。完成映射后，你会有一些推断但也存在疑问。通过
```
AskUserQuestion
```
来填补这些空白。每次只问一个问题，给出推荐答案并附上一行理由，等待回复后再问下一个。每个答案会影响下一个问题——切勿批量提问。用户是非技术人员，对你来说陌生的文件夹名称可能对他们来说是有意义的业务术语，只有他们能告诉你具体含义。
通常按以下顺序提问（跳过从仓库中已能明确的问题）：
1. 业务领域确认——“我看到[列表]。这些是你的主要业务领域吗？”给出推断的列表并附上一行理由；让用户纠正、添加或合并。
2. 模糊文件夹澄清——对于任何名称无法明确其用途的文件夹，询问其中存放的内容以及是否属于已确认的某个业务领域。
3. 同级结构一致性意图——当同级文件夹结构不一致时（例如部分客户文件夹有
```
profile.md
```
  ，其他没有），询问是否应该保持结构一致，或者这种差异是有意为之。
4. CLAUDE.md
  必要性确认——对于任何仅重复说明名称已有内容的子目录
```
CLAUDE.md
```
  ，询问是否存在值得保留的隐含上下文，或者是否可以删除。
5. 术语表检查——列出你在仓库或用户近期提示中发现的、看起来是用户特定且未在
```
agent-docs/glossary.md
```
  中出现的术语。询问：“这些术语是否值得添加，以便未来会话中出现时可以查询？”建议添加明显需要的术语；让用户接受、编辑或跳过。
一旦你获得足够信息可以自信地进行审核，就停止提问。不要过度询问。
对照原则审核。逐条检查清单。记录哪些部分运行良好，哪些存在问题。特别标记：
- 按文件类型分组的文件夹（根目录的
```
templates/
```
  、
```
docs/
```
  、
```
data/
```
  、
```
scripts/
```
  ）
- 包含空格、大写字母或无法描述内容的名称
- 结构不一致的同级文件夹
- 不符合原则8中四个条件的子目录
```
CLAUDE.md
```
  文件（无用内容——仅重复说明名称已有内容）
- 明显符合原则8条件但缺少
```
CLAUDE.md
```
  的业务领域文件夹（例如品牌语气等行为规则、每个实例各不相同的上下文信息）
- 缺少
```
agent-docs/glossary.md
```
  ，或根目录
```
CLAUDE.md
```
  未包含“询问并添加到术语表”的规则
- 根目录下的孤立业务内容（不是
```
.gitignore
```
  、
```
package.json
```
  等配置/元数据文件）
- 超过3级的通用嵌套目录
生成报告（模板如下）。包含当前/预期结构的对比树状图，以及用通俗易懂的语言列出的更改内容——不要使用shell命令，用户是非技术人员。
等待用户明确确认后再移动文件。即使用户触发了该技能，在他们批准具体计划前也不要移动文件。获得批准后，由你执行移动操作（你知道对应的命令），然后重新执行步骤1以确认结构正确。

Output template

输出模板

undefined

undefined

Structure Audit

结构审核报告

What's working

运行良好的部分

[Concrete patterns to keep]

[值得保留的具体模式]

Issues

问题

Critical (blocks navigation):

[Issue] — at
```
path/
```
— [what to do]

Warning (slows navigation):

[Issue] — at
```
path/
```
— [what to do]

Suggestion (polish):

[Issue] — at
```
path/
```
— [what to do]

严重问题（阻碍导航）：

[问题描述] — 位于
```
path/
```
— [解决方法]

警告（降低导航效率）：

[问题描述] — 位于
```
path/
```
— [解决方法]

建议（优化改进）：

[问题描述] — 位于
```
path/
```
— [解决方法]

Proposed structure

建议结构

Before: [ASCII tree of current shape]

After: [ASCII tree of proposed shape]

当前结构： [当前结构的ASCII树状图]

预期结构： [预期结构的ASCII树状图]

Changes I'll make

我将执行的更改

Rename
```
clients/Acme Corp
```
→
```
clients/acme-corp
```
(lowercase, no spaces — so my Glob/Grep tools can find it)

Move

templates/proposal-template.md

into

sales/templates/

(group by domain, not file type)

Remove
```
operations/CLAUDE.md
```
— its content just restates what the folder names already say

Confirm to execute? (yes / skip specific numbers / edit)

undefined

将
```
clients/Acme Corp
```
重命名为
```
clients/acme-corp
```
（小写、无空格——以便我的Glob/Grep工具可以找到它）
将
```
templates/proposal-template.md
```
移动到
```
sales/templates/
```
（按业务领域分组，而非文件类型）
删除
```
operations/CLAUDE.md
```
——其内容仅重复说明文件夹名称已有信息

是否确认执行？（是 / 跳过特定编号 / 修改）

undefined

When everything is good

当一切正常时

If the audit finds no issues, say so plainly:

undefined

如果审核未发现任何问题，直接说明：

undefined

Structure Audit

结构审核报告

Your repo is agent-navigable.

Domains are clear: [list inferred domains]
Names are self-describing and lowercase kebab-case
Sibling folders mirror each other's shape
CLAUDE.md placement matches where implicit context exists
```
agent-docs/glossary.md
```
exists and
```
CLAUDE.md
```
includes the ask-and-add rule
Nesting stays within 3 levels

No changes needed.

undefined

你的仓库具备Agent可导航性。

业务领域清晰：[推断的业务领域列表]
名称具有自描述性且采用小写短横线命名法
同级文件夹结构一致
```
CLAUDE.md
```
的放置符合隐含上下文的存在情况
```
agent-docs/glossary.md
```
已存在，且
```
CLAUDE.md
```
包含询问并添加术语的规则
嵌套目录不超过3级

无需进行任何更改。

undefined