hekouwang-claude-md-doctor-skill

SKILL.md

---
name: hekouwang-claude-md-doctor-skill
slug: hekouwang-claude-md-doctor-skill
displayName: CLAUDE.md / AGENTS.md 体检器
summary: AGENTS.md / CLAUDE.md linter & skill lint companion — Agent runtime config audit (not a project wiki). Dual-file dedup + .agents/skills/ routing.
license: MIT
homepage: https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill
version: 1.3.3
description: >
  会勇禾口王的AI笔记 · Agent 运行时配置体检器。检查项目的 AGENTS.md（跨 Agent 推荐）
  或 CLAUDE.md（及子目录本地配置）是否符合"把它当运行时配置、不是项目说明书"的最佳实践，
  给出评分卡 + 按优先级的修复建议，并可代为修复。触发：用户说「检查我的 CLAUDE.md /
  AGENTS.md / 运行时配置体检 / claude-md-doctor / agents.md 规范吗 / audit CLAUDE.md /
  lint AGENTS.md / 看看我的 agent 配置合不合规」。
  任何"评估/审查/优化某个项目 AGENTS.md 或 CLAUDE.md 质量"的请求都应触发。
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - AskUserQuestion
---

# hekouwang-claude-md-doctor-skill · Agent 运行时配置体检器

> **会勇禾口王的AI笔记** 出品 · `@huiyonghkw`
> GitHub: <https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill>
> _不聊 AI 会不会取代你，只聊先用 AI 的人怎么取代你。_

把"Agent 运行时配置最佳实践"做成一个能跑在任何项目上的检查器：机检定量 + 模型定性，
产出评分卡和可落地的修复建议。核心判据一句话——

> **AGENTS.md / CLAUDE.md 是每次会话都被重新加载、要付上下文费的"运行时配置"，不是给人读的项目说明书。**
> 2026 年起 Cursor / Codex / OpenClaw 等多读 **AGENTS.md**；Claude Code 仍读 **CLAUDE.md**。
> 一切检查项都从这句推导：值不值得每次会话都为这段内容付一次费？

### 减法优先（元判据 · 凌驾全部检查项之上）

Claude Code 之父 Boris Cherny 公开说自己的配置"surprisingly vanilla"、几乎不定制；
联合创造者 Cat Wu 自称 "context minimalist"——只告诉模型它需要知道的，剩下让它自己想。
**核心立场：模型每代都在变强，你今天费劲搭的脚手架很快白搭；别跟模型较劲做加法。**

所以下面这些检查项里凡是"让用户往里加内容"的(禁止清单/Hook/记忆/人格/本地文件)，
落地前都先过这一关 —— **加任何一段前先问：这条能不能不写在常驻正文里？**

- 能挂 **Hook**(确定性规则)→ 挂 Hook，别写正文(模型不必每次读)。
- 能下沉 **docs/** 的 → 下沉，正文留一行指针。
- 能靠 **linter / 类型检查 / 测试**兜住的 → 删掉，别让模型干 linter 的活。
- 通用写法 / 主流框架用法 → 删掉，那是模型已经会的(见 #10)。
- **只有"模型会反复犯错、且没有机械手段能兜住"的，才值得占常驻 token。**

机检层面：**#1 篇幅 / #3 可操作 / #4 路由器 / #10 别替模型补**这几项是减法核心，权重更高；
"加内容"类项(#6/#7/#8)缺失只算小扣分，避免工具一边喊"越短越好"、一边逼用户把文件写长。

## 品牌人设（体检报告的口吻 + 署名）

这套工具属于 **会勇禾口王的AI笔记**（定位：AI 实战拆解，硬核·具体·可复制；人设：你办公室里第一个把 AI 用明白的同事）。出体检报告时：

- **口吻**：像同事帮你看代码——直给结论、敢泼冷水（"这条是空话，5 秒判不了就是不合格"），不说"Great question / 我很乐意帮忙"这类客套。
- **价值化**：修复建议讲"省了什么"（少几十次会话的冗余、挡住一次资损/越权），不堆术语。
- **署名**：报告结尾固定带一行品牌签收 —— `—— 会勇禾口王的AI笔记 · @huiyonghkw`，并可附 slogan。命令行 `check.py` 的报告页脚已内置该署名。
- **去 AI 味**：定稿前避开"赋能/打造/至关重要/助力"等词，说人话。

---

## 免费 / 付费边界（重要）

- **免费（开源内核）**：`check.py` 的**文本 / JSON 报告 + 评分**。任何人本地或 Docker 跑、进 CI，随便用。
- **付费（增值）**：**品牌可视化体检报告卡**（评分弧 + 等级带 + 九项明细的精美分享图）。
  它依赖 `hekouwang-content-factory` 的**私有品牌字体与版式**，不随本仓库分发。

**触发"出图 / 报告卡 / 图表 / 可视化"时怎么办**：
1. 先照常给**免费文本报告**（机检 + 定性复核）。
2. 是否生成图：检查本机有没有 `hekouwang-content-factory`（品牌字体在
   `~/.claude/skills/hekouwang-content-factory/assets/fonts/`）。
   - **有**（作者本人环境）：可按 V2 米白生成报告卡 PNG。
   - **没有**（外部用户）：明确说明可视化报告是**付费增值项**，引导联系 **@huiyonghkw** 获取，
     不要用系统字体凑一张劣化图糊弄。
3. 一句话口径：**跑检查免费，出"好看的报告图"找我。**

---

## 与内置 `/doctor` 命令的分工（名字像，别混用）

Claude Code 内置了一个 `/doctor` 命令，名字也带 "doctor"，但**体检对象和本 skill 完全不同**——
一个查整套工具的运行环境，一个只查一份文档写得好不好。别把两者当同一个东西。

| 维度 | 内置 `/doctor` 命令 | 本 skill（claude-md-doctor） |
|------|--------------------|------------------------------|
| **体检对象** | 整个 **Claude Code 运行环境 / 安装** | 单个项目的 **CLAUDE.md 文件本身** |
| **关注点** | 安装健康、未用扩展(skill/MCP/plugin)、常驻上下文膨胀、慢 Hook、版本、权限模式、预批命令、本地记忆去重 | CLAUDE.md 是否「当运行时配置写而非项目说明书」、篇幅、该不该懒加载、评分卡 + 分级修复 |
| **改哪里** | `~/.claude/` 配置层（settings.json、skillOverrides、`.claude.json`） | 项目里的 `CLAUDE.md` / 子目录本地 CLAUDE.md 内容 |
| **作用范围** | 全局 · 跨所有项目的工具链 | 就这一个项目的文档 |
| **产物** | 环境体检报告 + 两道确认后改配置 | 评分卡（10 项）+ Top 3 修复建议，可代改 |

**唯一交集**：`/doctor` 的 **Check 2 / Check 3** 会碰 CLAUDE.md——去重本地 vs 入库 CLAUDE.md、
把该懒加载的内容迁到 skill/子目录。但它是从**「上下文成本」**这一个角度看，只管「有没有重复、该不该常驻」，
**不评文档质量**；本 skill 才从**「写法规范」**全面打分（可操作性、禁止清单、高危护栏、30 秒三问……）。

### 用法建议

- **想知道「我这套 Claude Code 装得干净、跑得健康吗」** → 跑内置 `/doctor`。
- **想知道「我这个项目的 CLAUDE.md 写得规范吗」** → 触发本 skill。
- **两者串起来用（推荐）**：先 `/doctor` 体检环境，若它在 Check 3 提示「CLAUDE.md 太大 / 该懒加载」，
  接着用本 skill 深度评一份 + 出 Top 3 + 代重构——`/doctor` 负责发现「这份文档偏大」，本 skill 负责回答「具体哪几条该删、怎么下沉」。
- **别指望 `/doctor` 替你把 CLAUDE.md 写规范**：它只做去重和迁移，不判「这条规则是不是空话」「禁止清单缺不缺」——那是本 skill 的活。

---

## 工作流（每次体检按这个顺序）

1. **确认目标目录**：用户没指明就用当前工作目录；说了某项目就用那个绝对路径。
2. **跑机检**（确定性层，零依赖）：
   ```bash
   python3 <此skill目录>/check.py <项目目录>
   ```
   - 需要结构化结果时加 `--json`（便于你解析后二次判断）。
   - 退出码：有 FAIL → 1，否则 0。
3. **定性复核**（机检之上，必须做）：机检是启发式，几项需要你**真正读正文**再下结论：
   - 实际打开根 `AGENTS.md` 或 `CLAUDE.md` 通读一遍（机检已自动选优先级更高的那份）；
   - 用下面《评分标准》逐条核对，**重点修正机检可能误判的项**（见"机检的盲区"）；
   - 抽查 1–2 个子目录本地 AGENTS.md / CLAUDE.md 是否写了真红线（不是空模板）。
4. **出报告**：先给一句话总评 + 分数档位，再用"✓/▲/✗ + 一句话 + 修复建议"逐条列，
   最后给 **Top 3 最该先改的**（按"花最小力气补最大漏洞"排序）。中文输出。
5. **提出代修复**：问用户要不要直接改（瘦身下沉 docs/、补禁止清单、补工作风格块、
   加高危模块本地 CLAUDE.md、配 Hook 等）。**得到同意再动文件**，一次改一类、可回退。

> 不要只把脚本输出原样贴给用户——脚本是线索，你的价值在定性判断 + 具体怎么改。

---

## 评分标准（12 项 · 也是机检的判分依据）

| # | 检查项 | 合格长什么样 | 不合格信号 |
|---|--------|------------|-----------|
| 0 | **无硬编码密钥（安全红线）** | 正文不出现 key/token/私钥/口令明文 | 出现 `sk-`/`AKIA`/私钥块/`password="..."` → **直接 FAIL** |
| 0b | **AGENTS + CLAUDE 不双份加载** | 只留一份真源；另一份是一行指针 | 根目录两份都「厚」、内容重复 → **WARN**（双倍上下文费） |
| 1 | **篇幅 ≤ 200 行** | 路由器不是图书馆，常驻越短越好 | >200 行；大段历史/营销/教程正文 |
| 2 | **禁止清单（Do NOT）** | 有"不要引入 X（因为 Y）"清单 | 只列要用的、不列禁用的 |
| 3 | **规则可操作** | 5 秒内能判定代码合不合规 | "写干净代码/优雅/高质量"这类空话 |
| 4 | **路由器不是图书馆** | 大块下沉 docs/，正文留指针（认 docs/ 文本指针与原生 `@import`） | 架构图/长表/历史塞在常驻正文 |
| 4b | **指针无死链** | docs/ 与 `@import` 都指向真实存在的文件 | 指针指向不存在的文件（按图索骥扑空，比没指针更糟） |
| 4c | **细则路由到 Skill** | 工作流细则在 `.agents/skills/`，正文留指针 | 有 skills 目录但正文很长且不提路由 |
| 5 | **高危模块本地配置** | 碰钱/认证/迁移目录各有 AGENTS.md 或 CLAUDE.md | 敏感模块只靠根文件一句话 |
| 6 | **Hook 强制层** | 最不能漏的规则挂成 Hook | 关键规则只"写着"靠模型记 |
| 7 | **MEMORY.md 回路** | 任务前读、任务后写的跨会话记忆 | 每次会话从零重新认识项目 |
| 8 | **工作风格块**（限 3–5 行） | 写了"你是谁/你讨厌什么/协作节奏"，且每行都指向一个"不写就会犯的具体错" | 没有人格；或写成性格小作文 |
| 9 | **30 秒三问** | 陌生人读完能答：产品？技术栈？新代码放哪 | 开头答不出这三问 |
| 10 | **别替模型补它已经会的** | 不教通用写法/主流框架用法，只装项目私有事实 | 有"如何使用 X / 使用教程 / step by step"这类随模型升级很快过时的教学段 |

**分档**：A 优秀 ≥85 · B 良好 ≥70 · C 及格 ≥50 · D 建议重写 <50。
（机检：PASS=1 / WARN=0.5 / FAIL=0，INFO 不计分。**按重要度加权**——安全红线 #0 与
减法核心项 #1/#3/#4/#10 权重 1.5，标准项 #0b/#2/#4b/#4c/#5/#9 为 1.0，加内容项 #6/#7/#8 为 0.6。
#0 命中按 FAIL 计且资损级，定性总评里应一票顶到「先改这条」。）

---

## 机检的盲区（定性复核时重点纠偏）

脚本只能判"机器能确定的"，以下几项**容易误判，必须你读正文定夺**：

- **#4 图书馆 vs 路由器**：脚本只按"大代码块/大表/历史标题"猜。
  - **目录树是路由地图，应保留**（脚本已不把纯 `├──└──` 树当图书馆图）；
  - 但"版本表/环境表"这类**真铁律**即使是表格也该留正文——别因为是表就建议下沉；
  - 反过来，一段没有特征字符的长叙事，脚本可能漏判，你要自己看出来。
- **#3 规则可操作**：脚本靠模糊词黑名单，可能误伤（如正文在"反对写干净代码这种空话"），
  也可能漏判（换了说法的空话）。读上下文再定。
- **#5 高危模块**：脚本按目录名猜（payment/auth/...），可能漏掉项目里叫法特殊的高危模块，
  也可能把无关同名目录算进来。结合项目实际业务判断。
- **#9 30 秒三问**：脚本只看关键词信号在不在；你要**真的当一次陌生人**读开头，看能不能答出。
- **#10 别替模型补它已经会的**：脚本只按"教程/如何使用/step by step"等措辞猜，会误伤——
  比如正文在写"本项目**自研**框架的用法"(模型确实不知道，该留)，或在"反对写教程"。
  读上下文定夺：**判据是"这段知识模型升级后会不会自动变强"**，会 → 删；不会(项目私有) → 留。
  - **本 skill 自检会触发 #10 误报**：因为正文里就列着"教程/如何使用/step by step"这些**待检测的黑名单词**（评分表、机检盲区、修复清单都得举例它们）——这是元层面的正常现象，定性时直接放行，别去删那些词（删了这个体检器就不工作了）。

---

## 安全红线（务必遵守）

- **绝不读取密钥文件**：`.env` / `.env.*` / `*.key` / `*.pem` / `*secret*` 一律不打开（脚本本身也不读）。
  需要某个非密钥值时，让用户用 `! grep KEY 文件` 自己取。
- 体检是只读操作；**任何文件改动都要先说明改哪些、为什么，得到同意再动**。
- 多语言/多框架项目通用——本 skill 不绑定任何具体技术栈。

---

## 修复动作清单（用户同意后按需执行）

- **拔密钥（最高优先）**：#0 命中时先把明文 key/token/私钥/口令移出 CLAUDE.md，改放
  `.env`／密钥管理器，正文最多留「见环境变量 XXX」；命中即视为已泄露，提醒用户**轮换**该凭据，
  并检查是否已被提交进 git（如是需清历史）。
- **修死链**：#4b 报的死指针——补上缺失的 docs 文件，或修正/删除指针。
- **瘦身**：把架构图/前端技术栈表/路由表等"图书馆"内容迁到 `docs/architecture.md`、
  `docs/runtime.md`，正文替换成一行指针（Tier 2 按需打开，不预读）。
- **补禁止清单**：和用户确认项目已淘汰/冲突的库与做法，写成 Do NOT 清单。
- **可操作化**：把"干净/简洁"改写成具体可判定规则。
- **删教学型冗余**：把"如何使用 X / 主流框架用法 / step by step 教程"这类段落删掉——
  模型已经会、且随升级自动变强，留着只是为"很快过时的东西"每次付上下文费。
- **加高危护栏**：给 payment/auth 等目录新建本地 CLAUDE.md（安全红线 + 已知陷阱 + 改动前确认）。
- **配 Hook**：把"改完跑测试/格式化/改 .env 提醒重启"等做成 `.claude/settings.json` 的
  Pre/PostToolUse Hook（告警型即可，别默认做有破坏性的自动执行）。
- **记忆回路**：在 CLAUDE.md 加"任务前读 MEMORY.md、任务后写回"指令。
- **工作风格块**：顶部加"My Working Style"（先方案后代码、列选项不猜、讨厌的回复腔等）。
- 改完**重新跑一次 `check.py`** 给前后对比分数。

---

## 落地骨架（建文件/重写时的推荐结构，≤200 行）

```
# 项目名
## 30 秒速览      # 产品 / 技术栈 / 新代码放哪 + 优化优先级
## 工作风格        # 你是谁、你讨厌什么、协作节奏（限 3–5 行，每行都对应一个"不写就会犯的错"，别写性格小作文）
## 跨会话记忆      # 任务前读 MEMORY.md，任务后写回
## 铁律            # 编号、可执行、带后果（含 Do NOT 清单）
## 关键事实表      # 版本 / 环境等不可由代码自查的硬信息（真铁律，留正文）
## 目录结构        # 新代码放哪里（路由地图，可留正文）
## 延伸文档        # Tier 2 指针：docs/...，按需打开不预读
## 规划中功能      # 尚未落地，别假设已存在
```