CLAUDE.md Doctor Skill：给项目记忆做体检的临床级 Skill 维护工具

Skill超级捕获手 技术创作者 2026-09-01 13 阅读

CLAUDE.md / AGENTS.md 已经成了 Claude Code 项目的「宪法」——决定模型每一次启动时记住哪些规矩、按什么流程干活。可多数团队写完就再没回头看过，等出现「明明写了不许用 npm，agent 还是跑了 npm」「package.json 里压根没有 typecheck 命令，CLAUDE.md 却写得有」这种坑时，已经没人记得是哪一条规则失效了。agent-clinic/claude-md-doctor 正是为这个痛点而生：把 CLAUDE.md 当病人，给它做体检、看历史会话的回测、开出处方。

总结

CLAUDE.md Doctor 是面向 Claude Code / Cursor 等 AI 编程 Agent 的「项目记忆体检 Skill」。一站式审计项目里所有 CLAUDE.md / AGENTS.md / .claude/rules/*.md，对照官方规范量出有效体积、找出失效的 @import、过期的脚本和不存在的文件路径，再把每条规则拿到用户真实 session transcript 里跑回测，告诉你「这一条 agent 实际遵守了多少」。最终吐出一份带图表、含证据链、可一键落 HTML 的医生风格报告。仓库上线一周即被 skilld.dev 周 trending 收录，社区短时间收下 50+ 赞，是 2026 年下半年 Skill 维护方向最具代表性的「诊断类」新秀。

功能与原则

核心能力由「静态体检 + 历史回测 + 处方生成」三段组成：

  • Vitals（生命体征）：度量每个 CLAUDE.md 的有效行数（官方目标 <200 行）、估算每 session 的 token 开销、识别 /init 模板从未删改、强调符号过饱和、把 changelog 漂进项目指令等病理特征。
  • Records check（病历核对）：扫描所有 @import、paths: scope、点名的脚本，定位已经不存在或属于同事机器的死链，揪出写了却没装的 npm/pnpm/make 指令。
  • Checkable claims（可验证声明）：对文件里可数化的断言（如「2,100 个测试跨 180 个文件」）逐项回查 repo，捕捉数字陈旧。
  • Session backtest（会话回测）：把规则拆出来，在 ~/.claude/projects/ 的历史 transcript 里逐条验算，给出每条规则的 Opportunities / Compliance / Verdict（healthy / ignored / inert）。
  • 处方 + Hook 武装阶梯：根据违规原因（defiance / dilution / absence / defiance-proven）匹配 reminder → warn → block 的 hook 强度，写到「review-then-arm」文件夹，绝不自动安装。

设计原则：审计由 Python 标准库本地完成，不上传任何项目字符串；每条结论都附 citation；不强制修改任何文件，agent 只负责诊断、用户决定治疗。

认可度

  • GitHub Star：截至 2026-09-01 约 26 ★（仓库仅上线 7 天，仍处于早期爆炸期）；Forks 1。
  • Skill 市场收录：skilld.dev 周榜 trending（@trisgwync 4 天前发布，52 likes，单帖传播力极高）；同步被 eliteai.tools、lobehub、askill.sh、skilld.dev 收录。
  • 社媒讨论量：X/Twitter @trisgwync 首发；r/ClaudeCode 论坛同期出现 FAQ 比对讨论；GitHub Discussions 暂未开放。
  • Trending 经历：曾出现在 skilld.dev 「Trending Agent Skills This Week, September 2026」周榜上游。

注：因仓库创建于 2026-08-25，Star 数仍处于「早期冷启动」，但社区点赞数（52 likes / 4 天）和 13 个官方 topic 标签（agent-skills / claude-skills / context-engineering 等）已经印证它在 Skill 维护者圈层的影响力。

链接

  • GitHub：https://github.com/agent-clinic/claude-md-doctor
  • skilld.dev 周榜入口：https://skilld.dev/gh/agent-clinic/claude-md-doctor/claude-md-doctor
  • SKILL.md（原始）：https://github.com/agent-clinic/claude-md-doctor/blob/main/skills/claude-md-doctor/SKILL.md

原作者

Tristan Chen（GitHub：tx871217 / X：@trisgwync），agent-clinic 组织创始人。该组织于 2026-08-25 成立，专注「给 Agent 工作流做临床级诊断」的 Skill 工具集，本仓库是首个公开项目。Tristan 在 r/ClaudeCode 社区长期分享 Claude Code 工作流洞见，对项目记忆 / Hook 工程 / 上下文工程有系统化整理。

介绍

CLAUDE.md Doctor 把检查工程分成 5 个 stage：

  1. Intake（挂号）：扫描 repo + 全局 + 祖辈目录的所有 CLAUDE.md / AGENTS.md / .claude/rules/*.md；识别 pointer（@AGENTS.md）是否健康——裸文本 pointer 是「Claude Code 永远不会加载目标」的危险模式。
  2. Vitals（生命体征）：度量体积、token 成本、结构、/init 残留、emphasis 密度等指标。
  3. Records（病历核对）：核对所有被引用路径、脚本、globs 的有效性。
  4. Checkable claims（可验证声明）：把文件里数字、组件数、命令数等跟真实 repo 对账。
  5. Adherence backtest（依从回测）：把每条规则拆出来，在 ~/.claude/projects/ 的历史 transcript 里逐条跑——「规则 X 在最近 N 次会话里被遵守的比例是多少」，并给出每条规则的 verdict 和 cause。
  6. Report（处方）：最终输出单文件自包含 HTML 报告 + JSON 报告 + 一个 share-safe card（不暴露项目字符串）。

整个过程只用 Python 3.9+ 标准库，零外部依赖、零网络请求、零数据上传，完全适合放进 CI 或本地脚本循环跑。

特点

  • 真·回测：不只看 CLAUDE.md 写得好不好，还拿真实会话历史去验算「规则有没有被遵守」，比单纯静态 lint 多一层证据链。
  • Hooks 武装阶梯：根据违规原因（defiance / dilution / absence）精准匹配 reminder / warn / block 三档 hook，写到「review-then-arm」目录，绝不自动安装——避免一刀切把生产环境卡死。
  • 无 CLAUDE.md 也能用：自动 reverse mode，挖掘 session transcript 里的重复修正、失败-修复对、权限拒绝、重复前言等信号，反向生成 PROPOSED-CLAUDE.md，每条规则带 HTML comment 形式的 receipt（加载时自动剥离，零 token 浪费）。
  • 认识完整记忆面：理解 CLAUDE.local.md、嵌套文件、.claude/rules/ 的 paths: scope、@import 深度 4、ancestor 目录、claudeMdExcludes 等真实 Claude Code 行为，避免「误诊 pointer 文件太短」这种常见错误。
  • 本地零依赖：仅 Python 3.9+ 标准库，可直接跑在 CI / 离线机器 / air-gapped 环境。

使用方法

方式 1 — Claude Code plugin（推荐）

/plugin marketplace add agent-clinic/claude-md-doctor
/plugin install claude-md-doctor

方式 2 — skills.sh CLI

npx skills add agent-clinic/claude-md-doctor

方式 3 — 裸安装

git clone https://github.com/agent-clinic/claude-md-doctor.git
cp -r claude-md-doctor/skills/claude-md-doctor/ ~/.claude/skills/

最小调用

在任意 repo 里对 agent 说：

“Give my CLAUDE.md a checkup”

或直接 /claude-md-doctor:claude-md-doctor（bare 安装则是 /claude-md-doctor）。

输出落到 .claude-md-doctor/report.html 与 report.json，外加一个可贴 README 的 claude-md-health.svg 徽章。

使用场景与人群

  • 典型场景：
  • 项目 onboarding：新人接手一个跑了一年的 Claude Code repo，先跑一遍体检，找出真正还有效的规则。
  • 规则失效定位：发现「agent 老是不按规矩来」，但不知道是哪条规则没起作用——回测表里直接看 verdict 列。
  • 季度规则审阅：CI 里跑一次，把 health badge 贴到 README，对外展示项目记忆治理水平。
  • 0 → 1 起步：还没有 CLAUDE.md 的 repo，启用 reverse mode 自动从 session 挖掘成稿。
  • 目标人群：Claude Code 高级用户 / 团队 Lead、Agent 工作流研究者、关注 Context Engineering 实践的开发者。

输入与输出案例

案例 1：典型「写了但没装」病历

输入（repo 的 CLAUDE.md 片段）：

“`markdown

Critical Rules

  • Always run pnpm typecheck before finishing
  • Never hardcode a colour — use the design tokens
  • Never import legacy API types
    “`

Doctor 输出（节选）：

Rule Opportunities Compliance Verdict
Run pnpm typecheck before finishing 2 0% ignored
Never hardcode a colour 0 — inert
Never import legacy API types 12 100% healthy

处方：pnpm typecheck 脚本不存在 → 移到 .claude/rules/point-of-use.md 或在 package.json 里补齐；「Never hardcode a colour」0 次机会 → 删除或挪到具体组件文件头。

案例 2：0 → 1 reverse mode

输入：repo 完全没有 CLAUDE.md，但 ~/.claude/projects/ 里有 40 段会话 transcript。

Doctor 挖掘后产出的 PROPOSED-CLAUDE.md 摘要：

“`markdown

– Always use pnpm, never npm



– Run pnpm --version before installing any dependency
“`

每条规则的 HTML comment receipt 在 Claude 加载时自动剥离，不消耗任何 token；hook-class 规则还会同时落到 review-then-arm/ 文件夹，等用户确认后再装。

GitHub: https://github.com/agent-clinic/claude-md-doctor

评论区

0 条评论

登录后可评论。

Skill超级捕获手 13 阅读