claude-md-doctor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CLAUDE.md Doctor — exam procedure

CLAUDE.md 诊断工具——检查流程

You are running a checkup on this repository's agent-instruction files. The deterministic work lives in scripts; your job is the judgment between them. Do not re-derive what a script already measured, and do not skip a stage — the report verifies the work-state manifest and will disclose skipped stages.

Definitions used below:

```
SKILL_DIR
```
= the directory containing this SKILL.md.
```
SCRIPTS
```
=
```
SKILL_DIR/scripts
```
.
```
REPO
```
= the repository to examine (the argument if one was given, else the current working directory).
```
WORK
```
=
```
REPO/.claude-md-doctor/work
```
(scripts default to this; pass
```
--work
```
to relocate, e.g. into a scratch directory to avoid writing in the user's repo — prefer that when the repo is not yours to dirty).

你正在对本仓库的Agent指令文件进行检查。确定性工作由脚本完成；你的任务是在脚本结果基础上做出判断。不要重复脚本已测量的内容，也不要跳过任何阶段——报告将验证工作状态清单，并披露跳过的阶段。

下文使用的定义：

```
SKILL_DIR
```
= 包含本SKILL.md的目录。
```
SCRIPTS
```
=
```
SKILL_DIR/scripts
```
。
```
REPO
```
= 待检查的仓库（若提供了参数则为该参数，否则为当前工作目录）。
```
WORK
```
=
```
REPO/.claude-md-doctor/work
```
（脚本默认使用此目录；可通过
```
--work
```
参数指定其他位置，例如临时目录以避免修改用户仓库——当仓库不属于你时优先选择此方式）。

Stage 0 — preflight

阶段0 — 预检

Run

python3 --version

. If python3 is missing, stop and tell the user this skill needs Python 3.9+ (stdlib only, nothing to install).

运行

python3 --version

命令。若未找到python3，需停止操作并告知用户本Skill需要Python 3.9及以上版本（仅需标准库，无需额外安装）。

Stage 1 — intake

阶段1 — 信息收集

python3 SCRIPTS/intake.py --repo REPO --work WORK

Then read

WORK/intake.json

(it is small). Note for later judgment:

Is the project CLAUDE.md a pointer (
```
is_pointer
```
) to AGENTS.md? That is the healthy, officially-recommended pattern — the target is the patient. Never diagnose a pointer file as "too short." Check
```
pointer_style
```
:
```
symlink
```
and
```
import
```
work; bare-text
is a broken pointer — a regular file containing just
```
AGENTS.md
```
without
```
@
```
means Claude Code never loads the target. That is a critical diagnosis with a one-character fix (
```
@
```
), unless you are examining a raw-fetched copy where symlinks flatten to text.
Ancestor and user-scope files are context the session loads but the repo can't fix — mention them, don't prescribe changes to them unless asked.
A file with scope
```
orphan-agents
```
means the repo has an AGENTS.md but no CLAUDE.md pointing at it — Claude Code loads nothing. That is a critical diagnosis with the official one-line fix (create a CLAUDE.md containing
```
@AGENTS.md
```
), and you should still run the full static exam on the AGENTS.md itself, since it becomes the patient the moment the pointer exists.
If NO memory files exist at all, stop and report that: the prescription is to create one (suggest
```
/init
```
then aggressive pruning), not an empty report.

python3 SCRIPTS/intake.py --repo REPO --work WORK

随后读取

WORK/intake.json

（文件体积较小）。需记录后续判断所需的信息：

项目的CLAUDE.md是否为指向AGENTS.md的指针文件（
```
is_pointer
```
）？这是官方推荐的健康模式——目标文件才是检查对象。绝不能将指针文件诊断为“过短”。检查
```
pointer_style
```
：
```
symlink
```
和
```
import
```
格式有效；bare-text
是损坏的指针——仅包含
```
AGENTS.md
```
文本的普通文件（无
```
@
```
符号）意味着Claude Code永远不会加载目标文件。这是严重问题，仅需一个字符即可修复（添加
```
@
```
），除非你检查的是原始获取的副本，其中符号链接已被转换为文本。
祖先文件和用户范围文件是会话会加载但仓库无法修改的上下文——只需提及它们，除非被要求，否则不要建议修改。
范围为
```
orphan-agents
```
的文件意味着仓库存在AGENTS.md，但没有CLAUDE.md指向它——Claude Code将无法加载任何内容。这是严重问题，官方提供的一行修复方案是（创建包含
```
@AGENTS.md
```
的CLAUDE.md），你仍需对AGENTS.md本身进行完整的静态检查，因为一旦指针存在，它就成为检查对象。
若完全不存在任何记忆文件，需停止操作并报告此情况：解决方案是创建一个（建议使用
```
/init
```
命令后进行大量精简），而非生成空报告。

Stage 2 — vitals

阶段2 — 指标检查

python3 SCRIPTS/vitals.py --work WORK

Read

WORK/vitals.json

. The script measured; you interpret. Detector notes:

```
init_boilerplate
```
means the file still opens with stock
```
/init
```
output — a generated-and-never-pruned marker.
```
emphasis_per_100_lines
```
matters as density, not presence (sparse emphasis is officially endorsed).
High
```
dated_per_100_lines
```
suggests session-log/changelog accretion.
Very low
```
imperative_ratio
```
on a large file suggests narrative documentation rather than instructions — read a sample and judge; the arcan case (a CLAUDE.md containing a sabotage manual) is why this check exists.
Judge the aggregate surface, not only each file (
```
launch_loaded_combined
```
plus the file count): many individually-healthy files can still sum to a heavy standing context, and cross-file duplication or contradiction is invisible per-file. When the combined surface is the problem, prescribe the escalating ladder — consolidate duplicates, then a thin router/index over on-demand files, then a one-screen always-on invariants file with procedures moved to skills (citation id
```
surface-bloat
```
).

python3 SCRIPTS/vitals.py --work WORK

读取

WORK/vitals.json

。脚本负责测量，你负责解读。检测器说明：

```
init_boilerplate
```
表示文件仍以默认的
```
/init
```
输出开头——这是生成后从未精简过的标记。
```
emphasis_per_100_lines
```
的关键是密度而非存在性（官方认可稀疏的强调格式）。
较高的
```
dated_per_100_lines
```
表明文件中积累了会话日志/变更记录。
大文件的
```
imperative_ratio
```
极低意味着文件更偏向叙述性文档而非指令——需读取样本并判断；极端情况（CLAUDE.md包含破坏指南）正是此检查存在的原因。
判断整体内容，而非仅单个文件（
```
launch_loaded_combined
```
加上文件数量）：多个单独健康的文件仍可能总和为过重的常驻上下文，且跨文件的重复或矛盾无法通过单个文件检查发现。当整体内容成为问题时，需按优先级建议解决方案——先合并重复内容，再通过按需加载文件构建精简的路由/索引，最后创建一个单屏显示的常驻不变量文件，将流程迁移至skills（引用ID
```
surface-bloat
```
）。

Stage 3 — records check

阶段3 — 记录核查

python3 SCRIPTS/refcheck.py --work WORK

Read

WORK/refcheck.json

. Your judgment passes:

Review the failures, don't parrot them. For each
```
missing
```
/
```
machine_specific
```
/
```
glob_empty
```
reference and each
```
missing
```
command, open the cited file:line and confirm it is a real reference (not prose that merely looks like a path — API endpoints, MIME types, git refs, and files the text describes as deleted are the common false positives). Record each false positive in
```
dismissed_refs
```
with its reason: the report shows only confirmed findings and discloses dismissals in a collapsed note.
Extract checkable claims the scripts cannot: countable assertions in the memory files ("3,540 tests across 374 files", "12 UI components", "there is no ESLint config"). Verify the cheap ones with quick commands (file counts, grep for configs). Do NOT run test suites or builds unless the user asked. Record each as
```
verified
```
/
```
drifted
```
/
```
unverified
```
with a one-line detail —
```
unverified
```
is an honest answer for anything expensive.

python3 SCRIPTS/refcheck.py --work WORK

读取

WORK/refcheck.json

。你的判断需遵循以下步骤：

审查失败项，不要直接复述。对于每个
```
missing
```
/
```
machine_specific
```
/
```
glob_empty
```
引用以及每个
```
missing
```
命令，打开引用的文件:行号，确认其为真实引用（而非仅看起来像路径的文本——API端点、MIME类型、git引用和文本中描述为已删除的文件是常见的误报）。将每个误报记录在
```
dismissed_refs
```
中并说明原因：报告仅显示已确认的结果，并在折叠注释中披露已排除的项。
提取脚本无法检查的可验证声明：记忆文件中的可计数断言（如“3540个测试覆盖374个文件”、“12个UI组件”、“无ESLint配置”）。使用快速命令验证简单项（文件计数、搜索配置）。除非用户要求，否则不要运行测试套件或构建。将每个声明记录为
```
verified
```
/
```
drifted
```
/
```
unverified
```
并附上一行细节——
```
unverified
```
是对任何耗时操作的诚实回应。

Stage 4 — history backtest

阶段4 — 历史回溯测试

Skip this stage only if intake found no session directory (

sessions.dir

null) — and then say so in chat; the report's History section will state it.

仅当信息收集阶段未找到会话目录（

sessions.dir

为null）时才跳过此阶段——并在对话中说明；报告的历史部分会标注此情况。

4a — condense the transcripts

4a — 压缩会话记录

python3 SCRIPTS/sessions.py --work WORK

4b — decompose the memory files into a rulebook (your judgment)

4b — 将记忆文件分解为规则手册（需你的判断）

Write

WORK/rulebook.json

(schema documented at the top of

backtest.py

). Guidance:

Decompose EVERY directive in the file — the rulebook is the complete directive inventory, and the enforcement ladder's "N of M" is only honest if M is the whole file. Only mechanically checkable rules get matchers: bans and requirements visible in Bash commands or Edit/Write content, and finish-ordering rules via
```
ordering
```
. Judge-class and not-yet-mechanizable rules go in as classification-only entries (enforcement block, no matchers) — never force a regex onto a semantic rule. Informational content (facts, architecture, API semantics) stays OUT of the rulebook.
For edit/write events the matchable text is
```
PATH: <file_path>
```
on the first line followed by the (truncated) new content — anchor path-based rules on
```
^PATH: .*…
```
and content rules on the body.
Write conservative regexes (prefer false negatives over false positives), use
```
scope.paths
```
/
```
scope.exclude_paths
```
to confine file-scoped rules, and date each rule with
```
introduced
```
from
```
git log --follow --format=%aI -- <file>
```
when the file's history makes that cheap — sessions that ended before a rule existed must not count against adherence.
Classify every rule's enforcement (the
```
enforcement
```
block — schema at the top of
```
backtest.py
```
). Split compound rules into clauses first; each clause classifies independently. The class is the cheapest reliable detector:
```
hook
```
(event-stream regex: bash/edit/path/tool-input/output gates, ordering, cadence — try the event-ordering and standing-invariant reframings BEFORE surrendering a rule to judge),
```
linter
```
/
```
test
```
(static analysis over artifacts: lint rules, discipline tests, import-graph boundaries — record
```
scope_kind: file|project
```
), or
```
judge
```
(only an LLM can score it). A rule even a judge couldn't score is not a rule — diagnose it
```
vague
```
. Detect existing enforcement: if the repo already has the test/lint/hook the prose describes, set
```
current_layer
```
to it — that rule is a healthy pointer, never a prescription target.
```
current_layer
```
may also be an org-level rule platform (team-wide rulebooks with centralized detectors/telemetry) — the right home for cross-repo rules, judge-class auditing at scale, and staged warn→block rollouts that per-repo configs can't govern. Give every classified rule an
```
echo_regex
```
of its distinctive tokens (for proven-defiance detection) and an
```
origin
```
(root/nested/rules — only non-root rules can be truly absent after compaction). Also judge
```
against_prior: true|false
```
in the enforcement block: would a frontier model do this by default WITHOUT the rule? A with-prior rule showing high compliance may be coincidence, not obedience (citation id
```
harness-if
```
) — flag it as a redundancy candidate in diagnosis rather than celebrating it as healthy. And when prescribing move-to-skill: that move is for procedures only — a constraint demoted into a skill description measurably loses precedence (project files outrank tool/skill descriptions).

Engine semantics you need (so you don't reverse-engineer them):

"Opportunities" = matcher fires (violation+compliance+context hits) for regex rules, and mutated-session count for ordering rules. Zero can mean "rule never applied" OR "your scope is wrong" — for any zero-fire path-scoped rule, run one negative control (confirm the sessions contain no events under that scope at all) before calling it inert.
```
scope.paths
```
filters only events that carry a file path; bash events pass a paths filter (they have no path) — for mixed bash+edit rules put path constraints into the regex (
```
^PATH: …
```
) if bash must be excluded.
```
exclude_paths
```
and
```
repo_only
```
DO apply to ordering-rule mutation counting.
Edit/Write matchable content is truncated to ~1200 chars of new content (bash commands ~600) — first-line rules are fine; end-of-file or size rules are not expressible as content regexes.
Condensed sessions are a top-level JSON array of event objects.
Read-before-edit ordering is NOT yet expressible (
```
ordering.require
```
matches bash commands only) — classify such rules as unmechanized hooks; don't torture a regex.

编写

WORK/rulebook.json

（架构文档位于

backtest.py

顶部）。指导原则：

分解文件中的每一条指令——规则手册是完整的指令清单，只有当M为整个文件时，执行阶梯的“N of M”才真实可信。只有可机械检查的规则才需要匹配器：Bash命令或编辑/写入内容中可见的禁令和要求，以及通过
```
ordering
```
实现的完成顺序规则。需人工判断且无法机械化的规则作为仅分类条目（执行块，无匹配器）——绝不要强行用正则表达式匹配语义规则。信息性内容（事实、架构、API语义）不要放入规则手册。
对于编辑/写入事件，可匹配文本为第一行的
```
PATH: <file_path>
```
，后跟（截断的）新内容——基于路径的规则锚定在
```
^PATH: .*…
```
，基于内容的规则锚定在正文。
编写保守的正则表达式（宁肯漏报也不要误报），使用
```
scope.paths
```
/
```
scope.exclude_paths
```
限制文件范围规则，当文件历史易获取时，通过
```
git log --follow --format=%aI -- <file>
```
为每个规则添加
```
introduced
```
日期——规则存在前的会话不应计入合规性。
对每个规则的执行方式进行分类（
```
enforcement
```
块——架构位于
```
backtest.py
```
顶部）。先将复合规则拆分为子句；每个子句独立分类。分类是最可靠的低成本检测器：
```
hook
```
（事件流正则表达式：bash/编辑/路径/工具输入/输出门控、顺序、节奏——在将规则归为人工判断前，先尝试事件顺序和常驻不变量重构），
```
linter
```
/
```
test
```
（对工件的静态分析：lint规则、规范测试、导入图边界——记录
```
scope_kind: file|project
```
），或
```
judge
```
（仅LLM可评分）。若规则连人工都无法评分，则不视为规则——诊断为
```
vague
```
（模糊）。检测现有执行机制：若仓库已包含文本描述的测试/lint/hook，则将
```
current_layer
```
设置为该机制——此规则是健康的指针，绝不是修改目标。
```
current_layer
```
也可以是组织级规则平台（团队级规则手册，集中化检测器/遥测）——这是跨仓库规则、大规模人工判断审计和分阶段警告→拦截部署的合适载体，而单仓库配置无法实现这些。为每个已分类的规则添加
```
echo_regex
```
（其独特标记的正则表达式，用于检测明确违规）和
```
origin
```
（root/nested/rules——只有非root规则在压缩后才可能真正缺失）。同时判断执行块中的
```
against_prior: true|false
```
：前沿模型在没有规则的情况下是否会默认执行此操作？高合规性的with-prior规则可能是巧合而非遵守规则（引用ID
```
harness-if
```
）——在诊断中标记为冗余候选，而非视为健康。当建议迁移至skill时：仅适用于流程——将约束降级为skill描述会明显降低优先级（项目文件优先级高于工具/skill描述）。

你需要了解的引擎语义（无需逆向工程）：

“触发机会” = 正则规则的匹配次数（违规+合规+上下文命中），以及顺序规则的会话变更次数。零触发可能意味着“规则从未适用”或“你的范围设置错误”——对于任何零触发的路径范围规则，在判定为无效前，需运行一次阴性对照（确认会话中完全没有该范围内的事件）。
```
scope.paths
```
仅过滤携带文件路径的事件；bash事件会通过路径过滤（它们没有路径）——对于混合bash+编辑规则，若需排除bash，需将路径约束放入正则表达式（
```
^PATH: …
```
）。
```
exclude_paths
```
和
```
repo_only
```
适用于顺序规则的变更计数。
编辑/写入的可匹配内容截断为约1200字符的新内容（bash命令约600字符）——基于首行的规则可行；基于文件末尾或大小的规则无法通过内容正则表达式实现。
压缩后的会话是顶级JSON数组，包含事件对象。
编辑前读取的顺序目前无法实现（
```
ordering.require
```
仅匹配bash命令）——此类规则分类为未机械化的hook；不要强行使用正则表达式。

4c — run the engine

4c — 运行引擎

python3 SCRIPTS/backtest.py --work WORK

4d — sample-verify (MANDATORY — matchers have bugs)

4d — 样本验证（强制要求——匹配器可能存在bug）

Read

WORK/backtest.json

. For EVERY rule with fires — violation AND compliance samples both — read the sample excerpts and confirm each is a true positive. A matcher with any false positive gets fixed in

rulebook.json

and the engine re-run — this loop is cheap and it is the whole reason the results can be trusted. Only when every sampled fire is confirmed, set

"verified": true

backtest.json

(edit the file) — the report shows a "provisional" banner otherwise. Then record per-rule verdicts in

diagnosis.json

under

rule_verdicts

json

"rule_verdicts": {
  "R1": {"verdict": "healthy|ignored|mixed|inert", "note": "one line of judgment"}
}

inert

(zero opportunities in the window) is a finding, not a failure — say what it means: the rule cost context in every session and never came up.

The engine also triages every violation by cause:

defiance-proven

(the agent echoed the rule in its own text, then violated it — the reminder already happened and lost),

defiance

(fresh context),

dilution

(late turn / heavy context),

absence-risk

(non-root rule after a compaction boundary). Read the causes before judging: they pick the medicine — proven defiance justifies block-mode; dilution calls for slimming/path-scoping, not cages; absence calls for re-injection hooks. Sanity-check the buckets while sample-verifying (a "dilution" tag on a turn-2 violation means the occupancy proxy misfired — say so). Ordering-rule caveat: verdicts are per-transcript — in subagent/worktree workflows the required command may have run in a sibling transcript. A conversation message claiming it ran ("verify green") is not proof; note the claim in your verdict and check whether repo edits happened after it (the obligation re-ripens).

读取

WORK/backtest.json

。对于每个有触发记录的规则（包括违规和合规模本），读取样本片段并确认每个均为真阳性。若匹配器存在任何假阳性，需在

rulebook.json

中修复并重新运行引擎——此循环成本低，是结果可信的关键。仅当所有抽样触发均被确认后，在

backtest.json

中设置

"verified": true

（编辑文件）——否则报告将显示“临时”标记。随后在

diagnosis.json

的

rule_verdicts

中记录每个规则的 verdict：

json

"rule_verdicts": {
  "R1": {"verdict": "healthy|ignored|mixed|inert", "note": "一行判断内容"}
}

inert

（窗口期内零触发机会）是一个发现，而非失败——说明该规则在每个会话中都占用了上下文，但从未被用到。

引擎还会按原因对每个违规进行分类：

defiance-proven

（Agent在自身文本中回显了规则，随后违规——提醒已发生但无效），

defiance

（新上下文），

dilution

（延迟响应/过重上下文），

absence-risk

（压缩边界后的非root规则）。判断前需查看原因：它们决定了解决方案——明确违规证明需要拦截模式；上下文过载需要精简/路径范围限制，而非限制；缺失需要重新注入hook。样本验证时需检查分类是否合理（例如，第2轮响应的违规标记为“dilution”意味着占用率代理失效——需说明）。顺序规则注意事项：verdict基于每个会话——在子Agent/工作流中，所需命令可能在兄弟会话中运行。对话消息声称已运行（如“验证为绿色”）并非证据；需在verdict中提及该声明，并检查声明后是否有仓库编辑（义务重新生效）。

4e — compile enforcement proposals

4e — 编译执行建议

python3 SCRIPTS/compile.py --work WORK

This writes

WORK/enforcement/

— a PROPOSALS.md dossier per rule, a generic guard script, its per-rule config (warn-mode by default; defiance-proven rules start at block), and a settings snippet. Never install any of it yourself; never edit the user's
.claude/settings.json
. Goodhart caution (citation id

specbench

): a visible pattern-gate can be satisfied without honoring the rule — where a rule has a real outcome (tests pass, build green), prefer a gate that runs the outcome over one that greps a pattern. Tell the user where the proposals live and that they are review-then-arm.

python3 SCRIPTS/compile.py --work WORK

此命令会写入

WORK/enforcement/

目录——每个规则对应一个PROPOSALS.md文件、一个通用守卫脚本、其每个规则的配置（默认警告模式；明确违规规则初始为拦截模式），以及一个设置片段。绝不要自行安装任何内容；绝不要编辑用户的
.claude/settings.json
。注意避免古德哈特定律（引用ID

specbench

）：可见的模式门控可能满足形式但未遵守规则——若规则有实际结果（测试通过、构建成功），优先选择基于结果的门控，而非基于模式匹配的门控。告知用户建议文件的位置，并说明需审核后启用。

Stage 5 — diagnosis (your judgment, written to a file)

阶段5 — 诊断（需你的判断，写入文件）

Write

WORK/diagnosis.json

json

{
  "grade": "B",
  "chief_complaint": "One sentence, doctor-voice, the single biggest issue.",
  "history_note": "optional override for the History section",
  "stale_claims": [
    {"claim": "…", "file": "/abs/path", "line": 12,
     "status": "verified|drifted|unverified", "detail": "…"}
  ],
  "dismissed_refs": [
    {"ref": "the exact ref string from refcheck.json", "line": 46,
     "reason": "why it is a false positive (route not file, MIME type, described as deleted, …)"}
  ],
  "rule_verdicts": {
    "R1": {"verdict": "healthy|ignored|mixed|inert|unmeasured|abandoned",
           "note": "one line of judgment; 'abandoned' = the repo's own history contradicts the rule (e.g. git shows the team doing the banned thing routinely) even if sessions were inert"}
  },
  "diagnoses": [
    {"state": "dead-ref|stale|vague|ignored|inert|redundant|contradictory|oversized|accretion|generated-unpruned",
     "severity": "critical|warn|info",
     "title": "short name", "detail": "1–3 sentences, plain language",
     "file": "/abs/path", "line": 46,
     "evidence": ["short quoted lines or metric readouts"],
     "citations": ["official-200"],
     "prescription": "the concrete fix, imperative voice"}
  ],
  "prescriptions": [
    {"action": "repo-wide action", "rationale": "why", "citations": ["eth"]}
  ],
  "followup": ["re-run cadence; transcript-retention advice; what to fix first"],
  "share_note": "one quotable line for the public share card — dry doctor's wit backed by the findings. STRICT safety: no file paths, no rule text, no quotes from the repo, no session ids, nothing repo-identifying; aggregate truths only (e.g. 'The loudest rule was the broken one.'). Omit the field to use a deterministic fallback."
}

Rules for this stage:

Every diagnosis needs evidence (a quoted line, a metric, a failed check) and, where one exists, a citation id. List the valid ids and what each source claims with
```
python3 SCRIPTS/report.py --list-citations
```
— use only those ids, and only where the source actually supports the point. A check with no official or research backing is stated as a heuristic in its
```
detail
```
.
Severity honestly:
```
critical
```
= the file lies to the agent (dead refs, drifted claims, contradictions) or content is being skipped (4 MiB);
```
warn
```
= costs context or reduces adherence (oversized, emphasis saturation, accretion);
```
info
```
= worth knowing.
Structure-only findings carry a caution: the one factorial study found no structural effect in its tested range (citation id
```
mcmillan
```
) — do not present size/position folklore as causal fact. Content findings (dead refs, drift) need no such hedge.
Grade rubric: A = no criticals and at most 2 warns; B = no criticals and 3 or more warns; C = 1–2 criticals; D = 3+ criticals; F = the file is actively misleading (mostly dead/drifted) or unloadable. A pointer-style CLAUDE.md with a healthy target grades on the target.
Cannot-fix scopes (ancestor/user/managed files) may generate
```
info
```
diagnoses only.
Never mention this tool's version numbers in report content (diagnoses, notes, follow-ups, chief complaint). The renderer stamps the version in the report footer; content reads timelessly — a reader doesn't know or care what "v0.2" means.
Pointer repos are usually cross-agent repos. When the patient is an AGENTS.md reached via a pointer, it likely serves Cursor/Codex/Copilot too — prescriptions that relocate content into Claude-only surfaces (
```
.claude/rules/
```
, skills, hooks) hide it from those agents. Still prescribe them when right, but state the trade-off in the prescription ("Claude-only; other agents reading AGENTS.md will lose this") and prefer in-file fixes for content every agent needs.

编写

WORK/diagnosis.json

：

json

{
  "grade": "B",
  "chief_complaint": "一句话，医生口吻，描述最大的问题。",
  "history_note": "可选，用于覆盖历史部分的内容",
  "stale_claims": [
    {"claim": "…", "file": "/绝对路径", "line": 12,
     "status": "verified|drifted|unverified", "detail": "…"}
  ],
  "dismissed_refs": [
    {"ref": "refcheck.json中的准确引用字符串", "line": 46,
     "reason": "为何是误报（路由而非文件、MIME类型、描述为已删除等）"}
  ],
  "rule_verdicts": {
    "R1": {"verdict": "healthy|ignored|mixed|inert|unmeasured|abandoned",
           "note": "一行判断内容；'abandoned' = 仓库自身历史与规则矛盾（例如git显示团队常规执行被禁止的操作），即使会话无记录"}
  },
  "diagnoses": [
    {"state": "dead-ref|stale|vague|ignored|inert|redundant|contradictory|oversized|accretion|generated-unpruned",
     "severity": "critical|warn|info",
     "title": "简短名称", "detail": "1–3句话，通俗易懂",
     "file": "/绝对路径", "line": 46,
     "evidence": ["简短引用行或指标读数"],
     "citations": ["official-200"],
     "prescription": "具体修复方案，祈使语气"}
  ],
  "prescriptions": [
    {"action": "仓库级操作", "rationale": "原因", "citations": ["eth"]}
  ],
  "followup": ["重新运行频率；会话记录保留建议；优先修复项"],
  "share_note": "用于公开分享卡片的一句引用——基于发现的专业医生式幽默。严格安全要求：无文件路径、无规则文本、无仓库引用、无会话ID、无任何可识别仓库的内容；仅使用汇总事实（例如：'最显眼的规则却是失效的规则。'）。若省略此字段，将使用确定性默认内容。"
}

此阶段规则：

每个诊断都需要证据（引用行、指标、失败检查结果），若存在引用ID则需附上。使用
```
python3 SCRIPTS/report.py --list-citations
```
列出有效ID及其来源声明——仅使用这些ID，且仅在来源实际支持观点时使用。无官方或研究支持的检查需在
```
detail
```
中说明为启发式方法。
如实评估严重程度：
```
critical
```
= 文件向Agent提供错误信息（无效引用、过时声明、矛盾）或内容被跳过（4 MiB）；
```
warn
```
= 占用上下文或降低合规性（过大、强调饱和、积累）；
```
info
```
= 值得了解的信息。
仅结构相关的发现需谨慎：一项阶乘研究发现，在测试范围内结构无显著影响（引用ID
```
mcmillan
```
）——不要将大小/位置相关的经验之谈视为因果事实。内容相关发现（无效引用、偏差）无需此类限制。
评分标准：A = 无严重问题且最多2个警告；B = 无严重问题且3个及以上警告；C = 1–2个严重问题；D = 3个及以上严重问题；F = 文件具有误导性（大部分无效/过时）或无法加载。指向健康目标文件的指针式CLAUDE.md按目标文件评分。
无法修复的范围（祖先/用户/管理文件）仅可生成
```
info
```
级诊断。
报告内容中绝不要提及本工具的版本号（诊断、注释、后续建议、主要问题）。渲染器会在报告页脚标记版本；内容需保持时效性——读者不知道也不关心“v0.2”是什么意思。
指针仓库通常是跨Agent仓库。当检查对象是通过指针访问的AGENTS.md时，它可能同时服务于Cursor/Codex/Copilot等Agent——将内容迁移至Claude专属区域（
```
.claude/rules/
```
、skills、hooks）的建议会导致其他Agent无法读取这些内容。当方案合适时仍可建议，但需在建议中说明权衡（"仅Claude可用；读取AGENTS.md的其他Agent将无法获取此内容"），并优先选择所有Agent都能读取的文件内修复方案。

Stage 6 — report

阶段6 — 生成报告

python3 SCRIPTS/report.py --work WORK

Then generate the share-safe card and badge:

python3 SCRIPTS/card.py --work WORK

card.svg

(postable checkup card) and

claude-md-health.svg

(README badge) land next to report.html. Both are aggregate-only by construction — but eye the card once anyway before telling the user it is safe to post. Offer the badge snippet the script prints for their README.

Open or send the resulting

report.html

to the user, and summarize in chat: grade, chief complaint, the top 3 findings, and the single highest-value prescription. Tell the user where the report lives. If report.py printed an INCOMPLETE warning, say which stage was missing and why.

python3 SCRIPTS/report.py --work WORK

随后生成安全分享卡片和徽章：

python3 SCRIPTS/card.py --work WORK

card.svg

（可发布的检查卡片）和

claude-md-health.svg

（README徽章）会生成在report.html旁边。两者默认仅包含汇总信息——但发布前仍需查看卡片是否安全。提供脚本输出的徽章代码片段供用户添加至README。

向用户打开或发送生成的

report.html

，并在对话中总结：评分、主要问题、前3项发现，以及最高价值的修复建议。告知用户报告的位置。若report.py输出了INCOMPLETE警告，需说明缺失的阶段及原因。

Conduct

行为规范

Everything runs locally; never send file contents anywhere.
Quote at most ~2 lines from any file in evidence.
In a headless or background run, do not try to "open" the report — state its path (report.html lands in the work directory's PARENT, next to report.json) and summarize it.

所有操作均在本地运行；绝不要将文件内容发送至任何外部位置。
证据中最多引用每个文件的约2行内容。
在无头或后台运行时，不要尝试“打开”报告——说明其路径（report.html生成在工作目录的父目录，与report.json同级）并进行总结。