{"id":"82348997-454d-4231-adfe-0491390bf1e1","entityType":"agent","slug":"clawhub-huiyonghkw-hekouwang-claude-md-doctor-skill","name":"hekouwang-claude-md-doctor-skill","canonicalUrl":"https://www.xpersona.co/agent/clawhub-huiyonghkw-hekouwang-claude-md-doctor-skill","canonicalPath":"/agent/clawhub-huiyonghkw-hekouwang-claude-md-doctor-skill","generatedAt":"2026-10-11T17:46:46.528Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T13:59:24.371Z","emptyReason":null},"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 质量\"的请求都应触发。","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17639bexg8w6nymygatvtx99585dbjd:hekouwang-claude-md-doctor-skill","sourceUrl":"https://clawhub.ai/huiyonghkw/hekouwang-claude-md-doctor-skill","homepage":"https://clawhub.ai/huiyonghkw/skills/hekouwang-claude-md-doctor-skill","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/huiyonghkw/hekouwang-claude-md-doctor-skill","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/huiyonghkw/skills/hekouwang-claude-md-doctor-skill","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"hekouwang-claude-md-doctor-skill technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T13:59:24.371Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T13:59:24.371Z","emptyReason":null},"stars":null,"forks":null,"downloads":1053,"packageName":null,"latestVersion":"1.3.2","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T13:59:24.357Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T13:59:24.371Z","lastCrawledAt":"2026-10-11T13:59:24.357Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T13:59:24.357Z","lastVerifiedAt":null,"highlights":[{"version":"1.3.2","createdAt":"2026-08-12T11:37:00.249Z","changelog":"ClawHub category: development","fileCount":23,"zipByteSize":45845},{"version":"1.3.1","createdAt":"2026-08-12T08:02:43.033Z","changelog":"doctor-suite + README freemium","fileCount":23,"zipByteSize":45674},{"version":"1.3.0","createdAt":"2026-08-12T06:58:32.960Z","changelog":"**AGENTS.md 体检新增，覆盖多种 Agent 运行时配置** - 支持检查项目中的 AGENTS.md 和 CLAUDE.md（自动优先级选择），适配跨 Agent 平台。 - 新增 3 项检测：AGENTS + CLAUDE 不双份加载、细则路由到 skills 目录、本地高危模块通用。 - 测试结构增强，加入多组 AGENTS.md/CLAUDE.md/dual 配置用例。 - 文件检测与核心描述文本全面升级，文档与代码同步支持并强调 AGENTS.md。 - 移除 skill-card.md，完善 README/变更记录说明。 （如需报告可视化，现已明确为付费增值项。）","fileCount":21,"zipByteSize":42805},{"version":"1.2.2","createdAt":"2026-07-15T15:22:09.096Z","changelog":"补齐本地领先的两个版本（1.2.1 / 1.2.2）。SKILL.md 声明 allowed-tools 收敛越权面；补「本 skill 自检会触发 #10 误报」豁免说明——正文里的「教程/如何使用/step by step」是待检测的黑名单词本身，机检误报教学冗余，定性时直接放行。","fileCount":14,"zipByteSize":36653},{"version":"1.1.2","createdAt":"2026-06-22T07:22:13.775Z","changelog":"自体检（用姊妹工具 skill-doctor 跑）后的两处打磨： 优化 SKILL.md 声明 allowed-tools：收敛到本 skill 真正需要的工具集，减小越权面。 补「本 skill 自检会触发 #10 误报」豁免说明：正文里的\"教程/如何使用/step by step\"是 待检测的黑名单词本身（评分表/盲区/修复清单都要举例），机检会误报教学冗余—— 与 skill-doctor 对齐，注明定性时直接放行，别删那些词（删了体检器就不工作）。","fileCount":14,"zipByteSize":33846},{"version":"1.1.1","createdAt":"2026-06-21T13:44:17.043Z","changelog":"对照社区教程 luongnv89/claude-howto 的 Memory 最佳实践逐条比对，补上三处真空白（只取\"安全 + 机制正确性\"，不取\"把文件写全\"的加法倾向）： - 🔴 新增安全红线 #0「无硬编码密钥」:扫正文里的 sk-/AKIA/AIza/gh*_/xox*/JWT/私钥块/password=/secret= 等指纹,命中即 FAIL(权重 1.5,资损级)。报告对命中值脱敏(前 4 位 + 长度);占位/示例值(<your-pwd>/${VAR}/example)自动豁免。 - 🟡 新增 #4b 指针死链检查:docs/ 文本指针与原生 @import 路径都校验目标文件是否存在,死链 → WARN。 - #4 路由器检查认原生 @import 语法:此前只认纯文本 docs/...,现在官方 @path 导入也算合格的\"下沉指针\"。 - 文档/测试同步:评分表补 #0 与 #4b,good 夹具加 docs/ 桩文件示范指针可解析。","fileCount":14,"zipByteSize":33358},{"version":"1.1.0","createdAt":"2026-06-18T04:46:10.786Z","changelog":"hekouwang-claude-md-doctor-skill 1.1.0 - 核心方法升级：增加“减法优先”元判据，明确强调“只保留必需内容，优先精简 CLAUDE.md”，优化所有检查与修复建议的权重和流程。 - 评分标准增至 10 项，新增“别替模型补它已经会的”检查项，并调整权重体系，突出减法核心指标。 - 优化“工作风格块”要求，明确限 3–5 行、每行需指向具体易犯错点，禁止写性格小作文。 - 丰富定性复核指导，详细说明核心检查项常见误判情形和判据。 - 移除 skill-card.md 文件，保持项目结构轻量。 - 增补公开出处与品牌定位描述，完善用户认知与复用引导。","fileCount":12,"zipByteSize":29520},{"version":"1.0.0","createdAt":"2026-06-17T07:06:57.439Z","changelog":"Initial release of hekouwang-claude-md-doctor-skill: - Provides automated compliance checks for project CLAUDE.md files, focusing on \"runtime config\" best practices. - Delivers a scored report with prioritized, actionable fix recommendations. - Differentiates between free (text/JSON report, scoring) and paid (visual report card) features. - Enforces a direct, practical feedback style with branded signature for every report. - Secures check workflow: only reads files, explicit user consent required before any file edits. - Compatible across different project types and languages; does not access secrets.","fileCount":12,"zipByteSize":25734}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17639bexg8w6nymygatvtx99585dbjd:hekouwang-claude-md-doctor-skill","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17639bexg8w6nymygatvtx99585dbjd:hekouwang-claude-md-doctor-skill` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/huiyonghkw/hekouwang-claude-md-doctor-skill before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-huiyonghkw-hekouwang-claude-md-doctor-skill/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-huiyonghkw-hekouwang-claude-md-doctor-skill/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-huiyonghkw-hekouwang-claude-md-doctor-skill/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-huiyonghkw-hekouwang-claude-md-doctor-skill/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-huiyonghkw-hekouwang-claude-md-doctor-skill/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-huiyonghkw-hekouwang-claude-md-doctor-skill/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T17:46:46.523Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-huiyonghkw-hekouwang-claude-md-doctor-skill/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-huiyonghkw-hekouwang-claude-md-doctor-skill/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-huiyonghkw-hekouwang-claude-md-doctor-skill/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-huiyonghkw-hekouwang-claude-md-doctor-skill/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T13:59:24.371Z","emptyReason":null},"readme":"Skill: hekouwang-claude-md-doctor-skill\n\nOwner: huiyonghkw\n\nSummary: 会勇禾口王的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 质量\"的请求都应触发。\n\nTags: latest:1.3.2\n\nVersion history:\n\nv1.3.2 | 2026-08-12T11:37:00.249Z | user\n\nClawHub category: development\n\nv1.3.1 | 2026-08-12T08:02:43.033Z | user\n\ndoctor-suite + README freemium\n\nv1.3.0 | 2026-08-12T06:58:32.960Z | auto\n\n**AGENTS.md 体检新增，覆盖多种 Agent 运行时配置**\n\n- 支持检查项目中的 AGENTS.md 和 CLAUDE.md（自动优先级选择），适配跨 Agent 平台。\n- 新增 3 项检测：AGENTS + CLAUDE 不双份加载、细则路由到 skills 目录、本地高危模块通用。\n- 测试结构增强，加入多组 AGENTS.md/CLAUDE.md/dual 配置用例。\n- 文件检测与核心描述文本全面升级，文档与代码同步支持并强调 AGENTS.md。\n- 移除 skill-card.md，完善 README/变更记录说明。\n\n（如需报告可视化，现已明确为付费增值项。）\n\nv1.2.2 | 2026-07-15T15:22:09.096Z | user\n\n补齐本地领先的两个版本（1.2.1 / 1.2.2）。SKILL.md 声明 allowed-tools 收敛越权面；补「本 skill 自检会触发 #10 误报」豁免说明——正文里的「教程/如何使用/step by step」是待检测的黑名单词本身，机检误报教学冗余，定性时直接放行。\n\nv1.1.2 | 2026-06-22T07:22:13.775Z | user\n\n自体检（用姊妹工具 skill-doctor 跑）后的两处打磨：\n\n优化\nSKILL.md 声明 allowed-tools：收敛到本 skill 真正需要的工具集，减小越权面。\n补「本 skill 自检会触发 #10 误报」豁免说明：正文里的\"教程/如何使用/step by step\"是 待检测的黑名单词本身（评分表/盲区/修复清单都要举例），机检会误报教学冗余—— 与 skill-doctor 对齐，注明定性时直接放行，别删那些词（删了体检器就不工作）。\n\nv1.1.1 | 2026-06-21T13:44:17.043Z | user\n\n对照社区教程 luongnv89/claude-howto 的 Memory 最佳实践逐条比对，补上三处真空白（只取\"安全 + 机制正确性\"，不取\"把文件写全\"的加法倾向）：\n\n  - 🔴 新增安全红线 #0「无硬编码密钥」:扫正文里的 sk-/AKIA/AIza/gh*_/xox*/JWT/私钥块/password=/secret= 等指纹,命中即 FAIL(权重 1.5,资损级)。报告对命中值脱敏(前\n  4 位 + 长度);占位/示例值(<your-pwd>/${VAR}/example)自动豁免。\n  - 🟡 新增 #4b 指针死链检查:docs/ 文本指针与原生 @import 路径都校验目标文件是否存在,死链 → WARN。\n  - #4 路由器检查认原生 @import 语法:此前只认纯文本 docs/...,现在官方 @path 导入也算合格的\"下沉指针\"。\n  - 文档/测试同步:评分表补 #0 与 #4b,good 夹具加 docs/ 桩文件示范指针可解析。\n\nv1.1.0 | 2026-06-18T04:46:10.786Z | user\n\nhekouwang-claude-md-doctor-skill 1.1.0\n\n- 核心方法升级：增加“减法优先”元判据，明确强调“只保留必需内容，优先精简 CLAUDE.md”，优化所有检查与修复建议的权重和流程。\n- 评分标准增至 10 项，新增“别替模型补它已经会的”检查项，并调整权重体系，突出减法核心指标。\n- 优化“工作风格块”要求，明确限 3–5 行、每行需指向具体易犯错点，禁止写性格小作文。\n- 丰富定性复核指导，详细说明核心检查项常见误判情形和判据。\n- 移除 skill-card.md 文件，保持项目结构轻量。\n- 增补公开出处与品牌定位描述，完善用户认知与复用引导。\n\nv1.0.0 | 2026-06-17T07:06:57.439Z | auto\n\nInitial release of hekouwang-claude-md-doctor-skill:\n\n- Provides automated compliance checks for project CLAUDE.md files, focusing on \"runtime config\" best practices.\n- Delivers a scored report with prioritized, actionable fix recommendations.\n- Differentiates between free (text/JSON report, scoring) and paid (visual report card) features.\n- Enforces a direct, practical feedback style with branded signature for every report.\n- Secures check workflow: only reads files, explicit user consent required before any file edits.\n- Compatible across different project types and languages; does not access secrets.\n\nArchive index:\n\nArchive v1.3.2: 23 files, 45845 bytes\n\nFiles: CHANGELOG.md (6437b), check.py (32103b), CONTRIBUTING.md (1772b), Dockerfile (763b), LICENSE (1096b), README.en.md (7688b), README.md (8092b), references/doctor-suite.md (1118b), scripts/run-all-doctors.sh (3290b), skill-card.md (2428b), SKILL.md (16199b), tests/fixtures/bad/CLAUDE.md (423b), tests/fixtures/dual/AGENTS.md (1308b), tests/fixtures/dual/CLAUDE.md (1308b), tests/fixtures/dual/docs/api.md (69b), tests/fixtures/dual/docs/architecture.md (95b), tests/fixtures/good-agents/AGENTS.md (1308b), tests/fixtures/good-agents/docs/api.md (69b), tests/fixtures/good-agents/docs/architecture.md (95b), tests/fixtures/good/CLAUDE.md (1308b), tests/fixtures/good/docs/api.md (69b), tests/fixtures/good/docs/architecture.md (95b), _meta.json (151b)\n\nFile v1.3.2:SKILL.md\n\n---\nname: hekouwang-claude-md-doctor-skill\nslug: hekouwang-claude-md-doctor-skill\ndisplayName: CLAUDE.md / AGENTS.md 体检器\nsummary: AGENTS.md / CLAUDE.md linter & skill lint companion — Agent runtime config audit (not a project wiki). Dual-file dedup + .agents/skills/ routing.\nlicense: MIT\nhomepage: https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill\nversion: 1.3.2\ndescription: >\n  会勇禾口王的AI笔记 · Agent 运行时配置体检器。检查项目的 AGENTS.md（跨 Agent 推荐）\n  或 CLAUDE.md（及子目录本地配置）是否符合\"把它当运行时配置、不是项目说明书\"的最佳实践，\n  给出评分卡 + 按优先级的修复建议，并可代为修复。触发：用户说「检查我的 CLAUDE.md /\n  AGENTS.md / 运行时配置体检 / claude-md-doctor / agents.md 规范吗 / audit CLAUDE.md /\n  lint AGENTS.md / 看看我的 agent 配置合不合规」。\n  任何\"评估/审查/优化某个项目 AGENTS.md 或 CLAUDE.md 质量\"的请求都应触发。\nallowed-tools:\n  - Bash\n  - Read\n  - Write\n  - Edit\n  - Glob\n  - Grep\n  - AskUserQuestion\n---\n\n# hekouwang-claude-md-doctor-skill · Agent 运行时配置体检器\n\n> **会勇禾口王的AI笔记** 出品 · `@huiyonghkw`\n> GitHub: <https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill>\n> _不聊 AI 会不会取代你，只聊先用 AI 的人怎么取代你。_\n\n把\"Agent 运行时配置最佳实践\"做成一个能跑在任何项目上的检查器：机检定量 + 模型定性，\n产出评分卡和可落地的修复建议。核心判据一句话——\n\n> **AGENTS.md / CLAUDE.md 是每次会话都被重新加载、要付上下文费的\"运行时配置\"，不是给人读的项目说明书。**\n> 2026 年起 Cursor / Codex / OpenClaw 等多读 **AGENTS.md**；Claude Code 仍读 **CLAUDE.md**。\n> 一切检查项都从这句推导：值不值得每次会话都为这段内容付一次费？\n\n### 减法优先（元判据 · 凌驾全部检查项之上）\n\nClaude Code 之父 Boris Cherny 公开说自己的配置\"surprisingly vanilla\"、几乎不定制；\n联合创造者 Cat Wu 自称 \"context minimalist\"——只告诉模型它需要知道的，剩下让它自己想。\n**核心立场：模型每代都在变强，你今天费劲搭的脚手架很快白搭；别跟模型较劲做加法。**\n\n所以下面这些检查项里凡是\"让用户往里加内容\"的(禁止清单/Hook/记忆/人格/本地文件)，\n落地前都先过这一关 —— **加任何一段前先问：这条能不能不写在常驻正文里？**\n\n- 能挂 **Hook**(确定性规则)→ 挂 Hook，别写正文(模型不必每次读)。\n- 能下沉 **docs/** 的 → 下沉，正文留一行指针。\n- 能靠 **linter / 类型检查 / 测试**兜住的 → 删掉，别让模型干 linter 的活。\n- 通用写法 / 主流框架用法 → 删掉，那是模型已经会的(见 #10)。\n- **只有\"模型会反复犯错、且没有机械手段能兜住\"的，才值得占常驻 token。**\n\n机检层面：**#1 篇幅 / #3 可操作 / #4 路由器 / #10 别替模型补**这几项是减法核心，权重更高；\n\"加内容\"类项(#6/#7/#8)缺失只算小扣分，避免工具一边喊\"越短越好\"、一边逼用户把文件写长。\n\n## 品牌人设（体检报告的口吻 + 署名）\n\n这套工具属于 **会勇禾口王的AI笔记**（定位：AI 实战拆解，硬核·具体·可复制；人设：你办公室里第一个把 AI 用明白的同事）。出体检报告时：\n\n- **口吻**：像同事帮你看代码——直给结论、敢泼冷水（\"这条是空话，5 秒判不了就是不合格\"），不说\"Great question / 我很乐意帮忙\"这类客套。\n- **价值化**：修复建议讲\"省了什么\"（少几十次会话的冗余、挡住一次资损/越权），不堆术语。\n- **署名**：报告结尾固定带一行品牌签收 —— `—— 会勇禾口王的AI笔记 · @huiyonghkw`，并可附 slogan。命令行 `check.py` 的报告页脚已内置该署名。\n- **去 AI 味**：定稿前避开\"赋能/打造/至关重要/助力\"等词，说人话。\n\n---\n\n## 免费 / 付费边界（重要）\n\n- **免费（开源内核）**：`check.py` 的**文本 / JSON 报告 + 评分**。任何人本地或 Docker 跑、进 CI，随便用。\n- **付费（增值）**：**品牌可视化体检报告卡**（评分弧 + 等级带 + 九项明细的精美分享图）。\n  它依赖 `hekouwang-content-factory` 的**私有品牌字体与版式**，不随本仓库分发。\n\n**触发\"出图 / 报告卡 / 图表 / 可视化\"时怎么办**：\n1. 先照常给**免费文本报告**（机检 + 定性复核）。\n2. 是否生成图：检查本机有没有 `hekouwang-content-factory`（品牌字体在\n   `~/.claude/skills/hekouwang-content-factory/assets/fonts/`）。\n   - **有**（作者本人环境）：可按 V2 米白生成报告卡 PNG。\n   - **没有**（外部用户）：明确说明可视化报告是**付费增值项**，引导联系 **@huiyonghkw** 获取，\n     不要用系统字体凑一张劣化图糊弄。\n3. 一句话口径：**跑检查免费，出\"好看的报告图\"找我。**\n\n---\n\n## 与内置 `/doctor` 命令的分工（名字像，别混用）\n\nClaude Code 内置了一个 `/doctor` 命令，名字也带 \"doctor\"，但**体检对象和本 skill 完全不同**——\n一个查整套工具的运行环境，一个只查一份文档写得好不好。别把两者当同一个东西。\n\n| 维度 | 内置 `/doctor` 命令 | 本 skill（claude-md-doctor） |\n|------|--------------------|------------------------------|\n| **体检对象** | 整个 **Claude Code 运行环境 / 安装** | 单个项目的 **CLAUDE.md 文件本身** |\n| **关注点** | 安装健康、未用扩展(skill/MCP/plugin)、常驻上下文膨胀、慢 Hook、版本、权限模式、预批命令、本地记忆去重 | CLAUDE.md 是否「当运行时配置写而非项目说明书」、篇幅、该不该懒加载、评分卡 + 分级修复 |\n| **改哪里** | `~/.claude/` 配置层（settings.json、skillOverrides、`.claude.json`） | 项目里的 `CLAUDE.md` / 子目录本地 CLAUDE.md 内容 |\n| **作用范围** | 全局 · 跨所有项目的工具链 | 就这一个项目的文档 |\n| **产物** | 环境体检报告 + 两道确认后改配置 | 评分卡（10 项）+ Top 3 修复建议，可代改 |\n\n**唯一交集**：`/doctor` 的 **Check 2 / Check 3** 会碰 CLAUDE.md——去重本地 vs 入库 CLAUDE.md、\n把该懒加载的内容迁到 skill/子目录。但它是从**「上下文成本」**这一个角度看，只管「有没有重复、该不该常驻」，\n**不评文档质量**；本 skill 才从**「写法规范」**全面打分（可操作性、禁止清单、高危护栏、30 秒三问……）。\n\n### 用法建议\n\n- **想知道「我这套 Claude Code 装得干净、跑得健康吗」** → 跑内置 `/doctor`。\n- **想知道「我这个项目的 CLAUDE.md 写得规范吗」** → 触发本 skill。\n- **两者串起来用（推荐）**：先 `/doctor` 体检环境，若它在 Check 3 提示「CLAUDE.md 太大 / 该懒加载」，\n  接着用本 skill 深度评一份 + 出 Top 3 + 代重构——`/doctor` 负责发现「这份文档偏大」，本 skill 负责回答「具体哪几条该删、怎么下沉」。\n- **别指望 `/doctor` 替你把 CLAUDE.md 写规范**：它只做去重和迁移，不判「这条规则是不是空话」「禁止清单缺不缺」——那是本 skill 的活。\n\n---\n\n## 工作流（每次体检按这个顺序）\n\n1. **确认目标目录**：用户没指明就用当前工作目录；说了某项目就用那个绝对路径。\n2. **跑机检**（确定性层，零依赖）：\n   ```bash\n   python3 <此skill目录>/check.py <项目目录>\n   ```\n   - 需要结构化结果时加 `--json`（便于你解析后二次判断）。\n   - 退出码：有 FAIL → 1，否则 0。\n3. **定性复核**（机检之上，必须做）：机检是启发式，几项需要你**真正读正文**再下结论：\n   - 实际打开根 `AGENTS.md` 或 `CLAUDE.md` 通读一遍（机检已自动选优先级更高的那份）；\n   - 用下面《评分标准》逐条核对，**重点修正机检可能误判的项**（见\"机检的盲区\"）；\n   - 抽查 1–2 个子目录本地 AGENTS.md / CLAUDE.md 是否写了真红线（不是空模板）。\n4. **出报告**：先给一句话总评 + 分数档位，再用\"✓/▲/✗ + 一句话 + 修复建议\"逐条列，\n   最后给 **Top 3 最该先改的**（按\"花最小力气补最大漏洞\"排序）。中文输出。\n5. **提出代修复**：问用户要不要直接改（瘦身下沉 docs/、补禁止清单、补工作风格块、\n   加高危模块本地 CLAUDE.md、配 Hook 等）。**得到同意再动文件**，一次改一类、可回退。\n\n> 不要只把脚本输出原样贴给用户——脚本是线索，你的价值在定性判断 + 具体怎么改。\n\n---\n\n## 评分标准（12 项 · 也是机检的判分依据）\n\n| # | 检查项 | 合格长什么样 | 不合格信号 |\n|---|--------|------------|-----------|\n| 0 | **无硬编码密钥（安全红线）** | 正文不出现 key/token/私钥/口令明文 | 出现 `sk-`/`AKIA`/私钥块/`password=\"...\"` → **直接 FAIL** |\n| 0b | **AGENTS + CLAUDE 不双份加载** | 只留一份真源；另一份是一行指针 | 根目录两份都「厚」、内容重复 → **WARN**（双倍上下文费） |\n| 1 | **篇幅 ≤ 200 行** | 路由器不是图书馆，常驻越短越好 | >200 行；大段历史/营销/教程正文 |\n| 2 | **禁止清单（Do NOT）** | 有\"不要引入 X（因为 Y）\"清单 | 只列要用的、不列禁用的 |\n| 3 | **规则可操作** | 5 秒内能判定代码合不合规 | \"写干净代码/优雅/高质量\"这类空话 |\n| 4 | **路由器不是图书馆** | 大块下沉 docs/，正文留指针（认 docs/ 文本指针与原生 `@import`） | 架构图/长表/历史塞在常驻正文 |\n| 4b | **指针无死链** | docs/ 与 `@import` 都指向真实存在的文件 | 指针指向不存在的文件（按图索骥扑空，比没指针更糟） |\n| 4c | **细则路由到 Skill** | 工作流细则在 `.agents/skills/`，正文留指针 | 有 skills 目录但正文很长且不提路由 |\n| 5 | **高危模块本地配置** | 碰钱/认证/迁移目录各有 AGENTS.md 或 CLAUDE.md | 敏感模块只靠根文件一句话 |\n| 6 | **Hook 强制层** | 最不能漏的规则挂成 Hook | 关键规则只\"写着\"靠模型记 |\n| 7 | **MEMORY.md 回路** | 任务前读、任务后写的跨会话记忆 | 每次会话从零重新认识项目 |\n| 8 | **工作风格块**（限 3–5 行） | 写了\"你是谁/你讨厌什么/协作节奏\"，且每行都指向一个\"不写就会犯的具体错\" | 没有人格；或写成性格小作文 |\n| 9 | **30 秒三问** | 陌生人读完能答：产品？技术栈？新代码放哪 | 开头答不出这三问 |\n| 10 | **别替模型补它已经会的** | 不教通用写法/主流框架用法，只装项目私有事实 | 有\"如何使用 X / 使用教程 / step by step\"这类随模型升级很快过时的教学段 |\n\n**分档**：A 优秀 ≥85 · B 良好 ≥70 · C 及格 ≥50 · D 建议重写 <50。\n（机检：PASS=1 / WARN=0.5 / FAIL=0，INFO 不计分。**按重要度加权**——安全红线 #0 与\n减法核心项 #1/#3/#4/#10 权重 1.5，标准项 #0b/#2/#4b/#4c/#5/#9 为 1.0，加内容项 #6/#7/#8 为 0.6。\n#0 命中按 FAIL 计且资损级，定性总评里应一票顶到「先改这条」。）\n\n---\n\n## 机检的盲区（定性复核时重点纠偏）\n\n脚本只能判\"机器能确定的\"，以下几项**容易误判，必须你读正文定夺**：\n\n- **#4 图书馆 vs 路由器**：脚本只按\"大代码块/大表/历史标题\"猜。\n  - **目录树是路由地图，应保留**（脚本已不把纯 `├──└──` 树当图书馆图）；\n  - 但\"版本表/环境表\"这类**真铁律**即使是表格也该留正文——别因为是表就建议下沉；\n  - 反过来，一段没有特征字符的长叙事，脚本可能漏判，你要自己看出来。\n- **#3 规则可操作**：脚本靠模糊词黑名单，可能误伤（如正文在\"反对写干净代码这种空话\"），\n  也可能漏判（换了说法的空话）。读上下文再定。\n- **#5 高危模块**：脚本按目录名猜（payment/auth/...），可能漏掉项目里叫法特殊的高危模块，\n  也可能把无关同名目录算进来。结合项目实际业务判断。\n- **#9 30 秒三问**：脚本只看关键词信号在不在；你要**真的当一次陌生人**读开头，看能不能答出。\n- **#10 别替模型补它已经会的**：脚本只按\"教程/如何使用/step by step\"等措辞猜，会误伤——\n  比如正文在写\"本项目**自研**框架的用法\"(模型确实不知道，该留)，或在\"反对写教程\"。\n  读上下文定夺：**判据是\"这段知识模型升级后会不会自动变强\"**，会 → 删；不会(项目私有) → 留。\n  - **本 skill 自检会触发 #10 误报**：因为正文里就列着\"教程/如何使用/step by step\"这些**待检测的黑名单词**（评分表、机检盲区、修复清单都得举例它们）——这是元层面的正常现象，定性时直接放行，别去删那些词（删了这个体检器就不工作了）。\n\n---\n\n## 安全红线（务必遵守）\n\n- **绝不读取密钥文件**：`.env` / `.env.*` / `*.key` / `*.pem` / `*secret*` 一律不打开（脚本本身也不读）。\n  需要某个非密钥值时，让用户用 `! grep KEY 文件` 自己取。\n- 体检是只读操作；**任何文件改动都要先说明改哪些、为什么，得到同意再动**。\n- 多语言/多框架项目通用——本 skill 不绑定任何具体技术栈。\n\n---\n\n## 修复动作清单（用户同意后按需执行）\n\n- **拔密钥（最高优先）**：#0 命中时先把明文 key/token/私钥/口令移出 CLAUDE.md，改放\n  `.env`／密钥管理器，正文最多留「见环境变量 XXX」；命中即视为已泄露，提醒用户**轮换**该凭据，\n  并检查是否已被提交进 git（如是需清历史）。\n- **修死链**：#4b 报的死指针——补上缺失的 docs 文件，或修正/删除指针。\n- **瘦身**：把架构图/前端技术栈表/路由表等\"图书馆\"内容迁到 `docs/architecture.md`、\n  `docs/runtime.md`，正文替换成一行指针（Tier 2 按需打开，不预读）。\n- **补禁止清单**：和用户确认项目已淘汰/冲突的库与做法，写成 Do NOT 清单。\n- **可操作化**：把\"干净/简洁\"改写成具体可判定规则。\n- **删教学型冗余**：把\"如何使用 X / 主流框架用法 / step by step 教程\"这类段落删掉——\n  模型已经会、且随升级自动变强，留着只是为\"很快过时的东西\"每次付上下文费。\n- **加高危护栏**：给 payment/auth 等目录新建本地 CLAUDE.md（安全红线 + 已知陷阱 + 改动前确认）。\n- **配 Hook**：把\"改完跑测试/格式化/改 .env 提醒重启\"等做成 `.claude/settings.json` 的\n  Pre/PostToolUse Hook（告警型即可，别默认做有破坏性的自动执行）。\n- **记忆回路**：在 CLAUDE.md 加\"任务前读 MEMORY.md、任务后写回\"指令。\n- **工作风格块**：顶部加\"My Working Style\"（先方案后代码、列选项不猜、讨厌的回复腔等）。\n- 改完**重新跑一次 `check.py`** 给前后对比分数。\n\n---\n\n## 落地骨架（建文件/重写时的推荐结构，≤200 行）\n\n```\n# 项目名\n## 30 秒速览      # 产品 / 技术栈 / 新代码放哪 + 优化优先级\n## 工作风格        # 你是谁、你讨厌什么、协作节奏（限 3–5 行，每行都对应一个\"不写就会犯的错\"，别写性格小作文）\n## 跨会话记忆      # 任务前读 MEMORY.md，任务后写回\n## 铁律            # 编号、可执行、带后果（含 Do NOT 清单）\n## 关键事实表      # 版本 / 环境等不可由代码自查的硬信息（真铁律，留正文）\n## 目录结构        # 新代码放哪里（路由地图，可留正文）\n## 延伸文档        # Tier 2 指针：docs/...，按需打开不预读\n## 规划中功能      # 尚未落地，别假设已存在\n```\n\nFile v1.3.2:README.md\n\n# hekouwang-claude-md-doctor-skill\n\n**简体中文** · [English](README.en.md)\n\n[![CI](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n![Python](https://img.shields.io/badge/python-3.x-blue.svg)\n![dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)\n![open source](https://img.shields.io/badge/open%20source-free-success.svg)\n\n> **会勇禾口王的AI笔记** 出品 · `@huiyonghkw`\n> _不聊 AI 会不会取代你，只聊先用 AI 的人怎么取代你。_\n\nCLAUDE.md / AGENTS.md 体检器 —— 检查任意项目的运行时配置是否符合\"**路由器、不是图书馆**\"，\n给出评分卡 + 修复建议。\n\n## 30 秒验收\n\n```bash\npython3 check.py .                    # 体检当前项目（零依赖）\nbash scripts/run-all-doctors.sh .     # 三件套：md + skill + env\n```\n\n<p align=\"center\">\n  <img src=\"examples/demo.gif\" width=\"720\" alt=\"hekouwang-claude-md-doctor-skill 体检演示\">\n  <br><sub>↑ 一句「检查我的 CLAUDE.md」/ <code>python3 check.py</code>，秒出评分 + 修复建议（免费 CLI）</sub>\n</p>\n\n一句话判据：**CLAUDE.md 每次会话都被重新加载、要付上下文费。值不值得每次会话都为这段内容付一次费？**\n\n<p align=\"center\">\n  <img src=\"examples/report-card.gif\" width=\"420\" alt=\"CLAUDE.md 体检报告卡（动效示例）\">\n  <br><sub>↑ 品牌可视化报告卡（<b>付费增值</b>示例）——评分弧随分数填充、等级 D→A 变色。免费版输出文本/JSON 报告。</sub>\n</p>\n\n## 为什么需要它\n\n很多人把 CLAUDE.md 写成\"项目说明书\"：塞进历史、技术决策、营销叙事，动辄上千行。\n结果模型在冗长上下文里迷失，还挤掉了真正理解代码的空间。这个工具把 10 条可检查的\n最佳实践固化下来，让任何人一键体检自己的项目。\n\n核心立场是 Claude Code 之父 Boris Cherny / Cat Wu 的 **context minimalism —— 别跟模型较劲做加法**：\n模型每代都在变强，你今天费劲搭的脚手架很快白搭。所以评分按\"减法优先\"加权，\n\"越短越准\"类核心项权重更高，\"加内容\"类项缺了不重罚。\n\n## 10 项检查\n\n1. 篇幅 ≤ 200 行（路由器不是图书馆）\n2. 禁止清单（Do NOT introduce）\n3. 规则可操作（非\"写干净代码\"式空话）\n4. 路由器不是图书馆（大块下沉 docs/ 留指针）\n5. 高危模块有本地 CLAUDE.md（碰钱/认证/迁移）\n6. 关键规则有 Hook 强制（不靠模型记忆）\n7. 跨会话记忆回路（MEMORY.md）\n8. 工作风格块（你是谁 / 你讨厌什么 · 限 3–5 行）\n9. 30 秒三问（产品 / 技术栈 / 新代码放哪）\n10. 别替模型补它已经会的（无\"如何使用 X / 教程\"式随模型升级即过时的冗余）\n\n## 用法\n\n### 在 Claude Code 里（推荐）\n直接说：「**检查我的 CLAUDE.md**」「**CLAUDE.md 体检**」——会自动跑机检 +\n模型定性复核，给出评分和按优先级的修复建议，并可代为修复。\n\n### 命令行直接跑（零依赖，仅需 Python 3）\n```bash\npython3 check.py [项目目录]          # 默认当前目录，输出彩色报告\npython3 check.py [项目目录] --json   # 机器可读 JSON（CI 可用）\n```\n退出码：有 FAIL → 1，否则 0（可用于 CI 卡关）。\n\n### Docker（不想装 Python 也能跑）\n```bash\n# 拉官方镜像直接用（打 tag 时 GitHub Actions 自动发布到 GHCR）\ndocker run --rm -v \"$PWD:/work\" ghcr.io/huiyonghkw/hekouwang-claude-md-doctor-skill\n\n# 或本地自建\ndocker build -t claude-md-doctor .\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor            # 体检当前项目\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor /work --json\n```\n\n### 接进 CI 卡关（GitHub Actions 示例）\n```yaml\n- uses: actions/setup-python@v5\n  with: { python-version: \"3.x\" }\n- name: CLAUDE.md 体检（不合格则拦 PR）\n  run: |\n    curl -sO https://raw.githubusercontent.com/huiyonghkw/hekouwang-claude-md-doctor-skill/main/check.py\n    python3 check.py .\n```\n本仓库自身的 CI 见 [`.github/workflows/ci.yml`](.github/workflows/ci.yml)（语法 + good/bad 夹具 + JSON 合法性）。\n\n## 这不是内置的 `/doctor` 命令\n\nClaude Code 自带一个 `/doctor` 命令，名字也带 \"doctor\"，但**体检对象和本工具完全不同**——\n一个查整套工具的运行环境，一个只查一份文档写得好不好。别搞混。\n\n| 维度 | 内置 `/doctor` | 本工具（claude-md-doctor） |\n|------|---------------|----------------------------|\n| **体检对象** | 整个 Claude Code **运行环境 / 安装** | 单个项目的 **`CLAUDE.md` 文件本身** |\n| **关注点** | 安装健康、未用扩展、上下文膨胀、慢 Hook、版本、权限模式 | `CLAUDE.md` 是否当运行时配置写、篇幅、该不该懒加载、10 项评分 |\n| **改哪里** | `~/.claude/` 全局配置层 | 项目里的 `CLAUDE.md` 内容 |\n| **作用范围** | 全局 · 跨所有项目 | 就这一个项目的文档 |\n\n**唯一交集**：`/doctor` 会去重本地 vs 入库 `CLAUDE.md`、把该懒加载的内容迁走，但它只从\n「上下文成本」看、**不评文档质量**。**怎么用**：先 `/doctor` 发现「CLAUDE.md 太大」，\n再用本工具深度评分 + 出 Top 3 + 代重构——`/doctor` 负责发现文档偏大，本工具负责回答「具体哪几条该删、怎么改」。\n\n## 免费 / 付费（Freemium）\n\n- **免费（开源内核）**：命令行体检器 `check.py` —— 文本 / JSON 报告、评分、退出码。\n  本地或 Docker 随便跑、随便接进 CI。这是开放内核，永久免费。\n- **付费（增值服务）**：**品牌可视化体检报告卡** —— 评分弧 + 等级带 + 九项明细的\n  精美分享图（适合汇报 / 发圈 / 放进 PR）。它依赖私有视觉系统（品牌字体与版式，\n  即私有 Skill `hekouwang-content-factory`，**GitHub 上为 PRIVATE 仓库，非授权无法 clone / 获取**），\n  **不随本仓库分发**。需要出图版报告，请联系 **@huiyonghkw** 获取。\n\n> 一句话：**跑检查免费，出「好看的报告图」找我。**  \n> 联系：**GitHub / ClawHub [@huiyonghkw](https://github.com/huiyonghkw)** · 可视化报告卡私信获取\n\n## 体检器三件套\n\n与 [`skill-doctor`](https://github.com/huiyonghkw/hekouwang-claude-skill-doctor-skill)、[`env-doctor`](https://github.com/huiyonghkw/hekouwang-env-doctor-skill) 组成 **hekouwang-doctor-suite**。一键：`bash scripts/run-all-doctors.sh <项目根>`（见 `references/doctor-suite.md`）。\n\n## 设计\n\n- **机检层（`check.py`）**：确定性、零依赖、可移植，跑启发式检查并打分。\n- **定性层（`SKILL.md`）**：模型读正文复核机检盲区（图书馆 vs 路由器、规则是否可执行），\n  再出最终报告与修复方案。\n- **安全**：绝不读取 `.env` / `*.key` / `*.pem` 等密钥文件；体检只读，改动需确认。\n\n## 评分档位\n\nA 优秀 ≥85 · B 良好 ≥70 · C 及格 ≥50 · D 建议重写 <50\n\n## 许可协议 / License\n\n本仓库代码以 **MIT License** 开源 —— 免费使用、修改、分发、商用，仅需保留版权与许可声明。详见 [LICENSE](LICENSE)。\n\n> 范围说明：MIT 覆盖本仓库代码（`check.py` / `SKILL.md` 等）。品牌名「会勇禾口王的AI笔记」与**付费可视化报告卡**（依赖未公开的品牌字体与版式）属增值服务，不在开源范围内——但这不影响你免费、自由地使用命令行体检器。\n\n## 贡献 / Contributing\n\n欢迎提 Issue / PR：新增检查项、降低误报、补充其它语言/框架的启发式规则。\n保持零运行时依赖（仅 Python 3 标准库）是硬约束。\n\n---\n\n<sub>—— 会勇禾口王的AI笔记 · @huiyonghkw · AI 实战拆解：编程 × 内容创作 × 自动化（硬核 · 具体 · 可复制）</sub>\n\nFile v1.3.2:_meta.json\n\n{\n  \"ownerId\": \"kn73qd1gcmjr446mwcbdxef70x82vxcw\",\n  \"slug\": \"hekouwang-claude-md-doctor-skill\",\n  \"version\": \"1.3.2\",\n  \"publishedAt\": 1786534620249\n}\n\nFile v1.3.2:references/doctor-suite.md\n\n# hekouwang-doctor-suite · 体检器三件套\n\n> 竞品多是单点；这套把「项目配置 → 技能包 → 本机环境」串成一条验收链。\n\n```\nhekouwang-doctor-suite（概念）\n├── md-doctor      → AGENTS.md / CLAUDE.md（运行时配置）\n├── skill-doctor   → SKILL.md（Agent 技能包）\n└── env-doctor     → 磁盘 / 版本管理器 / AI 宿主目录\n```\n\n## 一键跑\n\n```bash\nbash scripts/run-all-doctors.sh /path/to/your-project\n```\n\n（脚本在 `hekouwang-claude-md-doctor-skill`；`skill-doctor` / `env-doctor` 仓内各有一份相同副本。）\n\n## 建议顺序\n\n1. **md-doctor** — 根配置是否「路由器」而非「图书馆」\n2. **skill-doctor** — `.agents/skills/` 下各 skill 是否按需加载\n3. **env-doctor** — 本机是否留着已换掉的 nvm / 膨胀的 AI 缓存\n\n## 免费 vs 付费\n\n| | 免费（开源） | 付费增值 |\n|---|---|---|\n| 机检 | `check.py` / `scan.sh` 文本报告 + JSON | 品牌可视化报告卡（评分弧 + 等级带） |\n| CI | 退出码卡关 | — |\n| 联系 | GitHub Issue / PR | ClawHub **@huiyonghkw** |\n\nFile v1.3.2:CHANGELOG.md\n\n# Changelog\n\n本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。\n\n## [1.3.2] - 2026-08-12\n\n### 变更\n- ClawHub 分类：`development`\n\n## [1.3.1] - 2026-08-12\n\n### 新增\n- `scripts/run-all-doctors.sh`：hekouwang-doctor-suite 三件套一键体检\n- `references/doctor-suite.md`：套件说明与免费/付费对照\n\n### 变更\n- `check.py`：无 `HEKOUWANG_CONTENT_FACTORY` 时提示付费报告卡 CTA\n- README：30 秒验收 + 三件套互链；summary 补英文 SEO 关键词\n\n## [1.3.0] - 2026-08-12\n\n### 新增\n- **`check.py` 支持 AGENTS.md**：根目录优先体检 `AGENTS.md`，其次 `CLAUDE.md` / `CLAUDE.local.md`；\n  子目录扫描同时认两份本地配置。\n- **#0b 双文件去重**：根目录 `AGENTS.md` + `CLAUDE.md` 同时存在且都不是薄指针 → WARN（双倍上下文费）。\n- **#4c Skill 路由**：正文应把细则指针到 `.agents/skills/`（或 `.cursor/skills/`），别堆在常驻正文。\n- 报告标题改为 **AGENT CONFIG DOCTOR**；JSON 输出增加 `root_configs` 字段。\n\n### 文档\n- `SKILL.md` 触发词补 `AGENTS.md` / `agents.md` / `运行时配置体检`；评分表扩至 12 项。\n- 新增测试夹具 `tests/fixtures/good-agents/`、`tests/fixtures/dual/`。\n\n## [1.2.2] - 2026-07-09\n\n### 文档\n- **新增「与内置 `/doctor` 命令的分工」小节**：两者名字都带 doctor 但体检对象完全不同——\n  内置 `/doctor` 查整套 Claude Code 运行环境（安装/未用扩展/上下文膨胀/权限/版本），\n  本 skill 只查一份 CLAUDE.md 的写法质量。给出对比表 + 唯一交集（`/doctor` Check 2/3 碰 CLAUDE.md\n  但只从上下文成本看、不评质量）+ 用法建议（先 `/doctor` 发现文档偏大，再用本 skill 深度评 + 重构）。\n- **README.md / README.en.md 同步**：两份 README 也各补一节「这不是内置的 `/doctor` 命令」\n  （精简对比表 + 唯一交集 + 组合用法），中英一致。\n\n## [1.2.1] - 2026-06-22\n\n自体检（用姊妹工具 skill-doctor 跑）后的两处打磨：\n\n### 优化\n- **SKILL.md 声明 `allowed-tools`**：收敛到本 skill 真正需要的工具集，减小越权面。\n- **补「本 skill 自检会触发 #10 误报」豁免说明**：正文里的\"教程/如何使用/step by step\"是\n  待检测的黑名单词本身（评分表/盲区/修复清单都要举例），机检会误报教学冗余——\n  与 skill-doctor 对齐，注明定性时直接放行，别删那些词（删了体检器就不工作）。\n\n## [1.2.0] - 2026-06-21\n\n对照社区教程 `luongnv89/claude-howto` 的 Memory 最佳实践逐条比对后，补上三个真空白\n（只取它的\"安全 + 机制正确性\"，不取它\"把文件写全\"的加法倾向）。\n\n### 新增\n- **安全红线检查「无硬编码密钥」(#0)**：扫正文里的 `sk-`/`AKIA`/`AIza`/`gh*_`/`xox*`/\n  JWT / 私钥块 / `password=`/`secret=` 等指纹，命中即 **FAIL**（权重 1.5、资损级）。\n  报告对命中值脱敏（前 4 位 + 长度）。占位/示例值（`<your-pwd>`/`${VAR}`/`example` 等）自动豁免。\n  补齐教程头号 Don't \"Never store secrets in CLAUDE.md\"——此前脚本只防自己读 .env，\n  却不查被体检文件本身是否藏密钥。\n- **指针死链检查 (#4b)**：`docs/` 文本指针与原生 `@import` 路径都校验目标文件是否存在，\n  死链 → WARN（指向不存在的文件比没指针更糟）。\n\n### 变更\n- **#4 路由器检查认原生 `@import` 语法**：此前只认纯文本 `docs/...`，用官方 `@path` 导入\n  反而不给\"下沉指针\"加分；现在两种写法都算合格指针。\n\n### 文档 / 测试\n- `SKILL.md` 评分表补 #0 与 #4b，加权说明与修复动作清单同步（拔密钥 + 轮换提醒、修死链）。\n- good 夹具补 `docs/architecture.md`、`docs/api.md` 桩文件，示范\"指针均可解析\"。\n\n## [1.1.0] - 2026-06-18\n\n把 Claude Code 之父 Boris Cherny / Cat Wu 的\"context minimalism · 别跟模型较劲做加法\"\n立场接进体检逻辑。\n\n### 新增\n- **第 10 项检查「别替模型补它已经会的」**：扫教学型措辞(如何使用 / 使用教程 /\n  step by step / how to use)，命中即 WARN——这类通用写法随模型升级自动变强，\n  写进常驻正文只是为\"很快过时的东西\"每次付上下文费。\n- **「减法优先」元判据**：写进 `SKILL.md`，凌驾 9 项之上——加任何一段前先问\n  \"能不能不写在常驻正文里\"。\n\n### 变更\n- **评分改为按重要度加权**：减法核心项(#1 篇幅 / #3 可操作 / #4 路由器 / #10)权重 1.5，\n  加内容项(#6 Hook / #7 记忆 / #8 人格)降到 0.6。修掉旧逻辑\"一边喊越短越好、\n  一边因缺工作风格块扣分、逼用户把文件写长\"的自相矛盾。\n- **#8 工作风格块加上限护栏**：限 3–5 行，每行须对应一个\"不写就会犯的具体错\"，别写性格小作文。\n\n### 文档\n- `README` / `README.en` 同步「10 项检查」并写明「减法优先 · 别跟模型较劲做加法」立场。\n- `SKILL.md` 顶部署名补 GitHub 仓库地址\n  （<https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill>），方便 skillhub 溯源。\n\n## [1.0.0] - 2026-06-17\n\n首个正式版本。把\"CLAUDE.md 当运行时配置、不是项目说明书\"的最佳实践做成可跑在任意项目上的体检器。\n\n### 功能\n- **9 项检查的命令行体检器 `check.py`**：篇幅 / 禁止清单 / 规则可操作 / 路由非图书馆 /\n  高危模块本地 CLAUDE.md / Hook 强制 / MEMORY.md 回路 / 工作风格 / 30 秒三问。\n- 输出彩色文本报告或 `--json`；评分 0–100（A/B/C/D）；有 FAIL → 退出码 1（可 CI 卡关）。\n- 零运行时依赖（仅 Python 3 标准库）；只读，绝不读取 `.env` / `*.key` / `*.pem`。\n- **`SKILL.md` 定性复核层**：在 Claude Code 内说「检查我的 CLAUDE.md」即可机检 + 模型复核 + 代修复。\n- **Docker**：`docker run --rm -v \"$PWD:/work\" claude-md-doctor`，免装 Python。\n- **GitHub Actions CI**：语法 + good/bad 夹具 + JSON 合法性。\n- 中英双语 README、MIT LICENSE、CONTRIBUTING、示例动图（CLI 实录 + 动效报告卡）。\n\n### 商业模型\n- 命令行体检器开源免费（MIT）；品牌可视化报告卡为付费增值，依赖未公开字体/版式，不在仓库内。\n\n[1.0.0]: https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/releases/tag/v1.0.0\n\nFile v1.3.2:CONTRIBUTING.md\n\n# 贡献指南 / Contributing\n\n感谢参与 **hekouwang-claude-md-doctor-skill**！欢迎新增检查项、降低误报、为其它语言/框架补启发式规则。\n\n## 硬约束（不可破）\n\n1. **零运行时依赖** —— `check.py` 只用 Python 3 标准库。不要引入第三方包。\n2. **只读 + 安全** —— 检查器绝不读取 `.env` / `*.key` / `*.pem` 等密钥文件，不写用户文件。\n3. **跨语言通用** —— 不绑定任何具体技术栈；新规则要对多数项目成立。\n\n## 本地开发\n\n```bash\ngit clone https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill\ncd hekouwang-claude-md-doctor-skill\n\npython3 check.py tests/fixtures/good     # 期望 exit 0\npython3 check.py tests/fixtures/bad      # 期望 exit 1（有 FAIL 卡关）\npython -m py_compile check.py            # 语法自检\n```\n\n## 加一条检查项\n\n1. 在 `check.py` 的 `check()` 里用 `add(key, title, status, detail, fix)` 追加结果。\n2. `status` 取 `PASS` / `WARN` / `FAIL` / `INFO`（INFO 不计分）。\n3. 机检只做\"机器能确定的\"；需要读正文判断的，写进 `SKILL.md` 的「定性复核」与「机检盲区」。\n4. 在 `tests/fixtures/` 增/改夹具，确保 `good` 仍 exit 0、`bad` 仍 exit 1。\n5. 误报是头号大忌——宁可 `WARN` 不轻易 `FAIL`，并在 `detail` 里说清线索。\n\n## 提交 PR\n\n- 一个 PR 聚焦一件事；附上前后 `check.py` 输出对比。\n- 通过 CI（`.github/workflows/ci.yml`：语法 + good/bad 夹具 + JSON 合法性）。\n- commit 信息讲清「改了什么 + 为什么」。\n\n## 范围说明\n\n代码以 MIT 开源（见 [LICENSE](LICENSE)）。品牌名「会勇禾口王的AI笔记」与付费可视化报告卡为增值服务，不在本仓库开源范围内。\n\nFile v1.3.2:README.en.md\n\n# hekouwang-claude-md-doctor-skill\n\n[简体中文](README.md) · **English**\n\n[![CI](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n![Python](https://img.shields.io/badge/python-3.x-blue.svg)\n![dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)\n![open source](https://img.shields.io/badge/open%20source-free-success.svg)\n\n> Made by **会勇禾口王的AI笔记** (Hekouwang's AI Notes) · `@huiyonghkw`\n\nA health checker for `CLAUDE.md` — audits any project's `CLAUDE.md` against the\nbest practice of *\"treat it as runtime config, not a project manual\"*, and returns\na scorecard plus prioritized fixes.\n\n<p align=\"center\">\n  <img src=\"examples/demo.gif\" width=\"720\" alt=\"hekouwang-claude-md-doctor-skill demo\">\n  <br><sub>↑ Say \"check my CLAUDE.md\" or run <code>python3 check.py</code> — instant score + fixes (free CLI)</sub>\n</p>\n\nThe one rule it all comes down to: **CLAUDE.md is reloaded into context on every\nsession and costs tokens every time. Is this line worth paying for on every single session?**\n\n<p align=\"center\">\n  <img src=\"examples/report-card.gif\" width=\"420\" alt=\"CLAUDE.md report card (animated)\">\n  <br><sub>↑ Branded visual report card (<b>paid add-on</b> sample) — the score arc fills and the grade morphs D→A. The free version outputs a text/JSON report.</sub>\n</p>\n\n## Why it exists\n\nMost people write `CLAUDE.md` like a project manual: history, tech decisions,\nmarketing prose — easily over a thousand lines. The model then drowns in a bloated\ncontext and loses the room it needs to actually understand your code. This tool\nfreezes 10 checkable best practices into a one-command audit anyone can run.\n\nIts guiding stance is the **context minimalism** that Claude Code's creators\nBoris Cherny and Cat Wu preach — *don't fight the model by adding things*: models\nget stronger every generation, so the scaffolding you laboriously build today\ngoes stale fast. Scoring is therefore weighted \"subtraction-first\": the\nshorter-is-sharper core checks count more, missing \"add-content\" checks count less.\n\n## The 10 checks\n\n1. **Length ≤ 200 lines** — a router, not a library\n2. **A \"Do NOT introduce\" list** — block well-meant but incompatible deps\n3. **Actionable rules** — not vague \"write clean code\" platitudes\n4. **Router, not library** — move big blocks to `docs/`, leave pointers\n5. **Local CLAUDE.md for high-risk modules** — money / auth / migrations\n6. **Hooks enforce the critical rules** — don't rely on the model's memory\n7. **A MEMORY.md cross-session loop**\n8. **A working-style block** — who you are / what you hate (cap 3–5 lines)\n9. **The 30-second test** — product? stack? where does new code go?\n10. **Don't teach the model what it already knows** — no \"how to use X / tutorial\"\n    prose that goes stale the moment the model improves\n\n## Usage\n\n### Inside Claude Code (recommended)\nJust say **\"check my CLAUDE.md\"**. It runs the mechanical check, then does a\nmodel-driven qualitative review, and returns a score with prioritized fixes —\nand can apply the fixes for you.\n\n### Command line (zero deps, just Python 3)\n```bash\npython3 check.py [project_dir]          # defaults to CWD, prints a colored report\npython3 check.py [project_dir] --json   # machine-readable JSON (for CI)\n```\nExit code: `1` if any FAIL, else `0` (usable as a CI gate).\n\n### Docker (no Python needed)\n```bash\n# Pull the prebuilt image (auto-published to GHCR on each tag via GitHub Actions)\ndocker run --rm -v \"$PWD:/work\" ghcr.io/huiyonghkw/hekouwang-claude-md-doctor-skill\n\n# Or build locally\ndocker build -t claude-md-doctor .\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor            # check current project\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor /work --json\n```\n\n### Gate your PRs (GitHub Actions)\n```yaml\n- uses: actions/setup-python@v5\n  with: { python-version: \"3.x\" }\n- name: CLAUDE.md health check (fail the PR if non-compliant)\n  run: |\n    curl -sO https://raw.githubusercontent.com/huiyonghkw/hekouwang-claude-md-doctor-skill/main/check.py\n    python3 check.py .\n```\nThis repo's own CI lives in [`.github/workflows/ci.yml`](.github/workflows/ci.yml) (syntax + good/bad fixtures + JSON validity).\n\n## This is NOT the built-in `/doctor` command\n\nClaude Code ships a `/doctor` command that also says \"doctor\" — but it checks a\n**completely different thing**: `/doctor` audits your whole tool *environment*,\nthis tool audits one *document*. Don't confuse them.\n\n| Dimension | Built-in `/doctor` | This tool (claude-md-doctor) |\n|-----------|--------------------|------------------------------|\n| **Audits** | Your whole Claude Code **environment / install** | A single project's **`CLAUDE.md` file** |\n| **Looks at** | Install health, unused extensions, context bloat, slow hooks, version, permission mode | Whether `CLAUDE.md` reads as runtime config, length, lazy-loading, the 10-check score |\n| **Edits** | `~/.claude/` global config | The project's `CLAUDE.md` content |\n| **Scope** | Global · across all projects | Just this one project's doc |\n\n**The one overlap**: `/doctor` dedups local vs checked-in `CLAUDE.md` and migrates\nlazy-loadable content out — but only from a \"context cost\" angle; it **does not\ngrade document quality**. **How to combine them**: run `/doctor` first to catch\n\"your CLAUDE.md is too big\", then use this tool to score it, surface the Top 3,\nand rewrite it — `/doctor` finds that the doc is bloated, this tool answers *which\nlines to cut and how*.\n\n## Free / Paid (Freemium)\n\n- **Free (open-source core)**: the `check.py` CLI — text / JSON report, score,\n  exit code. Run it locally or in Docker, wire it into CI. Free forever.\n- **Paid (add-on service)**: the **branded visual report card** (score arc +\n  grade band + 9-check breakdown, great for sharing / PRs). It depends on a\n  private visual system (brand fonts & layout) and is **not shipped in this repo**.\n  Want the image version? Contact **@huiyonghkw**.\n\n> In one line: **running the check is free; getting the pretty report image, talk to me.**\n\n## Design\n\n- **Mechanical layer (`check.py`)**: deterministic, zero-dependency, portable —\n  runs heuristic checks and scores them.\n- **Qualitative layer (`SKILL.md`)**: the model reads the actual file to cover the\n  checker's blind spots (library vs router, whether rules are truly actionable),\n  then produces the final report and fix plan.\n- **Safety**: never reads `.env` / `*.key` / `*.pem` secrets; the audit is\n  read-only and any edits require confirmation.\n\n## Grade bands\n\nA (excellent) ≥85 · B (good) ≥70 · C (pass) ≥50 · D (rewrite) <50\n\n## License\n\nThe code in this repo is open-sourced under the **MIT License** — free to use,\nmodify, distribute, and use commercially; just keep the copyright and license\nnotice. See [LICENSE](LICENSE).\n\n> Scope: MIT covers the repo's code (`check.py` / `SKILL.md`, etc.). The brand\n> name \"会勇禾口王的AI笔记\" and the **paid visual report card** (which relies on\n> unreleased brand fonts & layout) are an add-on service, outside the open-source\n> scope — but that does not affect your free, unrestricted use of the CLI checker.\n\n## Contributing\n\nIssues / PRs welcome: new checks, fewer false positives, heuristics for more\nlanguages/frameworks. Keeping **zero runtime dependencies** (Python 3 stdlib only)\nis a hard constraint.\n\n---\n\n<sub>—— 会勇禾口王的AI笔记 · @huiyonghkw · AI in practice: coding × content × automation</sub>\n\nFile v1.3.2:skill-card.md\n\n## Description:\n\nAudits AGENTS.md and CLAUDE.md files as agent runtime configuration, returning a scorecard, prioritized fixes, and optional assisted edits.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[huiyonghkw](https://clawhub.ai/user/huiyonghkw)\n\n### License/Terms of Use:\n\nMIT\n\n## Use Case:\n\nDevelopers and agent users use this skill to evaluate whether AGENTS.md or CLAUDE.md files are concise, actionable runtime configuration rather than project manuals. It helps produce a quality score, prioritized cleanup guidance, and user-approved edits for those files.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The documentation includes CI guidance that downloads and runs check.py from a raw URL.\n\nMitigation: Vendor the reviewed script or pin it to a full commit and verify its SHA-256 before CI execution.\n\nRisk: The optional run-all-doctors.sh suite expands beyond document linting into local skill and environment inspection.\n\nMitigation: Review the md-doctor, skill-doctor, and env-doctor commands before running the suite and limit it to projects where that broader inspection is acceptable.\n\nRisk: The skill can propose and, with confirmation, edit AGENTS.md or CLAUDE.md project files.\n\nMitigation: Review the proposed changes and resulting diffs before accepting edits, especially in repositories with sensitive runtime instructions.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/huiyonghkw/skills/hekouwang-claude-md-doctor-skill)\n- [Project homepage from ClawHub metadata](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill)\n- [Doctor suite reference](references/doctor-suite.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown report with optional JSON from the checker and user-approved file edits]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Can run a local Python checker; edits to AGENTS.md or CLAUDE.md are expected to require user confirmation.]\n\n## Skill Version(s):\n\n1.3.2 (source: frontmatter, changelog, ClawHub release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.3.2:tests/fixtures/bad/CLAUDE.md\n\n# 我的项目\n\n请写干净的代码，保持简洁优雅，注重性能，遵循最佳实践。\n代码要高质量、易于维护。谢谢配合。\n\n## React 使用教程\n\n如何使用 useState：调用 `const [x, setX] = useState(0)`，setX 触发重渲染。\n如何使用 useEffect：把副作用放进 useEffect，依赖数组控制何时重跑。\n这些都是 React 的标准用法，跟着 step by step 写就行。\n\nFile v1.3.2:tests/fixtures/dual/AGENTS.md\n\n# Acme Dashboard\n\n> 30 秒速览：面向运营经理的 B2B 分析仪表盘。优化优先级：加载速度 > 交互 > 视觉。\n> 新代码按下方目录结构放进对应模块；动手前先看该模块 README。\n\n## 工作风格\n- 先给方案再写代码；不确定时列选项，不要猜。\n- 汇报用中文，代码与注释用英文；文件引用用绝对路径。\n- 不说「Great question!」这类客套，直接给结论。\n\n## 跨会话记忆\n- 任务开始前扫一遍 `MEMORY.md`；结束后把新的非显然结论写回。\n\n## 铁律\n1. 用 named export（路由文件除外）。\n2. 禁 `any`，用泛型或接口替代。\n3. 单组件不超过 200 行（有充分理由可超）。\n\n## 技术栈（tech stack）\n- Next.js 15 App Router + TypeScript\n- Tailwind CSS + shadcn/ui\n- PostgreSQL（数据层）\n\nDo NOT introduce unless explicitly requested:\n- Redux（已迁移到 React Context + Zustand）\n- styled-components（全站 Tailwind，不收 CSS-in-JS）\n- MongoDB（数据层锁定 PostgreSQL）\n\n## 目录结构（directory · 新代码放哪里）\n```\nsrc/\n  app/        # 路由与页面\n  components/ # 复用组件\n  lib/        # 工具与数据访问\n```\n\n## 延伸文档（Tier 2，按需打开）\n- 架构总览：`docs/architecture.md`\n- API 文档：`docs/api.md`\n\nFile v1.3.2:tests/fixtures/dual/CLAUDE.md\n\n# Acme Dashboard\n\n> 30 秒速览：面向运营经理的 B2B 分析仪表盘。优化优先级：加载速度 > 交互 > 视觉。\n> 新代码按下方目录结构放进对应模块；动手前先看该模块 README。\n\n## 工作风格\n- 先给方案再写代码；不确定时列选项，不要猜。\n- 汇报用中文，代码与注释用英文；文件引用用绝对路径。\n- 不说「Great question!」这类客套，直接给结论。\n\n## 跨会话记忆\n- 任务开始前扫一遍 `MEMORY.md`；结束后把新的非显然结论写回。\n\n## 铁律\n1. 用 named export（路由文件除外）。\n2. 禁 `any`，用泛型或接口替代。\n3. 单组件不超过 200 行（有充分理由可超）。\n\n## 技术栈（tech stack）\n- Next.js 15 App Router + TypeScript\n- Tailwind CSS + shadcn/ui\n- PostgreSQL（数据层）\n\nDo NOT introduce unless explicitly requested:\n- Redux（已迁移到 React Context + Zustand）\n- styled-components（全站 Tailwind，不收 CSS-in-JS）\n- MongoDB（数据层锁定 PostgreSQL）\n\n## 目录结构（directory · 新代码放哪里）\n```\nsrc/\n  app/        # 路由与页面\n  components/ # 复用组件\n  lib/        # 工具与数据访问\n```\n\n## 延伸文档（Tier 2，按需打开）\n- 架构总览：`docs/architecture.md`\n- API 文档：`docs/api.md`\n\nFile v1.3.2:tests/fixtures/dual/docs/api.md\n\n# API 文档\n\n（夹具桩文件：演示下沉指针可解析。）\n\nArchive v1.3.1: 23 files, 45674 bytes\n\nFiles: CHANGELOG.md (6367b), check.py (32103b), CONTRIBUTING.md (1772b), Dockerfile (763b), LICENSE (1096b), README.en.md (7688b), README.md (8092b), references/doctor-suite.md (1118b), scripts/run-all-doctors.sh (3290b), skill-card.md (2057b), SKILL.md (16199b), tests/fixtures/bad/CLAUDE.md (423b), tests/fixtures/dual/AGENTS.md (1308b), tests/fixtures/dual/CLAUDE.md (1308b), tests/fixtures/dual/docs/api.md (69b), tests/fixtures/dual/docs/architecture.md (95b), tests/fixtures/good-agents/AGENTS.md (1308b), tests/fixtures/good-agents/docs/api.md (69b), tests/fixtures/good-agents/docs/architecture.md (95b), tests/fixtures/good/CLAUDE.md (1308b), tests/fixtures/good/docs/api.md (69b), tests/fixtures/good/docs/architecture.md (95b), _meta.json (151b)\n\nFile v1.3.1:SKILL.md\n\n---\nname: hekouwang-claude-md-doctor-skill\nslug: hekouwang-claude-md-doctor-skill\ndisplayName: CLAUDE.md / AGENTS.md 体检器\nsummary: AGENTS.md / CLAUDE.md linter & skill lint companion — Agent runtime config audit (not a project wiki). Dual-file dedup + .agents/skills/ routing.\nlicense: MIT\nhomepage: https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill\nversion: 1.3.1\ndescription: >\n  会勇禾口王的AI笔记 · Agent 运行时配置体检器。检查项目的 AGENTS.md（跨 Agent 推荐）\n  或 CLAUDE.md（及子目录本地配置）是否符合\"把它当运行时配置、不是项目说明书\"的最佳实践，\n  给出评分卡 + 按优先级的修复建议，并可代为修复。触发：用户说「检查我的 CLAUDE.md /\n  AGENTS.md / 运行时配置体检 / claude-md-doctor / agents.md 规范吗 / audit CLAUDE.md /\n  lint AGENTS.md / 看看我的 agent 配置合不合规」。\n  任何\"评估/审查/优化某个项目 AGENTS.md 或 CLAUDE.md 质量\"的请求都应触发。\nallowed-tools:\n  - Bash\n  - Read\n  - Write\n  - Edit\n  - Glob\n  - Grep\n  - AskUserQuestion\n---\n\n# hekouwang-claude-md-doctor-skill · Agent 运行时配置体检器\n\n> **会勇禾口王的AI笔记** 出品 · `@huiyonghkw`\n> GitHub: <https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill>\n> _不聊 AI 会不会取代你，只聊先用 AI 的人怎么取代你。_\n\n把\"Agent 运行时配置最佳实践\"做成一个能跑在任何项目上的检查器：机检定量 + 模型定性，\n产出评分卡和可落地的修复建议。核心判据一句话——\n\n> **AGENTS.md / CLAUDE.md 是每次会话都被重新加载、要付上下文费的\"运行时配置\"，不是给人读的项目说明书。**\n> 2026 年起 Cursor / Codex / OpenClaw 等多读 **AGENTS.md**；Claude Code 仍读 **CLAUDE.md**。\n> 一切检查项都从这句推导：值不值得每次会话都为这段内容付一次费？\n\n### 减法优先（元判据 · 凌驾全部检查项之上）\n\nClaude Code 之父 Boris Cherny 公开说自己的配置\"surprisingly vanilla\"、几乎不定制；\n联合创造者 Cat Wu 自称 \"context minimalist\"——只告诉模型它需要知道的，剩下让它自己想。\n**核心立场：模型每代都在变强，你今天费劲搭的脚手架很快白搭；别跟模型较劲做加法。**\n\n所以下面这些检查项里凡是\"让用户往里加内容\"的(禁止清单/Hook/记忆/人格/本地文件)，\n落地前都先过这一关 —— **加任何一段前先问：这条能不能不写在常驻正文里？**\n\n- 能挂 **Hook**(确定性规则)→ 挂 Hook，别写正文(模型不必每次读)。\n- 能下沉 **docs/** 的 → 下沉，正文留一行指针。\n- 能靠 **linter / 类型检查 / 测试**兜住的 → 删掉，别让模型干 linter 的活。\n- 通用写法 / 主流框架用法 → 删掉，那是模型已经会的(见 #10)。\n- **只有\"模型会反复犯错、且没有机械手段能兜住\"的，才值得占常驻 token。**\n\n机检层面：**#1 篇幅 / #3 可操作 / #4 路由器 / #10 别替模型补**这几项是减法核心，权重更高；\n\"加内容\"类项(#6/#7/#8)缺失只算小扣分，避免工具一边喊\"越短越好\"、一边逼用户把文件写长。\n\n## 品牌人设（体检报告的口吻 + 署名）\n\n这套工具属于 **会勇禾口王的AI笔记**（定位：AI 实战拆解，硬核·具体·可复制；人设：你办公室里第一个把 AI 用明白的同事）。出体检报告时：\n\n- **口吻**：像同事帮你看代码——直给结论、敢泼冷水（\"这条是空话，5 秒判不了就是不合格\"），不说\"Great question / 我很乐意帮忙\"这类客套。\n- **价值化**：修复建议讲\"省了什么\"（少几十次会话的冗余、挡住一次资损/越权），不堆术语。\n- **署名**：报告结尾固定带一行品牌签收 —— `—— 会勇禾口王的AI笔记 · @huiyonghkw`，并可附 slogan。命令行 `check.py` 的报告页脚已内置该署名。\n- **去 AI 味**：定稿前避开\"赋能/打造/至关重要/助力\"等词，说人话。\n\n---\n\n## 免费 / 付费边界（重要）\n\n- **免费（开源内核）**：`check.py` 的**文本 / JSON 报告 + 评分**。任何人本地或 Docker 跑、进 CI，随便用。\n- **付费（增值）**：**品牌可视化体检报告卡**（评分弧 + 等级带 + 九项明细的精美分享图）。\n  它依赖 `hekouwang-content-factory` 的**私有品牌字体与版式**，不随本仓库分发。\n\n**触发\"出图 / 报告卡 / 图表 / 可视化\"时怎么办**：\n1. 先照常给**免费文本报告**（机检 + 定性复核）。\n2. 是否生成图：检查本机有没有 `hekouwang-content-factory`（品牌字体在\n   `~/.claude/skills/hekouwang-content-factory/assets/fonts/`）。\n   - **有**（作者本人环境）：可按 V2 米白生成报告卡 PNG。\n   - **没有**（外部用户）：明确说明可视化报告是**付费增值项**，引导联系 **@huiyonghkw** 获取，\n     不要用系统字体凑一张劣化图糊弄。\n3. 一句话口径：**跑检查免费，出\"好看的报告图\"找我。**\n\n---\n\n## 与内置 `/doctor` 命令的分工（名字像，别混用）\n\nClaude Code 内置了一个 `/doctor` 命令，名字也带 \"doctor\"，但**体检对象和本 skill 完全不同**——\n一个查整套工具的运行环境，一个只查一份文档写得好不好。别把两者当同一个东西。\n\n| 维度 | 内置 `/doctor` 命令 | 本 skill（claude-md-doctor） |\n|------|--------------------|------------------------------|\n| **体检对象** | 整个 **Claude Code 运行环境 / 安装** | 单个项目的 **CLAUDE.md 文件本身** |\n| **关注点** | 安装健康、未用扩展(skill/MCP/plugin)、常驻上下文膨胀、慢 Hook、版本、权限模式、预批命令、本地记忆去重 | CLAUDE.md 是否「当运行时配置写而非项目说明书」、篇幅、该不该懒加载、评分卡 + 分级修复 |\n| **改哪里** | `~/.claude/` 配置层（settings.json、skillOverrides、`.claude.json`） | 项目里的 `CLAUDE.md` / 子目录本地 CLAUDE.md 内容 |\n| **作用范围** | 全局 · 跨所有项目的工具链 | 就这一个项目的文档 |\n| **产物** | 环境体检报告 + 两道确认后改配置 | 评分卡（10 项）+ Top 3 修复建议，可代改 |\n\n**唯一交集**：`/doctor` 的 **Check 2 / Check 3** 会碰 CLAUDE.md——去重本地 vs 入库 CLAUDE.md、\n把该懒加载的内容迁到 skill/子目录。但它是从**「上下文成本」**这一个角度看，只管「有没有重复、该不该常驻」，\n**不评文档质量**；本 skill 才从**「写法规范」**全面打分（可操作性、禁止清单、高危护栏、30 秒三问……）。\n\n### 用法建议\n\n- **想知道「我这套 Claude Code 装得干净、跑得健康吗」** → 跑内置 `/doctor`。\n- **想知道「我这个项目的 CLAUDE.md 写得规范吗」** → 触发本 skill。\n- **两者串起来用（推荐）**：先 `/doctor` 体检环境，若它在 Check 3 提示「CLAUDE.md 太大 / 该懒加载」，\n  接着用本 skill 深度评一份 + 出 Top 3 + 代重构——`/doctor` 负责发现「这份文档偏大」，本 skill 负责回答「具体哪几条该删、怎么下沉」。\n- **别指望 `/doctor` 替你把 CLAUDE.md 写规范**：它只做去重和迁移，不判「这条规则是不是空话」「禁止清单缺不缺」——那是本 skill 的活。\n\n---\n\n## 工作流（每次体检按这个顺序）\n\n1. **确认目标目录**：用户没指明就用当前工作目录；说了某项目就用那个绝对路径。\n2. **跑机检**（确定性层，零依赖）：\n   ```bash\n   python3 <此skill目录>/check.py <项目目录>\n   ```\n   - 需要结构化结果时加 `--json`（便于你解析后二次判断）。\n   - 退出码：有 FAIL → 1，否则 0。\n3. **定性复核**（机检之上，必须做）：机检是启发式，几项需要你**真正读正文**再下结论：\n   - 实际打开根 `AGENTS.md` 或 `CLAUDE.md` 通读一遍（机检已自动选优先级更高的那份）；\n   - 用下面《评分标准》逐条核对，**重点修正机检可能误判的项**（见\"机检的盲区\"）；\n   - 抽查 1–2 个子目录本地 AGENTS.md / CLAUDE.md 是否写了真红线（不是空模板）。\n4. **出报告**：先给一句话总评 + 分数档位，再用\"✓/▲/✗ + 一句话 + 修复建议\"逐条列，\n   最后给 **Top 3 最该先改的**（按\"花最小力气补最大漏洞\"排序）。中文输出。\n5. **提出代修复**：问用户要不要直接改（瘦身下沉 docs/、补禁止清单、补工作风格块、\n   加高危模块本地 CLAUDE.md、配 Hook 等）。**得到同意再动文件**，一次改一类、可回退。\n\n> 不要只把脚本输出原样贴给用户——脚本是线索，你的价值在定性判断 + 具体怎么改。\n\n---\n\n## 评分标准（12 项 · 也是机检的判分依据）\n\n| # | 检查项 | 合格长什么样 | 不合格信号 |\n|---|--------|------------|-----------|\n| 0 | **无硬编码密钥（安全红线）** | 正文不出现 key/token/私钥/口令明文 | 出现 `sk-`/`AKIA`/私钥块/`password=\"...\"` → **直接 FAIL** |\n| 0b | **AGENTS + CLAUDE 不双份加载** | 只留一份真源；另一份是一行指针 | 根目录两份都「厚」、内容重复 → **WARN**（双倍上下文费） |\n| 1 | **篇幅 ≤ 200 行** | 路由器不是图书馆，常驻越短越好 | >200 行；大段历史/营销/教程正文 |\n| 2 | **禁止清单（Do NOT）** | 有\"不要引入 X（因为 Y）\"清单 | 只列要用的、不列禁用的 |\n| 3 | **规则可操作** | 5 秒内能判定代码合不合规 | \"写干净代码/优雅/高质量\"这类空话 |\n| 4 | **路由器不是图书馆** | 大块下沉 docs/，正文留指针（认 docs/ 文本指针与原生 `@import`） | 架构图/长表/历史塞在常驻正文 |\n| 4b | **指针无死链** | docs/ 与 `@import` 都指向真实存在的文件 | 指针指向不存在的文件（按图索骥扑空，比没指针更糟） |\n| 4c | **细则路由到 Skill** | 工作流细则在 `.agents/skills/`，正文留指针 | 有 skills 目录但正文很长且不提路由 |\n| 5 | **高危模块本地配置** | 碰钱/认证/迁移目录各有 AGENTS.md 或 CLAUDE.md | 敏感模块只靠根文件一句话 |\n| 6 | **Hook 强制层** | 最不能漏的规则挂成 Hook | 关键规则只\"写着\"靠模型记 |\n| 7 | **MEMORY.md 回路** | 任务前读、任务后写的跨会话记忆 | 每次会话从零重新认识项目 |\n| 8 | **工作风格块**（限 3–5 行） | 写了\"你是谁/你讨厌什么/协作节奏\"，且每行都指向一个\"不写就会犯的具体错\" | 没有人格；或写成性格小作文 |\n| 9 | **30 秒三问** | 陌生人读完能答：产品？技术栈？新代码放哪 | 开头答不出这三问 |\n| 10 | **别替模型补它已经会的** | 不教通用写法/主流框架用法，只装项目私有事实 | 有\"如何使用 X / 使用教程 / step by step\"这类随模型升级很快过时的教学段 |\n\n**分档**：A 优秀 ≥85 · B 良好 ≥70 · C 及格 ≥50 · D 建议重写 <50。\n（机检：PASS=1 / WARN=0.5 / FAIL=0，INFO 不计分。**按重要度加权**——安全红线 #0 与\n减法核心项 #1/#3/#4/#10 权重 1.5，标准项 #0b/#2/#4b/#4c/#5/#9 为 1.0，加内容项 #6/#7/#8 为 0.6。\n#0 命中按 FAIL 计且资损级，定性总评里应一票顶到「先改这条」。）\n\n---\n\n## 机检的盲区（定性复核时重点纠偏）\n\n脚本只能判\"机器能确定的\"，以下几项**容易误判，必须你读正文定夺**：\n\n- **#4 图书馆 vs 路由器**：脚本只按\"大代码块/大表/历史标题\"猜。\n  - **目录树是路由地图，应保留**（脚本已不把纯 `├──└──` 树当图书馆图）；\n  - 但\"版本表/环境表\"这类**真铁律**即使是表格也该留正文——别因为是表就建议下沉；\n  - 反过来，一段没有特征字符的长叙事，脚本可能漏判，你要自己看出来。\n- **#3 规则可操作**：脚本靠模糊词黑名单，可能误伤（如正文在\"反对写干净代码这种空话\"），\n  也可能漏判（换了说法的空话）。读上下文再定。\n- **#5 高危模块**：脚本按目录名猜（payment/auth/...），可能漏掉项目里叫法特殊的高危模块，\n  也可能把无关同名目录算进来。结合项目实际业务判断。\n- **#9 30 秒三问**：脚本只看关键词信号在不在；你要**真的当一次陌生人**读开头，看能不能答出。\n- **#10 别替模型补它已经会的**：脚本只按\"教程/如何使用/step by step\"等措辞猜，会误伤——\n  比如正文在写\"本项目**自研**框架的用法\"(模型确实不知道，该留)，或在\"反对写教程\"。\n  读上下文定夺：**判据是\"这段知识模型升级后会不会自动变强\"**，会 → 删；不会(项目私有) → 留。\n  - **本 skill 自检会触发 #10 误报**：因为正文里就列着\"教程/如何使用/step by step\"这些**待检测的黑名单词**（评分表、机检盲区、修复清单都得举例它们）——这是元层面的正常现象，定性时直接放行，别去删那些词（删了这个体检器就不工作了）。\n\n---\n\n## 安全红线（务必遵守）\n\n- **绝不读取密钥文件**：`.env` / `.env.*` / `*.key` / `*.pem` / `*secret*` 一律不打开（脚本本身也不读）。\n  需要某个非密钥值时，让用户用 `! grep KEY 文件` 自己取。\n- 体检是只读操作；**任何文件改动都要先说明改哪些、为什么，得到同意再动**。\n- 多语言/多框架项目通用——本 skill 不绑定任何具体技术栈。\n\n---\n\n## 修复动作清单（用户同意后按需执行）\n\n- **拔密钥（最高优先）**：#0 命中时先把明文 key/token/私钥/口令移出 CLAUDE.md，改放\n  `.env`／密钥管理器，正文最多留「见环境变量 XXX」；命中即视为已泄露，提醒用户**轮换**该凭据，\n  并检查是否已被提交进 git（如是需清历史）。\n- **修死链**：#4b 报的死指针——补上缺失的 docs 文件，或修正/删除指针。\n- **瘦身**：把架构图/前端技术栈表/路由表等\"图书馆\"内容迁到 `docs/architecture.md`、\n  `docs/runtime.md`，正文替换成一行指针（Tier 2 按需打开，不预读）。\n- **补禁止清单**：和用户确认项目已淘汰/冲突的库与做法，写成 Do NOT 清单。\n- **可操作化**：把\"干净/简洁\"改写成具体可判定规则。\n- **删教学型冗余**：把\"如何使用 X / 主流框架用法 / step by step 教程\"这类段落删掉——\n  模型已经会、且随升级自动变强，留着只是为\"很快过时的东西\"每次付上下文费。\n- **加高危护栏**：给 payment/auth 等目录新建本地 CLAUDE.md（安全红线 + 已知陷阱 + 改动前确认）。\n- **配 Hook**：把\"改完跑测试/格式化/改 .env 提醒重启\"等做成 `.claude/settings.json` 的\n  Pre/PostToolUse Hook（告警型即可，别默认做有破坏性的自动执行）。\n- **记忆回路**：在 CLAUDE.md 加\"任务前读 MEMORY.md、任务后写回\"指令。\n- **工作风格块**：顶部加\"My Working Style\"（先方案后代码、列选项不猜、讨厌的回复腔等）。\n- 改完**重新跑一次 `check.py`** 给前后对比分数。\n\n---\n\n## 落地骨架（建文件/重写时的推荐结构，≤200 行）\n\n```\n# 项目名\n## 30 秒速览      # 产品 / 技术栈 / 新代码放哪 + 优化优先级\n## 工作风格        # 你是谁、你讨厌什么、协作节奏（限 3–5 行，每行都对应一个\"不写就会犯的错\"，别写性格小作文）\n## 跨会话记忆      # 任务前读 MEMORY.md，任务后写回\n## 铁律            # 编号、可执行、带后果（含 Do NOT 清单）\n## 关键事实表      # 版本 / 环境等不可由代码自查的硬信息（真铁律，留正文）\n## 目录结构        # 新代码放哪里（路由地图，可留正文）\n## 延伸文档        # Tier 2 指针：docs/...，按需打开不预读\n## 规划中功能      # 尚未落地，别假设已存在\n```\n\nFile v1.3.1:README.md\n\n# hekouwang-claude-md-doctor-skill\n\n**简体中文** · [English](README.en.md)\n\n[![CI](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n![Python](https://img.shields.io/badge/python-3.x-blue.svg)\n![dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)\n![open source](https://img.shields.io/badge/open%20source-free-success.svg)\n\n> **会勇禾口王的AI笔记** 出品 · `@huiyonghkw`\n> _不聊 AI 会不会取代你，只聊先用 AI 的人怎么取代你。_\n\nCLAUDE.md / AGENTS.md 体检器 —— 检查任意项目的运行时配置是否符合\"**路由器、不是图书馆**\"，\n给出评分卡 + 修复建议。\n\n## 30 秒验收\n\n```bash\npython3 check.py .                    # 体检当前项目（零依赖）\nbash scripts/run-all-doctors.sh .     # 三件套：md + skill + env\n```\n\n<p align=\"center\">\n  <img src=\"examples/demo.gif\" width=\"720\" alt=\"hekouwang-claude-md-doctor-skill 体检演示\">\n  <br><sub>↑ 一句「检查我的 CLAUDE.md」/ <code>python3 check.py</code>，秒出评分 + 修复建议（免费 CLI）</sub>\n</p>\n\n一句话判据：**CLAUDE.md 每次会话都被重新加载、要付上下文费。值不值得每次会话都为这段内容付一次费？**\n\n<p align=\"center\">\n  <img src=\"examples/report-card.gif\" width=\"420\" alt=\"CLAUDE.md 体检报告卡（动效示例）\">\n  <br><sub>↑ 品牌可视化报告卡（<b>付费增值</b>示例）——评分弧随分数填充、等级 D→A 变色。免费版输出文本/JSON 报告。</sub>\n</p>\n\n## 为什么需要它\n\n很多人把 CLAUDE.md 写成\"项目说明书\"：塞进历史、技术决策、营销叙事，动辄上千行。\n结果模型在冗长上下文里迷失，还挤掉了真正理解代码的空间。这个工具把 10 条可检查的\n最佳实践固化下来，让任何人一键体检自己的项目。\n\n核心立场是 Claude Code 之父 Boris Cherny / Cat Wu 的 **context minimalism —— 别跟模型较劲做加法**：\n模型每代都在变强，你今天费劲搭的脚手架很快白搭。所以评分按\"减法优先\"加权，\n\"越短越准\"类核心项权重更高，\"加内容\"类项缺了不重罚。\n\n## 10 项检查\n\n1. 篇幅 ≤ 200 行（路由器不是图书馆）\n2. 禁止清单（Do NOT introduce）\n3. 规则可操作（非\"写干净代码\"式空话）\n4. 路由器不是图书馆（大块下沉 docs/ 留指针）\n5. 高危模块有本地 CLAUDE.md（碰钱/认证/迁移）\n6. 关键规则有 Hook 强制（不靠模型记忆）\n7. 跨会话记忆回路（MEMORY.md）\n8. 工作风格块（你是谁 / 你讨厌什么 · 限 3–5 行）\n9. 30 秒三问（产品 / 技术栈 / 新代码放哪）\n10. 别替模型补它已经会的（无\"如何使用 X / 教程\"式随模型升级即过时的冗余）\n\n## 用法\n\n### 在 Claude Code 里（推荐）\n直接说：「**检查我的 CLAUDE.md**」「**CLAUDE.md 体检**」——会自动跑机检 +\n模型定性复核，给出评分和按优先级的修复建议，并可代为修复。\n\n### 命令行直接跑（零依赖，仅需 Python 3）\n```bash\npython3 check.py [项目目录]          # 默认当前目录，输出彩色报告\npython3 check.py [项目目录] --json   # 机器可读 JSON（CI 可用）\n```\n退出码：有 FAIL → 1，否则 0（可用于 CI 卡关）。\n\n### Docker（不想装 Python 也能跑）\n```bash\n# 拉官方镜像直接用（打 tag 时 GitHub Actions 自动发布到 GHCR）\ndocker run --rm -v \"$PWD:/work\" ghcr.io/huiyonghkw/hekouwang-claude-md-doctor-skill\n\n# 或本地自建\ndocker build -t claude-md-doctor .\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor            # 体检当前项目\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor /work --json\n```\n\n### 接进 CI 卡关（GitHub Actions 示例）\n```yaml\n- uses: actions/setup-python@v5\n  with: { python-version: \"3.x\" }\n- name: CLAUDE.md 体检（不合格则拦 PR）\n  run: |\n    curl -sO https://raw.githubusercontent.com/huiyonghkw/hekouwang-claude-md-doctor-skill/main/check.py\n    python3 check.py .\n```\n本仓库自身的 CI 见 [`.github/workflows/ci.yml`](.github/workflows/ci.yml)（语法 + good/bad 夹具 + JSON 合法性）。\n\n## 这不是内置的 `/doctor` 命令\n\nClaude Code 自带一个 `/doctor` 命令，名字也带 \"doctor\"，但**体检对象和本工具完全不同**——\n一个查整套工具的运行环境，一个只查一份文档写得好不好。别搞混。\n\n| 维度 | 内置 `/doctor` | 本工具（claude-md-doctor） |\n|------|---------------|----------------------------|\n| **体检对象** | 整个 Claude Code **运行环境 / 安装** | 单个项目的 **`CLAUDE.md` 文件本身** |\n| **关注点** | 安装健康、未用扩展、上下文膨胀、慢 Hook、版本、权限模式 | `CLAUDE.md` 是否当运行时配置写、篇幅、该不该懒加载、10 项评分 |\n| **改哪里** | `~/.claude/` 全局配置层 | 项目里的 `CLAUDE.md` 内容 |\n| **作用范围** | 全局 · 跨所有项目 | 就这一个项目的文档 |\n\n**唯一交集**：`/doctor` 会去重本地 vs 入库 `CLAUDE.md`、把该懒加载的内容迁走，但它只从\n「上下文成本」看、**不评文档质量**。**怎么用**：先 `/doctor` 发现「CLAUDE.md 太大」，\n再用本工具深度评分 + 出 Top 3 + 代重构——`/doctor` 负责发现文档偏大，本工具负责回答「具体哪几条该删、怎么改」。\n\n## 免费 / 付费（Freemium）\n\n- **免费（开源内核）**：命令行体检器 `check.py` —— 文本 / JSON 报告、评分、退出码。\n  本地或 Docker 随便跑、随便接进 CI。这是开放内核，永久免费。\n- **付费（增值服务）**：**品牌可视化体检报告卡** —— 评分弧 + 等级带 + 九项明细的\n  精美分享图（适合汇报 / 发圈 / 放进 PR）。它依赖私有视觉系统（品牌字体与版式，\n  即私有 Skill `hekouwang-content-factory`，**GitHub 上为 PRIVATE 仓库，非授权无法 clone / 获取**），\n  **不随本仓库分发**。需要出图版报告，请联系 **@huiyonghkw** 获取。\n\n> 一句话：**跑检查免费，出「好看的报告图」找我。**  \n> 联系：**GitHub / ClawHub [@huiyonghkw](https://github.com/huiyonghkw)** · 可视化报告卡私信获取\n\n## 体检器三件套\n\n与 [`skill-doctor`](https://github.com/huiyonghkw/hekouwang-claude-skill-doctor-skill)、[`env-doctor`](https://github.com/huiyonghkw/hekouwang-env-doctor-skill) 组成 **hekouwang-doctor-suite**。一键：`bash scripts/run-all-doctors.sh <项目根>`（见 `references/doctor-suite.md`）。\n\n## 设计\n\n- **机检层（`check.py`）**：确定性、零依赖、可移植，跑启发式检查并打分。\n- **定性层（`SKILL.md`）**：模型读正文复核机检盲区（图书馆 vs 路由器、规则是否可执行），\n  再出最终报告与修复方案。\n- **安全**：绝不读取 `.env` / `*.key` / `*.pem` 等密钥文件；体检只读，改动需确认。\n\n## 评分档位\n\nA 优秀 ≥85 · B 良好 ≥70 · C 及格 ≥50 · D 建议重写 <50\n\n## 许可协议 / License\n\n本仓库代码以 **MIT License** 开源 —— 免费使用、修改、分发、商用，仅需保留版权与许可声明。详见 [LICENSE](LICENSE)。\n\n> 范围说明：MIT 覆盖本仓库代码（`check.py` / `SKILL.md` 等）。品牌名「会勇禾口王的AI笔记」与**付费可视化报告卡**（依赖未公开的品牌字体与版式）属增值服务，不在开源范围内——但这不影响你免费、自由地使用命令行体检器。\n\n## 贡献 / Contributing\n\n欢迎提 Issue / PR：新增检查项、降低误报、补充其它语言/框架的启发式规则。\n保持零运行时依赖（仅 Python 3 标准库）是硬约束。\n\n---\n\n<sub>—— 会勇禾口王的AI笔记 · @huiyonghkw · AI 实战拆解：编程 × 内容创作 × 自动化（硬核 · 具体 · 可复制）</sub>\n\nFile v1.3.1:_meta.json\n\n{\n  \"ownerId\": \"kn73qd1gcmjr446mwcbdxef70x82vxcw\",\n  \"slug\": \"hekouwang-claude-md-doctor-skill\",\n  \"version\": \"1.3.1\",\n  \"publishedAt\": 1786521763033\n}\n\nFile v1.3.1:references/doctor-suite.md\n\n# hekouwang-doctor-suite · 体检器三件套\n\n> 竞品多是单点；这套把「项目配置 → 技能包 → 本机环境」串成一条验收链。\n\n```\nhekouwang-doctor-suite（概念）\n├── md-doctor      → AGENTS.md / CLAUDE.md（运行时配置）\n├── skill-doctor   → SKILL.md（Agent 技能包）\n└── env-doctor     → 磁盘 / 版本管理器 / AI 宿主目录\n```\n\n## 一键跑\n\n```bash\nbash scripts/run-all-doctors.sh /path/to/your-project\n```\n\n（脚本在 `hekouwang-claude-md-doctor-skill`；`skill-doctor` / `env-doctor` 仓内各有一份相同副本。）\n\n## 建议顺序\n\n1. **md-doctor** — 根配置是否「路由器」而非「图书馆」\n2. **skill-doctor** — `.agents/skills/` 下各 skill 是否按需加载\n3. **env-doctor** — 本机是否留着已换掉的 nvm / 膨胀的 AI 缓存\n\n## 免费 vs 付费\n\n| | 免费（开源） | 付费增值 |\n|---|---|---|\n| 机检 | `check.py` / `scan.sh` 文本报告 + JSON | 品牌可视化报告卡（评分弧 + 等级带） |\n| CI | 退出码卡关 | — |\n| 联系 | GitHub Issue / PR | ClawHub **@huiyonghkw** |\n\nFile v1.3.1:CHANGELOG.md\n\n# Changelog\n\n本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。\n\n## [1.3.1] - 2026-08-12\n\n### 新增\n- `scripts/run-all-doctors.sh`：hekouwang-doctor-suite 三件套一键体检\n- `references/doctor-suite.md`：套件说明与免费/付费对照\n\n### 变更\n- `check.py`：无 `HEKOUWANG_CONTENT_FACTORY` 时提示付费报告卡 CTA\n- README：30 秒验收 + 三件套互链；summary 补英文 SEO 关键词\n\n## [1.3.0] - 2026-08-12\n\n### 新增\n- **`check.py` 支持 AGENTS.md**：根目录优先体检 `AGENTS.md`，其次 `CLAUDE.md` / `CLAUDE.local.md`；\n  子目录扫描同时认两份本地配置。\n- **#0b 双文件去重**：根目录 `AGENTS.md` + `CLAUDE.md` 同时存在且都不是薄指针 → WARN（双倍上下文费）。\n- **#4c Skill 路由**：正文应把细则指针到 `.agents/skills/`（或 `.cursor/skills/`），别堆在常驻正文。\n- 报告标题改为 **AGENT CONFIG DOCTOR**；JSON 输出增加 `root_configs` 字段。\n\n### 文档\n- `SKILL.md` 触发词补 `AGENTS.md` / `agents.md` / `运行时配置体检`；评分表扩至 12 项。\n- 新增测试夹具 `tests/fixtures/good-agents/`、`tests/fixtures/dual/`。\n\n## [1.2.2] - 2026-07-09\n\n### 文档\n- **新增「与内置 `/doctor` 命令的分工」小节**：两者名字都带 doctor 但体检对象完全不同——\n  内置 `/doctor` 查整套 Claude Code 运行环境（安装/未用扩展/上下文膨胀/权限/版本），\n  本 skill 只查一份 CLAUDE.md 的写法质量。给出对比表 + 唯一交集（`/doctor` Check 2/3 碰 CLAUDE.md\n  但只从上下文成本看、不评质量）+ 用法建议（先 `/doctor` 发现文档偏大，再用本 skill 深度评 + 重构）。\n- **README.md / README.en.md 同步**：两份 README 也各补一节「这不是内置的 `/doctor` 命令」\n  （精简对比表 + 唯一交集 + 组合用法），中英一致。\n\n## [1.2.1] - 2026-06-22\n\n自体检（用姊妹工具 skill-doctor 跑）后的两处打磨：\n\n### 优化\n- **SKILL.md 声明 `allowed-tools`**：收敛到本 skill 真正需要的工具集，减小越权面。\n- **补「本 skill 自检会触发 #10 误报」豁免说明**：正文里的\"教程/如何使用/step by step\"是\n  待检测的黑名单词本身（评分表/盲区/修复清单都要举例），机检会误报教学冗余——\n  与 skill-doctor 对齐，注明定性时直接放行，别删那些词（删了体检器就不工作）。\n\n## [1.2.0] - 2026-06-21\n\n对照社区教程 `luongnv89/claude-howto` 的 Memory 最佳实践逐条比对后，补上三个真空白\n（只取它的\"安全 + 机制正确性\"，不取它\"把文件写全\"的加法倾向）。\n\n### 新增\n- **安全红线检查「无硬编码密钥」(#0)**：扫正文里的 `sk-`/`AKIA`/`AIza`/`gh*_`/`xox*`/\n  JWT / 私钥块 / `password=`/`secret=` 等指纹，命中即 **FAIL**（权重 1.5、资损级）。\n  报告对命中值脱敏（前 4 位 + 长度）。占位/示例值（`<your-pwd>`/`${VAR}`/`example` 等）自动豁免。\n  补齐教程头号 Don't \"Never store secrets in CLAUDE.md\"——此前脚本只防自己读 .env，\n  却不查被体检文件本身是否藏密钥。\n- **指针死链检查 (#4b)**：`docs/` 文本指针与原生 `@import` 路径都校验目标文件是否存在，\n  死链 → WARN（指向不存在的文件比没指针更糟）。\n\n### 变更\n- **#4 路由器检查认原生 `@import` 语法**：此前只认纯文本 `docs/...`，用官方 `@path` 导入\n  反而不给\"下沉指针\"加分；现在两种写法都算合格指针。\n\n### 文档 / 测试\n- `SKILL.md` 评分表补 #0 与 #4b，加权说明与修复动作清单同步（拔密钥 + 轮换提醒、修死链）。\n- good 夹具补 `docs/architecture.md`、`docs/api.md` 桩文件，示范\"指针均可解析\"。\n\n## [1.1.0] - 2026-06-18\n\n把 Claude Code 之父 Boris Cherny / Cat Wu 的\"context minimalism · 别跟模型较劲做加法\"\n立场接进体检逻辑。\n\n### 新增\n- **第 10 项检查「别替模型补它已经会的」**：扫教学型措辞(如何使用 / 使用教程 /\n  step by step / how to use)，命中即 WARN——这类通用写法随模型升级自动变强，\n  写进常驻正文只是为\"很快过时的东西\"每次付上下文费。\n- **「减法优先」元判据**：写进 `SKILL.md`，凌驾 9 项之上——加任何一段前先问\n  \"能不能不写在常驻正文里\"。\n\n### 变更\n- **评分改为按重要度加权**：减法核心项(#1 篇幅 / #3 可操作 / #4 路由器 / #10)权重 1.5，\n  加内容项(#6 Hook / #7 记忆 / #8 人格)降到 0.6。修掉旧逻辑\"一边喊越短越好、\n  一边因缺工作风格块扣分、逼用户把文件写长\"的自相矛盾。\n- **#8 工作风格块加上限护栏**：限 3–5 行，每行须对应一个\"不写就会犯的具体错\"，别写性格小作文。\n\n### 文档\n- `README` / `README.en` 同步「10 项检查」并写明「减法优先 · 别跟模型较劲做加法」立场。\n- `SKILL.md` 顶部署名补 GitHub 仓库地址\n  （<https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill>），方便 skillhub 溯源。\n\n## [1.0.0] - 2026-06-17\n\n首个正式版本。把\"CLAUDE.md 当运行时配置、不是项目说明书\"的最佳实践做成可跑在任意项目上的体检器。\n\n### 功能\n- **9 项检查的命令行体检器 `check.py`**：篇幅 / 禁止清单 / 规则可操作 / 路由非图书馆 /\n  高危模块本地 CLAUDE.md / Hook 强制 / MEMORY.md 回路 / 工作风格 / 30 秒三问。\n- 输出彩色文本报告或 `--json`；评分 0–100（A/B/C/D）；有 FAIL → 退出码 1（可 CI 卡关）。\n- 零运行时依赖（仅 Python 3 标准库）；只读，绝不读取 `.env` / `*.key` / `*.pem`。\n- **`SKILL.md` 定性复核层**：在 Claude Code 内说「检查我的 CLAUDE.md」即可机检 + 模型复核 + 代修复。\n- **Docker**：`docker run --rm -v \"$PWD:/work\" claude-md-doctor`，免装 Python。\n- **GitHub Actions CI**：语法 + good/bad 夹具 + JSON 合法性。\n- 中英双语 README、MIT LICENSE、CONTRIBUTING、示例动图（CLI 实录 + 动效报告卡）。\n\n### 商业模型\n- 命令行体检器开源免费（MIT）；品牌可视化报告卡为付费增值，依赖未公开字体/版式，不在仓库内。\n\n[1.0.0]: https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/releases/tag/v1.0.0\n\nFile v1.3.1:CONTRIBUTING.md\n\n# 贡献指南 / Contributing\n\n感谢参与 **hekouwang-claude-md-doctor-skill**！欢迎新增检查项、降低误报、为其它语言/框架补启发式规则。\n\n## 硬约束（不可破）\n\n1. **零运行时依赖** —— `check.py` 只用 Python 3 标准库。不要引入第三方包。\n2. **只读 + 安全** —— 检查器绝不读取 `.env` / `*.key` / `*.pem` 等密钥文件，不写用户文件。\n3. **跨语言通用** —— 不绑定任何具体技术栈；新规则要对多数项目成立。\n\n## 本地开发\n\n```bash\ngit clone https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill\ncd hekouwang-claude-md-doctor-skill\n\npython3 check.py tests/fixtures/good     # 期望 exit 0\npython3 check.py tests/fixtures/bad      # 期望 exit 1（有 FAIL 卡关）\npython -m py_compile check.py            # 语法自检\n```\n\n## 加一条检查项\n\n1. 在 `check.py` 的 `check()` 里用 `add(key, title, status, detail, fix)` 追加结果。\n2. `status` 取 `PASS` / `WARN` / `FAIL` / `INFO`（INFO 不计分）。\n3. 机检只做\"机器能确定的\"；需要读正文判断的，写进 `SKILL.md` 的「定性复核」与「机检盲区」。\n4. 在 `tests/fixtures/` 增/改夹具，确保 `good` 仍 exit 0、`bad` 仍 exit 1。\n5. 误报是头号大忌——宁可 `WARN` 不轻易 `FAIL`，并在 `detail` 里说清线索。\n\n## 提交 PR\n\n- 一个 PR 聚焦一件事；附上前后 `check.py` 输出对比。\n- 通过 CI（`.github/workflows/ci.yml`：语法 + good/bad 夹具 + JSON 合法性）。\n- commit 信息讲清「改了什么 + 为什么」。\n\n## 范围说明\n\n代码以 MIT 开源（见 [LICENSE](LICENSE)）。品牌名「会勇禾口王的AI笔记」与付费可视化报告卡为增值服务，不在本仓库开源范围内。\n\nFile v1.3.1:README.en.md\n\n# hekouwang-claude-md-doctor-skill\n\n[简体中文](README.md) · **English**\n\n[![CI](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n![Python](https://img.shields.io/badge/python-3.x-blue.svg)\n![dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)\n![open source](https://img.shields.io/badge/open%20source-free-success.svg)\n\n> Made by **会勇禾口王的AI笔记** (Hekouwang's AI Notes) · `@huiyonghkw`\n\nA health checker for `CLAUDE.md` — audits any project's `CLAUDE.md` against the\nbest practice of *\"treat it as runtime config, not a project manual\"*, and returns\na scorecard plus prioritized fixes.\n\n<p align=\"center\">\n  <img src=\"examples/demo.gif\" width=\"720\" alt=\"hekouwang-claude-md-doctor-skill demo\">\n  <br><sub>↑ Say \"check my CLAUDE.md\" or run <code>python3 check.py</code> — instant score + fixes (free CLI)</sub>\n</p>\n\nThe one rule it all comes down to: **CLAUDE.md is reloaded into context on every\nsession and costs tokens every time. Is this line worth paying for on every single session?**\n\n<p align=\"center\">\n  <img src=\"examples/report-card.gif\" width=\"420\" alt=\"CLAUDE.md report card (animated)\">\n  <br><sub>↑ Branded visual report card (<b>paid add-on</b> sample) — the score arc fills and the grade morphs D→A. The free version outputs a text/JSON report.</sub>\n</p>\n\n## Why it exists\n\nMost people write `CLAUDE.md` like a project manual: history, tech decisions,\nmarketing prose — easily over a thousand lines. The model then drowns in a bloated\ncontext and loses the room it needs to actually understand your code. This tool\nfreezes 10 checkable best practices into a one-command audit anyone can run.\n\nIts guiding stance is the **context minimalism** that Claude Code's creators\nBoris Cherny and Cat Wu preach — *don't fight the model by adding things*: models\nget stronger every generation, so the scaffolding you laboriously build today\ngoes stale fast. Scoring is therefore weighted \"subtraction-first\": the\nshorter-is-sharper core checks count more, missing \"add-content\" checks count less.\n\n## The 10 checks\n\n1. **Length ≤ 200 lines** — a router, not a library\n2. **A \"Do NOT introduce\" list** — block well-meant but incompatible deps\n3. **Actionable rules** — not vague \"write clean code\" platitudes\n4. **Router, not library** — move big blocks to `docs/`, leave pointers\n5. **Local CLAUDE.md for high-risk modules** — money / auth / migrations\n6. **Hooks enforce the critical rules** — don't rely on the model's memory\n7. **A MEMORY.md cross-session loop**\n8. **A working-style block** — who you are / what you hate (cap 3–5 lines)\n9. **The 30-second test** — product? stack? where does new code go?\n10. **Don't teach the model what it already knows** — no \"how to use X / tutorial\"\n    prose that goes stale the moment the model improves\n\n## Usage\n\n### Inside Claude Code (recommended)\nJust say **\"check my CLAUDE.md\"**. It runs the mechanical check, then does a\nmodel-driven qualitative review, and returns a score with prioritized fixes —\nand can apply the fixes for you.\n\n### Command line (zero deps, just Python 3)\n```bash\npython3 check.py [project_dir]          # defaults to CWD, prints a colored report\npython3 check.py [project_dir] --json   # machine-readable JSON (for CI)\n```\nExit code: `1` if any FAIL, else `0` (usable as a CI gate).\n\n### Docker (no Python needed)\n```bash\n# Pull the prebuilt image (auto-published to GHCR on each tag via GitHub Actions)\ndocker run --rm -v \"$PWD:/work\" ghcr.io/huiyonghkw/hekouwang-claude-md-doctor-skill\n\n# Or build locally\ndocker build -t claude-md-doctor .\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor            # check current project\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor /work --json\n```\n\n### Gate your PRs (GitHub Actions)\n```yaml\n- uses: actions/setup-python@v5\n  with: { python-version: \"3.x\" }\n- name: CLAUDE.md health check (fail the PR if non-compliant)\n  run: |\n    curl -sO https://raw.githubusercontent.com/huiyonghkw/hekouwang-claude-md-doctor-skill/main/check.py\n    python3 check.py .\n```\nThis repo's own CI lives in [`.github/workflows/ci.yml`](.github/workflows/ci.yml) (syntax + good/bad fixtures + JSON validity).\n\n## This is NOT the built-in `/doctor` command\n\nClaude Code ships a `/doctor` command that also says \"doctor\" — but it checks a\n**completely different thing**: `/doctor` audits your whole tool *environment*,\nthis tool audits one *document*. Don't confuse them.\n\n| Dimension | Built-in `/doctor` | This tool (claude-md-doctor) |\n|-----------|--------------------|------------------------------|\n| **Audits** | Your whole Claude Code **environment / install** | A single project's **`CLAUDE.md` file** |\n| **Looks at** | Install health, unused extensions, context bloat, slow hooks, version, permission mode | Whether `CLAUDE.md` reads as runtime config, length, lazy-loading, the 10-check score |\n| **Edits** | `~/.claude/` global config | The project's `CLAUDE.md` content |\n| **Scope** | Global · across all projects | Just this one project's doc |\n\n**The one overlap**: `/doctor` dedups local vs checked-in `CLAUDE.md` and migrates\nlazy-loadable content out — but only from a \"context cost\" angle; it **does not\ngrade document quality**. **How to combine them**: run `/doctor` first to catch\n\"your CLAUDE.md is too big\", then use this tool to score it, surface the Top 3,\nand rewrite it — `/doctor` finds that the doc is bloated, this tool answers *which\nlines to cut and how*.\n\n## Free / Paid (Freemium)\n\n- **Free (open-source core)**: the `check.py` CLI — text / JSON report, score,\n  exit code. Run it locally or in Docker, wire it into CI. Free forever.\n- **Paid (add-on service)**: the **branded visual report card** (score arc +\n  grade band + 9-check breakdown, great for sharing / PRs). It depends on a\n  private visual system (brand fonts & layout) and is **not shipped in this repo**.\n  Want the image version? Contact **@huiyonghkw**.\n\n> In one line: **running the check is free; getting the pretty report image, talk to me.**\n\n## Design\n\n- **Mechanical layer (`check.py`)**: deterministic, zero-dependency, portable —\n  runs heuristic checks and scores them.\n- **Qualitative layer (`SKILL.md`)**: the model reads the actual file to cover the\n  checker's blind spots (library vs router, whether rules are truly actionable),\n  then produces the final report and fix plan.\n- **Safety**: never reads `.env` / `*.key` / `*.pem` secrets; the audit is\n  read-only and any edits require confirmation.\n\n## Grade bands\n\nA (excellent) ≥85 · B (good) ≥70 · C (pass) ≥50 · D (rewrite) <50\n\n## License\n\nThe code in this repo is open-sourced under the **MIT License** — free to use,\nmodify, distribute, and use commercially; just keep the copyright and license\nnotice. See [LICENSE](LICENSE).\n\n> Scope: MIT covers the repo's code (`check.py` / `SKILL.md`, etc.). The brand\n> name \"会勇禾口王的AI笔记\" and the **paid visual report card** (which relies on\n> unreleased brand fonts & layout) are an add-on service, outside the open-source\n> scope — but that does not affect your free, unrestricted use of the CLI checker.\n\n## Contributing\n\nIssues / PRs welcome: new checks, fewer false positives, heuristics for more\nlanguages/frameworks. Keeping **zero runtime dependencies** (Python 3 stdlib only)\nis a hard constraint.\n\n---\n\n<sub>—— 会勇禾口王的AI笔记 · @huiyonghkw · AI in practice: coding × content × automation</sub>\n\nFile v1.3.1:skill-card.md\n\n## Description:\n\nAudits AGENTS.md or CLAUDE.md runtime configuration files, returns a scorecard with prioritized fixes, and can apply user-approved repairs.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[huiyonghkw](https://clawhub.ai/user/huiyonghkw)\n\n### License/Terms of Use:\n\nMIT\n\n## Use Case:\n\nDevelopers and engineers use this skill to audit project agent runtime configuration files for context cost, actionable guidance, routing, and safety guardrails. It produces a report and prioritized repair plan, with file edits only after user approval.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The optional suite script runs broader sibling skill and local environment checks beyond the core AGENTS.md/CLAUDE.md audit.\n\nMitigation: Use the core checker for standard audits; run scripts/run-all-doctors.sh only when broader local checks are intentional.\n\nRisk: The skill can propose or apply changes to project runtime configuration files.\n\nMitigation: Review the generated scorecard and proposed edits before approving file changes.\n\n## Reference(s):\n\n- [Repository homepage](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill)\n- [Doctor Suite reference](references/doctor-suite.md)\n- [ClawHub skill page](https://clawhub.ai/huiyonghkw/skills/hekouwang-claude-md-doctor-skill)\n\n## Skill Output:\n\n**Output Type(s):** [Analysis, Markdown, JSON, Code, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown report with optional JSON CLI output and proposed file edits]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May run the local checker; proposed file edits require user approval.]\n\n## Skill Version(s):\n\n1.3.1 (source: frontmatter and changelog, released 2026-08-12)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.3.1:tests/fixtures/bad/CLAUDE.md\n\n# 我的项目\n\n请写干净的代码，保持简洁优雅，注重性能，遵循最佳实践。\n代码要高质量、易于维护。谢谢配合。\n\n## React 使用教程\n\n如何使用 useState：调用 `const [x, setX] = useState(0)`，setX 触发重渲染。\n如何使用 useEffect：把副作用放进 useEffect，依赖数组控制何时重跑。\n这些都是 React 的标准用法，跟着 step by step 写就行。\n\nFile v1.3.1:tests/fixtures/dual/AGENTS.md\n\n# Acme Dashboard\n\n> 30 秒速览：面向运营经理的 B2B 分析仪表盘。优化优先级：加载速度 > 交互 > 视觉。\n> 新代码按下方目录结构放进对应模块；动手前先看该模块 README。\n\n## 工作风格\n- 先给方案再写代码；不确定时列选项，不要猜。\n- 汇报用中文，代码与注释用英文；文件引用用绝对路径。\n- 不说「Great question!」这类客套，直接给结论。\n\n## 跨会话记忆\n- 任务开始前扫一遍 `MEMORY.md`；结束后把新的非显然结论写回。\n\n## 铁律\n1. 用 named export（路由文件除外）。\n2. 禁 `any`，用泛型或接口替代。\n3. 单组件不超过 200 行（有充分理由可超）。\n\n## 技术栈（tech stack）\n- Next.js 15 App Router + TypeScript\n- Tailwind CSS + shadcn/ui\n- PostgreSQL（数据层）\n\nDo NOT introduce unless explicitly requested:\n- Redux（已迁移到 React Context + Zustand）\n- styled-components（全站 Tailwind，不收 CSS-in-JS）\n- MongoDB（数据层锁定 PostgreSQL）\n\n## 目录结构（directory · 新代码放哪里）\n```\nsrc/\n  app/        # 路由与页面\n  components/ # 复用组件\n  lib/        # 工具与数据访问\n```\n\n## 延伸文档（Tier 2，按需打开）\n- 架构总览：`docs/architecture.md`\n- API 文档：`docs/api.md`\n\nFile v1.3.1:tests/fixtures/dual/CLAUDE.md\n\n# Acme Dashboard\n\n> 30 秒速览：面向运营经理的 B2B 分析仪表盘。优化优先级：加载速度 > 交互 > 视觉。\n> 新代码按下方目录结构放进对应模块；动手前先看该模块 README。\n\n## 工作风格\n- 先给方案再写代码；不确定时列选项，不要猜。\n- 汇报用中文，代码与注释用英文；文件引用用绝对路径。\n- 不说「Great question!」这类客套，直接给结论。\n\n## 跨会话记忆\n- 任务开始前扫一遍 `MEMORY.md`；结束后把新的非显然结论写回。\n\n## 铁律\n1. 用 named export（路由文件除外）。\n2. 禁 `any`，用泛型或接口替代。\n3. 单组件不超过 200 行（有充分理由可超）。\n\n## 技术栈（tech stack）\n- Next.js 15 App Router + TypeScript\n- Tailwind CSS + shadcn/ui\n- PostgreSQL（数据层）\n\nDo NOT introduce unless explicitly requested:\n- Redux（已迁移到 React Context + Zustand）\n- styled-components（全站 Tailwind，不收 CSS-in-JS）\n- MongoDB（数据层锁定 PostgreSQL）\n\n## 目录结构（directory · 新代码放哪里）\n```\nsrc/\n  app/        # 路由与页面\n  components/ # 复用组件\n  lib/        # 工具与数据访问\n```\n\n## 延伸文档（Tier 2，按需打开）\n- 架构总览：`docs/architecture.md`\n- API 文档：`docs/api.md`\n\nFile v1.3.1:tests/fixtures/dual/docs/api.md\n\n# API 文档\n\n（夹具桩文件：演示下沉指针可解析。）\n\nArchive v1.3.0: 21 files, 42805 bytes\n\nFiles: CHANGELOG.md (6020b), check.py (31929b), CONTRIBUTING.md (1772b), Dockerfile (763b), LICENSE (1096b), README.en.md (7688b), README.md (7509b), skill-card.md (2107b), SKILL.md (15872b), tests/fixtures/bad/CLAUDE.md (423b), tests/fixtures/dual/AGENTS.md (1308b), tests/fixtures/dual/CLAUDE.md (1308b), tests/fixtures/dual/docs/api.md (69b), tests/fixtures/dual/docs/architecture.md (95b), tests/fixtures/good-agents/AGENTS.md (1308b), tests/fixtures/good-agents/docs/api.md (69b), tests/fixtures/good-agents/docs/architecture.md (95b), tests/fixtures/good/CLAUDE.md (1308b), tests/fixtures/good/docs/api.md (69b), tests/fixtures/good/docs/architecture.md (95b), _meta.json (151b)\n\nFile v1.3.0:SKILL.md\n\n---\nname: hekouwang-claude-md-doctor-skill\nversion: 1.3.0\ndescription: >\n  会勇禾口王的AI笔记 · Agent 运行时配置体检器。检查项目的 AGENTS.md（跨 Agent 推荐）\n  或 CLAUDE.md（及子目录本地配置）是否符合\"把它当运行时配置、不是项目说明书\"的最佳实践，\n  给出评分卡 + 按优先级的修复建议，并可代为修复。触发：用户说「检查我的 CLAUDE.md /\n  AGENTS.md / 运行时配置体检 / claude-md-doctor / agents.md 规范吗 / audit CLAUDE.md /\n  lint AGENTS.md / 看看我的 agent 配置合不合规」。\n  任何\"评估/审查/优化某个项目 AGENTS.md 或 CLAUDE.md 质量\"的请求都应触发。\nallowed-tools:\n  - Bash\n  - Read\n  - Write\n  - Edit\n  - Glob\n  - Grep\n  - AskUserQuestion\n---\n\n# hekouwang-claude-md-doctor-skill · Agent 运行时配置体检器\n\n> **会勇禾口王的AI笔记** 出品 · `@huiyonghkw`\n> GitHub: <https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill>\n> _不聊 AI 会不会取代你，只聊先用 AI 的人怎么取代你。_\n\n把\"Agent 运行时配置最佳实践\"做成一个能跑在任何项目上的检查器：机检定量 + 模型定性，\n产出评分卡和可落地的修复建议。核心判据一句话——\n\n> **AGENTS.md / CLAUDE.md 是每次会话都被重新加载、要付上下文费的\"运行时配置\"，不是给人读的项目说明书。**\n> 2026 年起 Cursor / Codex / OpenClaw 等多读 **AGENTS.md**；Claude Code 仍读 **CLAUDE.md**。\n> 一切检查项都从这句推导：值不值得每次会话都为这段内容付一次费？\n\n### 减法优先（元判据 · 凌驾全部检查项之上）\n\nClaude Code 之父 Boris Cherny 公开说自己的配置\"surprisingly vanilla\"、几乎不定制；\n联合创造者 Cat Wu 自称 \"context minimalist\"——只告诉模型它需要知道的，剩下让它自己想。\n**核心立场：模型每代都在变强，你今天费劲搭的脚手架很快白搭；别跟模型较劲做加法。**\n\n所以下面这些检查项里凡是\"让用户往里加内容\"的(禁止清单/Hook/记忆/人格/本地文件)，\n落地前都先过这一关 —— **加任何一段前先问：这条能不能不写在常驻正文里？**\n\n- 能挂 **Hook**(确定性规则)→ 挂 Hook，别写正文(模型不必每次读)。\n- 能下沉 **docs/** 的 → 下沉，正文留一行指针。\n- 能靠 **linter / 类型检查 / 测试**兜住的 → 删掉，别让模型干 linter 的活。\n- 通用写法 / 主流框架用法 → 删掉，那是模型已经会的(见 #10)。\n- **只有\"模型会反复犯错、且没有机械手段能兜住\"的，才值得占常驻 token。**\n\n机检层面：**#1 篇幅 / #3 可操作 / #4 路由器 / #10 别替模型补**这几项是减法核心，权重更高；\n\"加内容\"类项(#6/#7/#8)缺失只算小扣分，避免工具一边喊\"越短越好\"、一边逼用户把文件写长。\n\n## 品牌人设（体检报告的口吻 + 署名）\n\n这套工具属于 **会勇禾口王的AI笔记**（定位：AI 实战拆解，硬核·具体·可复制；人设：你办公室里第一个把 AI 用明白的同事）。出体检报告时：\n\n- **口吻**：像同事帮你看代码——直给结论、敢泼冷水（\"这条是空话，5 秒判不了就是不合格\"），不说\"Great question / 我很乐意帮忙\"这类客套。\n- **价值化**：修复建议讲\"省了什么\"（少几十次会话的冗余、挡住一次资损/越权），不堆术语。\n- **署名**：报告结尾固定带一行品牌签收 —— `—— 会勇禾口王的AI笔记 · @huiyonghkw`，并可附 slogan。命令行 `check.py` 的报告页脚已内置该署名。\n- **去 AI 味**：定稿前避开\"赋能/打造/至关重要/助力\"等词，说人话。\n\n---\n\n## 免费 / 付费边界（重要）\n\n- **免费（开源内核）**：`check.py` 的**文本 / JSON 报告 + 评分**。任何人本地或 Docker 跑、进 CI，随便用。\n- **付费（增值）**：**品牌可视化体检报告卡**（评分弧 + 等级带 + 九项明细的精美分享图）。\n  它依赖 `hekouwang-content-factory` 的**私有品牌字体与版式**，不随本仓库分发。\n\n**触发\"出图 / 报告卡 / 图表 / 可视化\"时怎么办**：\n1. 先照常给**免费文本报告**（机检 + 定性复核）。\n2. 是否生成图：检查本机有没有 `hekouwang-content-factory`（品牌字体在\n   `~/.claude/skills/hekouwang-content-factory/assets/fonts/`）。\n   - **有**（作者本人环境）：可按 V2 米白生成报告卡 PNG。\n   - **没有**（外部用户）：明确说明可视化报告是**付费增值项**，引导联系 **@huiyonghkw** 获取，\n     不要用系统字体凑一张劣化图糊弄。\n3. 一句话口径：**跑检查免费，出\"好看的报告图\"找我。**\n\n---\n\n## 与内置 `/doctor` 命令的分工（名字像，别混用）\n\nClaude Code 内置了一个 `/doctor` 命令，名字也带 \"doctor\"，但**体检对象和本 skill 完全不同**——\n一个查整套工具的运行环境，一个只查一份文档写得好不好。别把两者当同一个东西。\n\n| 维度 | 内置 `/doctor` 命令 | 本 skill（claude-md-doctor） |\n|------|--------------------|------------------------------|\n| **体检对象** | 整个 **Claude Code 运行环境 / 安装** | 单个项目的 **CLAUDE.md 文件本身** |\n| **关注点** | 安装健康、未用扩展(skill/MCP/plugin)、常驻上下文膨胀、慢 Hook、版本、权限模式、预批命令、本地记忆去重 | CLAUDE.md 是否「当运行时配置写而非项目说明书」、篇幅、该不该懒加载、评分卡 + 分级修复 |\n| **改哪里** | `~/.claude/` 配置层（settings.json、skillOverrides、`.claude.json`） | 项目里的 `CLAUDE.md` / 子目录本地 CLAUDE.md 内容 |\n| **作用范围** | 全局 · 跨所有项目的工具链 | 就这一个项目的文档 |\n| **产物** | 环境体检报告 + 两道确认后改配置 | 评分卡（10 项）+ Top 3 修复建议，可代改 |\n\n**唯一交集**：`/doctor` 的 **Check 2 / Check 3** 会碰 CLAUDE.md——去重本地 vs 入库 CLAUDE.md、\n把该懒加载的内容迁到 skill/子目录。但它是从**「上下文成本」**这一个角度看，只管「有没有重复、该不该常驻」，\n**不评文档质量**；本 skill 才从**「写法规范」**全面打分（可操作性、禁止清单、高危护栏、30 秒三问……）。\n\n### 用法建议\n\n- **想知道「我这套 Claude Code 装得干净、跑得健康吗」** → 跑内置 `/doctor`。\n- **想知道「我这个项目的 CLAUDE.md 写得规范吗」** → 触发本 skill。\n- **两者串起来用（推荐）**：先 `/doctor` 体检环境，若它在 Check 3 提示「CLAUDE.md 太大 / 该懒加载」，\n  接着用本 skill 深度评一份 + 出 Top 3 + 代重构——`/doctor` 负责发现「这份文档偏大」，本 skill 负责回答「具体哪几条该删、怎么下沉」。\n- **别指望 `/doctor` 替你把 CLAUDE.md 写规范**：它只做去重和迁移，不判「这条规则是不是空话」「禁止清单缺不缺」——那是本 skill 的活。\n\n---\n\n## 工作流（每次体检按这个顺序）\n\n1. **确认目标目录**：用户没指明就用当前工作目录；说了某项目就用那个绝对路径。\n2. **跑机检**（确定性层，零依赖）：\n   ```bash\n   python3 <此skill目录>/check.py <项目目录>\n   ```\n   - 需要结构化结果时加 `--json`（便于你解析后二次判断）。\n   - 退出码：有 FAIL → 1，否则 0。\n3. **定性复核**（机检之上，必须做）：机检是启发式，几项需要你**真正读正文**再下结论：\n   - 实际打开根 `AGENTS.md` 或 `CLAUDE.md` 通读一遍（机检已自动选优先级更高的那份）；\n   - 用下面《评分标准》逐条核对，**重点修正机检可能误判的项**（见\"机检的盲区\"）；\n   - 抽查 1–2 个子目录本地 AGENTS.md / CLAUDE.md 是否写了真红线（不是空模板）。\n4. **出报告**：先给一句话总评 + 分数档位，再用\"✓/▲/✗ + 一句话 + 修复建议\"逐条列，\n   最后给 **Top 3 最该先改的**（按\"花最小力气补最大漏洞\"排序）。中文输出。\n5. **提出代修复**：问用户要不要直接改（瘦身下沉 docs/、补禁止清单、补工作风格块、\n   加高危模块本地 CLAUDE.md、配 Hook 等）。**得到同意再动文件**，一次改一类、可回退。\n\n> 不要只把脚本输出原样贴给用户——脚本是线索，你的价值在定性判断 + 具体怎么改。\n\n---\n\n## 评分标准（12 项 · 也是机检的判分依据）\n\n| # | 检查项 | 合格长什么样 | 不合格信号 |\n|---|--------|------------|-----------|\n| 0 | **无硬编码密钥（安全红线）** | 正文不出现 key/token/私钥/口令明文 | 出现 `sk-`/`AKIA`/私钥块/`password=\"...\"` → **直接 FAIL** |\n| 0b | **AGENTS + CLAUDE 不双份加载** | 只留一份真源；另一份是一行指针 | 根目录两份都「厚」、内容重复 → **WARN**（双倍上下文费） |\n| 1 | **篇幅 ≤ 200 行** | 路由器不是图书馆，常驻越短越好 | >200 行；大段历史/营销/教程正文 |\n| 2 | **禁止清单（Do NOT）** | 有\"不要引入 X（因为 Y）\"清单 | 只列要用的、不列禁用的 |\n| 3 | **规则可操作** | 5 秒内能判定代码合不合规 | \"写干净代码/优雅/高质量\"这类空话 |\n| 4 | **路由器不是图书馆** | 大块下沉 docs/，正文留指针（认 docs/ 文本指针与原生 `@import`） | 架构图/长表/历史塞在常驻正文 |\n| 4b | **指针无死链** | docs/ 与 `@import` 都指向真实存在的文件 | 指针指向不存在的文件（按图索骥扑空，比没指针更糟） |\n| 4c | **细则路由到 Skill** | 工作流细则在 `.agents/skills/`，正文留指针 | 有 skills 目录但正文很长且不提路由 |\n| 5 | **高危模块本地配置** | 碰钱/认证/迁移目录各有 AGENTS.md 或 CLAUDE.md | 敏感模块只靠根文件一句话 |\n| 6 | **Hook 强制层** | 最不能漏的规则挂成 Hook | 关键规则只\"写着\"靠模型记 |\n| 7 | **MEMORY.md 回路** | 任务前读、任务后写的跨会话记忆 | 每次会话从零重新认识项目 |\n| 8 | **工作风格块**（限 3–5 行） | 写了\"你是谁/你讨厌什么/协作节奏\"，且每行都指向一个\"不写就会犯的具体错\" | 没有人格；或写成性格小作文 |\n| 9 | **30 秒三问** | 陌生人读完能答：产品？技术栈？新代码放哪 | 开头答不出这三问 |\n| 10 | **别替模型补它已经会的** | 不教通用写法/主流框架用法，只装项目私有事实 | 有\"如何使用 X / 使用教程 / step by step\"这类随模型升级很快过时的教学段 |\n\n**分档**：A 优秀 ≥85 · B 良好 ≥70 · C 及格 ≥50 · D 建议重写 <50。\n（机检：PASS=1 / WARN=0.5 / FAIL=0，INFO 不计分。**按重要度加权**——安全红线 #0 与\n减法核心项 #1/#3/#4/#10 权重 1.5，标准项 #0b/#2/#4b/#4c/#5/#9 为 1.0，加内容项 #6/#7/#8 为 0.6。\n#0 命中按 FAIL 计且资损级，定性总评里应一票顶到「先改这条」。）\n\n---\n\n## 机检的盲区（定性复核时重点纠偏）\n\n脚本只能判\"机器能确定的\"，以下几项**容易误判，必须你读正文定夺**：\n\n- **#4 图书馆 vs 路由器**：脚本只按\"大代码块/大表/历史标题\"猜。\n  - **目录树是路由地图，应保留**（脚本已不把纯 `├──└──` 树当图书馆图）；\n  - 但\"版本表/环境表\"这类**真铁律**即使是表格也该留正文——别因为是表就建议下沉；\n  - 反过来，一段没有特征字符的长叙事，脚本可能漏判，你要自己看出来。\n- **#3 规则可操作**：脚本靠模糊词黑名单，可能误伤（如正文在\"反对写干净代码这种空话\"），\n  也可能漏判（换了说法的空话）。读上下文再定。\n- **#5 高危模块**：脚本按目录名猜（payment/auth/...），可能漏掉项目里叫法特殊的高危模块，\n  也可能把无关同名目录算进来。结合项目实际业务判断。\n- **#9 30 秒三问**：脚本只看关键词信号在不在；你要**真的当一次陌生人**读开头，看能不能答出。\n- **#10 别替模型补它已经会的**：脚本只按\"教程/如何使用/step by step\"等措辞猜，会误伤——\n  比如正文在写\"本项目**自研**框架的用法\"(模型确实不知道，该留)，或在\"反对写教程\"。\n  读上下文定夺：**判据是\"这段知识模型升级后会不会自动变强\"**，会 → 删；不会(项目私有) → 留。\n  - **本 skill 自检会触发 #10 误报**：因为正文里就列着\"教程/如何使用/step by step\"这些**待检测的黑名单词**（评分表、机检盲区、修复清单都得举例它们）——这是元层面的正常现象，定性时直接放行，别去删那些词（删了这个体检器就不工作了）。\n\n---\n\n## 安全红线（务必遵守）\n\n- **绝不读取密钥文件**：`.env` / `.env.*` / `*.key` / `*.pem` / `*secret*` 一律不打开（脚本本身也不读）。\n  需要某个非密钥值时，让用户用 `! grep KEY 文件` 自己取。\n- 体检是只读操作；**任何文件改动都要先说明改哪些、为什么，得到同意再动**。\n- 多语言/多框架项目通用——本 skill 不绑定任何具体技术栈。\n\n---\n\n## 修复动作清单（用户同意后按需执行）\n\n- **拔密钥（最高优先）**：#0 命中时先把明文 key/token/私钥/口令移出 CLAUDE.md，改放\n  `.env`／密钥管理器，正文最多留「见环境变量 XXX」；命中即视为已泄露，提醒用户**轮换**该凭据，\n  并检查是否已被提交进 git（如是需清历史）。\n- **修死链**：#4b 报的死指针——补上缺失的 docs 文件，或修正/删除指针。\n- **瘦身**：把架构图/前端技术栈表/路由表等\"图书馆\"内容迁到 `docs/architecture.md`、\n  `docs/runtime.md`，正文替换成一行指针（Tier 2 按需打开，不预读）。\n- **补禁止清单**：和用户确认项目已淘汰/冲突的库与做法，写成 Do NOT 清单。\n- **可操作化**：把\"干净/简洁\"改写成具体可判定规则。\n- **删教学型冗余**：把\"如何使用 X / 主流框架用法 / step by step 教程\"这类段落删掉——\n  模型已经会、且随升级自动变强，留着只是为\"很快过时的东西\"每次付上下文费。\n- **加高危护栏**：给 payment/auth 等目录新建本地 CLAUDE.md（安全红线 + 已知陷阱 + 改动前确认）。\n- **配 Hook**：把\"改完跑测试/格式化/改 .env 提醒重启\"等做成 `.claude/settings.json` 的\n  Pre/PostToolUse Hook（告警型即可，别默认做有破坏性的自动执行）。\n- **记忆回路**：在 CLAUDE.md 加\"任务前读 MEMORY.md、任务后写回\"指令。\n- **工作风格块**：顶部加\"My Working Style\"（先方案后代码、列选项不猜、讨厌的回复腔等）。\n- 改完**重新跑一次 `check.py`** 给前后对比分数。\n\n---\n\n## 落地骨架（建文件/重写时的推荐结构，≤200 行）\n\n```\n# 项目名\n## 30 秒速览      # 产品 / 技术栈 / 新代码放哪 + 优化优先级\n## 工作风格        # 你是谁、你讨厌什么、协作节奏（限 3–5 行，每行都对应一个\"不写就会犯的错\"，别写性格小作文）\n## 跨会话记忆      # 任务前读 MEMORY.md，任务后写回\n## 铁律            # 编号、可执行、带后果（含 Do NOT 清单）\n## 关键事实表      # 版本 / 环境等不可由代码自查的硬信息（真铁律，留正文）\n## 目录结构        # 新代码放哪里（路由地图，可留正文）\n## 延伸文档        # Tier 2 指针：docs/...，按需打开不预读\n## 规划中功能      # 尚未落地，别假设已存在\n```\n\nFile v1.3.0:README.md\n\n# hekouwang-claude-md-doctor-skill\n\n**简体中文** · [English](README.en.md)\n\n[![CI](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n![Python](https://img.shields.io/badge/python-3.x-blue.svg)\n![dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)\n![open source](https://img.shields.io/badge/open%20source-free-success.svg)\n\n> **会勇禾口王的AI笔记** 出品 · `@huiyonghkw`\n> _不聊 AI 会不会取代你，只聊先用 AI 的人怎么取代你。_\n\nCLAUDE.md 体检器 —— 检查任意项目的 `CLAUDE.md` 是否符合\"把它当**运行时配置**、\n不是项目说明书\"的最佳实践，给出评分卡 + 修复建议。\n\n<p align=\"center\">\n  <img src=\"examples/demo.gif\" width=\"720\" alt=\"hekouwang-claude-md-doctor-skill 体检演示\">\n  <br><sub>↑ 一句「检查我的 CLAUDE.md」/ <code>python3 check.py</code>，秒出评分 + 修复建议（免费 CLI）</sub>\n</p>\n\n一句话判据：**CLAUDE.md 每次会话都被重新加载、要付上下文费。值不值得每次会话都为这段内容付一次费？**\n\n<p align=\"center\">\n  <img src=\"examples/report-card.gif\" width=\"420\" alt=\"CLAUDE.md 体检报告卡（动效示例）\">\n  <br><sub>↑ 品牌可视化报告卡（<b>付费增值</b>示例）——评分弧随分数填充、等级 D→A 变色。免费版输出文本/JSON 报告。</sub>\n</p>\n\n## 为什么需要它\n\n很多人把 CLAUDE.md 写成\"项目说明书\"：塞进历史、技术决策、营销叙事，动辄上千行。\n结果模型在冗长上下文里迷失，还挤掉了真正理解代码的空间。这个工具把 10 条可检查的\n最佳实践固化下来，让任何人一键体检自己的项目。\n\n核心立场是 Claude Code 之父 Boris Cherny / Cat Wu 的 **context minimalism —— 别跟模型较劲做加法**：\n模型每代都在变强，你今天费劲搭的脚手架很快白搭。所以评分按\"减法优先\"加权，\n\"越短越准\"类核心项权重更高，\"加内容\"类项缺了不重罚。\n\n## 10 项检查\n\n1. 篇幅 ≤ 200 行（路由器不是图书馆）\n2. 禁止清单（Do NOT introduce）\n3. 规则可操作（非\"写干净代码\"式空话）\n4. 路由器不是图书馆（大块下沉 docs/ 留指针）\n5. 高危模块有本地 CLAUDE.md（碰钱/认证/迁移）\n6. 关键规则有 Hook 强制（不靠模型记忆）\n7. 跨会话记忆回路（MEMORY.md）\n8. 工作风格块（你是谁 / 你讨厌什么 · 限 3–5 行）\n9. 30 秒三问（产品 / 技术栈 / 新代码放哪）\n10. 别替模型补它已经会的（无\"如何使用 X / 教程\"式随模型升级即过时的冗余）\n\n## 用法\n\n### 在 Claude Code 里（推荐）\n直接说：「**检查我的 CLAUDE.md**」「**CLAUDE.md 体检**」——会自动跑机检 +\n模型定性复核，给出评分和按优先级的修复建议，并可代为修复。\n\n### 命令行直接跑（零依赖，仅需 Python 3）\n```bash\npython3 check.py [项目目录]          # 默认当前目录，输出彩色报告\npython3 check.py [项目目录] --json   # 机器可读 JSON（CI 可用）\n```\n退出码：有 FAIL → 1，否则 0（可用于 CI 卡关）。\n\n### Docker（不想装 Python 也能跑）\n```bash\n# 拉官方镜像直接用（打 tag 时 GitHub Actions 自动发布到 GHCR）\ndocker run --rm -v \"$PWD:/work\" ghcr.io/huiyonghkw/hekouwang-claude-md-doctor-skill\n\n# 或本地自建\ndocker build -t claude-md-doctor .\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor            # 体检当前项目\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor /work --json\n```\n\n### 接进 CI 卡关（GitHub Actions 示例）\n```yaml\n- uses: actions/setup-python@v5\n  with: { python-version: \"3.x\" }\n- name: CLAUDE.md 体检（不合格则拦 PR）\n  run: |\n    curl -sO https://raw.githubusercontent.com/huiyonghkw/hekouwang-claude-md-doctor-skill/main/check.py\n    python3 check.py .\n```\n本仓库自身的 CI 见 [`.github/workflows/ci.yml`](.github/workflows/ci.yml)（语法 + good/bad 夹具 + JSON 合法性）。\n\n## 这不是内置的 `/doctor` 命令\n\nClaude Code 自带一个 `/doctor` 命令，名字也带 \"doctor\"，但**体检对象和本工具完全不同**——\n一个查整套工具的运行环境，一个只查一份文档写得好不好。别搞混。\n\n| 维度 | 内置 `/doctor` | 本工具（claude-md-doctor） |\n|------|---------------|----------------------------|\n| **体检对象** | 整个 Claude Code **运行环境 / 安装** | 单个项目的 **`CLAUDE.md` 文件本身** |\n| **关注点** | 安装健康、未用扩展、上下文膨胀、慢 Hook、版本、权限模式 | `CLAUDE.md` 是否当运行时配置写、篇幅、该不该懒加载、10 项评分 |\n| **改哪里** | `~/.claude/` 全局配置层 | 项目里的 `CLAUDE.md` 内容 |\n| **作用范围** | 全局 · 跨所有项目 | 就这一个项目的文档 |\n\n**唯一交集**：`/doctor` 会去重本地 vs 入库 `CLAUDE.md`、把该懒加载的内容迁走，但它只从\n「上下文成本」看、**不评文档质量**。**怎么用**：先 `/doctor` 发现「CLAUDE.md 太大」，\n再用本工具深度评分 + 出 Top 3 + 代重构——`/doctor` 负责发现文档偏大，本工具负责回答「具体哪几条该删、怎么改」。\n\n## 免费 / 付费（Freemium）\n\n- **免费（开源内核）**：命令行体检器 `check.py` —— 文本 / JSON 报告、评分、退出码。\n  本地或 Docker 随便跑、随便接进 CI。这是开放内核，永久免费。\n- **付费（增值服务）**：**品牌可视化体检报告卡** —— 评分弧 + 等级带 + 九项明细的\n  精美分享图（适合汇报 / 发圈 / 放进 PR）。它依赖私有视觉系统（品牌字体与版式，\n  即私有 Skill `hekouwang-content-factory`，**GitHub 上为 PRIVATE 仓库，非授权无法 clone / 获取**），\n  **不随本仓库分发**。需要出图版报告，请联系 **@huiyonghkw** 获取。\n\n> 一句话：**跑检查免费，出「好看的报告图」找我。**\n\n## 设计\n\n- **机检层（`check.py`）**：确定性、零依赖、可移植，跑启发式检查并打分。\n- **定性层（`SKILL.md`）**：模型读正文复核机检盲区（图书馆 vs 路由器、规则是否可执行），\n  再出最终报告与修复方案。\n- **安全**：绝不读取 `.env` / `*.key` / `*.pem` 等密钥文件；体检只读，改动需确认。\n\n## 评分档位\n\nA 优秀 ≥85 · B 良好 ≥70 · C 及格 ≥50 · D 建议重写 <50\n\n## 许可协议 / License\n\n本仓库代码以 **MIT License** 开源 —— 免费使用、修改、分发、商用，仅需保留版权与许可声明。详见 [LICENSE](LICENSE)。\n\n> 范围说明：MIT 覆盖本仓库代码（`check.py` / `SKILL.md` 等）。品牌名「会勇禾口王的AI笔记」与**付费可视化报告卡**（依赖未公开的品牌字体与版式）属增值服务，不在开源范围内——但这不影响你免费、自由地使用命令行体检器。\n\n## 贡献 / Contributing\n\n欢迎提 Issue / PR：新增检查项、降低误报、补充其它语言/框架的启发式规则。\n保持零运行时依赖（仅 Python 3 标准库）是硬约束。\n\n---\n\n<sub>—— 会勇禾口王的AI笔记 · @huiyonghkw · AI 实战拆解：编程 × 内容创作 × 自动化（硬核 · 具体 · 可复制）</sub>\n\nFile v1.3.0:_meta.json\n\n{\n  \"ownerId\": \"kn73qd1gcmjr446mwcbdxef70x82vxcw\",\n  \"slug\": \"hekouwang-claude-md-doctor-skill\",\n  \"version\": \"1.3.0\",\n  \"publishedAt\": 1786517912960\n}\n\nFile v1.3.0:CHANGELOG.md\n\n# Changelog\n\n本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。\n\n## [1.3.0] - 2026-08-12\n\n### 新增\n- **`check.py` 支持 AGENTS.md**：根目录优先体检 `AGENTS.md`，其次 `CLAUDE.md` / `CLAUDE.local.md`；\n  子目录扫描同时认两份本地配置。\n- **#0b 双文件去重**：根目录 `AGENTS.md` + `CLAUDE.md` 同时存在且都不是薄指针 → WARN（双倍上下文费）。\n- **#4c Skill 路由**：正文应把细则指针到 `.agents/skills/`（或 `.cursor/skills/`），别堆在常驻正文。\n- 报告标题改为 **AGENT CONFIG DOCTOR**；JSON 输出增加 `root_configs` 字段。\n\n### 文档\n- `SKILL.md` 触发词补 `AGENTS.md` / `agents.md` / `运行时配置体检`；评分表扩至 12 项。\n- 新增测试夹具 `tests/fixtures/good-agents/`、`tests/fixtures/dual/`。\n\n## [1.2.2] - 2026-07-09\n\n### 文档\n- **新增「与内置 `/doctor` 命令的分工」小节**：两者名字都带 doctor 但体检对象完全不同——\n  内置 `/doctor` 查整套 Claude Code 运行环境（安装/未用扩展/上下文膨胀/权限/版本），\n  本 skill 只查一份 CLAUDE.md 的写法质量。给出对比表 + 唯一交集（`/doctor` Check 2/3 碰 CLAUDE.md\n  但只从上下文成本看、不评质量）+ 用法建议（先 `/doctor` 发现文档偏大，再用本 skill 深度评 + 重构）。\n- **README.md / README.en.md 同步**：两份 README 也各补一节「这不是内置的 `/doctor` 命令」\n  （精简对比表 + 唯一交集 + 组合用法），中英一致。\n\n## [1.2.1] - 2026-06-22\n\n自体检（用姊妹工具 skill-doctor 跑）后的两处打磨：\n\n### 优化\n- **SKILL.md 声明 `allowed-tools`**：收敛到本 skill 真正需要的工具集，减小越权面。\n- **补「本 skill 自检会触发 #10 误报」豁免说明**：正文里的\"教程/如何使用/step by step\"是\n  待检测的黑名单词本身（评分表/盲区/修复清单都要举例），机检会误报教学冗余——\n  与 skill-doctor 对齐，注明定性时直接放行，别删那些词（删了体检器就不工作）。\n\n## [1.2.0] - 2026-06-21\n\n对照社区教程 `luongnv89/claude-howto` 的 Memory 最佳实践逐条比对后，补上三个真空白\n（只取它的\"安全 + 机制正确性\"，不取它\"把文件写全\"的加法倾向）。\n\n### 新增\n- **安全红线检查「无硬编码密钥」(#0)**：扫正文里的 `sk-`/`AKIA`/`AIza`/`gh*_`/`xox*`/\n  JWT / 私钥块 / `password=`/`secret=` 等指纹，命中即 **FAIL**（权重 1.5、资损级）。\n  报告对命中值脱敏（前 4 位 + 长度）。占位/示例值（`<your-pwd>`/`${VAR}`/`example` 等）自动豁免。\n  补齐教程头号 Don't \"Never store secrets in CLAUDE.md\"——此前脚本只防自己读 .env，\n  却不查被体检文件本身是否藏密钥。\n- **指针死链检查 (#4b)**：`docs/` 文本指针与原生 `@import` 路径都校验目标文件是否存在，\n  死链 → WARN（指向不存在的文件比没指针更糟）。\n\n### 变更\n- **#4 路由器检查认原生 `@import` 语法**：此前只认纯文本 `docs/...`，用官方 `@path` 导入\n  反而不给\"下沉指针\"加分；现在两种写法都算合格指针。\n\n### 文档 / 测试\n- `SKILL.md` 评分表补 #0 与 #4b，加权说明与修复动作清单同步（拔密钥 + 轮换提醒、修死链）。\n- good 夹具补 `docs/architecture.md`、`docs/api.md` 桩文件，示范\"指针均可解析\"。\n\n## [1.1.0] - 2026-06-18\n\n把 Claude Code 之父 Boris Cherny / Cat Wu 的\"context minimalism · 别跟模型较劲做加法\"\n立场接进体检逻辑。\n\n### 新增\n- **第 10 项检查「别替模型补它已经会的」**：扫教学型措辞(如何使用 / 使用教程 /\n  step by step / how to use)，命中即 WARN——这类通用写法随模型升级自动变强，\n  写进常驻正文只是为\"很快过时的东西\"每次付上下文费。\n- **「减法优先」元判据**：写进 `SKILL.md`，凌驾 9 项之上——加任何一段前先问\n  \"能不能不写在常驻正文里\"。\n\n### 变更\n- **评分改为按重要度加权**：减法核心项(#1 篇幅 / #3 可操作 / #4 路由器 / #10)权重 1.5，\n  加内容项(#6 Hook / #7 记忆 / #8 人格)降到 0.6。修掉旧逻辑\"一边喊越短越好、\n  一边因缺工作风格块扣分、逼用户把文件写长\"的自相矛盾。\n- **#8 工作风格块加上限护栏**：限 3–5 行，每行须对应一个\"不写就会犯的具体错\"，别写性格小作文。\n\n### 文档\n- `README` / `README.en` 同步「10 项检查」并写明「减法优先 · 别跟模型较劲做加法」立场。\n- `SKILL.md` 顶部署名补 GitHub 仓库地址\n  （<https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill>），方便 skillhub 溯源。\n\n## [1.0.0] - 2026-06-17\n\n首个正式版本。把\"CLAUDE.md 当运行时配置、不是项目说明书\"的最佳实践做成可跑在任意项目上的体检器。\n\n### 功能\n- **9 项检查的命令行体检器 `check.py`**：篇幅 / 禁止清单 / 规则可操作 / 路由非图书馆 /\n  高危模块本地 CLAUDE.md / Hook 强制 / MEMORY.md 回路 / 工作风格 / 30 秒三问。\n- 输出彩色文本报告或 `--json`；评分 0–100（A/B/C/D）；有 FAIL → 退出码 1（可 CI 卡关）。\n- 零运行时依赖（仅 Python 3 标准库）；只读，绝不读取 `.env` / `*.key` / `*.pem`。\n- **`SKILL.md` 定性复核层**：在 Claude Code 内说「检查我的 CLAUDE.md」即可机检 + 模型复核 + 代修复。\n- **Docker**：`docker run --rm -v \"$PWD:/work\" claude-md-doctor`，免装 Python。\n- **GitHub Actions CI**：语法 + good/bad 夹具 + JSON 合法性。\n- 中英双语 README、MIT LICENSE、CONTRIBUTING、示例动图（CLI 实录 + 动效报告卡）。\n\n### 商业模型\n- 命令行体检器开源免费（MIT）；品牌可视化报告卡为付费增值，依赖未公开字体/版式，不在仓库内。\n\n[1.0.0]: https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/releases/tag/v1.0.0\n\nFile v1.3.0:CONTRIBUTING.md\n\n# 贡献指南 / Contributing\n\n感谢参与 **hekouwang-claude-md-doctor-skill**！欢迎新增检查项、降低误报、为其它语言/框架补启发式规则。\n\n## 硬约束（不可破）\n\n1. **零运行时依赖** —— `check.py` 只用 Python 3 标准库。不要引入第三方包。\n2. **只读 + 安全** —— 检查器绝不读取 `.env` / `*.key` / `*.pem` 等密钥文件，不写用户文件。\n3. **跨语言通用** —— 不绑定任何具体技术栈；新规则要对多数项目成立。\n\n## 本地开发\n\n```bash\ngit clone https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill\ncd hekouwang-claude-md-doctor-skill\n\npython3 check.py tests/fixtures/good     # 期望 exit 0\npython3 check.py tests/fixtures/bad      # 期望 exit 1（有 FAIL 卡关）\npython -m py_compile check.py            # 语法自检\n```\n\n## 加一条检查项\n\n1. 在 `check.py` 的 `check()` 里用 `add(key, title, status, detail, fix)` 追加结果。\n2. `status` 取 `PASS` / `WARN` / `FAIL` / `INFO`（INFO 不计分）。\n3. 机检只做\"机器能确定的\"；需要读正文判断的，写进 `SKILL.md` 的「定性复核」与「机检盲区」。\n4. 在 `tests/fixtures/` 增/改夹具，确保 `good` 仍 exit 0、`bad` 仍 exit 1。\n5. 误报是头号大忌——宁可 `WARN` 不轻易 `FAIL`，并在 `detail` 里说清线索。\n\n## 提交 PR\n\n- 一个 PR 聚焦一件事；附上前后 `check.py` 输出对比。\n- 通过 CI（`.github/workflows/ci.yml`：语法 + good/bad 夹具 + JSON 合法性）。\n- commit 信息讲清「改了什么 + 为什么」。\n\n## 范围说明\n\n代码以 MIT 开源（见 [LICENSE](LICENSE)）。品牌名「会勇禾口王的AI笔记」与付费可视化报告卡为增值服务，不在本仓库开源范围内。\n\nFile v1.3.0:README.en.md\n\n# hekouwang-claude-md-doctor-skill\n\n[简体中文](README.md) · **English**\n\n[![CI](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n![Python](https://img.shields.io/badge/python-3.x-blue.svg)\n![dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)\n![open source](https://img.shields.io/badge/open%20source-free-success.svg)\n\n> Made by **会勇禾口王的AI笔记** (Hekouwang's AI Notes) · `@huiyonghkw`\n\nA health checker for `CLAUDE.md` — audits any project's `CLAUDE.md` against the\nbest practice of *\"treat it as runtime config, not a project manual\"*, and returns\na scorecard plus prioritized fixes.\n\n<p align=\"center\">\n  <img src=\"examples/demo.gif\" width=\"720\" alt=\"hekouwang-claude-md-doctor-skill demo\">\n  <br><sub>↑ Say \"check my CLAUDE.md\" or run <code>python3 check.py</code> — instant score + fixes (free CLI)</sub>\n</p>\n\nThe one rule it all comes down to: **CLAUDE.md is reloaded into context on every\nsession and costs tokens every time. Is this line worth paying for on every single session?**\n\n<p align=\"center\">\n  <img src=\"examples/report-card.gif\" width=\"420\" alt=\"CLAUDE.md report card (animated)\">\n  <br><sub>↑ Branded visual report card (<b>paid add-on</b> sample) — the score arc fills and the grade morphs D→A. The free version outputs a text/JSON report.</sub>\n</p>\n\n## Why it exists\n\nMost people write `CLAUDE.md` like a project manual: history, tech decisions,\nmarketing prose — easily over a thousand lines. The model then drowns in a bloated\ncontext and loses the room it needs to actually understand your code. This tool\nfreezes 10 checkable best practices into a one-command audit anyone can run.\n\nIts guiding stance is the **context minimalism** that Claude Code's creators\nBoris Cherny and Cat Wu preach — *don't fight the model by adding things*: models\nget stronger every generation, so the scaffolding you laboriously build today\ngoes stale fast. Scoring is therefore weighted \"subtraction-first\": the\nshorter-is-sharper core checks count more, missing \"add-content\" checks count less.\n\n## The 10 checks\n\n1. **Length ≤ 200 lines** — a router, not a library\n2. **A \"Do NOT introduce\" list** — block well-meant but incompatible deps\n3. **Actionable rules** — not vague \"write clean code\" platitudes\n4. **Router, not library** — move big blocks to `docs/`, leave pointers\n5. **Local CLAUDE.md for high-risk modules** — money / auth / migrations\n6. **Hooks enforce the critical rules** — don't rely on the model's memory\n7. **A MEMORY.md cross-session loop**\n8. **A working-style block** — who you are / what you hate (cap 3–5 lines)\n9. **The 30-second test** — product? stack? where does new code go?\n10. **Don't teach the model what it already knows** — no \"how to use X / tutorial\"\n    prose that goes stale the moment the model improves\n\n## Usage\n\n### Inside Claude Code (recommended)\nJust say **\"check my CLAUDE.md\"**. It runs the mechanical check, then does a\nmodel-driven qualitative review, and returns a score with prioritized fixes —\nand can apply the fixes for you.\n\n### Command line (zero deps, just Python 3)\n```bash\npython3 check.py [project_dir]          # defaults to CWD, prints a colored report\npython3 check.py [project_dir] --json   # machine-readable JSON (for CI)\n```\nExit code: `1` if any FAIL, else `0` (usable as a CI gate).\n\n### Docker (no Python needed)\n```bash\n# Pull the prebuilt image (auto-published to GHCR on each tag via GitHub Actions)\ndocker run --rm -v \"$PWD:/work\" ghcr.io/huiyonghkw/hekouwang-claude-md-doctor-skill\n\n# Or build locally\ndocker build -t claude-md-doctor .\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor            # check current project\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor /work --json\n```\n\n### Gate your PRs (GitHub Actions)\n```yaml\n- uses: actions/setup-python@v5\n  with: { python-version: \"3.x\" }\n- name: CLAUDE.md health check (fail the PR if non-compliant)\n  run: |\n    curl -sO https://raw.githubusercontent.com/huiyonghkw/hekouwang-claude-md-doctor-skill/main/check.py\n    python3 check.py .\n```\nThis repo's own CI lives in [`.github/workflows/ci.yml`](.github/workflows/ci.yml) (syntax + good/bad fixtures + JSON validity).\n\n## This is NOT the built-in `/doctor` command\n\nClaude Code ships a `/doctor` command that also says \"doctor\" — but it checks a\n**completely different thing**: `/doctor` audits your whole tool *environment*,\nthis tool audits one *document*. Don't confuse them.\n\n| Dimension | Built-in `/doctor` | This tool (claude-md-doctor) |\n|-----------|--------------------|------------------------------|\n| **Audits** | Your whole Claude Code **environment / install** | A single project's **`CLAUDE.md` file** |\n| **Looks at** | Install health, unused extensions, context bloat, slow hooks, version, permission mode | Whether `CLAUDE.md` reads as runtime config, length, lazy-loading, the 10-check score |\n| **Edits** | `~/.claude/` global config | The project's `CLAUDE.md` content |\n| **Scope** | Global · across all projects | Just this one project's doc |\n\n**The one overlap**: `/doctor` dedups local vs checked-in `CLAUDE.md` and migrates\nlazy-loadable content out — but only from a \"context cost\" angle; it **does not\ngrade document quality**. **How to combine them**: run `/doctor` first to catch\n\"your CLAUDE.md is too big\", then use this tool to score it, surface the Top 3,\nand rewrite it — `/doctor` finds that the doc is bloated, this tool answers *which\nlines to cut and how*.\n\n## Free / Paid (Freemium)\n\n- **Free (open-source core)**: the `check.py` CLI — text / JSON report, score,\n  exit code. Run it locally or in Docker, wire it into CI. Free forever.\n- **Paid (add-on service)**: the **branded visual report card** (score arc +\n  grade band + 9-check breakdown, great for sharing / PRs). It depends on a\n  private visual system (brand fonts & layout) and is **not shipped in this repo**.\n  Want the image version? Contact **@huiyonghkw**.\n\n> In one line: **running the check is free; getting the pretty report image, talk to me.**\n\n## Design\n\n- **Mechanical layer (`check.py`)**: deterministic, zero-dependency, portable —\n  runs heuristic checks and scores them.\n- **Qualitative layer (`SKILL.md`)**: the model reads the actual file to cover the\n  checker's blind spots (library vs router, whether rules are truly actionable),\n  then produces the final report and fix plan.\n- **Safety**: never reads `.env` / `*.key` / `*.pem` secrets; the audit is\n  read-only and any edits require confirmation.\n\n## Grade bands\n\nA (excellent) ≥85 · B (good) ≥70 · C (pass) ≥50 · D (rewrite) <50\n\n## License\n\nThe code in this repo is open-sourced under the **MIT License** — free to use,\nmodify, distribute, and use commercially; just keep the copyright and license\nnotice. See [LICENSE](LICENSE).\n\n> Scope: MIT covers the repo's code (`check.py` / `SKILL.md`, etc.). The brand\n> name \"会勇禾口王的AI笔记\" and the **paid visual report card** (which relies on\n> unreleased brand fonts & layout) are an add-on service, outside the open-source\n> scope — but that does not affect your free, unrestricted use of the CLI checker.\n\n## Contributing\n\nIssues / PRs welcome: new checks, fewer false positives, heuristics for more\nlanguages/frameworks. Keeping **zero runtime dependencies** (Python 3 stdlib only)\nis a hard constraint.\n\n---\n\n<sub>—— 会勇禾口王的AI笔记 · @huiyonghkw · AI in practice: coding × content × automation</sub>\n\nFile v1.3.0:skill-card.md\n\n## Description:\n\nAudits project AGENTS.md or CLAUDE.md files as agent runtime configuration and returns a scorecard with prioritized remediation guidance.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[huiyonghkw](https://clawhub.ai/user/huiyonghkw)\n\n### License/Terms of Use:\n\nMIT\n\n## Use Case:\n\nDevelopers and engineers use this skill to review agent runtime configuration files, identify context bloat, vague rules, broken pointers, or risky guidance, and decide what to trim or fix before those files are loaded by coding agents.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill may propose edits to AGENTS.md or CLAUDE.md that change future agent behavior.\n\nMitigation: Keep the workflow in audit mode unless edits are explicitly wanted, and review each proposed change before approving it.\n\nRisk: The checker reviews local agent configuration files that may contain project-specific operating guidance.\n\nMitigation: Run it only against intended project directories and keep secrets out of AGENTS.md and CLAUDE.md; the documented checker avoids .env, key, and PEM files.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/huiyonghkw/skills/hekouwang-claude-md-doctor-skill)\n- [README.en.md](README.en.md)\n- [CHANGELOG.md](CHANGELOG.md)\n- [check.py](check.py)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, JSON, Code, Shell commands, Configuration guidance]\n\n**Output Format:** [Markdown report with optional JSON checker output, shell commands, and proposed file edits.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Optional edits require user approval; the CLI checker can emit machine-readable JSON.]\n\n## Skill Version(s):\n\n1.3.0 (source: frontmatter and changelog, released 2026-08-12; server release version 1.3.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.3.0:tests/fixtures/bad/CLAUDE.md\n\n# 我的项目\n\n请写干净的代码，保持简洁优雅，注重性能，遵循最佳实践。\n代码要高质量、易于维护。谢谢配合。\n\n## React 使用教程\n\n如何使用 useState：调用 `const [x, setX] = useState(0)`，setX 触发重渲染。\n如何使用 useEffect：把副作用放进 useEffect，依赖数组控制何时重跑。\n这些都是 React 的标准用法，跟着 step by step 写就行。\n\nFile v1.3.0:tests/fixtures/dual/AGENTS.md\n\n# Acme Dashboard\n\n> 30 秒速览：面向运营经理的 B2B 分析仪表盘。优化优先级：加载速度 > 交互 > 视觉。\n> 新代码按下方目录结构放进对应模块；动手前先看该模块 README。\n\n## 工作风格\n- 先给方案再写代码；不确定时列选项，不要猜。\n- 汇报用中文，代码与注释用英文；文件引用用绝对路径。\n- 不说「Great question!」这类客套，直接给结论。\n\n## 跨会话记忆\n- 任务开始前扫一遍 `MEMORY.md`；结束后把新的非显然结论写回。\n\n## 铁律\n1. 用 named export（路由文件除外）。\n2. 禁 `any`，用泛型或接口替代。\n3. 单组件不超过 200 行（有充分理由可超）。\n\n## 技术栈（tech stack）\n- Next.js 15 App Router + TypeScript\n- Tailwind CSS + shadcn/ui\n- PostgreSQL（数据层）\n\nDo NOT introduce unless explicitly requested:\n- Redux（已迁移到 React Context + Zustand）\n- styled-components（全站 Tailwind，不收 CSS-in-JS）\n- MongoDB（数据层锁定 PostgreSQL）\n\n## 目录结构（directory · 新代码放哪里）\n```\nsrc/\n  app/        # 路由与页面\n  components/ # 复用组件\n  lib/        # 工具与数据访问\n```\n\n## 延伸文档（Tier 2，按需打开）\n- 架构总览：`docs/architecture.md`\n- API 文档：`docs/api.md`\n\nFile v1.3.0:tests/fixtures/dual/CLAUDE.md\n\n# Acme Dashboard\n\n> 30 秒速览：面向运营经理的 B2B 分析仪表盘。优化优先级：加载速度 > 交互 > 视觉。\n> 新代码按下方目录结构放进对应模块；动手前先看该模块 README。\n\n## 工作风格\n- 先给方案再写代码；不确定时列选项，不要猜。\n- 汇报用中文，代码与注释用英文；文件引用用绝对路径。\n- 不说「Great question!」这类客套，直接给结论。\n\n## 跨会话记忆\n- 任务开始前扫一遍 `MEMORY.md`；结束后把新的非显然结论写回。\n\n## 铁律\n1. 用 named export（路由文件除外）。\n2. 禁 `any`，用泛型或接口替代。\n3. 单组件不超过 200 行（有充分理由可超）。\n\n## 技术栈（tech stack）\n- Next.js 15 App Router + TypeScript\n- Tailwind CSS + shadcn/ui\n- PostgreSQL（数据层）\n\nDo NOT introduce unless explicitly requested:\n- Redux（已迁移到 React Context + Zustand）\n- styled-components（全站 Tailwind，不收 CSS-in-JS）\n- MongoDB（数据层锁定 PostgreSQL）\n\n## 目录结构（directory · 新代码放哪里）\n```\nsrc/\n  app/        # 路由与页面\n  components/ # 复用组件\n  lib/        # 工具与数据访问\n```\n\n## 延伸文档（Tier 2，按需打开）\n- 架构总览：`docs/architecture.md`\n- API 文档：`docs/api.md`\n\nFile v1.3.0:tests/fixtures/dual/docs/api.md\n\n# API 文档\n\n（夹具桩文件：演示下沉指针可解析。）\n\nFile v1.3.0:tests/fixtures/dual/docs/architecture.md\n\n# 架构总览\n\n（夹具桩文件：演示「正文留指针、内容下沉到 docs/」。）\n\nArchive v1.2.2: 14 files, 36653 bytes\n\nFiles: CHANGELOG.md (5275b), check.py (27719b), CONTRIBUTING.md (1772b), Dockerfile (763b), LICENSE (1096b), README.en.md (7688b), README.md (7509b), skill-card.md (2342b), SKILL.md (15295b), tests/fixtures/bad/CLAUDE.md (423b), tests/fixtures/good/CLAUDE.md (1308b), tests/fixtures/good/docs/api.md (69b), tests/fixtures/good/docs/architecture.md (95b), _meta.json (151b)\n\nFile v1.2.2:SKILL.md\n\n---\nname: hekouwang-claude-md-doctor-skill\nversion: 1.2.2\ndescription: >\n  会勇禾口王的AI笔记 · CLAUDE.md 体检器。检查一个项目的 CLAUDE.md（及子目录本地\n  CLAUDE.md）是否符合\"把它当运行时配置、不是项目说明书\"的最佳实践，给出评分卡 +\n  按优先级的修复建议，并可代为修复。触发：用户说「检查我的 CLAUDE.md / CLAUDE.md\n  体检 / 我的 CLAUDE.md 规范吗 / claude-md-doctor / hekouwang-claude-md-doctor-skill /\n  audit CLAUDE.md / lint CLAUDE.md / 看看我的 claude 配置合不合规」。\n  任何\"评估/审查/优化某个项目 CLAUDE.md 质量\"的请求都应触发。\nallowed-tools:\n  - Bash\n  - Read\n  - Write\n  - Edit\n  - Glob\n  - Grep\n  - AskUserQuestion\n---\n\n# hekouwang-claude-md-doctor-skill · CLAUDE.md 体检器\n\n> **会勇禾口王的AI笔记** 出品 · `@huiyonghkw`\n> GitHub: <https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill>\n> _不聊 AI 会不会取代你，只聊先用 AI 的人怎么取代你。_\n\n把\"CLAUDE.md 最佳实践\"做成一个能跑在任何项目上的检查器：机检定量 + 模型定性，\n产出评分卡和可落地的修复建议。核心判据一句话——\n\n> **CLAUDE.md 是每次会话都被重新加载、要付上下文费的\"运行时配置\"，不是给人读的项目说明书。**\n> 一切检查项都从这句推导：值不值得每次会话都为这段内容付一次费？\n\n### 减法优先（元判据 · 凌驾全部检查项之上）\n\nClaude Code 之父 Boris Cherny 公开说自己的配置\"surprisingly vanilla\"、几乎不定制；\n联合创造者 Cat Wu 自称 \"context minimalist\"——只告诉模型它需要知道的，剩下让它自己想。\n**核心立场：模型每代都在变强，你今天费劲搭的脚手架很快白搭；别跟模型较劲做加法。**\n\n所以下面这些检查项里凡是\"让用户往里加内容\"的(禁止清单/Hook/记忆/人格/本地文件)，\n落地前都先过这一关 —— **加任何一段前先问：这条能不能不写在常驻正文里？**\n\n- 能挂 **Hook**(确定性规则)→ 挂 Hook，别写正文(模型不必每次读)。\n- 能下沉 **docs/** 的 → 下沉，正文留一行指针。\n- 能靠 **linter / 类型检查 / 测试**兜住的 → 删掉，别让模型干 linter 的活。\n- 通用写法 / 主流框架用法 → 删掉，那是模型已经会的(见 #10)。\n- **只有\"模型会反复犯错、且没有机械手段能兜住\"的，才值得占常驻 token。**\n\n机检层面：**#1 篇幅 / #3 可操作 / #4 路由器 / #10 别替模型补**这几项是减法核心，权重更高；\n\"加内容\"类项(#6/#7/#8)缺失只算小扣分，避免工具一边喊\"越短越好\"、一边逼用户把文件写长。\n\n## 品牌人设（体检报告的口吻 + 署名）\n\n这套工具属于 **会勇禾口王的AI笔记**（定位：AI 实战拆解，硬核·具体·可复制；人设：你办公室里第一个把 AI 用明白的同事）。出体检报告时：\n\n- **口吻**：像同事帮你看代码——直给结论、敢泼冷水（\"这条是空话，5 秒判不了就是不合格\"），不说\"Great question / 我很乐意帮忙\"这类客套。\n- **价值化**：修复建议讲\"省了什么\"（少几十次会话的冗余、挡住一次资损/越权），不堆术语。\n- **署名**：报告结尾固定带一行品牌签收 —— `—— 会勇禾口王的AI笔记 · @huiyonghkw`，并可附 slogan。命令行 `check.py` 的报告页脚已内置该署名。\n- **去 AI 味**：定稿前避开\"赋能/打造/至关重要/助力\"等词，说人话。\n\n---\n\n## 免费 / 付费边界（重要）\n\n- **免费（开源内核）**：`check.py` 的**文本 / JSON 报告 + 评分**。任何人本地或 Docker 跑、进 CI，随便用。\n- **付费（增值）**：**品牌可视化体检报告卡**（评分弧 + 等级带 + 九项明细的精美分享图）。\n  它依赖 `hekouwang-content-factory` 的**私有品牌字体与版式**，不随本仓库分发。\n\n**触发\"出图 / 报告卡 / 图表 / 可视化\"时怎么办**：\n1. 先照常给**免费文本报告**（机检 + 定性复核）。\n2. 是否生成图：检查本机有没有 `hekouwang-content-factory`（品牌字体在\n   `~/.claude/skills/hekouwang-content-factory/assets/fonts/`）。\n   - **有**（作者本人环境）：可按 V2 米白生成报告卡 PNG。\n   - **没有**（外部用户）：明确说明可视化报告是**付费增值项**，引导联系 **@huiyonghkw** 获取，\n     不要用系统字体凑一张劣化图糊弄。\n3. 一句话口径：**跑检查免费，出\"好看的报告图\"找我。**\n\n---\n\n## 与内置 `/doctor` 命令的分工（名字像，别混用）\n\nClaude Code 内置了一个 `/doctor` 命令，名字也带 \"doctor\"，但**体检对象和本 skill 完全不同**——\n一个查整套工具的运行环境，一个只查一份文档写得好不好。别把两者当同一个东西。\n\n| 维度 | 内置 `/doctor` 命令 | 本 skill（claude-md-doctor） |\n|------|--------------------|------------------------------|\n| **体检对象** | 整个 **Claude Code 运行环境 / 安装** | 单个项目的 **CLAUDE.md 文件本身** |\n| **关注点** | 安装健康、未用扩展(skill/MCP/plugin)、常驻上下文膨胀、慢 Hook、版本、权限模式、预批命令、本地记忆去重 | CLAUDE.md 是否「当运行时配置写而非项目说明书」、篇幅、该不该懒加载、评分卡 + 分级修复 |\n| **改哪里** | `~/.claude/` 配置层（settings.json、skillOverrides、`.claude.json`） | 项目里的 `CLAUDE.md` / 子目录本地 CLAUDE.md 内容 |\n| **作用范围** | 全局 · 跨所有项目的工具链 | 就这一个项目的文档 |\n| **产物** | 环境体检报告 + 两道确认后改配置 | 评分卡（10 项）+ Top 3 修复建议，可代改 |\n\n**唯一交集**：`/doctor` 的 **Check 2 / Check 3** 会碰 CLAUDE.md——去重本地 vs 入库 CLAUDE.md、\n把该懒加载的内容迁到 skill/子目录。但它是从**「上下文成本」**这一个角度看，只管「有没有重复、该不该常驻」，\n**不评文档质量**；本 skill 才从**「写法规范」**全面打分（可操作性、禁止清单、高危护栏、30 秒三问……）。\n\n### 用法建议\n\n- **想知道「我这套 Claude Code 装得干净、跑得健康吗」** → 跑内置 `/doctor`。\n- **想知道「我这个项目的 CLAUDE.md 写得规范吗」** → 触发本 skill。\n- **两者串起来用（推荐）**：先 `/doctor` 体检环境，若它在 Check 3 提示「CLAUDE.md 太大 / 该懒加载」，\n  接着用本 skill 深度评一份 + 出 Top 3 + 代重构——`/doctor` 负责发现「这份文档偏大」，本 skill 负责回答「具体哪几条该删、怎么下沉」。\n- **别指望 `/doctor` 替你把 CLAUDE.md 写规范**：它只做去重和迁移，不判「这条规则是不是空话」「禁止清单缺不缺」——那是本 skill 的活。\n\n---\n\n## 工作流（每次体检按这个顺序）\n\n1. **确认目标目录**：用户没指明就用当前工作目录；说了某项目就用那个绝对路径。\n2. **跑机检**（确定性层，零依赖）：\n   ```bash\n   python3 <此skill目录>/check.py <项目目录>\n   ```\n   - 需要结构化结果时加 `--json`（便于你解析后二次判断）。\n   - 退出码：有 FAIL → 1，否则 0。\n3. **定性复核**（机检之上，必须做）：机检是启发式，几项需要你**真正读正文**再下结论：\n   - 实际打开根 `CLAUDE.md` 通读一遍；\n   - 用下面《评分标准》逐条核对，**重点修正机检可能误判的项**（见\"机检的盲区\"）；\n   - 抽查 1–2 个子目录本地 CLAUDE.md 是否写了真红线（不是空模板）。\n4. **出报告**：先给一句话总评 + 分数档位，再用\"✓/▲/✗ + 一句话 + 修复建议\"逐条列，\n   最后给 **Top 3 最该先改的**（按\"花最小力气补最大漏洞\"排序）。中文输出。\n5. **提出代修复**：问用户要不要直接改（瘦身下沉 docs/、补禁止清单、补工作风格块、\n   加高危模块本地 CLAUDE.md、配 Hook 等）。**得到同意再动文件**，一次改一类、可回退。\n\n> 不要只把脚本输出原样贴给用户——脚本是线索，你的价值在定性判断 + 具体怎么改。\n\n---\n\n## 评分标准（10 项 · 也是机检的判分依据）\n\n| # | 检查项 | 合格长什么样 | 不合格信号 |\n|---|--------|------------|-----------|\n| 0 | **无硬编码密钥（安全红线）** | 正文不出现 key/token/私钥/口令明文 | 出现 `sk-`/`AKIA`/私钥块/`password=\"...\"` → **直接 FAIL** |\n| 1 | **篇幅 ≤ 200 行** | 路由器不是图书馆，常驻越短越好 | >200 行；大段历史/营销/教程正文 |\n| 2 | **禁止清单（Do NOT）** | 有\"不要引入 X（因为 Y）\"清单 | 只列要用的、不列禁用的 |\n| 3 | **规则可操作** | 5 秒内能判定代码合不合规 | \"写干净代码/优雅/高质量\"这类空话 |\n| 4 | **路由器不是图书馆** | 大块下沉 docs/，正文留指针（认 docs/ 文本指针与原生 `@import`） | 架构图/长表/历史塞在常驻正文 |\n| 4b | **指针无死链** | docs/ 与 `@import` 都指向真实存在的文件 | 指针指向不存在的文件（按图索骥扑空，比没指针更糟） |\n| 5 | **高危模块本地 CLAUDE.md** | 碰钱/认证/迁移目录各有护栏 | 敏感模块只靠根文件一句话 |\n| 6 | **Hook 强制层** | 最不能漏的规则挂成 Hook | 关键规则只\"写着\"靠模型记 |\n| 7 | **MEMORY.md 回路** | 任务前读、任务后写的跨会话记忆 | 每次会话从零重新认识项目 |\n| 8 | **工作风格块**（限 3–5 行） | 写了\"你是谁/你讨厌什么/协作节奏\"，且每行都指向一个\"不写就会犯的具体错\" | 没有人格；或写成性格小作文 |\n| 9 | **30 秒三问** | 陌生人读完能答：产品？技术栈？新代码放哪 | 开头答不出这三问 |\n| 10 | **别替模型补它已经会的** | 不教通用写法/主流框架用法，只装项目私有事实 | 有\"如何使用 X / 使用教程 / step by step\"这类随模型升级很快过时的教学段 |\n\n**分档**：A 优秀 ≥85 · B 良好 ≥70 · C 及格 ≥50 · D 建议重写 <50。\n（机检：PASS=1 / WARN=0.5 / FAIL=0，INFO 不计分。**按重要度加权**——安全红线 #0 与\n减法核心项 #1/#3/#4/#10 权重 1.5，标准项 #2/#4b/#5/#9 为 1.0，加内容项 #6/#7/#8 为 0.6。\n#0 命中按 FAIL 计且资损级，定性总评里应一票顶到「先改这条」。）\n\n---\n\n## 机检的盲区（定性复核时重点纠偏）\n\n脚本只能判\"机器能确定的\"，以下几项**容易误判，必须你读正文定夺**：\n\n- **#4 图书馆 vs 路由器**：脚本只按\"大代码块/大表/历史标题\"猜。\n  - **目录树是路由地图，应保留**（脚本已不把纯 `├──└──` 树当图书馆图）；\n  - 但\"版本表/环境表\"这类**真铁律**即使是表格也该留正文——别因为是表就建议下沉；\n  - 反过来，一段没有特征字符的长叙事，脚本可能漏判，你要自己看出来。\n- **#3 规则可操作**：脚本靠模糊词黑名单，可能误伤（如正文在\"反对写干净代码这种空话\"），\n  也可能漏判（换了说法的空话）。读上下文再定。\n- **#5 高危模块**：脚本按目录名猜（payment/auth/...），可能漏掉项目里叫法特殊的高危模块，\n  也可能把无关同名目录算进来。结合项目实际业务判断。\n- **#9 30 秒三问**：脚本只看关键词信号在不在；你要**真的当一次陌生人**读开头，看能不能答出。\n- **#10 别替模型补它已经会的**：脚本只按\"教程/如何使用/step by step\"等措辞猜，会误伤——\n  比如正文在写\"本项目**自研**框架的用法\"(模型确实不知道，该留)，或在\"反对写教程\"。\n  读上下文定夺：**判据是\"这段知识模型升级后会不会自动变强\"**，会 → 删；不会(项目私有) → 留。\n  - **本 skill 自检会触发 #10 误报**：因为正文里就列着\"教程/如何使用/step by step\"这些**待检测的黑名单词**（评分表、机检盲区、修复清单都得举例它们）——这是元层面的正常现象，定性时直接放行，别去删那些词（删了这个体检器就不工作了）。\n\n---\n\n## 安全红线（务必遵守）\n\n- **绝不读取密钥文件**：`.env` / `.env.*` / `*.key` / `*.pem` / `*secret*` 一律不打开（脚本本身也不读）。\n  需要某个非密钥值时，让用户用 `! grep KEY 文件` 自己取。\n- 体检是只读操作；**任何文件改动都要先说明改哪些、为什么，得到同意再动**。\n- 多语言/多框架项目通用——本 skill 不绑定任何具体技术栈。\n\n---\n\n## 修复动作清单（用户同意后按需执行）\n\n- **拔密钥（最高优先）**：#0 命中时先把明文 key/token/私钥/口令移出 CLAUDE.md，改放\n  `.env`／密钥管理器，正文最多留「见环境变量 XXX」；命中即视为已泄露，提醒用户**轮换**该凭据，\n  并检查是否已被提交进 git（如是需清历史）。\n- **修死链**：#4b 报的死指针——补上缺失的 docs 文件，或修正/删除指针。\n- **瘦身**：把架构图/前端技术栈表/路由表等\"图书馆\"内容迁到 `docs/architecture.md`、\n  `docs/runtime.md`，正文替换成一行指针（Tier 2 按需打开，不预读）。\n- **补禁止清单**：和用户确认项目已淘汰/冲突的库与做法，写成 Do NOT 清单。\n- **可操作化**：把\"干净/简洁\"改写成具体可判定规则。\n- **删教学型冗余**：把\"如何使用 X / 主流框架用法 / step by step 教程\"这类段落删掉——\n  模型已经会、且随升级自动变强，留着只是为\"很快过时的东西\"每次付上下文费。\n- **加高危护栏**：给 payment/auth 等目录新建本地 CLAUDE.md（安全红线 + 已知陷阱 + 改动前确认）。\n- **配 Hook**：把\"改完跑测试/格式化/改 .env 提醒重启\"等做成 `.claude/settings.json` 的\n  Pre/PostToolUse Hook（告警型即可，别默认做有破坏性的自动执行）。\n- **记忆回路**：在 CLAUDE.md 加\"任务前读 MEMORY.md、任务后写回\"指令。\n- **工作风格块**：顶部加\"My Working Style\"（先方案后代码、列选项不猜、讨厌的回复腔等）。\n- 改完**重新跑一次 `check.py`** 给前后对比分数。\n\n---\n\n## 落地骨架（建文件/重写时的推荐结构，≤200 行）\n\n```\n# 项目名\n## 30 秒速览      # 产品 / 技术栈 / 新代码放哪 + 优化优先级\n## 工作风格        # 你是谁、你讨厌什么、协作节奏（限 3–5 行，每行都对应一个\"不写就会犯的错\"，别写性格小作文）\n## 跨会话记忆      # 任务前读 MEMORY.md，任务后写回\n## 铁律            # 编号、可执行、带后果（含 Do NOT 清单）\n## 关键事实表      # 版本 / 环境等不可由代码自查的硬信息（真铁律，留正文）\n## 目录结构        # 新代码放哪里（路由地图，可留正文）\n## 延伸文档        # Tier 2 指针：docs/...，按需打开不预读\n## 规划中功能      # 尚未落地，别假设已存在\n```\n\nFile v1.2.2:README.md\n\n# hekouwang-claude-md-doctor-skill\n\n**简体中文** · [English](README.en.md)\n\n[![CI](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n![Python](https://img.shields.io/badge/python-3.x-blue.svg)\n![dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)\n![open source](https://img.shields.io/badge/open%20source-free-success.svg)\n\n> **会勇禾口王的AI笔记** 出品 · `@huiyonghkw`\n> _不聊 AI 会不会取代你，只聊先用 AI 的人怎么取代你。_\n\nCLAUDE.md 体检器 —— 检查任意项目的 `CLAUDE.md` 是否符合\"把它当**运行时配置**、\n不是项目说明书\"的最佳实践，给出评分卡 + 修复建议。\n\n<p align=\"center\">\n  <img src=\"examples/demo.gif\" width=\"720\" alt=\"hekouwang-claude-md-doctor-skill 体检演示\">\n  <br><sub>↑ 一句「检查我的 CLAUDE.md」/ <code>python3 check.py</code>，秒出评分 + 修复建议（免费 CLI）</sub>\n</p>\n\n一句话判据：**CLAUDE.md 每次会话都被重新加载、要付上下文费。值不值得每次会话都为这段内容付一次费？**\n\n<p align=\"center\">\n  <img src=\"examples/report-card.gif\" width=\"420\" alt=\"CLAUDE.md 体检报告卡（动效示例）\">\n  <br><sub>↑ 品牌可视化报告卡（<b>付费增值</b>示例）——评分弧随分数填充、等级 D→A 变色。免费版输出文本/JSON 报告。</sub>\n</p>\n\n## 为什么需要它\n\n很多人把 CLAUDE.md 写成\"项目说明书\"：塞进历史、技术决策、营销叙事，动辄上千行。\n结果模型在冗长上下文里迷失，还挤掉了真正理解代码的空间。这个工具把 10 条可检查的\n最佳实践固化下来，让任何人一键体检自己的项目。\n\n核心立场是 Claude Code 之父 Boris Cherny / Cat Wu 的 **context minimalism —— 别跟模型较劲做加法**：\n模型每代都在变强，你今天费劲搭的脚手架很快白搭。所以评分按\"减法优先\"加权，\n\"越短越准\"类核心项权重更高，\"加内容\"类项缺了不重罚。\n\n## 10 项检查\n\n1. 篇幅 ≤ 200 行（路由器不是图书馆）\n2. 禁止清单（Do NOT introduce）\n3. 规则可操作（非\"写干净代码\"式空话）\n4. 路由器不是图书馆（大块下沉 docs/ 留指针）\n5. 高危模块有本地 CLAUDE.md（碰钱/认证/迁移）\n6. 关键规则有 Hook 强制（不靠模型记忆）\n7. 跨会话记忆回路（MEMORY.md）\n8. 工作风格块（你是谁 / 你讨厌什么 · 限 3–5 行）\n9. 30 秒三问（产品 / 技术栈 / 新代码放哪）\n10. 别替模型补它已经会的（无\"如何使用 X / 教程\"式随模型升级即过时的冗余）\n\n## 用法\n\n### 在 Claude Code 里（推荐）\n直接说：「**检查我的 CLAUDE.md**」「**CLAUDE.md 体检**」——会自动跑机检 +\n模型定性复核，给出评分和按优先级的修复建议，并可代为修复。\n\n### 命令行直接跑（零依赖，仅需 Python 3）\n```bash\npython3 check.py [项目目录]          # 默认当前目录，输出彩色报告\npython3 check.py [项目目录] --json   # 机器可读 JSON（CI 可用）\n```\n退出码：有 FAIL → 1，否则 0（可用于 CI 卡关）。\n\n### Docker（不想装 Python 也能跑）\n```bash\n# 拉官方镜像直接用（打 tag 时 GitHub Actions 自动发布到 GHCR）\ndocker run --rm -v \"$PWD:/work\" ghcr.io/huiyonghkw/hekouwang-claude-md-doctor-skill\n\n# 或本地自建\ndocker build -t claude-md-doctor .\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor            # 体检当前项目\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor /work --json\n```\n\n### 接进 CI 卡关（GitHub Actions 示例）\n```yaml\n- uses: actions/setup-python@v5\n  with: { python-version: \"3.x\" }\n- name: CLAUDE.md 体检（不合格则拦 PR）\n  run: |\n    curl -sO https://raw.githubusercontent.com/huiyonghkw/hekouwang-claude-md-doctor-skill/main/check.py\n    python3 check.py .\n```\n本仓库自身的 CI 见 [`.github/workflows/ci.yml`](.github/workflows/ci.yml)（语法 + good/bad 夹具 + JSON 合法性）。\n\n## 这不是内置的 `/doctor` 命令\n\nClaude Code 自带一个 `/doctor` 命令，名字也带 \"doctor\"，但**体检对象和本工具完全不同**——\n一个查整套工具的运行环境，一个只查一份文档写得好不好。别搞混。\n\n| 维度 | 内置 `/doctor` | 本工具（claude-md-doctor） |\n|------|---------------|----------------------------|\n| **体检对象** | 整个 Claude Code **运行环境 / 安装** | 单个项目的 **`CLAUDE.md` 文件本身** |\n| **关注点** | 安装健康、未用扩展、上下文膨胀、慢 Hook、版本、权限模式 | `CLAUDE.md` 是否当运行时配置写、篇幅、该不该懒加载、10 项评分 |\n| **改哪里** | `~/.claude/` 全局配置层 | 项目里的 `CLAUDE.md` 内容 |\n| **作用范围** | 全局 · 跨所有项目 | 就这一个项目的文档 |\n\n**唯一交集**：`/doctor` 会去重本地 vs 入库 `CLAUDE.md`、把该懒加载的内容迁走，但它只从\n「上下文成本」看、**不评文档质量**。**怎么用**：先 `/doctor` 发现「CLAUDE.md 太大」，\n再用本工具深度评分 + 出 Top 3 + 代重构——`/doctor` 负责发现文档偏大，本工具负责回答「具体哪几条该删、怎么改」。\n\n## 免费 / 付费（Freemium）\n\n- **免费（开源内核）**：命令行体检器 `check.py` —— 文本 / JSON 报告、评分、退出码。\n  本地或 Docker 随便跑、随便接进 CI。这是开放内核，永久免费。\n- **付费（增值服务）**：**品牌可视化体检报告卡** —— 评分弧 + 等级带 + 九项明细的\n  精美分享图（适合汇报 / 发圈 / 放进 PR）。它依赖私有视觉系统（品牌字体与版式，\n  即私有 Skill `hekouwang-content-factory`，**GitHub 上为 PRIVATE 仓库，非授权无法 clone / 获取**），\n  **不随本仓库分发**。需要出图版报告，请联系 **@huiyonghkw** 获取。\n\n> 一句话：**跑检查免费，出「好看的报告图」找我。**\n\n## 设计\n\n- **机检层（`check.py`）**：确定性、零依赖、可移植，跑启发式检查并打分。\n- **定性层（`SKILL.md`）**：模型读正文复核机检盲区（图书馆 vs 路由器、规则是否可执行），\n  再出最终报告与修复方案。\n- **安全**：绝不读取 `.env` / `*.key` / `*.pem` 等密钥文件；体检只读，改动需确认。\n\n## 评分档位\n\nA 优秀 ≥85 · B 良好 ≥70 · C 及格 ≥50 · D 建议重写 <50\n\n## 许可协议 / License\n\n本仓库代码以 **MIT License** 开源 —— 免费使用、修改、分发、商用，仅需保留版权与许可声明。详见 [LICENSE](LICENSE)。\n\n> 范围说明：MIT 覆盖本仓库代码（`check.py` / `SKILL.md` 等）。品牌名「会勇禾口王的AI笔记」与**付费可视化报告卡**（依赖未公开的品牌字体与版式）属增值服务，不在开源范围内——但这不影响你免费、自由地使用命令行体检器。\n\n## 贡献 / Contributing\n\n欢迎提 Issue / PR：新增检查项、降低误报、补充其它语言/框架的启发式规则。\n保持零运行时依赖（仅 Python 3 标准库）是硬约束。\n\n---\n\n<sub>—— 会勇禾口王的AI笔记 · @huiyonghkw · AI 实战拆解：编程 × 内容创作 × 自动化（硬核 · 具体 · 可复制）</sub>\n\nFile v1.2.2:_meta.json\n\n{\n  \"ownerId\": \"kn73qd1gcmjr446mwcbdxef70x82vxcw\",\n  \"slug\": \"hekouwang-claude-md-doctor-skill\",\n  \"version\": \"1.2.2\",\n  \"publishedAt\": 1784128929096\n}\n\nFile v1.2.2:CHANGELOG.md\n\n# Changelog\n\n本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。\n\n## [1.2.2] - 2026-07-09\n\n### 文档\n- **新增「与内置 `/doctor` 命令的分工」小节**：两者名字都带 doctor 但体检对象完全不同——\n  内置 `/doctor` 查整套 Claude Code 运行环境（安装/未用扩展/上下文膨胀/权限/版本），\n  本 skill 只查一份 CLAUDE.md 的写法质量。给出对比表 + 唯一交集（`/doctor` Check 2/3 碰 CLAUDE.md\n  但只从上下文成本看、不评质量）+ 用法建议（先 `/doctor` 发现文档偏大，再用本 skill 深度评 + 重构）。\n- **README.md / README.en.md 同步**：两份 README 也各补一节「这不是内置的 `/doctor` 命令」\n  （精简对比表 + 唯一交集 + 组合用法），中英一致。\n\n## [1.2.1] - 2026-06-22\n\n自体检（用姊妹工具 skill-doctor 跑）后的两处打磨：\n\n### 优化\n- **SKILL.md 声明 `allowed-tools`**：收敛到本 skill 真正需要的工具集，减小越权面。\n- **补「本 skill 自检会触发 #10 误报」豁免说明**：正文里的\"教程/如何使用/step by step\"是\n  待检测的黑名单词本身（评分表/盲区/修复清单都要举例），机检会误报教学冗余——\n  与 skill-doctor 对齐，注明定性时直接放行，别删那些词（删了体检器就不工作）。\n\n## [1.2.0] - 2026-06-21\n\n对照社区教程 `luongnv89/claude-howto` 的 Memory 最佳实践逐条比对后，补上三个真空白\n（只取它的\"安全 + 机制正确性\"，不取它\"把文件写全\"的加法倾向）。\n\n### 新增\n- **安全红线检查「无硬编码密钥」(#0)**：扫正文里的 `sk-`/`AKIA`/`AIza`/`gh*_`/`xox*`/\n  JWT / 私钥块 / `password=`/`secret=` 等指纹，命中即 **FAIL**（权重 1.5、资损级）。\n  报告对命中值脱敏（前 4 位 + 长度）。占位/示例值（`<your-pwd>`/`${VAR}`/`example` 等）自动豁免。\n  补齐教程头号 Don't \"Never store secrets in CLAUDE.md\"——此前脚本只防自己读 .env，\n  却不查被体检文件本身是否藏密钥。\n- **指针死链检查 (#4b)**：`docs/` 文本指针与原生 `@import` 路径都校验目标文件是否存在，\n  死链 → WARN（指向不存在的文件比没指针更糟）。\n\n### 变更\n- **#4 路由器检查认原生 `@import` 语法**：此前只认纯文本 `docs/...`，用官方 `@path` 导入\n  反而不给\"下沉指针\"加分；现在两种写法都算合格指针。\n\n### 文档 / 测试\n- `SKILL.md` 评分表补 #0 与 #4b，加权说明与修复动作清单同步（拔密钥 + 轮换提醒、修死链）。\n- good 夹具补 `docs/architecture.md`、`docs/api.md` 桩文件，示范\"指针均可解析\"。\n\n## [1.1.0] - 2026-06-18\n\n把 Claude Code 之父 Boris Cherny / Cat Wu 的\"context minimalism · 别跟模型较劲做加法\"\n立场接进体检逻辑。\n\n### 新增\n- **第 10 项检查「别替模型补它已经会的」**：扫教学型措辞(如何使用 / 使用教程 /\n  step by step / how to use)，命中即 WARN——这类通用写法随模型升级自动变强，\n  写进常驻正文只是为\"很快过时的东西\"每次付上下文费。\n- **「减法优先」元判据**：写进 `SKILL.md`，凌驾 9 项之上——加任何一段前先问\n  \"能不能不写在常驻正文里\"。\n\n### 变更\n- **评分改为按重要度加权**：减法核心项(#1 篇幅 / #3 可操作 / #4 路由器 / #10)权重 1.5，\n  加内容项(#6 Hook / #7 记忆 / #8 人格)降到 0.6。修掉旧逻辑\"一边喊越短越好、\n  一边因缺工作风格块扣分、逼用户把文件写长\"的自相矛盾。\n- **#8 工作风格块加上限护栏**：限 3–5 行，每行须对应一个\"不写就会犯的具体错\"，别写性格小作文。\n\n### 文档\n- `README` / `README.en` 同步「10 项检查」并写明「减法优先 · 别跟模型较劲做加法」立场。\n- `SKILL.md` 顶部署名补 GitHub 仓库地址\n  （<https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill>），方便 skillhub 溯源。\n\n## [1.0.0] - 2026-06-17\n\n首个正式版本。把\"CLAUDE.md 当运行时配置、不是项目说明书\"的最佳实践做成可跑在任意项目上的体检器。\n\n### 功能\n- **9 项检查的命令行体检器 `check.py`**：篇幅 / 禁止清单 / 规则可操作 / 路由非图书馆 /\n  高危模块本地 CLAUDE.md / Hook 强制 / MEMORY.md 回路 / 工作风格 / 30 秒三问。\n- 输出彩色文本报告或 `--json`；评分 0–100（A/B/C/D）；有 FAIL → 退出码 1（可 CI 卡关）。\n- 零运行时依赖（仅 Python 3 标准库）；只读，绝不读取 `.env` / `*.key` / `*.pem`。\n- **`SKILL.md` 定性复核层**：在 Claude Code 内说「检查我的 CLAUDE.md」即可机检 + 模型复核 + 代修复。\n- **Docker**：`docker run --rm -v \"$PWD:/work\" claude-md-doctor`，免装 Python。\n- **GitHub Actions CI**：语法 + good/bad 夹具 + JSON 合法性。\n- 中英双语 README、MIT LICENSE、CONTRIBUTING、示例动图（CLI 实录 + 动效报告卡）。\n\n### 商业模型\n- 命令行体检器开源免费（MIT）；品牌可视化报告卡为付费增值，依赖未公开字体/版式，不在仓库内。\n\n[1.0.0]: https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/releases/tag/v1.0.0\n\nFile v1.2.2:CONTRIBUTING.md\n\n# 贡献指南 / Contributing\n\n感谢参与 **hekouwang-claude-md-doctor-skill**！欢迎新增检查项、降低误报、为其它语言/框架补启发式规则。\n\n## 硬约束（不可破）\n\n1. **零运行时依赖** —— `check.py` 只用 Python 3 标准库。不要引入第三方包。\n2. **只读 + 安全** —— 检查器绝不读取 `.env` / `*.key` / `*.pem` 等密钥文件，不写用户文件。\n3. **跨语言通用** —— 不绑定任何具体技术栈；新规则要对多数项目成立。\n\n## 本地开发\n\n```bash\ngit clone https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill\ncd hekouwang-claude-md-doctor-skill\n\npython3 check.py tests/fixtures/good     # 期望 exit 0\npython3 check.py tests/fixtures/bad      # 期望 exit 1（有 FAIL 卡关）\npython -m py_compile check.py            # 语法自检\n```\n\n## 加一条检查项\n\n1. 在 `check.py` 的 `check()` 里用 `add(key, title, status, detail, fix)` 追加结果。\n2. `status` 取 `PASS` / `WARN` / `FAIL` / `INFO`（INFO 不计分）。\n3. 机检只做\"机器能确定的\"；需要读正文判断的，写进 `SKILL.md` 的「定性复核」与「机检盲区」。\n4. 在 `tests/fixtures/` 增/改夹具，确保 `good` 仍 exit 0、`bad` 仍 exit 1。\n5. 误报是头号大忌——宁可 `WARN` 不轻易 `FAIL`，并在 `detail` 里说清线索。\n\n## 提交 PR\n\n- 一个 PR 聚焦一件事；附上前后 `check.py` 输出对比。\n- 通过 CI（`.github/workflows/ci.yml`：语法 + good/bad 夹具 + JSON 合法性）。\n- commit 信息讲清「改了什么 + 为什么」。\n\n## 范围说明\n\n代码以 MIT 开源（见 [LICENSE](LICENSE)）。品牌名「会勇禾口王的AI笔记」与付费可视化报告卡为增值服务，不在本仓库开源范围内。\n\nFile v1.2.2:README.en.md\n\n# hekouwang-claude-md-doctor-skill\n\n[简体中文](README.md) · **English**\n\n[![CI](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n![Python](https://img.shields.io/badge/python-3.x-blue.svg)\n![dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)\n![open source](https://img.shields.io/badge/open%20source-free-success.svg)\n\n> Made by **会勇禾口王的AI笔记** (Hekouwang's AI Notes) · `@huiyonghkw`\n\nA health checker for `CLAUDE.md` — audits any project's `CLAUDE.md` against the\nbest practice of *\"treat it as runtime config, not a project manual\"*, and returns\na scorecard plus prioritized fixes.\n\n<p align=\"center\">\n  <img src=\"examples/demo.gif\" width=\"720\" alt=\"hekouwang-claude-md-doctor-skill demo\">\n  <br><sub>↑ Say \"check my CLAUDE.md\" or run <code>python3 check.py</code> — instant score + fixes (free CLI)</sub>\n</p>\n\nThe one rule it all comes down to: **CLAUDE.md is reloaded into context on every\nsession and costs tokens every time. Is this line worth paying for on every single session?**\n\n<p align=\"center\">\n  <img src=\"examples/report-card.gif\" width=\"420\" alt=\"CLAUDE.md report card (animated)\">\n  <br><sub>↑ Branded visual report card (<b>paid add-on</b> sample) — the score arc fills and the grade morphs D→A. The free version outputs a text/JSON report.</sub>\n</p>\n\n## Why it exists\n\nMost people write `CLAUDE.md` like a project manual: history, tech decisions,\nmarketing prose — easily over a thousand lines. The model then drowns in a bloated\ncontext and loses the room it needs to actually understand your code. This tool\nfreezes 10 checkable best practices into a one-command audit anyone can run.\n\nIts guiding stance is the **context minimalism** that Claude Code's creators\nBoris Cherny and Cat Wu preach — *don't fight the model by adding things*: models\nget stronger every generation, so the scaffolding you laboriously build today\ngoes stale fast. Scoring is therefore weighted \"subtraction-first\": the\nshorter-is-sharper core checks count more, missing \"add-content\" checks count less.\n\n## The 10 checks\n\n1. **Length ≤ 200 lines** — a router, not a library\n2. **A \"Do NOT introduce\" list** — block well-meant but incompatible deps\n3. **Actionable rules** — not vague \"write clean code\" platitudes\n4. **Router, not library** — move big blocks to `docs/`, leave pointers\n5. **Local CLAUDE.md for high-risk modules** — money / auth / migrations\n6. **Hooks enforce the critical rules** — don't rely on the model's memory\n7. **A MEMORY.md cross-session loop**\n8. **A working-style block** — who you are / what you hate (cap 3–5 lines)\n9. **The 30-second test** — product? stack? where does new code go?\n10. **Don't teach the model what it already knows** — no \"how to use X / tutorial\"\n    prose that goes stale the moment the model improves\n\n## Usage\n\n### Inside Claude Code (recommended)\nJust say **\"check my CLAUDE.md\"**. It runs the mechanical check, then does a\nmodel-driven qualitative review, and returns a score with prioritized fixes —\nand can apply the fixes for you.\n\n### Command line (zero deps, just Python 3)\n```bash\npython3 check.py [project_dir]          # defaults to CWD, prints a colored report\npython3 check.py [project_dir] --json   # machine-readable JSON (for CI)\n```\nExit code: `1` if any FAIL, else `0` (usable as a CI gate).\n\n### Docker (no Python needed)\n```bash\n# Pull the prebuilt image (auto-published to GHCR on each tag via GitHub Actions)\ndocker run --rm -v \"$PWD:/work\" ghcr.io/huiyonghkw/hekouwang-claude-md-doctor-skill\n\n# Or build locally\ndocker build -t claude-md-doctor .\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor            # check current project\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor /work --json\n```\n\n### Gate your PRs (GitHub Actions)\n```yaml\n- uses: actions/setup-python@v5\n  with: { python-version: \"3.x\" }\n- name: CLAUDE.md health check (fail the PR if non-compliant)\n  run: |\n    curl -sO https://raw.githubusercontent.com/huiyonghkw/hekouwang-claude-md-doctor-skill/main/check.py\n    python3 check.py .\n```\nThis repo's own CI lives in [`.github/workflows/ci.yml`](.github/workflows/ci.yml) (syntax + good/bad fixtures + JSON validity).\n\n## This is NOT the built-in `/doctor` command\n\nClaude Code ships a `/doctor` command that also says \"doctor\" — but it checks a\n**completely different thing**: `/doctor` audits your whole tool *environment*,\nthis tool audits one *document*. Don't confuse them.\n\n| Dimension | Built-in `/doctor` | This tool (claude-md-doctor) |\n|-----------|--------------------|------------------------------|\n| **Audits** | Your whole Claude Code **environment / install** | A single project's **`CLAUDE.md` file** |\n| **Looks at** | Install health, unused extensions, context bloat, slow hooks, version, permission mode | Whether `CLAUDE.md` reads as runtime config, length, lazy-loading, the 10-check score |\n| **Edits** | `~/.claude/` global config | The project's `CLAUDE.md` content |\n| **Scope** | Global · across all projects | Just this one project's doc |\n\n**The one overlap**: `/doctor` dedups local vs checked-in `CLAUDE.md` and migrates\nlazy-loadable content out — but only from a \"context cost\" angle; it **does not\ngrade document quality**. **How to combine them**: run `/doctor` first to catch\n\"your CLAUDE.md is too big\", then use this tool to score it, surface the Top 3,\nand rewrite it — `/doctor` finds that the doc is bloated, this tool answers *which\nlines to cut and how*.\n\n## Free / Paid (Freemium)\n\n- **Free (open-source core)**: the `check.py` CLI — text / JSON report, score,\n  exit code. Run it locally or in Docker, wire it into CI. Free forever.\n- **Paid (add-on service)**: the **branded visual report card** (score arc +\n  grade band + 9-check breakdown, great for sharing / PRs). It depends on a\n  private visual system (brand fonts & layout) and is **not shipped in this repo**.\n  Want the image version? Contact **@huiyonghkw**.\n\n> In one line: **running the check is free; getting the pretty report image, talk to me.**\n\n## Design\n\n- **Mechanical layer (`check.py`)**: deterministic, zero-dependency, portable —\n  runs heuristic checks and scores them.\n- **Qualitative layer (`SKILL.md`)**: the model reads the actual file to cover the\n  checker's blind spots (library vs router, whether rules are truly actionable),\n  then produces the final report and fix plan.\n- **Safety**: never reads `.env` / `*.key` / `*.pem` secrets; the audit is\n  read-only and any edits require confirmation.\n\n## Grade bands\n\nA (excellent) ≥85 · B (good) ≥70 · C (pass) ≥50 · D (rewrite) <50\n\n## License\n\nThe code in this repo is open-sourced under the **MIT License** — free to use,\nmodify, distribute, and use commercially; just keep the copyright and license\nnotice. See [LICENSE](LICENSE).\n\n> Scope: MIT covers the repo's code (`check.py` / `SKILL.md`, etc.). The brand\n> name \"会勇禾口王的AI笔记\" and the **paid visual report card** (which relies on\n> unreleased brand fonts & layout) are an add-on service, outside the open-source\n> scope — but that does not affect your free, unrestricted use of the CLI checker.\n\n## Contributing\n\nIssues / PRs welcome: new checks, fewer false positives, heuristics for more\nlanguages/frameworks. Keeping **zero runtime dependencies** (Python 3 stdlib only)\nis a hard constraint.\n\n---\n\n<sub>—— 会勇禾口王的AI笔记 · @huiyonghkw · AI in practice: coding × content × automation</sub>\n\nFile v1.2.2:skill-card.md\n\n## Description: <br>\nAudits project CLAUDE.md files as runtime configuration, returns a scorecard with prioritized repair guidance, and can help apply confirmed fixes. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[huiyonghkw](https://clawhub.ai/user/huiyonghkw) <br>\n\n### License/Terms of Use: <br>\nMIT <br>\n\n\n## Use Case: <br>\nDevelopers and teams use this skill to review CLAUDE.md files for context hygiene, actionable project instructions, secret-safety checks, and prioritized improvements before using them in Claude Code. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Suggested repairs can change persistent project instructions that affect future agent sessions. <br>\nMitigation: Review proposed edits to CLAUDE.md and MEMORY.md before accepting them, and keep the audit report separate from approved configuration changes. <br>\nRisk: Hook configuration changes can influence future tool execution. <br>\nMitigation: Inspect any proposed .claude/settings.json hook commands and approve only commands whose scope and side effects are understood. <br>\nRisk: The checker combines deterministic heuristics with qualitative review, so a score can miss project-specific context. <br>\nMitigation: Treat the scorecard as review guidance and verify important recommendations against the project's tests, linters, and security requirements. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/huiyonghkw/skills/hekouwang-claude-md-doctor-skill) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Text, Markdown, JSON, Code, Shell commands, Configuration, Guidance] <br>\n**Output Format:** [Markdown or text report with optional JSON output and inline code or shell-command snippets] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Can propose edits to CLAUDE.md, MEMORY.md, and hook configuration after user confirmation.] <br>\n\n## Skill Version(s): <br>\n1.2.2 (source: frontmatter, changelog, server release metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v1.2.2:tests/fixtures/bad/CLAUDE.md\n\n# 我的项目\n\n请写干净的代码，保持简洁优雅，注重性能，遵循最佳实践。\n代码要高质量、易于维护。谢谢配合。\n\n## React 使用教程\n\n如何使用 useState：调用 `const [x, setX] = useState(0)`，setX 触发重渲染。\n如何使用 useEffect：把副作用放进 useEffect，依赖数组控制何时重跑。\n这些都是 React 的标准用法，跟着 step by step 写就行。\n\nFile v1.2.2:tests/fixtures/good/CLAUDE.md\n\n# Acme Dashboard\n\n> 30 秒速览：面向运营经理的 B2B 分析仪表盘。优化优先级：加载速度 > 交互 > 视觉。\n> 新代码按下方目录结构放进对应模块；动手前先看该模块 README。\n\n## 工作风格\n- 先给方案再写代码；不确定时列选项，不要猜。\n- 汇报用中文，代码与注释用英文；文件引用用绝对路径。\n- 不说「Great question!」这类客套，直接给结论。\n\n## 跨会话记忆\n- 任务开始前扫一遍 `MEMORY.md`；结束后把新的非显然结论写回。\n\n## 铁律\n1. 用 named export（路由文件除外）。\n2. 禁 `any`，用泛型或接口替代。\n3. 单组件不超过 200 行（有充分理由可超）。\n\n## 技术栈（tech stack）\n- Next.js 15 App Router + TypeScript\n- Tailwind CSS + shadcn/ui\n- PostgreSQL（数据层）\n\nDo NOT introduce unless explicitly requested:\n- Redux（已迁移到 React Context + Zustand）\n- styled-components（全站 Tailwind，不收 CSS-in-JS）\n- MongoDB（数据层锁定 PostgreSQL）\n\n## 目录结构（directory · 新代码放哪里）\n```\nsrc/\n  app/        # 路由与页面\n  components/ # 复用组件\n  lib/        # 工具与数据访问\n```\n\n## 延伸文档（Tier 2，按需打开）\n- 架构总览：`docs/architecture.md`\n- API 文档：`docs/api.md`\n\nFile v1.2.2:tests/fixtures/good/docs/api.md\n\n# API 文档\n\n（夹具桩文件：演示下沉指针可解析。）\n\nFile v1.2.2:tests/fixtures/good/docs/architecture.md\n\n# 架构总览\n\n（夹具桩文件：演示「正文留指针、内容下沉到 docs/」。）\n\nFile v1.2.2:LICENSE\n\nMIT License\n\nCopyright (c) 2026 huiyonghkw (会勇禾口王的AI笔记)\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\nArchive v1.1.2: 14 files, 33846 bytes\n\nFiles: .github/workflows/ci.yml (834b), .github/workflows/release.yml (1078b), CHANGELOG.md (4561b), check.py (27719b), CONTRIBUTING.md (1772b), README.en.md (6401b), README.md (6284b), skill-card.md (2064b), SKILL.md (12945b), tests/fixtures/bad/CLAUDE.md (423b), tests/fixtures/good/CLAUDE.md (1308b), tests/fixtures/good/docs/api.md (69b), tests/fixtures/good/docs/architecture.md (95b), _meta.json (151b)\n\nFile v1.1.2:SKILL.md\n\n---\nname: hekouwang-claude-md-doctor-skill\ndescription: >\n  会勇禾口王的AI笔记 · CLAUDE.md 体检器。检查一个项目的 CLAUDE.md（及子目录本地\n  CLAUDE.md）是否符合\"把它当运行时配置、不是项目说明书\"的最佳实践，给出评分卡 +\n  按优先级的修复建议，并可代为修复。触发：用户说「检查我的 CLAUDE.md / CLAUDE.md\n  体检 / 我的 CLAUDE.md 规范吗 / claude-md-doctor / hekouwang-claude-md-doctor-skill /\n  audit CLAUDE.md / lint CLAUDE.md / 看看我的 claude 配置合不合规」。\n  任何\"评估/审查/优化某个项目 CLAUDE.md 质量\"的请求都应触发。\nallowed-tools:\n  - Bash\n  - Read\n  - Write\n  - Edit\n  - Glob\n  - Grep\n  - AskUserQuestion\n---\n\n# hekouwang-claude-md-doctor-skill · CLAUDE.md 体检器\n\n> **会勇禾口王的AI笔记** 出品 · `@huiyonghkw`\n> GitHub: <https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill>\n> _不聊 AI 会不会取代你，只聊先用 AI 的人怎么取代你。_\n\n把\"CLAUDE.md 最佳实践\"做成一个能跑在任何项目上的检查器：机检定量 + 模型定性，\n产出评分卡和可落地的修复建议。核心判据一句话——\n\n> **CLAUDE.md 是每次会话都被重新加载、要付上下文费的\"运行时配置\"，不是给人读的项目说明书。**\n> 一切检查项都从这句推导：值不值得每次会话都为这段内容付一次费？\n\n### 减法优先（元判据 · 凌驾全部检查项之上）\n\nClaude Code 之父 Boris Cherny 公开说自己的配置\"surprisingly vanilla\"、几乎不定制；\n联合创造者 Cat Wu 自称 \"context minimalist\"——只告诉模型它需要知道的，剩下让它自己想。\n**核心立场：模型每代都在变强，你今天费劲搭的脚手架很快白搭；别跟模型较劲做加法。**\n\n所以下面这些检查项里凡是\"让用户往里加内容\"的(禁止清单/Hook/记忆/人格/本地文件)，\n落地前都先过这一关 —— **加任何一段前先问：这条能不能不写在常驻正文里？**\n\n- 能挂 **Hook**(确定性规则)→ 挂 Hook，别写正文(模型不必每次读)。\n- 能下沉 **docs/** 的 → 下沉，正文留一行指针。\n- 能靠 **linter / 类型检查 / 测试**兜住的 → 删掉，别让模型干 linter 的活。\n- 通用写法 / 主流框架用法 → 删掉，那是模型已经会的(见 #10)。\n- **只有\"模型会反复犯错、且没有机械手段能兜住\"的，才值得占常驻 token。**\n\n机检层面：**#1 篇幅 / #3 可操作 / #4 路由器 / #10 别替模型补**这几项是减法核心，权重更高；\n\"加内容\"类项(#6/#7/#8)缺失只算小扣分，避免工具一边喊\"越短越好\"、一边逼用户把文件写长。\n\n## 品牌人设（体检报告的口吻 + 署名）\n\n这套工具属于 **会勇禾口王的AI笔记**（定位：AI 实战拆解，硬核·具体·可复制；人设：你办公室里第一个把 AI 用明白的同事）。出体检报告时：\n\n- **口吻**：像同事帮你看代码——直给结论、敢泼冷水（\"这条是空话，5 秒判不了就是不合格\"），不说\"Great question / 我很乐意帮忙\"这类客套。\n- **价值化**：修复建议讲\"省了什么\"（少几十次会话的冗余、挡住一次资损/越权），不堆术语。\n- **署名**：报告结尾固定带一行品牌签收 —— `—— 会勇禾口王的AI笔记 · @huiyonghkw`，并可附 slogan。命令行 `check.py` 的报告页脚已内置该署名。\n- **去 AI 味**：定稿前避开\"赋能/打造/至关重要/助力\"等词，说人话。\n\n---\n\n## 免费 / 付费边界（重要）\n\n- **免费（开源内核）**：`check.py` 的**文本 / JSON 报告 + 评分**。任何人本地或 Docker 跑、进 CI，随便用。\n- **付费（增值）**：**品牌可视化体检报告卡**（评分弧 + 等级带 + 九项明细的精美分享图）。\n  它依赖 `hekouwang-content-factory` 的**私有品牌字体与版式**，不随本仓库分发。\n\n**触发\"出图 / 报告卡 / 图表 / 可视化\"时怎么办**：\n1. 先照常给**免费文本报告**（机检 + 定性复核）。\n2. 是否生成图：检查本机有没有 `hekouwang-content-factory`（品牌字体在\n   `~/.claude/skills/hekouwang-content-factory/assets/fonts/`）。\n   - **有**（作者本人环境）：可按 V2 米白生成报告卡 PNG。\n   - **没有**（外部用户）：明确说明可视化报告是**付费增值项**，引导联系 **@huiyonghkw** 获取，\n     不要用系统字体凑一张劣化图糊弄。\n3. 一句话口径：**跑检查免费，出\"好看的报告图\"找我。**\n\n---\n\n## 工作流（每次体检按这个顺序）\n\n1. **确认目标目录**：用户没指明就用当前工作目录；说了某项目就用那个绝对路径。\n2. **跑机检**（确定性层，零依赖）：\n   ```bash\n   python3 <此skill目录>/check.py <项目目录>\n   ```\n   - 需要结构化结果时加 `--json`（便于你解析后二次判断）。\n   - 退出码：有 FAIL → 1，否则 0。\n3. **定性复核**（机检之上，必须做）：机检是启发式，几项需要你**真正读正文**再下结论：\n   - 实际打开根 `CLAUDE.md` 通读一遍；\n   - 用下面《评分标准》逐条核对，**重点修正机检可能误判的项**（见\"机检的盲区\"）；\n   - 抽查 1–2 个子目录本地 CLAUDE.md 是否写了真红线（不是空模板）。\n4. **出报告**：先给一句话总评 + 分数档位，再用\"✓/▲/✗ + 一句话 + 修复建议\"逐条列，\n   最后给 **Top 3 最该先改的**（按\"花最小力气补最大漏洞\"排序）。中文输出。\n5. **提出代修复**：问用户要不要直接改（瘦身下沉 docs/、补禁止清单、补工作风格块、\n   加高危模块本地 CLAUDE.md、配 Hook 等）。**得到同意再动文件**，一次改一类、可回退。\n\n> 不要只把脚本输出原样贴给用户——脚本是线索，你的价值在定性判断 + 具体怎么改。\n\n---\n\n## 评分标准（10 项 · 也是机检的判分依据）\n\n| # | 检查项 | 合格长什么样 | 不合格信号 |\n|---|--------|------------|-----------|\n| 0 | **无硬编码密钥（安全红线）** | 正文不出现 key/token/私钥/口令明文 | 出现 `sk-`/`AKIA`/私钥块/`password=\"...\"` → **直接 FAIL** |\n| 1 | **篇幅 ≤ 200 行** | 路由器不是图书馆，常驻越短越好 | >200 行；大段历史/营销/教程正文 |\n| 2 | **禁止清单（Do NOT）** | 有\"不要引入 X（因为 Y）\"清单 | 只列要用的、不列禁用的 |\n| 3 | **规则可操作** | 5 秒内能判定代码合不合规 | \"写干净代码/优雅/高质量\"这类空话 |\n| 4 | **路由器不是图书馆** | 大块下沉 docs/，正文留指针（认 docs/ 文本指针与原生 `@import`） | 架构图/长表/历史塞在常驻正文 |\n| 4b | **指针无死链** | docs/ 与 `@import` 都指向真实存在的文件 | 指针指向不存在的文件（按图索骥扑空，比没指针更糟） |\n| 5 | **高危模块本地 CLAUDE.md** | 碰钱/认证/迁移目录各有护栏 | 敏感模块只靠根文件一句话 |\n| 6 | **Hook 强制层** | 最不能漏的规则挂成 Hook | 关键规则只\"写着\"靠模型记 |\n| 7 | **MEMORY.md 回路** | 任务前读、任务后写的跨会话记忆 | 每次会话从零重新认识项目 |\n| 8 | **工作风格块**（限 3–5 行） | 写了\"你是谁/你讨厌什么/协作节奏\"，且每行都指向一个\"不写就会犯的具体错\" | 没有人格；或写成性格小作文 |\n| 9 | **30 秒三问** | 陌生人读完能答：产品？技术栈？新代码放哪 | 开头答不出这三问 |\n| 10 | **别替模型补它已经会的** | 不教通用写法/主流框架用法，只装项目私有事实 | 有\"如何使用 X / 使用教程 / step by step\"这类随模型升级很快过时的教学段 |\n\n**分档**：A 优秀 ≥85 · B 良好 ≥70 · C 及格 ≥50 · D 建议重写 <50。\n（机检：PASS=1 / WARN=0.5 / FAIL=0，INFO 不计分。**按重要度加权**——安全红线 #0 与\n减法核心项 #1/#3/#4/#10 权重 1.5，标准项 #2/#4b/#5/#9 为 1.0，加内容项 #6/#7/#8 为 0.6。\n#0 命中按 FAIL 计且资损级，定性总评里应一票顶到「先改这条」。）\n\n---\n\n## 机检的盲区（定性复核时重点纠偏）\n\n脚本只能判\"机器能确定的\"，以下几项**容易误判，必须你读正文定夺**：\n\n- **#4 图书馆 vs 路由器**：脚本只按\"大代码块/大表/历史标题\"猜。\n  - **目录树是路由地图，应保留**（脚本已不把纯 `├──└──` 树当图书馆图）；\n  - 但\"版本表/环境表\"这类**真铁律**即使是表格也该留正文——别因为是表就建议下沉；\n  - 反过来，一段没有特征字符的长叙事，脚本可能漏判，你要自己看出来。\n- **#3 规则可操作**：脚本靠模糊词黑名单，可能误伤（如正文在\"反对写干净代码这种空话\"），\n  也可能漏判（换了说法的空话）。读上下文再定。\n- **#5 高危模块**：脚本按目录名猜（payment/auth/...），可能漏掉项目里叫法特殊的高危模块，\n  也可能把无关同名目录算进来。结合项目实际业务判断。\n- **#9 30 秒三问**：脚本只看关键词信号在不在；你要**真的当一次陌生人**读开头，看能不能答出。\n- **#10 别替模型补它已经会的**：脚本只按\"教程/如何使用/step by step\"等措辞猜，会误伤——\n  比如正文在写\"本项目**自研**框架的用法\"(模型确实不知道，该留)，或在\"反对写教程\"。\n  读上下文定夺：**判据是\"这段知识模型升级后会不会自动变强\"**，会 → 删；不会(项目私有) → 留。\n  - **本 skill 自检会触发 #10 误报**：因为正文里就列着\"教程/如何使用/step by step\"这些**待检测的黑名单词**（评分表、机检盲区、修复清单都得举例它们）——这是元层面的正常现象，定性时直接放行，别去删那些词（删了这个体检器就不工作了）。\n\n---\n\n## 安全红线（务必遵守）\n\n- **绝不读取密钥文件**：`.env` / `.env.*` / `*.key` / `*.pem` / `*secret*` 一律不打开（脚本本身也不读）。\n  需要某个非密钥值时，让用户用 `! grep KEY 文件` 自己取。\n- 体检是只读操作；**任何文件改动都要先说明改哪些、为什么，得到同意再动**。\n- 多语言/多框架项目通用——本 skill 不绑定任何具体技术栈。\n\n---\n\n## 修复动作清单（用户同意后按需执行）\n\n- **拔密钥（最高优先）**：#0 命中时先把明文 key/token/私钥/口令移出 CLAUDE.md，改放\n  `.env`／密钥管理器，正文最多留「见环境变量 XXX」；命中即视为已泄露，提醒用户**轮换**该凭据，\n  并检查是否已被提交进 git（如是需清历史）。\n- **修死链**：#4b 报的死指针——补上缺失的 docs 文件，或修正/删除指针。\n- **瘦身**：把架构图/前端技术栈表/路由表等\"图书馆\"内容迁到 `docs/architecture.md`、\n  `docs/runtime.md`，正文替换成一行指针（Tier 2 按需打开，不预读）。\n- **补禁止清单**：和用户确认项目已淘汰/冲突的库与做法，写成 Do NOT 清单。\n- **可操作化**：把\"干净/简洁\"改写成具体可判定规则。\n- **删教学型冗余**：把\"如何使用 X / 主流框架用法 / step by step 教程\"这类段落删掉——\n  模型已经会、且随升级自动变强，留着只是为\"很快过时的东西\"每次付上下文费。\n- **加高危护栏**：给 payment/auth 等目录新建本地 CLAUDE.md（安全红线 + 已知陷阱 + 改动前确认）。\n- **配 Hook**：把\"改完跑测试/格式化/改 .env 提醒重启\"等做成 `.claude/settings.json` 的\n  Pre/PostToolUse Hook（告警型即可，别默认做有破坏性的自动执行）。\n- **记忆回路**：在 CLAUDE.md 加\"任务前读 MEMORY.md、任务后写回\"指令。\n- **工作风格块**：顶部加\"My Working Style\"（先方案后代码、列选项不猜、讨厌的回复腔等）。\n- 改完**重新跑一次 `check.py`** 给前后对比分数。\n\n---\n\n## 落地骨架（建文件/重写时的推荐结构，≤200 行）\n\n```\n# 项目名\n## 30 秒速览      # 产品 / 技术栈 / 新代码放哪 + 优化优先级\n## 工作风格        # 你是谁、你讨厌什么、协作节奏（限 3–5 行，每行都对应一个\"不写就会犯的错\"，别写性格小作文）\n## 跨会话记忆      # 任务前读 MEMORY.md，任务后写回\n## 铁律            # 编号、可执行、带后果（含 Do NOT 清单）\n## 关键事实表      # 版本 / 环境等不可由代码自查的硬信息（真铁律，留正文）\n## 目录结构        # 新代码放哪里（路由地图，可留正文）\n## 延伸文档        # Tier 2 指针：docs/...，按需打开不预读\n## 规划中功能      # 尚未落地，别假设已存在\n```\n\nFile v1.1.2:README.md\n\n# hekouwang-claude-md-doctor-skill\n\n**简体中文** · [English](README.en.md)\n\n[![CI](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n![Python](https://img.shields.io/badge/python-3.x-blue.svg)\n![dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)\n![open source](https://img.shields.io/badge/open%20source-free-success.svg)\n\n> **会勇禾口王的AI笔记** 出品 · `@huiyonghkw`\n> _不聊 AI 会不会取代你，只聊先用 AI 的人怎么取代你。_\n\nCLAUDE.md 体检器 —— 检查任意项目的 `CLAUDE.md` 是否符合\"把它当**运行时配置**、\n不是项目说明书\"的最佳实践，给出评分卡 + 修复建议。\n\n<p align=\"center\">\n  <img src=\"examples/demo.gif\" width=\"720\" alt=\"hekouwang-claude-md-doctor-skill 体检演示\">\n  <br><sub>↑ 一句「检查我的 CLAUDE.md」/ <code>python3 check.py</code>，秒出评分 + 修复建议（免费 CLI）</sub>\n</p>\n\n一句话判据：**CLAUDE.md 每次会话都被重新加载、要付上下文费。值不值得每次会话都为这段内容付一次费？**\n\n<p align=\"center\">\n  <img src=\"examples/report-card.gif\" width=\"420\" alt=\"CLAUDE.md 体检报告卡（动效示例）\">\n  <br><sub>↑ 品牌可视化报告卡（<b>付费增值</b>示例）——评分弧随分数填充、等级 D→A 变色。免费版输出文本/JSON 报告。</sub>\n</p>\n\n## 为什么需要它\n\n很多人把 CLAUDE.md 写成\"项目说明书\"：塞进历史、技术决策、营销叙事，动辄上千行。\n结果模型在冗长上下文里迷失，还挤掉了真正理解代码的空间。这个工具把 10 条可检查的\n最佳实践固化下来，让任何人一键体检自己的项目。\n\n核心立场是 Claude Code 之父 Boris Cherny / Cat Wu 的 **context minimalism —— 别跟模型较劲做加法**：\n模型每代都在变强，你今天费劲搭的脚手架很快白搭。所以评分按\"减法优先\"加权，\n\"越短越准\"类核心项权重更高，\"加内容\"类项缺了不重罚。\n\n## 10 项检查\n\n1. 篇幅 ≤ 200 行（路由器不是图书馆）\n2. 禁止清单（Do NOT introduce）\n3. 规则可操作（非\"写干净代码\"式空话）\n4. 路由器不是图书馆（大块下沉 docs/ 留指针）\n5. 高危模块有本地 CLAUDE.md（碰钱/认证/迁移）\n6. 关键规则有 Hook 强制（不靠模型记忆）\n7. 跨会话记忆回路（MEMORY.md）\n8. 工作风格块（你是谁 / 你讨厌什么 · 限 3–5 行）\n9. 30 秒三问（产品 / 技术栈 / 新代码放哪）\n10. 别替模型补它已经会的（无\"如何使用 X / 教程\"式随模型升级即过时的冗余）\n\n## 用法\n\n### 在 Claude Code 里（推荐）\n直接说：「**检查我的 CLAUDE.md**」「**CLAUDE.md 体检**」——会自动跑机检 +\n模型定性复核，给出评分和按优先级的修复建议，并可代为修复。\n\n### 命令行直接跑（零依赖，仅需 Python 3）\n```bash\npython3 check.py [项目目录]          # 默认当前目录，输出彩色报告\npython3 check.py [项目目录] --json   # 机器可读 JSON（CI 可用）\n```\n退出码：有 FAIL → 1，否则 0（可用于 CI 卡关）。\n\n### Docker（不想装 Python 也能跑）\n```bash\n# 拉官方镜像直接用（打 tag 时 GitHub Actions 自动发布到 GHCR）\ndocker run --rm -v \"$PWD:/work\" ghcr.io/huiyonghkw/hekouwang-claude-md-doctor-skill\n\n# 或本地自建\ndocker build -t claude-md-doctor .\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor            # 体检当前项目\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor /work --json\n```\n\n### 接进 CI 卡关（GitHub Actions 示例）\n```yaml\n- uses: actions/setup-python@v5\n  with: { python-version: \"3.x\" }\n- name: CLAUDE.md 体检（不合格则拦 PR）\n  run: |\n    curl -sO https://raw.githubusercontent.com/huiyonghkw/hekouwang-claude-md-doctor-skill/main/check.py\n    python3 check.py .\n```\n本仓库自身的 CI 见 [`.github/workflows/ci.yml`](.github/workflows/ci.yml)（语法 + good/bad 夹具 + JSON 合法性）。\n\n## 免费 / 付费（Freemium）\n\n- **免费（开源内核）**：命令行体检器 `check.py` —— 文本 / JSON 报告、评分、退出码。\n  本地或 Docker 随便跑、随便接进 CI。这是开放内核，永久免费。\n- **付费（增值服务）**：**品牌可视化体检报告卡** —— 评分弧 + 等级带 + 九项明细的\n  精美分享图（适合汇报 / 发圈 / 放进 PR）。它依赖私有视觉系统（品牌字体与版式，\n  即私有 Skill `hekouwang-content-factory`，**GitHub 上为 PRIVATE 仓库，非授权无法 clone / 获取**），\n  **不随本仓库分发**。需要出图版报告，请联系 **@huiyonghkw** 获取。\n\n> 一句话：**跑检查免费，出「好看的报告图」找我。**\n\n## 设计\n\n- **机检层（`check.py`）**：确定性、零依赖、可移植，跑启发式检查并打分。\n- **定性层（`SKILL.md`）**：模型读正文复核机检盲区（图书馆 vs 路由器、规则是否可执行），\n  再出最终报告与修复方案。\n- **安全**：绝不读取 `.env` / `*.key` / `*.pem` 等密钥文件；体检只读，改动需确认。\n\n## 评分档位\n\nA 优秀 ≥85 · B 良好 ≥70 · C 及格 ≥50 · D 建议重写 <50\n\n## 许可协议 / License\n\n本仓库代码以 **MIT License** 开源 —— 免费使用、修改、分发、商用，仅需保留版权与许可声明。详见 [LICENSE](LICENSE)。\n\n> 范围说明：MIT 覆盖本仓库代码（`check.py` / `SKILL.md` 等）。品牌名「会勇禾口王的AI笔记」与**付费可视化报告卡**（依赖未公开的品牌字体与版式）属增值服务，不在开源范围内——但这不影响你免费、自由地使用命令行体检器。\n\n## 贡献 / Contributing\n\n欢迎提 Issue / PR：新增检查项、降低误报、补充其它语言/框架的启发式规则。\n保持零运行时依赖（仅 Python 3 标准库）是硬约束。\n\n---\n\n<sub>—— 会勇禾口王的AI笔记 · @huiyonghkw · AI 实战拆解：编程 × 内容创作 × 自动化（硬核 · 具体 · 可复制）</sub>\n\nFile v1.1.2:_meta.json\n\n{\n  \"ownerId\": \"kn73qd1gcmjr446mwcbdxef70x82vxcw\",\n  \"slug\": \"hekouwang-claude-md-doctor-skill\",\n  \"version\": \"1.1.2\",\n  \"publishedAt\": 1782112933775\n}\n\nFile v1.1.2:CHANGELOG.md\n\n# Changelog\n\n本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。\n\n## [1.2.1] - 2026-06-22\n\n自体检（用姊妹工具 skill-doctor 跑）后的两处打磨：\n\n### 优化\n- **SKILL.md 声明 `allowed-tools`**：收敛到本 skill 真正需要的工具集，减小越权面。\n- **补「本 skill 自检会触发 #10 误报」豁免说明**：正文里的\"教程/如何使用/step by step\"是\n  待检测的黑名单词本身（评分表/盲区/修复清单都要举例），机检会误报教学冗余——\n  与 skill-doctor 对齐，注明定性时直接放行，别删那些词（删了体检器就不工作）。\n\n## [1.2.0] - 2026-06-21\n\n对照社区教程 `luongnv89/claude-howto` 的 Memory 最佳实践逐条比对后，补上三个真空白\n（只取它的\"安全 + 机制正确性\"，不取它\"把文件写全\"的加法倾向）。\n\n### 新增\n- **安全红线检查「无硬编码密钥」(#0)**：扫正文里的 `sk-`/`AKIA`/`AIza`/`gh*_`/`xox*`/\n  JWT / 私钥块 / `password=`/`secret=` 等指纹，命中即 **FAIL**（权重 1.5、资损级）。\n  报告对命中值脱敏（前 4 位 + 长度）。占位/示例值（`<your-pwd>`/`${VAR}`/`example` 等）自动豁免。\n  补齐教程头号 Don't \"Never store secrets in CLAUDE.md\"——此前脚本只防自己读 .env，\n  却不查被体检文件本身是否藏密钥。\n- **指针死链检查 (#4b)**：`docs/` 文本指针与原生 `@import` 路径都校验目标文件是否存在，\n  死链 → WARN（指向不存在的文件比没指针更糟）。\n\n### 变更\n- **#4 路由器检查认原生 `@import` 语法**：此前只认纯文本 `docs/...`，用官方 `@path` 导入\n  反而不给\"下沉指针\"加分；现在两种写法都算合格指针。\n\n### 文档 / 测试\n- `SKILL.md` 评分表补 #0 与 #4b，加权说明与修复动作清单同步（拔密钥 + 轮换提醒、修死链）。\n- good 夹具补 `docs/architecture.md`、`docs/api.md` 桩文件，示范\"指针均可解析\"。\n\n## [1.1.0] - 2026-06-18\n\n把 Claude Code 之父 Boris Cherny / Cat Wu 的\"context minimalism · 别跟模型较劲做加法\"\n立场接进体检逻辑。\n\n### 新增\n- **第 10 项检查「别替模型补它已经会的」**：扫教学型措辞(如何使用 / 使用教程 /\n  step by step / how to use)，命中即 WARN——这类通用写法随模型升级自动变强，\n  写进常驻正文只是为\"很快过时的东西\"每次付上下文费。\n- **「减法优先」元判据**：写进 `SKILL.md`，凌驾 9 项之上——加任何一段前先问\n  \"能不能不写在常驻正文里\"。\n\n### 变更\n- **评分改为按重要度加权**：减法核心项(#1 篇幅 / #3 可操作 / #4 路由器 / #10)权重 1.5，\n  加内容项(#6 Hook / #7 记忆 / #8 人格)降到 0.6。修掉旧逻辑\"一边喊越短越好、\n  一边因缺工作风格块扣分、逼用户把文件写长\"的自相矛盾。\n- **#8 工作风格块加上限护栏**：限 3–5 行，每行须对应一个\"不写就会犯的具体错\"，别写性格小作文。\n\n### 文档\n- `README` / `README.en` 同步「10 项检查」并写明「减法优先 · 别跟模型较劲做加法」立场。\n- `SKILL.md` 顶部署名补 GitHub 仓库地址\n  （<https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill>），方便 skillhub 溯源。\n\n## [1.0.0] - 2026-06-17\n\n首个正式版本。把\"CLAUDE.md 当运行时配置、不是项目说明书\"的最佳实践做成可跑在任意项目上的体检器。\n\n### 功能\n- **9 项检查的命令行体检器 `check.py`**：篇幅 / 禁止清单 / 规则可操作 / 路由非图书馆 /\n  高危模块本地 CLAUDE.md / Hook 强制 / MEMORY.md 回路 / 工作风格 / 30 秒三问。\n- 输出彩色文本报告或 `--json`；评分 0–100（A/B/C/D）；有 FAIL → 退出码 1（可 CI 卡关）。\n- 零运行时依赖（仅 Python 3 标准库）；只读，绝不读取 `.env` / `*.key` / `*.pem`。\n- **`SKILL.md` 定性复核层**：在 Claude Code 内说「检查我的 CLAUDE.md」即可机检 + 模型复核 + 代修复。\n- **Docker**：`docker run --rm -v \"$PWD:/work\" claude-md-doctor`，免装 Python。\n- **GitHub Actions CI**：语法 + good/bad 夹具 + JSON 合法性。\n- 中英双语 README、MIT LICENSE、CONTRIBUTING、示例动图（CLI 实录 + 动效报告卡）。\n\n### 商业模型\n- 命令行体检器开源免费（MIT）；品牌可视化报告卡为付费增值，依赖未公开字体/版式，不在仓库内。\n\n[1.0.0]: https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/releases/tag/v1.0.0\n\nFile v1.1.2:CONTRIBUTING.md\n\n# 贡献指南 / Contributing\n\n感谢参与 **hekouwang-claude-md-doctor-skill**！欢迎新增检查项、降低误报、为其它语言/框架补启发式规则。\n\n## 硬约束（不可破）\n\n1. **零运行时依赖** —— `check.py` 只用 Python 3 标准库。不要引入第三方包。\n2. **只读 + 安全** —— 检查器绝不读取 `.env` / `*.key` / `*.pem` 等密钥文件，不写用户文件。\n3. **跨语言通用** —— 不绑定任何具体技术栈；新规则要对多数项目成立。\n\n## 本地开发\n\n```bash\ngit clone https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill\ncd hekouwang-claude-md-doctor-skill\n\npython3 check.py tests/fixtures/good     # 期望 exit 0\npython3 check.py tests/fixtures/bad      # 期望 exit 1（有 FAIL 卡关）\npython -m py_compile check.py            # 语法自检\n```\n\n## 加一条检查项\n\n1. 在 `check.py` 的 `check()` 里用 `add(key, title, status, detail, fix)` 追加结果。\n2. `status` 取 `PASS` / `WARN` / `FAIL` / `INFO`（INFO 不计分）。\n3. 机检只做\"机器能确定的\"；需要读正文判断的，写进 `SKILL.md` 的「定性复核」与「机检盲区」。\n4. 在 `tests/fixtures/` 增/改夹具，确保 `good` 仍 exit 0、`bad` 仍 exit 1。\n5. 误报是头号大忌——宁可 `WARN` 不轻易 `FAIL`，并在 `detail` 里说清线索。\n\n## 提交 PR\n\n- 一个 PR 聚焦一件事；附上前后 `check.py` 输出对比。\n- 通过 CI（`.github/workflows/ci.yml`：语法 + good/bad 夹具 + JSON 合法性）。\n- commit 信息讲清「改了什么 + 为什么」。\n\n## 范围说明\n\n代码以 MIT 开源（见 [LICENSE](LICENSE)）。品牌名「会勇禾口王的AI笔记」与付费可视化报告卡为增值服务，不在本仓库开源范围内。\n\nFile v1.1.2:README.en.md\n\n# hekouwang-claude-md-doctor-skill\n\n[简体中文](README.md) · **English**\n\n[![CI](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n![Python](https://img.shields.io/badge/python-3.x-blue.svg)\n![dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)\n![open source](https://img.shields.io/badge/open%20source-free-success.svg)\n\n> Made by **会勇禾口王的AI笔记** (Hekouwang's AI Notes) · `@huiyonghkw`\n\nA health checker for `CLAUDE.md` — audits any project's `CLAUDE.md` against the\nbest practice of *\"treat it as runtime config, not a project manual\"*, and returns\na scorecard plus prioritized fixes.\n\n<p align=\"center\">\n  <img src=\"examples/demo.gif\" width=\"720\" alt=\"hekouwang-claude-md-doctor-skill demo\">\n  <br><sub>↑ Say \"check my CLAUDE.md\" or run <code>python3 check.py</code> — instant score + fixes (free CLI)</sub>\n</p>\n\nThe one rule it all comes down to: **CLAUDE.md is reloaded into context on every\nsession and costs tokens every time. Is this line worth paying for on every single session?**\n\n<p align=\"center\">\n  <img src=\"examples/report-card.gif\" width=\"420\" alt=\"CLAUDE.md report card (animated)\">\n  <br><sub>↑ Branded visual report card (<b>paid add-on</b> sample) — the score arc fills and the grade morphs D→A. The free version outputs a text/JSON report.</sub>\n</p>\n\n## Why it exists\n\nMost people write `CLAUDE.md` like a project manual: history, tech decisions,\nmarketing prose — easily over a thousand lines. The model then drowns in a bloated\ncontext and loses the room it needs to actually understand your code. This tool\nfreezes 10 checkable best practices into a one-command audit anyone can run.\n\nIts guiding stance is the **context minimalism** that Claude Code's creators\nBoris Cherny and Cat Wu preach — *don't fight the model by adding things*: models\nget stronger every generation, so the scaffolding you laboriously build today\ngoes stale fast. Scoring is therefore weighted \"subtraction-first\": the\nshorter-is-sharper core checks count more, missing \"add-content\" checks count less.\n\n## The 10 checks\n\n1. **Length ≤ 200 lines** — a router, not a library\n2. **A \"Do NOT introduce\" list** — block well-meant but incompatible deps\n3. **Actionable rules** — not vague \"write clean code\" platitudes\n4. **Router, not library** — move big blocks to `docs/`, leave pointers\n5. **Local CLAUDE.md for high-risk modules** — money / auth / migrations\n6. **Hooks enforce the critical rules** — don't rely on the model's memory\n7. **A MEMORY.md cross-session loop**\n8. **A working-style block** — who you are / what you hate (cap 3–5 lines)\n9. **The 30-second test** — product? stack? where does new code go?\n10. **Don't teach the model what it already knows** — no \"how to use X / tutorial\"\n    prose that goes stale the moment the model improves\n\n## Usage\n\n### Inside Claude Code (recommended)\nJust say **\"check my CLAUDE.md\"**. It runs the mechanical check, then does a\nmodel-driven qualitative review, and returns a score with prioritized fixes —\nand can apply the fixes for you.\n\n### Command line (zero deps, just Python 3)\n```bash\npython3 check.py [project_dir]          # defaults to CWD, prints a colored report\npython3 check.py [project_dir] --json   # machine-readable JSON (for CI)\n```\nExit code: `1` if any FAIL, else `0` (usable as a CI gate).\n\n### Docker (no Python needed)\n```bash\n# Pull the prebuilt image (auto-published to GHCR on each tag via GitHub Actions)\ndocker run --rm -v \"$PWD:/work\" ghcr.io/huiyonghkw/hekouwang-claude-md-doctor-skill\n\n# Or build locally\ndocker build -t claude-md-doctor .\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor            # check current project\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor /work --json\n```\n\n### Gate your PRs (GitHub Actions)\n```yaml\n- uses: actions/setup-python@v5\n  with: { python-version: \"3.x\" }\n- name: CLAUDE.md health check (fail the PR if non-compliant)\n  run: |\n    curl -sO https://raw.githubusercontent.com/huiyonghkw/hekouwang-claude-md-doctor-skill/main/check.py\n    python3 check.py .\n```\nThis repo's own CI lives in [`.github/workflows/ci.yml`](.github/workflows/ci.yml) (syntax + good/bad fixtures + JSON validity).\n\n## Free / Paid (Freemium)\n\n- **Free (open-source core)**: the `check.py` CLI — text / JSON report, score,\n  exit code. Run it locally or in Docker, wire it into CI. Free forever.\n- **Paid (add-on service)**: the **branded visual report card** (score arc +\n  grade band + 9-check breakdown, great for sharing / PRs). It depends on a\n  private visual system (brand fonts & layout) and is **not shipped in this repo**.\n  Want the image version? Contact **@huiyonghkw**.\n\n> In one line: **running the check is free; getting the pretty report image, talk to me.**\n\n## Design\n\n- **Mechanical layer (`check.py`)**: deterministic, zero-dependency, portable —\n  runs heuristic checks and scores them.\n- **Qualitative layer (`SKILL.md`)**: the model reads the actual file to cover the\n  checker's blind spots (library vs router, whether rules are truly actionable),\n  then produces the final report and fix plan.\n- **Safety**: never reads `.env` / `*.key` / `*.pem` secrets; the audit is\n  read-only and any edits require confirmation.\n\n## Grade bands\n\nA (excellent) ≥85 · B (good) ≥70 · C (pass) ≥50 · D (rewrite) <50\n\n## License\n\nThe code in this repo is open-sourced under the **MIT License** — free to use,\nmodify, distribute, and use commercially; just keep the copyright and license\nnotice. See [LICENSE](LICENSE).\n\n> Scope: MIT covers the repo's code (`check.py` / `SKILL.md`, etc.). The brand\n> name \"会勇禾口王的AI笔记\" and the **paid visual report card** (which relies on\n> unreleased brand fonts & layout) are an add-on service, outside the open-source\n> scope — but that does not affect your free, unrestricted use of the CLI checker.\n\n## Contributing\n\nIssues / PRs welcome: new checks, fewer false positives, heuristics for more\nlanguages/frameworks. Keeping **zero runtime dependencies** (Python 3 stdlib only)\nis a hard constraint.\n\n---\n\n<sub>—— 会勇禾口王的AI笔记 · @huiyonghkw · AI in practice: coding × content × automation</sub>\n\nFile v1.1.2:skill-card.md\n\n## Description: <br>\nAudits project CLAUDE.md files as runtime configuration, returning a scorecard, prioritized fixes, and optional user-approved edits. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[huiyonghkw](https://clawhub.ai/user/huiyonghkw) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and teams use this skill to audit CLAUDE.md guidance for bloat, vague rules, missing safeguards, broken documentation pointers, and hardcoded secrets, then prioritize edits that keep agent context leaner and safer. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Approved fixes can change project guidance files and influence future agent sessions. <br>\nMitigation: Review each proposed change before applying it, especially Hook and MEMORY.md additions. <br>\nRisk: Project CLAUDE.md files may contain sensitive instructions or hardcoded credentials that should not be kept in agent context. <br>\nMitigation: Keep secrets out of CLAUDE.md and rotate any discovered credential as part of remediation. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/huiyonghkw/hekouwang-claude-md-doctor-skill) <br>\n- [README.en.md](artifact/README.en.md) <br>\n- [SKILL.md](artifact/SKILL.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Text, Markdown, Code, Shell commands, Configuration, Guidance] <br>\n**Output Format:** [Markdown report with optional JSON checker output, shell commands, and proposed file edits] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [File edits require user approval; the command-line checker can emit JSON for CI.] <br>\n\n## Skill Version(s): <br>\n1.1.2 (source: ClawHub release metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v1.1.2:tests/fixtures/bad/CLAUDE.md\n\n# 我的项目\n\n请写干净的代码，保持简洁优雅，注重性能，遵循最佳实践。\n代码要高质量、易于维护。谢谢配合。\n\n## React 使用教程\n\n如何使用 useState：调用 `const [x, setX] = useState(0)`，setX 触发重渲染。\n如何使用 useEffect：把副作用放进 useEffect，依赖数组控制何时重跑。\n这些都是 React 的标准用法，跟着 \n\nArchive v1.1.1: 14 files, 33358 bytes\n\nFiles: .github/workflows/ci.yml (834b), .github/workflows/release.yml (1078b), CHANGELOG.md (4007b), check.py (27719b), CONTRIBUTING.md (1772b), README.en.md (6401b), README.md (6284b), skill-card.md (2170b), SKILL.md (12526b), tests/fixtures/bad/CLAUDE.md (423b), tests/fixtures/good/CLAUDE.md (1308b), tests/fixtures/good/docs/api.md (69b), tests/fixtures/good/docs/architecture.md (95b), _meta.json (151b)\n\nArchive v1.1.0: 12 files, 29520 bytes\n\nFiles: .github/workflows/ci.yml (834b), .github/workflows/release.yml (1078b), CHANGELOG.md (2371b), check.py (22686b), CONTRIBUTING.md (1772b), README.en.md (6401b), README.md (6167b), skill-card.md (2408b), SKILL.md (11634b), tests/fixtures/bad/CLAUDE.md (423b), tests/fixtures/good/CLAUDE.md (1308b), _meta.json (151b)\n\nArchive v1.0.0: 12 files, 25734 bytes\n\nFiles: .github/workflows/ci.yml (834b), .github/workflows/release.yml (1078b), CHANGELOG.md (1326b), check.py (19688b), CONTRIBUTING.md (1772b), README.en.md (5844b), README.md (5732b), skill-card.md (2211b), SKILL.md (9138b), tests/fixtures/bad/CLAUDE.md (150b), tests/fixtures/good/CLAUDE.md (1308b), _meta.json (151b)","readmeExcerpt":"Skill: hekouwang-claude-md-doctor-skill Owner: huiyonghkw Summary: 会勇禾口王的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 质量\"的请求都应触发。 Tags: latest:1.3.2 Version history: ","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"python3 <此skill目录>/check.py <项目目录>"},{"language":"text","snippet":"# 项目名\n## 30 秒速览      # 产品 / 技术栈 / 新代码放哪 + 优化优先级\n## 工作风格        # 你是谁、你讨厌什么、协作节奏（限 3–5 行，每行都对应一个\"不写就会犯的错\"，别写性格小作文）\n## 跨会话记忆      # 任务前读 MEMORY.md，任务后写回\n## 铁律            # 编号、可执行、带后果（含 Do NOT 清单）\n## 关键事实表      # 版本 / 环境等不可由代码自查的硬信息（真铁律，留正文）\n## 目录结构        # 新代码放哪里（路由地图，可留正文）\n## 延伸文档        # Tier 2 指针：docs/...，按需打开不预读\n## 规划中功能      # 尚未落地，别假设已存在"},{"language":"bash","snippet":"python3 check.py .                    # 体检当前项目（零依赖）\nbash scripts/run-all-doctors.sh .     # 三件套：md + skill + env"},{"language":"bash","snippet":"python3 check.py [项目目录]          # 默认当前目录，输出彩色报告\npython3 check.py [项目目录] --json   # 机器可读 JSON（CI 可用）"},{"language":"bash","snippet":"# 拉官方镜像直接用（打 tag 时 GitHub Actions 自动发布到 GHCR）\ndocker run --rm -v \"$PWD:/work\" ghcr.io/huiyonghkw/hekouwang-claude-md-doctor-skill\n\n# 或本地自建\ndocker build -t claude-md-doctor .\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor            # 体检当前项目\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor /work --json"},{"language":"yaml","snippet":"- uses: actions/setup-python@v5\n  with: { python-version: \"3.x\" }\n- name: CLAUDE.md 体检（不合格则拦 PR）\n  run: |\n    curl -sO https://raw.githubusercontent.com/huiyonghkw/hekouwang-claude-md-doctor-skill/main/check.py\n    python3 check.py ."}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: hekouwang-claude-md-doctor-skill\nslug: hekouwang-claude-md-doctor-skill\ndisplayName: CLAUDE.md / AGENTS.md 体检器\nsummary: AGENTS.md / CLAUDE.md linter & skill lint companion — Agent runtime config audit (not a project wiki). Dual-file dedup + .agents/skills/ routing.\nlicense: MIT\nhomepage: https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill\nversion: 1.3.2\ndescription: >\n  会勇禾口王的AI笔记 · Agent 运行时配置体检器。检查项目的 AGENTS.md（跨 Agent 推荐）\n  或 CLAUDE.md（及子目录本地配置）是否符合\"把它当运行时配置、不是项目说明书\"的最佳实践，\n  给出评分卡 + 按优先级的修复建议，并可代为修复。触发：用户说「检查我的 CLAUDE.md /\n  AGENTS.md / 运行时配置体检 / claude-md-doctor / agents.md 规范吗 / audit CLAUDE.md /\n  lint AGENTS.md / 看看我的 agent 配置合不合规」。\n  任何\"评估/审查/优化某个项目 AGENTS.md 或 CLAUDE.md 质量\"的请求都应触发。\nallowed-tools:\n  - Bash\n  - Read\n  - Write\n  - Edit\n  - Glob\n  - Grep\n  - AskUserQuestion\n---\n\n# hekouwang-claude-md-doctor-skill · Agent 运行时配置体检器\n\n> **会勇禾口王的AI笔记** 出品 · `@huiyonghkw`\n> GitHub: <https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill>\n> _不聊 AI 会不会取代你，只聊先用 AI 的人怎么取代你。_\n\n把\"Agent 运行时配置最佳实践\"做成一个能跑在任何项目上的检查器：机检定量 + 模型定性，\n产出评分卡和可落地的修复建议。核心判据一句话——\n\n> **AGENTS.md / CLAUDE.md 是每次会话都被重新加载、要付上下文费的\"运行时配置\"，不是给人读的项目说明书。**\n> 2026 年起 Cursor / Codex / OpenClaw 等多读 **AGENTS.md**；Claude Code 仍读 **CLAUDE.md**。\n> 一切检查项都从这句推导：值不值得每次会话都为这段内容付一次费？\n\n### 减法优先（元判据 · 凌驾全部检查项之上）\n\nClaude Code 之父 Boris Cherny 公开说自己的配置\"surprisingly vanilla\"、几乎不定制；\n联合创造者 Cat Wu 自称 \"context minimalist\"——只告诉模型它需要知道的，剩下让它自己想。\n**核心立场：模型每代都在变强，你今天费劲搭的脚手架很快白搭；别跟模型较劲做加法。**\n\n所以下面这些检查项里凡是\"让用户往里加内容\"的(禁止清单/Hook/记忆/人格/本地文件)，\n落地前都先过这一关 —— **加任何一段前先问：这条能不能不写在常驻正文里？**\n\n- 能挂 **Hook**(确定性规则)→ 挂 Hook，别写正文(模型不必每次读)。\n- 能下沉 **docs/** 的 → 下沉，正文留一行指针。\n- 能靠 **linter / 类型检查 / 测试**兜住的 → 删掉，别让模型干 linter 的活。\n- 通用写法 / 主流框架用法 → 删掉，那是模型已经会的(见 #10)。\n- **只有\"模型会反复犯错、且没有机械手段能兜住\"的，才值得占常驻 token。**\n\n机检层面：**#1 篇幅 / #3 可操作 / #4 路由器 / #10 别替模型补**这几项是减法核心，权重更高；\n\"加内容\"类项(#6/#7/#8)缺失只算小扣分，避免工具一边喊\"越短越好\"、一边逼用户把文件写长。\n\n## 品牌人设（体检报告的口吻 + 署名）\n\n这套工具属于 **会勇禾口王的AI笔记**（定位：AI 实战拆解，硬核·具体·可复制；人设：你办公室里第一个把 AI 用明白的同事）。出体检报告时：\n\n- **口吻**：像同事帮你看代码——直给结论、敢泼冷水（\"这条是空话，5 秒判不了就是不合格\"），不说\"Great question / 我很乐意帮忙\"这类客套。\n- **价值化**：修复建议讲\"省了什么\"（少几十次会话的冗余、挡住一次资损/越权），不堆术语。\n- **署名**：报告结尾固定带一行品牌签收 —— `—— 会勇禾口王的AI笔记 · @huiyonghkw`，并可附 slogan。命令行 `check.py` 的报告页脚已内置该署名。\n- **去 AI 味**：定稿前避开\"赋能/打造/至关重要/助力\"等词，说人话。\n\n---\n\n## 免费 / 付费边界（重要）\n\n- **免费（开源内核）**：`check.py` 的**文本 / JSON 报告 + 评分**。任何人本地或 Docker 跑、进 CI，随便用。\n- **付费（增值）**：**品牌可视化体检报告卡**（评分弧 + 等级带 + 九项明细的精美分享图）。\n  它依赖 `hekouwang-content-factory` 的**私有品牌字体与版式**，不随本仓库分发。\n\n**触发\"出图 / 报告卡 / 图表 / 可视化\"时怎么办**：\n1. 先照常给**免费文本报告**（机检 + 定性复核）。\n2. 是否生成图：检查本机有没有 `hekouwang-content-factory`（品牌字体在\n   `~/.claude/skills/hekouwang-content-factory/assets/fonts/`）。\n   - **有**（作者本人环境）：可按 V2 米白生成报告卡 PNG。\n   - **没有**（外部用户）：明确说明可视化报告是**付费增值项**，引导联系 **@huiyonghkw** 获取，\n     不要用系统字体凑一张劣化图糊弄。\n3. 一句话口径：**跑检查免费，出\"好看的报告图\"找我。**\n\n---\n\n## 与内置 `/doctor` 命令的分工（名字像，别混用）\n\nClaude Code 内置了一个 `/doctor` 命令，名字也带 \"doctor\"，但**体检对象和本 skill 完全不同**——\n一个查整套工具的运行环境，一个只查一份文档写得好不好。别把两者当同一个东西。\n\n| 维度 | 内置 `/doctor` 命令 | 本 skill（claude-md-doctor） |\n|-"},{"path":"README.md","content":"# hekouwang-claude-md-doctor-skill\n\n**简体中文** · [English](README.en.md)\n\n[![CI](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n![Python](https://img.shields.io/badge/python-3.x-blue.svg)\n![dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)\n![open source](https://img.shields.io/badge/open%20source-free-success.svg)\n\n> **会勇禾口王的AI笔记** 出品 · `@huiyonghkw`\n> _不聊 AI 会不会取代你，只聊先用 AI 的人怎么取代你。_\n\nCLAUDE.md / AGENTS.md 体检器 —— 检查任意项目的运行时配置是否符合\"**路由器、不是图书馆**\"，\n给出评分卡 + 修复建议。\n\n## 30 秒验收\n\n```bash\npython3 check.py .                    # 体检当前项目（零依赖）\nbash scripts/run-all-doctors.sh .     # 三件套：md + skill + env\n```\n\n<p align=\"center\">\n  <img src=\"examples/demo.gif\" width=\"720\" alt=\"hekouwang-claude-md-doctor-skill 体检演示\">\n  <br><sub>↑ 一句「检查我的 CLAUDE.md」/ <code>python3 check.py</code>，秒出评分 + 修复建议（免费 CLI）</sub>\n</p>\n\n一句话判据：**CLAUDE.md 每次会话都被重新加载、要付上下文费。值不值得每次会话都为这段内容付一次费？**\n\n<p align=\"center\">\n  <img src=\"examples/report-card.gif\" width=\"420\" alt=\"CLAUDE.md 体检报告卡（动效示例）\">\n  <br><sub>↑ 品牌可视化报告卡（<b>付费增值</b>示例）——评分弧随分数填充、等级 D→A 变色。免费版输出文本/JSON 报告。</sub>\n</p>\n\n## 为什么需要它\n\n很多人把 CLAUDE.md 写成\"项目说明书\"：塞进历史、技术决策、营销叙事，动辄上千行。\n结果模型在冗长上下文里迷失，还挤掉了真正理解代码的空间。这个工具把 10 条可检查的\n最佳实践固化下来，让任何人一键体检自己的项目。\n\n核心立场是 Claude Code 之父 Boris Cherny / Cat Wu 的 **context minimalism —— 别跟模型较劲做加法**：\n模型每代都在变强，你今天费劲搭的脚手架很快白搭。所以评分按\"减法优先\"加权，\n\"越短越准\"类核心项权重更高，\"加内容\"类项缺了不重罚。\n\n## 10 项检查\n\n1. 篇幅 ≤ 200 行（路由器不是图书馆）\n2. 禁止清单（Do NOT introduce）\n3. 规则可操作（非\"写干净代码\"式空话）\n4. 路由器不是图书馆（大块下沉 docs/ 留指针）\n5. 高危模块有本地 CLAUDE.md（碰钱/认证/迁移）\n6. 关键规则有 Hook 强制（不靠模型记忆）\n7. 跨会话记忆回路（MEMORY.md）\n8. 工作风格块（你是谁 / 你讨厌什么 · 限 3–5 行）\n9. 30 秒三问（产品 / 技术栈 / 新代码放哪）\n10. 别替模型补它已经会的（无\"如何使用 X / 教程\"式随模型升级即过时的冗余）\n\n## 用法\n\n### 在 Claude Code 里（推荐）\n直接说：「**检查我的 CLAUDE.md**」「**CLAUDE.md 体检**」——会自动跑机检 +\n模型定性复核，给出评分和按优先级的修复建议，并可代为修复。\n\n### 命令行直接跑（零依赖，仅需 Python 3）\n```bash\npython3 check.py [项目目录]          # 默认当前目录，输出彩色报告\npython3 check.py [项目目录] --json   # 机器可读 JSON（CI 可用）\n```\n退出码：有 FAIL → 1，否则 0（可用于 CI 卡关）。\n\n### Docker（不想装 Python 也能跑）\n```bash\n# 拉官方镜像直接用（打 tag 时 GitHub Actions 自动发布到 GHCR）\ndocker run --rm -v \"$PWD:/work\" ghcr.io/huiyonghkw/hekouwang-claude-md-doctor-skill\n\n# 或本地自建\ndocker build -t claude-md-doctor .\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor            # 体检当前项目\ndocker run --rm -v \"$PWD:/work\" claude-md-doctor /work --json\n```\n\n### 接进 CI 卡关（GitHub Actions 示例）\n```yaml\n- uses: actions/setup-python@v5\n  with: { python-version: \"3.x\" }\n- name: CLAUDE.md 体检（不合格则拦 PR）\n  run: |\n    curl -sO https://raw.githubusercontent.com/huiyonghkw/hekouwang-claude-md-doctor-skill/main/check.py\n    python3 check.py .\n```\n本仓库自身的 CI 见 [`.github/workflows/ci.yml`](.github/workflows/ci.yml)（语法 + good/bad 夹具 + JSON 合法性）。\n\n## 这不是内置的 `/doctor` 命令\n\nClaude Code 自带一个 `/doctor` 命令，名字也带 \"doctor\"，但**体检对象和本工具完全不同**——\n一个查整套工具的运行环境，一个只查一份文档写得好不好。别搞混。\n\n| 维度 "},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn73qd1gcmjr446mwcbdxef70x82vxcw\",\n  \"slug\": \"hekouwang-claude-md-doctor-skill\",\n  \"version\": \"1.3.2\",\n  \"publishedAt\": 1786534620249\n}"},{"path":"references/doctor-suite.md","content":"# hekouwang-doctor-suite · 体检器三件套\n\n> 竞品多是单点；这套把「项目配置 → 技能包 → 本机环境」串成一条验收链。\n\n```\nhekouwang-doctor-suite（概念）\n├── md-doctor      → AGENTS.md / CLAUDE.md（运行时配置）\n├── skill-doctor   → SKILL.md（Agent 技能包）\n└── env-doctor     → 磁盘 / 版本管理器 / AI 宿主目录\n```\n\n## 一键跑\n\n```bash\nbash scripts/run-all-doctors.sh /path/to/your-project\n```\n\n（脚本在 `hekouwang-claude-md-doctor-skill`；`skill-doctor` / `env-doctor` 仓内各有一份相同副本。）\n\n## 建议顺序\n\n1. **md-doctor** — 根配置是否「路由器」而非「图书馆」\n2. **skill-doctor** — `.agents/skills/` 下各 skill 是否按需加载\n3. **env-doctor** — 本机是否留着已换掉的 nvm / 膨胀的 AI 缓存\n\n## 免费 vs 付费\n\n| | 免费（开源） | 付费增值 |\n|---|---|---|\n| 机检 | `check.py` / `scan.sh` 文本报告 + JSON | 品牌可视化报告卡（评分弧 + 等级带） |\n| CI | 退出码卡关 | — |\n| 联系 | GitHub Issue / PR | ClawHub **@huiyonghkw** |"},{"path":"CHANGELOG.md","content":"# Changelog\n\n本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。\n\n## [1.3.2] - 2026-08-12\n\n### 变更\n- ClawHub 分类：`development`\n\n## [1.3.1] - 2026-08-12\n\n### 新增\n- `scripts/run-all-doctors.sh`：hekouwang-doctor-suite 三件套一键体检\n- `references/doctor-suite.md`：套件说明与免费/付费对照\n\n### 变更\n- `check.py`：无 `HEKOUWANG_CONTENT_FACTORY` 时提示付费报告卡 CTA\n- README：30 秒验收 + 三件套互链；summary 补英文 SEO 关键词\n\n## [1.3.0] - 2026-08-12\n\n### 新增\n- **`check.py` 支持 AGENTS.md**：根目录优先体检 `AGENTS.md`，其次 `CLAUDE.md` / `CLAUDE.local.md`；\n  子目录扫描同时认两份本地配置。\n- **#0b 双文件去重**：根目录 `AGENTS.md` + `CLAUDE.md` 同时存在且都不是薄指针 → WARN（双倍上下文费）。\n- **#4c Skill 路由**：正文应把细则指针到 `.agents/skills/`（或 `.cursor/skills/`），别堆在常驻正文。\n- 报告标题改为 **AGENT CONFIG DOCTOR**；JSON 输出增加 `root_configs` 字段。\n\n### 文档\n- `SKILL.md` 触发词补 `AGENTS.md` / `agents.md` / `运行时配置体检`；评分表扩至 12 项。\n- 新增测试夹具 `tests/fixtures/good-agents/`、`tests/fixtures/dual/`。\n\n## [1.2.2] - 2026-07-09\n\n### 文档\n- **新增「与内置 `/doctor` 命令的分工」小节**：两者名字都带 doctor 但体检对象完全不同——\n  内置 `/doctor` 查整套 Claude Code 运行环境（安装/未用扩展/上下文膨胀/权限/版本），\n  本 skill 只查一份 CLAUDE.md 的写法质量。给出对比表 + 唯一交集（`/doctor` Check 2/3 碰 CLAUDE.md\n  但只从上下文成本看、不评质量）+ 用法建议（先 `/doctor` 发现文档偏大，再用本 skill 深度评 + 重构）。\n- **README.md / README.en.md 同步**：两份 README 也各补一节「这不是内置的 `/doctor` 命令」\n  （精简对比表 + 唯一交集 + 组合用法），中英一致。\n\n## [1.2.1] - 2026-06-22\n\n自体检（用姊妹工具 skill-doctor 跑）后的两处打磨：\n\n### 优化\n- **SKILL.md 声明 `allowed-tools`**：收敛到本 skill 真正需要的工具集，减小越权面。\n- **补「本 skill 自检会触发 #10 误报」豁免说明**：正文里的\"教程/如何使用/step by step\"是\n  待检测的黑名单词本身（评分表/盲区/修复清单都要举例），机检会误报教学冗余——\n  与 skill-doctor 对齐，注明定性时直接放行，别删那些词（删了体检器就不工作）。\n\n## [1.2.0] - 2026-06-21\n\n对照社区教程 `luongnv89/claude-howto` 的 Memory 最佳实践逐条比对后，补上三个真空白\n（只取它的\"安全 + 机制正确性\"，不取它\"把文件写全\"的加法倾向）。\n\n### 新增\n- **安全红线检查「无硬编码密钥」(#0)**：扫正文里的 `sk-`/`AKIA`/`AIza`/`gh*_`/`xox*`/\n  JWT / 私钥块 / `password=`/`secret=` 等指纹，命中即 **FAIL**（权重 1.5、资损级）。\n  报告对命中值脱敏（前 4 位 + 长度）。占位/示例值（`<your-pwd>`/`${VAR}`/`example` 等）自动豁免。\n  补齐教程头号 Don't \"Never store secrets in CLAUDE.md\"——此前脚本只防自己读 .env，\n  却不查被体检文件本身是否藏密钥。\n- **指针死链检查 (#4b)**：`docs/` 文本指针与原生 `@import` 路径都校验目标文件是否存在，\n  死链 → WARN（指向不存在的文件比没指针更糟）。\n\n### 变更\n- **#4 路由器检查认原生 `@import` 语法**：此前只认纯文本 `docs/...`，用官方 `@path` 导入\n  反而不给\"下沉指针\"加分；现在两种写法都算合格指针。\n\n### 文档 / 测试\n- `SKILL.md` 评分表补 #0 与 #4b，加权说明与修复动作清单同步（拔密钥 + 轮换提醒、修死链）。\n- good 夹具补 `docs/architecture.md`、`docs/api.md` 桩文件，示范\"指针均可解析\"。\n\n## [1.1.0] - 2026-06-18\n\n把 Claude Code 之父 Boris Cherny / Cat Wu 的\"context minimalism · 别跟模型较劲做加法\"\n立场接进体检逻辑。\n\n### 新增\n- **第 10 项检查「别替模型补它已经会的」**：扫教学型措辞(如何使用 / 使用教程 /\n  step by step / how to use)，命中即 WARN——这类通用写法随模型升级自动变强，\n  写进常驻正文只是为\"很快过时的东西\"每次付上下文费。\n- **「减法优先」元判据**：写进 `SKILL.md`，凌驾 9 项之上——加任何一段前先问\n  \"能不能不写在常驻正文里\"。\n\n### 变更\n- **评分改为按重要度加权**：减法核心项(#1 篇幅 / #3 可操作 / #4 路由器 / #10)权重 1.5，\n  加内容项(#6 Hook / #7 记忆 / #8 人格)降到 0.6。修掉旧逻辑\"一边喊越短越好、\n  一边因缺工作风格块扣分、逼用户把文件写长\"的自相矛盾。\n- **#8 工作风格块加上限护栏**：限 3–5 行，每行须对应一个\"不写就会犯的具体错\"，别写性格小作文。\n\n### 文档\n- `README` / `README.en` 同步「10 项检查」并写明「减法优先 · 别跟模型较劲做加法」立场。\n- `SKILL.md` 顶部署名补 GitHub 仓库地址\n  （<https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill>），方便 skillhub 溯源。\n\n## [1.0.0] - 2026-06-1"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1130,"uniquenessScore":41,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T13:59:24.371Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T13:59:24.371Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T17:46:46.528Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}