hekouwang-claude-md-doctor-skill

会勇禾口王的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 质量"的请求都应触发。

会勇禾口王的AI笔记@huiyonghkw

Install

openclaw skills install @huiyonghkw/hekouwang-claude-md-doctor-skill

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 的私有品牌字体与版式，不随本仓库分发。

触发"出图 / 报告卡 / 图表 / 可视化"时怎么办：

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

与内置 `/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 的活。

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

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

text

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