config-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

config-audit

Audits the repo's Claude configuration against
docs/config-guidelines.md
. Read-only. Produces
audit-report.md
consumed by
config-refactor
.

Triggers: /config-audit, audit config, audit claude config, review configuration, configuration health check

针对
docs/config-guidelines.md
审核仓库的Claude配置。只读模式。生成供
config-refactor
使用的
audit-report.md
。

触发词：/config-audit、audit config、audit claude config、review configuration、configuration health check

Process

流程

Step 0 — Detect execution context

步骤0 — 检测执行上下文

Determine which mode to run in (per Principle 13):

Global mode — CWD is the
```
claude-config
```
repo. Detected when ALL of:
- ```
install.sh
```
  exists at CWD root.
- ```
skills/_shared/
```
  exists at CWD root.
- OR basename of CWD matches
```
claude-config
```
  or
```
agent-config
```
  .
Project mode — CWD is any other directory containing a
```
CLAUDE.md
```
at root.

No-config mode — CWD has no

CLAUDE.md

. Stop and print:

No CLAUDE.md found in this directory. Run /project-setup --interactive or create one manually before auditing.

Record the detected mode and proceed. The mode controls Step 1 (guidelines source) and Step 2 (target file enumeration).

确定运行模式（遵循原则13）：

全局模式 — CWD为
```
claude-config
```
仓库。满足以下全部条件时触发：
- CWD根目录存在
```
install.sh
```
  。
- CWD根目录存在
```
skills/_shared/
```
  。
- 或CWD的基名称为
```
claude-config
```
  或
```
agent-config
```
  。
项目模式 — CWD为其他任何在根目录包含
```
CLAUDE.md
```
的目录。

无配置模式 — CWD中无

CLAUDE.md

。停止运行并打印：

未在此目录中找到CLAUDE.md。请先运行/project-setup --interactive或手动创建后再进行审核。

记录检测到的模式并继续执行。模式将控制步骤1（指南来源）和步骤2（目标文件枚举）。

Step 1 — Locate guidelines

步骤1 — 定位指南

Global mode — read

docs/config-guidelines.md

from CWD. This file is the spec.

Project mode — read

~/.claude/docs/config-guidelines.md

(the deployed global spec) as the read-only baseline. The project's own

CLAUDE.md

is the audit target, not a spec source.

If the guidelines file does not exist in either mode:

Emit CRITICAL "Guidelines file missing — cannot audit. In global mode, create
```
docs/config-guidelines.md
```
. In project mode, run
```
install.sh
```
from the
```
claude-config
```
repo on this machine."
Stop. Do not produce a partial report.

全局模式 — 读取CWD下的

docs/config-guidelines.md

，该文件为规范文件。

项目模式 — 读取

~/.claude/docs/config-guidelines.md

（已部署的全局规范）作为只读基准。项目自身的

CLAUDE.md

是审核目标，而非规范来源。

若任意模式下指南文件不存在：

输出严重错误提示："指南文件缺失——无法执行审核。全局模式下请创建
```
docs/config-guidelines.md
```
。项目模式下请在本机运行
```
claude-config
```
仓库中的
```
install.sh
```
。"
停止运行，不生成部分报告。

Step 2 — Enumerate target files

步骤2 — 枚举目标文件

Global mode — audit only these targets, in this order. This repo follows the

core/

adapters/<tool>/

→

install.sh

assembly model (Principle 14): root

CLAUDE.md

AGENTS.md

GEMINI.md

are build products — audit them at their source, never as hand-edited files.

CLAUDE.md

(root) — build product; audit its sources:

core/instructions/*

core/methodology/*

adapters/claude-code/claude.sections-*.md

core/output-styles/*.body.md

and

adapters/claude-code/output-styles/*

(output styles).

```
skills/*/SKILL.md
```
— see shape note below.
```
hooks/*
```
and
```
core/hooks/*
```
(read for cross-checks against
```
CLAUDE.md
```
, do NOT audit hook internals).
```
adapters/claude-code/settings.json
```
and
```
settings.local.json
```
(cross-checks only — duplicated rules, hook declarations matching files in
```
hooks/
```
).
```
adapters/<tool>/mcp/*.json
```
(existence only).
```
adapters/claude-code/keybindings.json
```
(existence only).
```
~/.claude/
```
orphan scan (Principle 12 whitelists).

Skill shape (Principle 14) — a

SKILL.md

containing an

ASSEMBLY:BEGIN

marker is spliced: its source of truth is

core/skills/<x>/logic.md

, and the spliced region in

SKILL.md

is a build product — audit findings inside it map to the

core/

source. A

SKILL.md

with no marker is direct-source: audit it in place. Both shapes coexist by design (27/39 spliced — live count enforced by

validate.sh

Check 7; the other 12 are direct-source by nature — governance/setup skills whose logic references Claude-specific paths), so audit tooling MUST handle both.

Do not audit anything else. Out of scope:

docs/

(except guidelines),

memory/

agents/

, test fixtures, README.

Project mode — audit only these targets:

```
CLAUDE.md
```
at CWD root (the project's own).
```
.claude/skills/*/SKILL.md
```
if present (project-local skills).

.claude/settings.json

and

.claude/settings.local.json

if present.

Out of scope in project mode:

~/.claude/

runtime directories, the global

CLAUDE.md

, anything outside the project root. The global layer is read-only reference for duplication checks (Principle 13 anti-duplication rule).

全局模式 — 仅按以下顺序审核这些目标。本仓库遵循

core/

adapters/<tool>/

→

install.sh

组装模型（原则14）：根目录下的

CLAUDE.md

、

AGENTS.md

、

GEMINI.md

为构建产物——需审核其源文件，切勿将其视为手动编辑文件。

CLAUDE.md

（根目录）——构建产物；审核其源文件：

core/instructions/*

、

core/methodology/*

、

adapters/claude-code/claude.sections-*.md

。

core/output-styles/*.body.md

和

adapters/claude-code/output-styles/*

（输出样式）。

```
skills/*/SKILL.md
```
——参见下方格式说明。
```
hooks/*
```
和
```
core/hooks/*
```
（仅用于与
```
CLAUDE.md
```
交叉核对，不审核钩子内部逻辑）。
```
adapters/claude-code/settings.json
```
和
```
settings.local.json
```
（仅用于交叉核对——重复规则、钩子声明与
```
hooks/
```
中的文件匹配情况）。
```
adapters/<tool>/mcp/*.json
```
（仅检查是否存在）。
```
adapters/claude-code/keybindings.json
```
（仅检查是否存在）。
```
~/.claude/
```
孤立文件扫描（原则12白名单）。

Skill格式（原则14） — 包含

ASSEMBLY:BEGIN

标记的

SKILL.md

为拼接式：其可信源为

core/skills/<x>/logic.md

，

SKILL.md

中的拼接区域为构建产物——审核发现需映射至

core/

源文件。无该标记的

SKILL.md

为直接源式：直接审核该文件。两种格式共存为设计要求（39个中有27个为拼接式——由

validate.sh

检查7强制验证当前数量；其余12个为直接源式——治理/设置类Skill，其逻辑引用Claude特定路径），因此审核工具必须兼容两种格式。

请勿审核其他内容。范围外内容：

docs/

（指南文件除外）、

memory/

、

agents/

、测试 fixtures、README。

项目模式 — 仅审核以下目标：

CWD根目录下的
```
CLAUDE.md
```
（项目自身的配置文件）。
若存在
```
.claude/skills/*/SKILL.md
```
（项目本地Skill）。

若存在

.claude/settings.json

和

.claude/settings.local.json

。

项目模式下范围外内容：

~/.claude/

运行时目录、全局

CLAUDE.md

、项目根目录外的任何内容。全局层仅作为重复检查的只读参考（原则13反重复规则）。

Step 3 — Run check matrix

步骤3 — 运行检查矩阵

Apply every check below. For each finding, record:

```
severity
```
: CRITICAL | WARNING | SUGGESTION
```
file
```
: absolute path
```
line
```
(if applicable)
```
rule
```
: the principle name from guidelines (e.g. "Principle 4 — Token budget")
```
finding
```
: one-sentence description
```
fix_hint
```
: one-sentence suggested action

应用以下所有检查项。针对每个发现，记录：

```
severity
```
: CRITICAL | WARNING | SUGGESTION（严重错误 | 警告 | 建议）
```
file
```
: 绝对路径
```
line
```
（若适用）
```
rule
```
: 指南中的原则名称（例如："原则4 — Token预算"）
```
finding
```
: 一句话描述
```
fix_hint
```
: 一句话建议操作

Token-budget checks (Principle 4)

Token预算检查（原则4）

For each target file:

Count lines.
Compare against the file's soft and hard limit from the guidelines table.
Over hard limit → CRITICAL.
Over soft limit → WARNING.

针对每个目标文件：

统计行数。
与指南表格中该文件的软限制和硬限制对比。
超过硬限制 → 严重错误。
超过软限制 → 警告。

Separation-of-concerns checks (Principle 2)

关注点分离检查（原则2）

Scan

CLAUDE.md

for:

Sections that match orchestrator/agent-specific scope (e.g. "Bind this to … agent or rule only", explicit sub-agent contracts, SDD model assignments). If found and no
```
agents/<name>.md
```
exists, raise WARNING "Move scoped section to
```
agents/
```
".
A manual skill catalog (table listing 5+ skills with descriptions). If found, raise WARNING "Remove manual skill catalog — harness auto-discovers skills (Principle 2)".

Scan each output-style source (

core/output-styles/*.body.md

and

adapters/claude-code/output-styles/*

) for:

Bullets that begin with verbs like "Verify", "Never agree", "Propose alternatives", "Explain why with evidence". These restate
```
CLAUDE.md
```
behavior rules → WARNING.
Prescriptive technical opinions ("X over Y", "always use X", "concepts > code"). Raise WARNING with rule "Principle 7 — Output styles are tone, not behavior".

扫描

CLAUDE.md

以查找：

符合编排器/Agent特定范围的章节（例如："仅绑定至…Agent或规则"、明确的子Agent契约、SDD模型分配）。若存在且无
```
agents/<name>.md
```
文件，触发警告："将特定范围章节移至
```
agents/
```
目录"。
手动Skill目录（列出5个以上Skill及描述的表格）。若存在，触发警告："移除手动Skill目录——工具将自动发现Skill（原则2）"。

扫描每个输出样式源文件（

core/output-styles/*.body.md

和

adapters/claude-code/output-styles/*

）以查找：

以"Verify"、"Never agree"、"Propose alternatives"、"Explain why with evidence"等动词开头的项目符号。这些内容重复了
```
CLAUDE.md
```
中的行为规则 → 警告。
规定性技术观点（"X优于Y"、"始终使用X"、"概念>代码"）。触发警告，规则为"原则7 — 输出样式为语气风格，而非行为规则"。

Anti-duplication checks (Principle 3)

反重复检查（原则3）

Build a normalized fingerprint of each rule line in

CLAUDE.md

and each rule line in output styles and skills. A "rule line" is a top-level bullet inside a

## Rules

-like section.

For each pair that exceeds 70% token overlap:

If one of the two files is a hook and the other is
```
CLAUDE.md
```
→ CRITICAL "Rule duplicated between hook and CLAUDE.md (Principle 3.1)".
If
```
CLAUDE.md
```
and an output-style → WARNING "Rule duplicated (Principle 3.2)".
If two skills → SUGGESTION "Extract shared rule into
```
skills/_shared/
```
".

为

CLAUDE.md

中的每条规则行、输出样式及Skill中的每条规则行生成标准化指纹。"规则行"指

## Rules

类章节下的顶级项目符号。

针对每对令牌重叠度超过70%的内容：

若其中一个文件为钩子，另一个为
```
CLAUDE.md
```
→ 严重错误："规则在钩子与CLAUDE.md之间重复（原则3.1）"。
若为
```
CLAUDE.md
```
与输出样式 → 警告："规则重复（原则3.2）"。
若为两个Skill → 建议："将共享规则提取至
```
skills/_shared/
```
目录"。

OS-correctness checks (Principle 5)

系统正确性检查（原则5）

Scan

CLAUDE.md

for these substrings (case-insensitive):

brew

apt-get

cat

find

sed

grep

(as Bash command, not the Grep tool),

ls

For each hit:

If the line is not prefixed by an OS-specific marker ("On Linux/macOS only:", "WSL:", etc.) → WARNING "OS-specific tooling assumed without declaration (Principle 5)".

扫描

CLAUDE.md

以查找以下子字符串（不区分大小写）：

brew

、

apt-get

、

cat

、

find

、

sed

、

grep

（作为Bash命令，而非Grep工具）、

ls

。

针对每个匹配项：

若该行未以系统特定标记前缀（"仅在Linux/macOS下："、"WSL："等）开头 → 警告："假设使用特定系统工具但未声明（原则5）"。

Engram-ownership checks (Principle 9)

Engram归属检查（原则9）

Scan

CLAUDE.md

for headings or bullets that look like the engram protocol payload:

"PROACTIVE SAVE TRIGGERS"
"SESSION START PROTOCOL"
"SESSION CLOSE PROTOCOL"
"AFTER COMPACTION"
```
mem_save
```
format template (a multi-bullet block describing
```
title
```
,
```
type
```
,
```
content
```
)

If found AND the same content is also injected by a

SessionStart

hook → CRITICAL "Engram protocol duplicated between hook and CLAUDE.md (Principle 9)".

If found AND no hook injects it → WARNING "Engram protocol in CLAUDE.md but no hook injects it; verify ownership".

扫描

CLAUDE.md

以查找类似Engram协议负载的标题或项目符号：

"PROACTIVE SAVE TRIGGERS"
"SESSION START PROTOCOL"
"SESSION CLOSE PROTOCOL"
"AFTER COMPACTION"
```
mem_save
```
格式模板（描述
```
title
```
、
```
type
```
、
```
content
```
的多项目符号块）

若存在且相同内容也由

SessionStart

钩子注入 → 严重错误："Engram协议在钩子与CLAUDE.md之间重复（原则9）"。

若存在且无钩子注入该内容 → 警告："Engram协议存在于CLAUDE.md中但无钩子注入；请验证归属"。

Force-read-inline table checks (Principle 10)

强制内联读取表格检查（原则10）

Find the "Skills — Force-read inline" table (or any table at root of

CLAUDE.md

listing skills with paths). Check:

More than 4 entries → WARNING "Force-read table exceeds 4 entries".
Title is "Skills catalog", "Auto-load skills", or any wording that implies full catalog → WARNING "Rename to 'Skills — Force-read inline'".
Any path that does not exist on disk → CRITICAL "Force-read entry points to missing file".

查找"Skills — Force-read inline"表格（或

CLAUDE.md

根目录下任何列出Skill及路径的表格）。检查：

条目超过4个 → 警告："强制读取表格条目超过4个"。
标题为"Skills catalog"、"Auto-load skills"或任何暗示完整目录的表述 → 警告："重命名为'Skills — Force-read inline'"。
任何指向磁盘上不存在路径的条目 → 严重错误："强制读取条目指向不存在的文件"。

Skill format checks (Principle 8)

Skill格式检查（原则8）

For each

skills/*/SKILL.md

Missing YAML frontmatter → CRITICAL.
Missing
```
name
```
,
```
description
```
, or
```
format
```
in frontmatter → CRITICAL.
```
format
```
value not in {procedural, reference, anti-pattern} → CRITICAL.
Missing
```
**Triggers**:
```
line in body → WARNING.
Section contract for declared format not met (see
```
core/format-types.md
```
) → WARNING.

针对每个

skills/*/SKILL.md

：

缺少YAML前置元数据 → 严重错误。
前置元数据中缺少
```
name
```
、
```
description
```
或
```
format
```
→ 严重错误。
```
format
```
值不在{procedural, reference, anti-pattern}中 → 严重错误。
正文中缺少
```
**Triggers**:
```
行 → 警告。
未满足声明格式的章节契约（参见
```
core/format-types.md
```
）→ 警告。

Two-layer duplication checks (Principle 13, project mode only)

双层重复检查（原则13，仅项目模式）

For each rule line in the project

CLAUDE.md

Normalize and fingerprint as in the anti-duplication check.
Compare against rules in the global
```
~/.claude/CLAUDE.md
```
.
Token overlap > 70% AND no
```
## Overrides global
```
block declares the rule → CRITICAL "Project CLAUDE.md restates global rule without override declaration (Principle 13)".
If a project rule contradicts a global rule (semantic opposite) and no override block is declared → CRITICAL "Project CLAUDE.md contradicts global without override (Principle 13)".

In global mode this check is skipped (only one layer present).

针对项目

CLAUDE.md

中的每条规则行：

按反重复检查中的方式生成标准化指纹。
与全局
```
~/.claude/CLAUDE.md
```
中的规则对比。
令牌重叠度>70%且无
```
## Overrides global
```
块声明该规则 → 严重错误："项目CLAUDE.md重复全局规则但未声明覆盖（原则13）"。
若项目规则与全局规则矛盾（语义相反）且未声明覆盖块 → 严重错误："项目CLAUDE.md与全局规则矛盾但未声明覆盖（原则13）"。

全局模式下跳过此检查（仅存在一层）。

Orphan checks in

~/.claude/

(Principle 12, global mode only)

~/.claude/

孤立文件检查（原则12，仅全局模式）

List the entries directly under

~/.claude/

. For each entry:

If the name is in the known-runtime whitelist (Principle 12) → ignore.
If the name is in the known-deployed whitelist → ignore.
Otherwise → WARNING "Orphan in ~/.claude/: <name>. Investigate origin or remove."

Do not recurse into runtime directories. The check is one level deep.

列出

~/.claude/

下的直接条目。针对每个条目：

若名称在已知运行时白名单（原则12）中 → 忽略。
若名称在已知部署白名单中 → 忽略。
否则 → 警告：
```
~/.claude/
```
中存在孤立文件：<name>。请调查来源或删除。

请勿递归进入运行时目录。检查仅针对一级目录。

Cross-reference checks (general)

交叉引用检查（通用）

For every absolute path mentioned in
```
CLAUDE.md
```
(e.g.
```
~/.claude/skills/foo/SKILL.md
```
), verify the corresponding repo path exists. If not → SUGGESTION "Dead reference".
For every skill name referenced inside another
```
SKILL.md
```
body, verify it exists in
```
skills/
```
. If not → SUGGESTION "Reference to missing skill".

针对
```
CLAUDE.md
```
中提及的每个绝对路径（例如：
```
~/.claude/skills/foo/SKILL.md
```
），验证对应的仓库路径是否存在。若不存在 → 建议："无效引用"。
针对另一个
```
SKILL.md
```
正文中引用的每个Skill名称，验证其是否存在于
```
skills/
```
目录中。若不存在 → 建议："引用了不存在的Skill"。

Step 4 — Write the report

步骤4 — 生成报告

Write the result to

audit-report.md

at the repo root with this exact structure:

markdown

undefined

将结果写入仓库根目录下的

audit-report.md

，需严格遵循以下结构：

markdown

undefined

Configuration Audit Report

Generated: YYYY-MM-DD HH:MM Guidelines version: <git short hash of docs/config-guidelines.md if available, else "untracked">

Summary

CRITICAL: <count>
WARNING: <count>
SUGGESTION: <count>

CRITICAL: <count>
WARNING: <count>
SUGGESTION: <count>

Findings

CRITICAL

[CRIT-1] <one-line title>

File:
```
<path>
```
(line <n> if applicable)
Rule: <principle name>
Finding: <one sentence>
Fix hint: <one sentence>

(repeat for each CRITICAL)

File:
```
<path>
```
(line <n> if applicable)
Rule: <principle name>
Finding: <one sentence>
Fix hint: <one sentence>

(repeat for each CRITICAL)

WARNING

(same shape)

SUGGESTION

(same shape)

No-issues sections

List target files that produced zero findings. One per line.

Next step

Run

/config-refactor

to apply fixes. The refactor skill reads this file as its spec.


Use stable IDs (`CRIT-1`, `WARN-1`, `SUGG-1` …) so `config-refactor` can reference them
exactly.

Run

/config-refactor

to apply fixes. The refactor skill reads this file as its spec.


使用稳定ID（`CRIT-1`、`WARN-1`、`SUGG-1`……）以便`config-refactor`能准确引用。

Step 5 — Print summary to chat

步骤5 — 向聊天窗口打印摘要

After writing the report, print a compact summary to the user:

The three counts.
The top 3 CRITICAL findings (title + file only).
The path to the full report.
One closing line: "Run
```
/config-refactor
```
to apply, or open the report to triage first."

Do NOT propose fixes inline. The refactor skill owns that.

生成报告后，向用户打印简洁摘要：

三类问题的数量。
前3个严重错误发现（仅标题和文件）。
完整报告的路径。
结束语："运行
```
/config-refactor
```
应用修复，或先打开报告进行分类处理。"

请勿在聊天窗口中直接提出修复方案。修复工作由refactor skill负责。

Rules

规则

Read-only. This skill never edits any file other than
```
audit-report.md
```
.
Never invent rules. Every finding cites a principle from
```
docs/config-guidelines.md
```
.
If a check would produce more than 20 findings of the same severity for the same file, collapse them into one finding ("File has 23 lines exceeding token budget by …") to keep the report readable.
Deterministic ordering: CRITICAL before WARNING before SUGGESTION; inside each, ordered by file path then line number.
The report MUST be self-contained —
```
config-refactor
```
reads only
```
audit-report.md
```
and
```
docs/config-guidelines.md
```
, never the original conversation.
Audit only the files listed in Step 2. Do not expand scope mid-run.

只读模式。本Skill仅编辑
```
audit-report.md
```
，绝不修改其他任何文件。
不得自行制定规则。每个发现必须引用
```
docs/config-guidelines.md
```
中的原则。
若同一文件同一严重级别的检查发现超过20个，需合并为一个发现（例如："文件有23行超出Token预算……"）以保证报告可读性。
确定性排序：严重错误优先于警告，警告优先于建议；同一级别内按文件路径和行号排序。
报告必须自包含——
```
config-refactor
```
仅读取
```
audit-report.md
```
和
```
docs/config-guidelines.md
```
，绝不读取原始对话内容。
仅审核步骤2中列出的文件。运行过程中不得扩大范围。

config-audit

Original

Translation

config-audit

config-audit

Process

流程

Step 0 — Detect execution context

步骤0 — 检测执行上下文

Step 1 — Locate guidelines

步骤1 — 定位指南

Step 2 — Enumerate target files

步骤2 — 枚举目标文件

Step 3 — Run check matrix

步骤3 — 运行检查矩阵

Token-budget checks (Principle 4)

Token预算检查（原则4）

Separation-of-concerns checks (Principle 2)

关注点分离检查（原则2）

Anti-duplication checks (Principle 3)

反重复检查（原则3）

OS-correctness checks (Principle 5)

系统正确性检查（原则5）

Engram-ownership checks (Principle 9)

Engram归属检查（原则9）

Force-read-inline table checks (Principle 10)

强制内联读取表格检查（原则10）

Skill format checks (Principle 8)

Skill格式检查（原则8）

Two-layer duplication checks (Principle 13, project mode only)

双层重复检查（原则13，仅项目模式）

Orphan checks in ~/.claude/ (Principle 12, global mode only)

~/.claude/孤立文件检查（原则12，仅全局模式）

Cross-reference checks (general)

交叉引用检查（通用）

Step 4 — Write the report

步骤4 — 生成报告

Configuration Audit Report

Configuration Audit Report

Summary

Summary

Findings

Findings

CRITICAL

CRITICAL

[CRIT-1] <one-line title>

[CRIT-1] <one-line title>

WARNING

WARNING

SUGGESTION

SUGGESTION

No-issues sections

No-issues sections

Next step

Next step

Step 5 — Print summary to chat

步骤5 — 向聊天窗口打印摘要

Rules

规则

Orphan checks in
`~/.claude/`
(Principle 12, global mode only)

`~/.claude/`
孤立文件检查（原则12，仅全局模式）