update-claudemd

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Update and Optimize CLAUDE.md

更新与优化CLAUDE.md

Reconcile project CLAUDE.md and its topic files against codebase reality and git history since each file's last commit. Enforce progressive disclosure: CLAUDE.md is a top-level index of project identity, universal invariants, and pointers to topic files at

.claude/rules/*.md

Reconciliation scope includes every file in

.claude/rules/

. Topic files are first-class content — they share the same staleness, accuracy, and duplication risks as CLAUDE.md itself and must be audited, reconciled, and (when warranted) edited during every run. They are not appendices.

Scope boundary: project CLAUDE.md (L1) and its topic files only. User-global

~/.claude/CLAUDE.md

(L0) is out of scope unless the user explicitly asks.

使项目的CLAUDE.md及其主题文件与代码库实际情况以及每个文件上次提交后的git历史保持一致。遵循渐进式披露（progressive disclosure）原则：CLAUDE.md是项目标识、通用不变量以及指向

.claude/rules/*.md

路径下主题文件的顶级索引。

一致性校验范围包含

.claude/rules/

下的所有文件。主题文件属于一等内容——它们和CLAUDE.md一样存在过时、不准确和重复的风险，每次运行时都必须经过审计、校验，并在必要时进行编辑。它们不是附录。

范围边界：仅包含项目级CLAUDE.md（L1）及其主题文件。用户全局的

~/.claude/CLAUDE.md

（L0）不在范围内，除非用户明确要求。

Governing Principle

指导原则

Content in CLAUDE.md is justified only if it changes how Claude acts in the next session AND is needed across most tasks — not subsystem-specific. Subsystem-scoped content still matters but belongs in a topic file, loaded on demand.

Content in a topic file is justified only if it changes how Claude acts within its subsystem AND is accurate against current codebase reality. Stale topic files are worse than missing ones because Claude trusts them.

Phase 3 operationalizes this principle with a seven-action set that lets content flow both downward (demote from CLAUDE.md to a topic file) and upward (promote from a topic file back to CLAUDE.md when a detail becomes universal). The goal is a living progressive-disclosure hierarchy, not a one-way archive.

CLAUDE.md中的内容只有在同时满足以下两个条件时才合理：一是会改变Claude在下一会话中的行为方式，二是大多数任务都需要该内容——而非仅针对子系统。子系统范围的内容同样重要，但应放在主题文件中，按需加载。

主题文件中的内容只有在同时满足以下两个条件时才合理：一是会改变Claude在对应子系统中的行为方式，二是与当前代码库实际情况一致。过时的主题文件比缺失的主题文件更糟，因为Claude会信任它们。

阶段3通过一套七项操作将此原则落地，支持内容双向流动：从CLAUDE.md降级到主题文件，以及当某个细节成为通用内容时从主题文件升级回CLAUDE.md。目标是构建一个动态的渐进式披露层级，而非单向归档。

Budget

篇幅预算

CLAUDE.md: soft target ~120 lines, soft ceiling 150 lines. Over-budget files are flagged, not forced — hand-maintained CLAUDE.md is respected. Line counts measured with

wc -l

Topic files: informational soft ceiling ~300 lines each. Topic files legitimately grow as their subsystem grows; past ~300 lines, flag the overage in Phase 7 and suggest splitting by sub-topic. Never block. The CLAUDE.md budget is the only hard constraint.

CLAUDE.md：软目标约120行，软上限150行。超出预算的文件会被标记，但不会强制修改——手动维护的CLAUDE.md会被尊重。行数通过

wc -l

命令统计。

主题文件：信息性软上限约300行/个。随着子系统的扩展，主题文件的篇幅自然会增长；当超过约300行时，在阶段7中标记超量情况，并建议按子主题拆分。但不会阻止操作。CLAUDE.md的预算是唯一的硬性约束。

Fan-out Rule

Fan-out规则

Codebase research scales with project size and churn. Compute once in Phase 1, apply in Phase 2.

Signals:

churn

— commits since last CLAUDE.md touch:

git log --since="<date>" --oneline --no-merges | wc -l

```
files
```
— tracked files:
```
git ls-files | wc -l
```

N (codebase-scan shards):

churn	files	N
< 20	< 100	1
20 – 59	100 – 499	2
60 – 149	500 – 1999	3
≥ 150	≥ 2000	4

Compute N for each column independently. Take the max. Cap at 4. When N > 1, partition by top-level directory clusters (e.g.

plugins/

→ shard 1;

scripts/ + tests/

→ shard 2).

代码库调研的规模随项目大小和变更频率（churn）而变化。在阶段1中计算一次，在阶段2中应用。

信号指标：

churn

—— 自上次修改CLAUDE.md以来的提交数：

git log --since="<date>" --oneline --no-merges | wc -l

```
files
```
—— 已追踪文件数：
```
git ls-files | wc -l
```

N（代码库扫描分片数）：

churn	files	N
< 20	< 100	1
20 – 59	100 – 499	2
60 – 149	500 – 1999	3
≥ 150	≥ 2000	4

分别对每一列计算N值，取最大值，上限为4。当N>1时，按顶级目录集群划分（例如

plugins/

→ 分片1；

scripts/ + tests/

→ 分片2）。

Phase 1 — Orient and Compute Fan-out

阶段1 — 定位并计算Fan-out数

Glob for

CLAUDE.md

at the project root. If missing, inform the user that creation is out of scope for this skill and stop.

Record current

CLAUDE.md

line count with

wc -l

. List

.claude/rules/*.md

if the directory exists and record each topic file's line count AND last-commit date via

git log -1 --format="%ai" -- <path>

. The per-file dates are required in Phase 2 so Agent B can anchor each file's staleness window independently — using CLAUDE.md's date for every file produces wrong windows when cadences differ.

Run cheap git probes in two steps.

First, resolve the last CLAUDE.md commit date (sequential — downstream probe depends on it):

git log -1 --format="%ai" -- CLAUDE.md

→ record as

<last_claudemd_date>

. If CLAUDE.md has no history, fall back to

git log --reverse --format="%ai" | head -1

Then run the remaining probes as parallel Bash calls:

git log --since="<last_claudemd_date>" --oneline --no-merges | wc -l

— churn

```
git ls-files | wc -l
```
— tracked files

git ls-files | awk -F/ 'NF>1{print $1}' | sort -u | wc -l

— top-level directory count

Compute N using the fan-out rule. Decide the shard plan: which top-level directories each Codebase Scan agent will cover.

Exit condition: CLAUDE.md exists, baseline line counts recorded, per-topic-file line counts and last-commit dates recorded, N computed, shard plan decided.

在项目根目录查找

CLAUDE.md

。如果不存在，告知用户创建该文件不在此技能的范围内，然后停止操作。

使用

wc -l

记录当前CLAUDE.md的行数。如果

.claude/rules/

目录存在，列出其中的

.claude/rules/*.md

文件，并记录每个主题文件的行数以及通过

git log -1 --format="%ai" -- <path>

获取的上次提交日期。阶段2需要每个文件的独立日期，以便Agent B为每个文件确定独立的过时窗口——如果对所有文件都使用CLAUDE.md的日期，当更新频率不同时会产生错误的窗口。

分两步执行轻量git探测。

首先，解析CLAUDE.md的上次提交日期（顺序执行——后续探测依赖此结果）：

git log -1 --format="%ai" -- CLAUDE.md

→ 记录为

<last_claudemd_date>

。如果CLAUDE.md无提交历史，回退使用

git log --reverse --format="%ai" | head -1

。

然后，并行执行其余的Bash探测：

git log --since="<last_claudemd_date>" --oneline --no-merges | wc -l

—— 变更频率（churn）

```
git ls-files | wc -l
```
—— 已追踪文件数

git ls-files | awk -F/ 'NF>1{print $1}' | sort -u | wc -l

—— 顶级目录数量

根据Fan-out规则计算N值，确定分片方案：每个Codebase Scan agent负责哪些顶级目录。

退出条件：CLAUDE.md存在，已记录基准行数、每个主题文件的行数和上次提交日期，已计算N值，已确定分片方案。

Phase 2 — Parallel Research

阶段2 — 并行调研

Launch

3 + N

Explore agents in a single message. All use

subagent_type: Explore

Agent A — CLAUDE.md and Topic Files Audit (

subagent_type: Explore

)

Read the project's CLAUDE.md and every file in

.claude/rules/

if present. Apply the same H1/H2/H3 classification pass to CLAUDE.md AND to every topic file — topic files are first-class content, not inventory.

For each H1/H2/H3 section in either source, record:

source

(CLAUDE.md path or topic file path),

name

line_count

, and

classification_hint

(project identity, universal invariant, subsystem-scoped detail, conditional guidance, or derivable from file inspection). For topic-file sections, also flag any that have become universal invariants — content that now changes how Claude acts across almost every task in the project, not just within one subsystem — these are promote-back candidates.

Flag stale content (version numbers, paths, commands, features that look wrong). Flag cross-file duplication — topic-file content that duplicates CLAUDE.md, or topic files that overlap each other.

Also scan for index drift between CLAUDE.md and the topic files directory:

```
dangling_references
```
— topic files pointed at from CLAUDE.md's
```
## Topic Files
```
section but missing from disk
```
unreferenced_topic_files
```
— topic files on disk with no pointer from CLAUDE.md

Return:

sections[{source, name, line_count, classification_hint, promote_back_candidate}]

stale_items[{source, item, reason}]

duplications[{items, locations}]

existing_topic_files[{path, line_count, last_touched, subject, section_count}]

dangling_references[]

unreferenced_topic_files[]

Agent B — Git History Per File (

subagent_type: Explore

)

Walk git history once per instruction file, anchored to each file's own last-touch date. Using the dates captured in Phase 1:

For CLAUDE.md: run

git log --since="<claudemd_last_touched>" --format="%s%n%b" --no-merges

across the whole repo.

For each topic file: run
```
git log --since="<topic_file_last_touched>" --format="%s%n%b" --no-merges -- <directories the topic file covers>
```
. The covered directories are inferred from the topic file's subject and load trigger (e.g. a topic file about hooks covers
```
plugins/*/hooks/
```
). If the subject spans the whole repo, use the repo root.

Fallback for files with no history: use the initial commit date from

git log --reverse --format="%ai" | head -1

Categorize each commit per file:

new_subsystems

(net-new code areas),

architecture_changes

(decisions or refactors affecting how code should be written),

convention_changes

(new patterns),

removed_features

(gone from the codebase),

other

. Skip CI, formatting, version bumps.

Return:

per_file[{path, last_touched, changes_since{new_subsystems, architecture_changes, convention_changes, removed_features, other}}]

. One entry per instruction file.

Agents C1..CN — Codebase Scan Shards (

subagent_type: Explore

)

One agent per shard. Each shard covers the assigned top-level directories from the shard plan. Extract: tech stack and frameworks, established patterns (testing style, error handling, module organization), non-obvious conventions a new contributor would trip on, key commands from config files or scripts, gotchas from comments or subdirectory READMEs, and clusters of content subsystem-scoped enough to deserve their own topic file. Return:

tech_stack

patterns

conventions

commands

gotchas

topic_file_candidates[{filename, subject}]

Exit condition: all

3 + N

agents return structured notes. If any agent returns empty or truncated, proceed with available results and note the gap in the Phase 5 proposal.

在一条消息中启动

3 + N

个Explore agent，所有agent的

subagent_type: Explore

。

Agent A — CLAUDE.md与主题文件审计 (

subagent_type: Explore

)

读取项目的CLAUDE.md以及

.claude/rules/

下的所有文件（如果存在）。对CLAUDE.md和每个主题文件执行相同的H1/H2/H3分类处理——主题文件是一等内容，而非库存项。

对于任一来源中的每个H1/H2/H3章节，记录：

source

（CLAUDE.md路径或主题文件路径）、

name

、

line_count

、

classification_hint

（项目标识、通用不变量、子系统范围细节、条件性指导、可通过文件检查推导）。对于主题文件的章节，还需标记任何已成为通用不变量的内容——即现在会改变Claude在项目中几乎所有任务中的行为方式，而非仅针对某一子系统的内容——这些是升级候选内容。

标记过时内容（版本号、路径、命令、看起来错误的功能）。标记跨文件重复内容——主题文件中与CLAUDE.md重复的内容，或主题文件之间互相重叠的内容。

同时扫描CLAUDE.md与主题文件目录之间的索引偏差：

```
dangling_references
```
—— CLAUDE.md的
```
## Topic Files
```
章节中指向但磁盘上不存在的主题文件
```
unreferenced_topic_files
```
—— 磁盘上存在但CLAUDE.md中无指向的主题文件

sections[{source, name, line_count, classification_hint, promote_back_candidate}]

、

stale_items[{source, item, reason}]

、

duplications[{items, locations}]

、

existing_topic_files[{path, line_count, last_touched, subject, section_count}]

、

dangling_references[]

、

unreferenced_topic_files[]

。

Agent B — 按文件查询Git历史 (

subagent_type: Explore

)

针对每个指令文件，基于其自身的上次修改日期遍历git历史。使用阶段1中捕获的日期：

对于CLAUDE.md：在整个仓库中执行

git log --since="<claudemd_last_touched>" --format="%s%n%b" --no-merges

。

对于每个主题文件：在该主题文件覆盖的目录中执行
```
git log --since="<topic_file_last_touched>" --format="%s%n%b" --no-merges -- <directories the topic file covers>
```
。覆盖的目录由主题文件的主题和加载触发条件推断（例如，关于hooks的主题文件覆盖
```
plugins/*/hooks/
```
）。如果主题覆盖整个仓库，则使用仓库根目录。

无历史记录文件的回退方案：使用

git log --reverse --format="%ai" | head -1

获取的初始提交日期。

按文件对每个提交进行分类：

new_subsystems

（新增代码区域）、

architecture_changes

（影响代码编写方式的决策或重构）、

convention_changes

（新模式）、

removed_features

（已从代码库移除的功能）、

other

。跳过CI、格式化、版本更新的提交。

per_file[{path, last_touched, changes_since{new_subsystems, architecture_changes, convention_changes, removed_features, other}}]

。每个指令文件对应一条记录。

Agents C1..CN — 代码库扫描分片 (

subagent_type: Explore

)

每个分片对应一个agent。每个分片负责分片方案中分配的顶级目录。提取：技术栈与框架、已确立的模式（测试风格、错误处理、模块组织）、新贡献者易踩的非显式约定、配置文件或脚本中的关键命令、注释或子目录README中的注意事项、适合单独主题文件的子系统范围内容集群。返回：

tech_stack

、

patterns

、

conventions

、

commands

、

gotchas

、

topic_file_candidates[{filename, subject}]

。

退出条件：所有

3 + N

个agent返回结构化笔记。如果任何agent返回空或截断的结果，使用已有结果继续操作，并在阶段5的提案中记录缺口。

Phase 3 — Classify

阶段3 — 分类

Assign exactly one action to every section from Agent A (CLAUDE.md sections AND topic-file sections) and every new finding from Agents B and C1..CN. The action set is bidirectional — content flows both downward (demote) and upward (promote):

```
keep
```
— content stays where it is, unchanged
```
update
```
— content stays where it is, rewritten for accuracy (stale facts, changed paths, new conventions)
```
delete
```
— derivable from reading
```
package.json
```
,
```
ls
```
, or one source file; or the feature no longer exists
```
demote → <topic-file>
```
— CLAUDE.md content that is subsystem-scoped moves to a topic file
```
promote → CLAUDE.md
```
— topic-file content that has become a universal invariant moves back to CLAUDE.md. Reserved for sections Agent A flagged as
```
promote_back_candidate
```
— content whose load trigger now applies to almost every task, not just one subsystem. This is the reverse of
```
demote
```
and must be used sparingly; the CLAUDE.md budget is tight
```
move → <other-topic-file>
```
— topic-file content whose subject clustering changed and now belongs in a different topic file
```
add
```
— new content surfaced by research that belongs in CLAUDE.md or a topic file

Address dangling-reference items from Agent A as reconciliation actions:

```
dangling_references
```
— either create the missing topic file (if the referenced subject is still valid) or remove the dead pointer from CLAUDE.md
```
unreferenced_topic_files
```
— either add a pointer from CLAUDE.md's
```
## Topic Files
```
section or delete the orphan (the user decides in Phase 5)

Cluster demotion candidates and topic-file candidates from codebase-scan shards by subject. Before creating a new topic file, check if an existing topic file already covers that subject — if so, add to the existing file instead.

The top 3-5 universal invariants in CLAUDE.md are never demoted. Conversely, a topic-file section is only promoted back when it clearly meets the "changes how Claude acts in almost every task" bar.

Exit condition: every section from every source and every new finding has exactly one action, demotion candidates are grouped into named topic-file clusters, dangling references and orphan topic files have resolution plans.

为Agent A提供的所有章节（CLAUDE.md章节和主题文件章节）以及Agent B和C1..CN的所有新发现分配恰好一项操作。操作集支持双向流动——内容既可降级也可升级：

```
keep
```
—— 内容保留在原位置，不做修改
```
update
```
—— 内容保留在原位置，重写以保证准确性（过时事实、变更路径、新约定）
```
delete
```
—— 可通过读取
```
package.json
```
、
```
ls
```
或单个源文件推导得出，或功能已不存在
```
demote → <topic-file>
```
—— CLAUDE.md中属于子系统范围的内容移动到主题文件
```
promote → CLAUDE.md
```
—— 主题文件中已成为通用不变量的内容移回CLAUDE.md。仅适用于Agent A标记为
```
promote_back_candidate
```
的章节——即加载触发条件现在适用于几乎所有任务，而非仅某一子系统的内容。这是
```
demote
```
的反向操作，必须谨慎使用；CLAUDE.md的预算紧张
```
move → <other-topic-file>
```
—— 主题文件中主题聚类已变更、应归属其他主题文件的内容
```
add
```
—— 调研发现的新内容，应添加到CLAUDE.md或主题文件

处理Agent A提供的悬空引用项作为一致性校验操作：

```
dangling_references
```
—— 要么创建缺失的主题文件（如果引用的主题仍然有效），要么从CLAUDE.md中移除无效指向
```
unreferenced_topic_files
```
—— 要么在CLAUDE.md的
```
## Topic Files
```
章节中添加指向，要么删除孤立文件（用户在阶段5中决定）

将降级候选内容和代码库扫描分片发现的主题文件候选内容按主题聚类。创建新主题文件前，检查是否已有主题文件覆盖该主题——如果有，添加到已有文件中。

CLAUDE.md中排名前3-5的通用不变量永远不会被降级。反之，只有当主题文件章节明确满足“会改变Claude在几乎所有任务中的行为方式”的标准时，才会被升级回CLAUDE.md。

退出条件：每个来源的每个章节和每个新发现都已分配恰好一项操作，降级候选内容已分组为命名的主题文件集群，悬空引用和孤立主题文件已有解决方案。

Phase 4 — Budget Check

阶段4 — 预算检查

Estimate the post-reconciliation CLAUDE.md line count:

current + added + promoted_in − demoted − deleted

. The

promoted_in

term accounts for topic-file sections moving back to CLAUDE.md; a large promote-back set can push CLAUDE.md over budget even when other actions are net-neutral.

If the estimate is ≤ 150, stop demoting. Having topic files does not justify over-demotion.

If the estimate is > 150, first pressure-test the promotions — a promote-back action must clear a high bar. Drop any promote-back whose universality is marginal. Then demote additional lowest-priority

keep

items by cluster until under 150. Top invariants are off-limits. If the file still exceeds 150 after reasonable demotion and pruned promotions — typically because it is hand-maintained with intentional density — flag the overage in Phase 5 and let the user decide whether to accept it.

Also check each touched topic file against the ~300-line informational ceiling. Flag any overage for Phase 5 presentation, but do not force demotion or splitting — topic files may legitimately be dense. The CLAUDE.md budget is the only hard constraint.

Exit condition: final action list exists with pre/post line count estimate, a CLAUDE.md budget status (

under

over (user override)

), and a list of topic files flagged as over the informational ceiling.

估算校验后的CLAUDE.md行数：

current + added + promoted_in − demoted − deleted

。

promoted_in

项对应从主题文件移回CLAUDE.md的章节；即使其他操作的净变化为零，大量的升级内容也可能使CLAUDE.md超出预算。

如果估算值≤150，停止降级操作。主题文件的存在不构成过度降级的理由。

如果估算值>150，首先重新审核升级内容——升级操作必须通过严格标准。取消任何通用性存疑的升级内容。然后按集群降级优先级最低的

keep

项，直到行数低于150。顶级不变量不可降级。如果经过合理降级和精简升级后文件仍超过150行——通常是因为它是手动维护且有意保持高密度——在阶段5中标记超量情况，由用户决定是否接受。

同时检查每个被修改的主题文件是否符合约300行的信息性上限。在阶段5的展示中标记任何超量情况，但不强制降级或拆分——主题文件可能合理地保持高密度。CLAUDE.md的预算是唯一的硬性约束。

退出条件：最终操作列表已确定，包含修改前后的行数估算、CLAUDE.md预算状态（

under

、

over (user override)

），以及超出信息性上限的主题文件列表。

Phase 5 — Propose

阶段5 — 提案

Present the plan in a structured summary. Every instruction file — CLAUDE.md and each topic file being touched — is shown with the same level of detail, not just as a filename.

CLAUDE.md

Line count:
```
<current> → <estimated>
```
(budget:
```
<status>
```
)
Keep: count of sections
Update: list with one-line rationale each (what is stale, what is being corrected)
Delete: list with one-line rationale each (e.g. "derivable from
```
package.json
```
")
Demote: grouped by target topic file, showing which sections go to each
Promoted in: list of sections moved back from topic files because they are now universal invariants
Add: list of new content with source (which research agent found it)

Topic files

For each topic file being created:

Filename, estimated line count, which sections seeded it (from demotion or research findings)

For each topic file being updated:

Path, line count:
```
<current> → <estimated>
```
Keep / update / delete / promoted out / moved in — same structured breakdown as CLAUDE.md
Budget flag if over ~300 lines

For each topic file being left alone: path and one-line reason (no drift detected).

Index reconciliation

Dangling references resolved (list)
Orphan topic files resolved (list)

Use AskUserQuestion with three options: approve all, approve selectively, reject.

Exit condition: user has explicitly approved an action set.

以结构化摘要的形式呈现方案。每个指令文件——CLAUDE.md和每个被修改的主题文件——都展示相同级别的细节，而非仅显示文件名。

CLAUDE.md

行数：
```
<current> → <estimated>
```
（预算：
```
<status>
```
）
保留：章节数量
更新：列表，每项附带一行理由（内容过时之处、更正内容）
删除：列表，每项附带一行理由（例如“可从
```
package.json
```
推导得出”）
降级：按目标主题文件分组，显示哪些章节移至对应文件
升级：从主题文件移回的章节列表，因已成为通用不变量
添加：新内容列表，附带来源（哪个调研agent发现）

主题文件

对于每个新建的主题文件：

文件名、估算行数、作为内容来源的章节（来自降级或调研发现）

对于每个更新的主题文件：

路径、行数：
```
<current> → <estimated>
```
保留/更新/删除/升级移出/移入——与CLAUDE.md相同的结构化分解
若超过约300行则标记预算超量

对于每个未修改的主题文件：路径和一行理由（未检测到偏差）

索引一致性校验

已解决的悬空引用（列表）
已解决的孤立主题文件（列表）

使用AskUserQuestion提供三个选项：全部批准、选择性批准、拒绝。

退出条件：用户已明确批准某一操作集。

Phase 6 — Write

阶段6 — 写入

Execute in this order so topic-file pointers resolve:

Run
```
cp CLAUDE.md CLAUDE.md.bak
```
via Bash to create a backup before any writes
Create
```
.claude/rules/
```
with
```
mkdir -p
```
if missing
Apply topic file actions in this sub-order: delete orphaned topic files the user approved for removal, then write new topic files, then edit existing topic files (applying keep/update/delete/promoted-out/moved-in actions). Promoted-out sections are removed from the topic file in this step; they reappear in CLAUDE.md in step 4
Write CLAUDE.md with a regenerated
```
## Topic Files
```
section at the end, excluding pointers to deleted topic files. Promoted-in sections from step 3 are written as new H2 sections in the CLAUDE.md body (not inside the
```
## Topic Files
```
index block)

The

## Topic Files

section is regenerated from actual disk state after step 2, not maintained manually. Each entry is a load trigger, not a descriptive link:

undefined

按以下顺序执行，确保主题文件指向可解析：

通过Bash执行
```
cp CLAUDE.md CLAUDE.md.bak
```
，在任何写入操作前创建备份
如果
```
.claude/rules/
```
不存在，使用
```
mkdir -p
```
创建
按以下子顺序执行主题文件操作：删除用户批准移除的孤立主题文件，然后写入新主题文件，再编辑现有主题文件（应用保留/更新/删除/升级移出/移入操作）。升级移出的章节在此步骤中从主题文件移除，在步骤4中重新出现在CLAUDE.md中
写入CLAUDE.md，在末尾重新生成
```
## Topic Files
```
章节，排除指向已删除主题文件的条目。步骤3中升级移入的章节作为新的H2章节写入CLAUDE.md主体（而非
```
## Topic Files
```
索引块内）

## Topic Files

章节根据步骤2后的实际磁盘状态重新生成，而非手动维护。每个条目是加载触发条件，而非描述性链接：

undefined

Topic Files

Read on demand — do not load preemptively.

```
.claude/rules/testing.md
```
— before writing or modifying tests
```
.claude/rules/hooks.md
```
— before editing anything in plugins/*/hooks/


The load-trigger phrase is generated from the topic file's subject, not copied from a heading.

Use `Edit` for targeted changes when most of CLAUDE.md is staying. Use `Write` only if more than 60% of the file is changing — at that point the document is being regenerated rather than updated.

Exit condition: all files written, `## Topic Files` section reflects actual disk state.

Read on demand — do not load preemptively.

```
.claude/rules/testing.md
```
— before writing or modifying tests
```
.claude/rules/hooks.md
```
— before editing anything in plugins/*/hooks/


加载触发语句根据主题文件的主题生成，而非复制自标题。

当CLAUDE.md的大部分内容保留时，使用`Edit`进行针对性修改。只有当超过60%的内容需要变更时才使用`Write`——此时文档相当于重新生成而非更新。

退出条件：所有文件已写入，`## Topic Files`章节反映实际磁盘状态。

Phase 7 — Report

阶段7 — 报告

Output a diff summary with per-file deltas for every instruction file touched:

CLAUDE.md

```
<before> → <after>
```
lines (
```
<budget status>
```
)
Deletions: list with rationale
Additions: list with source
Promoted in: list of topic-file sections that moved up to CLAUDE.md (if any)
Invariants preserved: top 3-5 quoted verbatim so the user can verify they survived

Topic files created — for each: path, line count, seeded-from source

Topic files updated — for each: path,

<before> → <after>

lines, one-line change summary (e.g. "2 stale paths corrected, 1 section promoted to CLAUDE.md, 1 new section added from Agent C2 findings"). Flag any topic file over the ~300-line informational ceiling.

Topic files unchanged — bare list (no drift detected).

Index reconciliation — dangling references resolved, orphan topic files resolved or linked.

Backup:

CLAUDE.md.bak

was created in Phase 6 step 1. Tell the user they can diff with

diff CLAUDE.md.bak CLAUDE.md

and remove it themselves once satisfied — the skill does not delete the backup.

Exit condition: report delivered, advise user to remove

CLAUDE.md.bak

after review.

输出差异摘要，包含每个被修改的指令文件的文件级增量：

CLAUDE.md

行数变化：
```
<before> → <after>
```
（
```
<budget status>
```
）
删除内容：列表，附带理由
添加内容：列表，附带来源
升级移入：从主题文件移至CLAUDE.md的章节列表（如有）
保留的不变量：引用前3-5个通用不变量的原文，以便用户验证是否保留

新建主题文件 —— 每个文件：路径、行数、内容来源

更新主题文件 —— 每个文件：路径、行数变化

<before> → <after>

、一行变更摘要（例如“修正2个过时路径，1个章节升级至CLAUDE.md，从Agent C2的发现中添加1个新章节”）。标记任何超过约300行信息性上限的主题文件。

未修改主题文件 —— 简洁列表（未检测到偏差）

索引一致性校验 —— 已解决的悬空引用、已解决或链接的孤立主题文件

备份：阶段6步骤1中已创建

CLAUDE.md.bak

。告知用户可使用

diff CLAUDE.md.bak CLAUDE.md

查看差异，确认无误后自行删除备份——此技能不会删除备份。

退出条件：报告已交付，建议用户审核后移除

CLAUDE.md.bak

。