claude-md

/claude-md -- 审查并改进 CLAUDE.md 文件

命名例外（有据可查）： skillforge 的检查清单禁止在技能名称中使用 claude 或 anthropic。本技能是一个有意设置的例外：它针对的是名为 CLAUDE.md 的具体文件，因此精确的名称本身就是其价值所在。请将此视为该库中唯一的此类例外。

两种模式，一个技能。审查会查找多个 CLAUDE.md 文件中的问题（规范性）。改进会依据最佳实践标准重写单个文件（结构性）。两者都基于同一项核心原则。

核心原则

可移除性测试：“对于 CLAUDE.md 中的每一行，都问自己——如果删掉这一行，Claude 会犯错吗？ 如果不会，就删掉它。” — Anthropic，Claude Code 最佳实践

这是统一规则。审查模式会将未通过测试的内容标记为偏离、冗余或重复。改进模式会建议删除这些内容。同一诊断，不同规模。

另一项不变原则适用于两种模式：CLAUDE.md 会纳入 git 跟踪，且每个打开仓库的 Agent 都能看到它。 粘贴进去的密钥会造成持久泄露。两种模式都会将密钥泄露检测视为 P0 级问题。

模式分派

调用方式	模式	执行内容
/claude-md（无参数，且项目中有 ./CLAUDE.md）	自动 → 改进	改进本地 CLAUDE.md
/claude-md（无参数，且没有本地文件）	自动 → 审查	扫描项目根目录（例如 ~/Projects）下的所有 CLAUDE.md 文件
/claude-md improve [path]	改进	重写单个文件的结构（10 条规则的评估标准）
/claude-md audit [project|all|path]	审查	规范性扫描：密钥 P0、偏离、重复、预算

如果两种模式都适用（例如，在没有 CLAUDE.md 的文件夹中运行 /claude-md improve），技能会请求澄清。

同样适用于 AGENTS.md（V2）

AGENTS.md 是跨 Agent 标准（Linux Foundation / Agentic AI Foundation 制定；Codex、Cursor、Gemini、Copilot 及 30 多种工具都会读取）。这里的所有内容——评估标准、密钥扫描、偏离检测和预算——同样适用于 AGENTS.md。两者同时存在时，应同时审查并标记重复内容：正确的做法是使用单一事实来源（AGENTS.md），并让 CLAUDE.md 作为精简的别名/@import，而不是让两个文件逐渐偏离。对仓库中作用范围最近的 AGENTS.md（在单体仓库中可能存在嵌套）也应同样处理。

---

改进模式

依据 Anthropic 官方最佳实践和经社区验证的指导，评估单个 CLAUDE.md，然后提出具体的重写差异。仅在用户批准后应用。

一项实证注意事项（特指 Claude Code）。 当目标文件较短（少于 100 行）且已符合 Karpathy 风格的规则时，添加更多规则可能会降低 Claude Code 的质量。Augment Code 于 2026 年 4 月在 40 个 OpenClaw PR 上，对 Auggie、Claude Code 和 Codex 测试了 Karpathy 规则：三者的速度和成本均有所改善（耗时和工具调用次数降低 3% 至 8%），但 Claude Code 的整体质量下降了 0.07（正确性下降 0.07，完整性下降 0.06，代码复用率下降 0.05）。Auggie 和 Codex 表现稳定。他们的假设是：Claude Code 的系统提示词已经包含了类似约束；进一步叠加会减少探索。当评估标准给 Claude Code 的目标文件打出 9/10 或 10/10 分时，默认建议是精简，而不是添加。

评估标准

十项检查，每项都有主要来源佐证。每条建议都会注明所依据的规则。

#	规则	来源
R1	长度少于 200 行。 内容越长，遵循度越低。	Anthropic — Claude 如何记住你的项目
R2	逐行进行可删除性测试。	Anthropic — Claude Code 最佳实践
R3	明确具体：指令必须具体到可验证。 不要写“要像资深工程师一样”。	Anthropic — 记忆文档
R4	突出关键规则。 使用 IMPORTANT: / YOU MUST / NEVER。谨慎使用——如果每条规则都标为 IMPORTANT，就没有规则显得重要了。	Anthropic — 最佳实践
R5	使用 Markdown 结构：标题 + 项目符号。 不要写成密集的段落。	Anthropic — 记忆文档
R6	包含 5 个规范章节（命令、架构、规则、工作流、不适用范围）。	社区共识 + Anthropic /init 模板
R7	硬性规则章节不超过 15 项。 超过后，规则的约束力会下降。	社区（zodchiii 讨论串，130 万次浏览）
R8	正确使用 3 层级结构。 跨文件：全局规则放在 ~/.claude/CLAUDE.md，项目规则放在 ./CLAUDE.md（纳入 git），个人规则放在 ./CLAUDE.local.md（加入 gitignore）。各层级之间不得重复。单个文件内部：按优先级排序——最上方放不可妥协的硬性规则，中间放依赖上下文的规则，底部放参考信息和便利内容。指令预算会优先压缩低优先级条目。	Anthropic — 最佳实践；Fraser（Medium，2026 年 5 月）
R9	当指令仅适用于特定文件时，在 .claude/rules/*.md 中使用路径范围规则。	Anthropic — 高级模式 PDF
R10	不包含自动记忆会捕获的内容，也不记录标准工具文档。 不要浪费篇幅介绍 Claude 能从 package.json 中判断出的技术栈细节，也不要介绍 Claude 已经了解的标准工具（git、gh、npm、pnpm、bun、cargo、python、node、tsc、eslint、prettier、make）。只记录自定义封装工具或项目特有且不明显的调用方式。	社区 + Anthropic 自动记忆文档；Fraser（Medium，2026 年 5 月）

改进模式流程

阶段 I-1：确定范围

1. 确定目标文件。如果有多个候选文件，请列出并询问。
2. 完整阅读文件。记录大小（行数、字符数）。
3. 阅读同级文件，检查不同层级之间是否存在重复内容：
   • ~/.claude/CLAUDE.md（改进项目文件时）
   • ./CLAUDE.local.md（如果存在）
   • ./.claude/rules/*.md（是否正在使用路径范围规则？）

阶段 I-2：评估

尽可能通过程序运行 10 条规则的检查：

LINES=$(wc -l < "$TARGET")                                   # R1
grep -c -iE 'IMPORTANT|YOU MUST|NEVER' "$TARGET"             # R4
grep -c '^#' "$TARGET"                                       # R5
# R10: cross-reference against package.json / pyproject.toml / Cargo.toml / etc.

按规则逐项生成评分表，并提供具体到行的依据。

阶段 I-3：提出方案

分为三类变更：

删除（不符合 R2 或 R10 的行）：

- DELETE line N: "[content]"
  Reason: [R2 — would Claude actually make a mistake without this?]
  OR: [R10 — auto memory captures this from package.json]

新增（根据 R6 补充缺失的规范章节）：

+ ADD section "## [Section Name]" with:
  [proposed content based on actual project — read package.json, README, .git/config]

改写（提高明确性，符合 R3；突出重点，符合 R4）：

~ REPLACE line N: "[vague content]"
  WITH: "[concrete, verifiable rewrite]"
  Reason: [R3: was vague | R4: high-impact rule needs IMPORTANT prefix]

阶段 I-4：展示

## CLAUDE.md Improvement Proposal

**File:** [path]
**Current size:** N lines (R1 budget: 200)
**Rubric pass rate:** M of 10

### Summary
- DELETE: K lines
- ADD: L sections
- REWRITE: J lines
- Net change: ±N lines (final: M lines)

### Proposed Diff
[full diff with reasons]

Apply these changes? (yes / partial / no)

阶段 I-5：应用

使用 Edit 工具进行精确修改——切勿用 Write 覆盖整个文件。每次只应用一项变更。完成所有变更后：

1. 重新评估：输出新的文件大小和新的规则通过率。
2. 建议：“随后运行 /claude-md audit，确认没有引入偏差。”
3. 如果文件中现在包含明显适用于特定路径的子章节，建议将其拆分到 .claude/rules/<topic>.md（R9）。

5 个规范章节（R6 详情）

R6 评分较高的 CLAUDE.md 包含以下章节。建议补上缺失的章节：

1. ## Project（1–2 行：项目是什么、面向哪些用户）
2. ## Stack（1–3 行：框架、语言、部署目标）
3. ## Commands（构建 / 开发 / 单项测试 / 全部测试 / Lint / 类型检查——简短、准确）
4. ## Architecture（文件夹 → 用途映射；不必列出完整目录）
5. ## Rules（少于 15 条；禁止性规则也计入；突出最关键的一条）
6. ## Workflow（用户希望 Claude 如何处理任务：尽量少改动、询问还是直接执行、提交约定）
7. ## Out of scope（Claude 不应触碰的文件 / 集成）

能产生叠加效应的高影响规则

如果文件确实缺少范围控制或安全规则，可以从以下规则中挑选。**但须遵守上文的精简而非增加原则：**对于已经符合要求、评分为 9–10/10 的 Claude Code 目标，不要批量添加这些规则——Claude Code 的系统提示词已经包含其中大部分，层层叠加会降低质量（Augment Code，2026 年 4 月）。只添加一两条能弥补实际观察到的问题的规则，其余跳过。

范围与安全（杠杆最高——防止代价高昂且难以撤销的错误）：

• 只修改与当前任务直接相关的文件、函数和代码行。不要重构、重命名或重新格式化我未要求修改的内容。把其他问题记在最后，不要动它们。
• 在对现有内容进行重大改动之前（重写章节、调整结构、更改语气），先停下来说明你准备改什么以及原因，然后等待确认。
• 删除文件、覆盖代码、丢弃记录或移除依赖之前，先停下来列出受影响的内容，并在当前消息中请求明确确认。“你之前提过这件事”不算确认。
• 生产环境操作必须暂停并在当前会话中获得确认：部署 / 推送、迁移或架构变更、对外 API 调用，以及任何具有不可逆副作用的命令。（如果必须确保暂停规则 100% 生效，真正的保障方式是使用 PreToolUse hook——CLAUDE.md 的遵循率上限约为 80%。）
• 每项编码任务完成后，结尾都要列出：已修改的文件、每个文件的一句话摘要、有意未触碰的文件、需要跟进的事项。
• 绝不要提交 .env 文件或密钥
• 未经明确确认，绝不要运行 git push --force

工作流：

• 重要：每次代码更改后都要运行类型检查
• 尽量少做改动，不要重构无关代码
• 每项逻辑改动分别提交，不要合成一个巨大的提交
• 如果两个方案难以取舍，解释各自的优缺点，让我选择
• 对于架构决策或复杂功能，先逐步分析问题，再编写代码。说明推理过程和不确定之处，然后再实现。

沟通（对 Claude Code 的边际价值最低——其系统提示词已经处理了大部分内容；只有观察到具体问题时才添加）：

• 回答长度应与任务复杂度相匹配。不要重复问题内容或用总结凑篇幅。
• 如果不确定某个事实、统计数据、日期或技术细节，请明确说明，而不是用听起来合理的内容填补空白。

这些措辞源自 Karpathy 派生规则汇编（Fraser，2026 年 5 月；“Dep”讨论串，2026 年 5 月）。其中标榜的统计数据（“准确率从 65% 提升至 94%”、每位开发者节省的金额、星标数量）只是营销示例，并非实测结果——引用时应引用规则措辞，而不是这些数字。

不要包含的内容（反模式）

• 个性化指令（“做一名资深工程师”）
• 代码检查工具已处理的代码格式化规则
• 在不同层级重复出现的规则
• 使用 @-imports 导入完整 README／大型文档（它们会在启动时进入上下文窗口）
• Claude 通过自动记忆自行学会的任何内容
• （V2）自动生成的大量内容。 切勿执行 /init 后就不管，也不要粘贴由 LLM 生成的上下文文件。对照研究：精心整理的上下文文件能让任务质量提高约 4 个百分点，令 token 开销增加约 20%；但自动生成的上下文文件会让任务成功率降低约 0.5–2%，同时令成本增加 20–23%。务必严格筛选；更多上下文不代表更好。（arXiv 2026，AGENTS.md 效率研究。）

---

审计模式

检查并审计所有项目中的 CLAUDE.md 文件。标记内容偏差（声称的事实与代码不再相符）、泄露的机密、重复区块、描述性与指令性内容的比例，以及接近 150-200 条指令上限的文件。

CLAUDE.md 文件会逐渐过时。实际审计多个项目时，通常会发现若干项目的 CLAUDE.md 存在内容偏差，有时还会发现泄露机密的情况。此模式会在一次检查中同时捕获这两类问题。

审计模式流程

阶段 A-1：发现

1. 找出项目根目录下的所有 CLAUDE.md（根据代码存放位置调整，例如 ~/Projects、~/work）：

   find ~/Projects ~/work -name 'CLAUDE.md' \
     -not -path '*/node_modules/*' -not -path '*/.venv/*' -not -path '*/vendor/*' 2>/dev/null
   

2. 对于每个文件，记录其所属项目和大小（行数）。

阶段 A-2：机密扫描（始终先运行）

对于每个 CLAUDE.md，使用 grep 搜索高置信度的机密模式。此阶段必须在其他审计之前运行，因为机密泄露属于 P0 级问题，会中断后续流程。

需要标记的模式：

• (?i)(secret|token|api[_-]?key|password)\s*[:=]\s*['"]\S{8,}['"]
• (?i)auth[_-]?secret\s*[:=]\s*\S{8,}
• 类似 Base64 的 JWT 前缀：eyJ[A-Za-z0-9_-]{10,}
• 内嵌凭据的 URL：https?://[^:/\s]+:[^@\s]+@
• Stripe/OpenAI/Anthropic 密钥前缀：sk_live_、sk_test_、pk_live_、sk-ant-、sk-proj-
• Supabase/Neon 连接字符串：postgres(ql)?://[^:]+:[^@]+@

**如果匹配到任何内容：**将文件标记为 🔴 P0 泄露。报告行号、匹配的模式，以及必要的补救措施：在源系统中轮换机密、编辑 CLAUDE.md 仅引用环境变量名称、清理 git 历史（git filter-repo --path CLAUDE.md --invert-paths 或 BFG）。

阶段 A-3：偏差检测

对于 CLAUDE.md 中的每项陈述，都要对照实际代码进行验证：

1. MCP 服务 — 与 settings.json / .mcp.json / mcp.json 对比
2. API 路由 — 搜索 CLAUDE.md 中提到的路由；确认它们都存在于 src/app/api/ 或路由文件中
3. 定时任务 — 对比声明的数量与实际的 */cron* 文件、vercel.json 中的 crons、wrangler.toml 中的触发器
4. 环境变量 — 每个提到的环境变量都应出现在 .env.example 中，或被代码读取（process.env.<NAME> / os.environ["<NAME>"]）
5. 外部服务 — 标记矛盾（例如“使用 Brevo SMTP”，但代码导入的是 @getbrevo/brevo REST 客户端）
6. 目录结构 — 将列出的目录与 ls 输出对比

对于每项偏差，报告 CLAUDE.md 中的行号、实际代码事实，以及能修正问题的一行编辑。

阶段 A-4：重复项与结构检查

1. 检测重复的章节标题（^## 、^### 出现 ≥2 次）
2. 检测近似重复的段落（不同的两行以相同的前 60 个字符开头）
3. 报告文件中与其他行相矛盾的任何行

阶段 A-5：指令预算 + 规范性比例

1. 统计指令——任何以祈使动词开头的行（Always、Never、Use、Don't、Prefer、Avoid、Run、Check、Write、Edit、Follow），或「Rules/Conventions/Do/Don't」标题下项目符号列表中的内容
2. 预算阈值：
   • ≤ 100 条指令：🟢 健康
   • 100–200 条：🟡 需监控

   • 200 条：🟠 超出预算——建议拆分或删减

3. 描述性与规范性分类器：
   • 描述性 = 描述代码当前呈现的内容（「这是一个使用 Postgres 的 Next.js 应用」）
   • 规范性 = 告诉 Claude 要做什么（「编辑迁移文件时，同时添加 up 和 down」） 报告比例。描述性内容会浪费预算。

阶段 A-5.5：HOOK 候选检测

CLAUDE.md 中的指令仅供参考——社区证据显示遵从率约为 70–80%。绝对命令式规则会悄无声息地受到这一上限的限制。扫描听起来具有确定性的规则，并标记可转换为 hook 的规则。

需要标记的模式：

• 以 NEVER、Never、Always、MUST、Do not 后接动词开头的行
• 指定破坏性命令的规则：rm -rf、git push --force、git reset --hard、DROP TABLE、truncate、vercel --prod、gcloud ... delete
• 要求提交前检查必须 100% 通过的规则：lint、typecheck、test 必须在提交前通过

对于每个匹配项：报告对应行，将其分类为 hook-candidate，并指出合适的 hook 类型：

• 破坏性命令门禁 → 返回退出代码 2 以阻止操作的 PreToolUse hook
• 提交前验证 → 针对 git commit 的 PreToolUse，或针对文件 Edit/Write 的 PostToolUse
• 编辑后始终运行的检查 → PostToolUse hook

报告措辞：「这条规则读起来像是确定性的，但实际上属于建议范畴。将其转换为 .claude/settings.json 中的 hook，以实现 100% 强制执行；保留 CLAUDE.md 中的这行作为 hook 意图的说明，或将其删除。」引用 Anthropic hooks 文档 和约 80% 的建议遵从率上限。

阶段 A-6：报告

按严重程度分组，逐个项目输出：

# CLAUDE.md Audit Report — <timestamp>

## Summary
- 6 CLAUDE.md files scanned
- 1 P0 LEAK (acme-web)
- 2 projects with drift (data-pipeline, saas-app)
- 0 over budget
- 3 projects clean

---

## acme-web 🔴 P0 LEAK
**File:** ~/Projects/acme-web/CLAUDE.md (142 instructions)

### Leaks (P0 — rotate before any other work)
- Line 38: `AUTH_SECRET=...` (value redacted in report)
  - Fix: replace with `The AUTH_SECRET env var is required; see .env.example`
  - Rotate the secret in production, then `git filter-repo --path CLAUDE.md --invert-paths`

### Drift
- Line 52: claims "Brevo SMTP" — code uses REST (`@getbrevo/brevo` at src/lib/email.ts:4)
  - Fix: change to "Brevo REST API via @getbrevo/brevo"

### Duplicates
- "## Email" heading appears at lines 50 and 89

阶段 A-7：提供修复（交互式）

报告之后询问：「应用针对 建议的编辑吗？[y/N]」。仅在获得确认后应用。不要自动应用 P0 LEAK 修复——这些修复需要轮换密钥并清理 Git 历史，必须由用户执行。

---

质量标准（两种模式均适用）

只有所有检查都通过，运行结果才算合格。否则重写不合格的建议。

• 每个删除项／偏差发现都要注明其执行的规则（improve 模式中的 R1–R10；audit 模式中的具体偏差类型）
• 每项新增内容都必须使用项目的真实数据（读取 package.json、pyproject.toml 等），不能使用通用占位符
• 每项改写都必须提供具体替换内容，不能只说「让表述更清楚」
• 建议中不得使用「考虑」「也许」「你可以考虑」——每条建议都必须具体，且可接受或拒绝
• 摘要必须包含精确数量，不能是估算值
• P0 LEAK 发现必须始终出现在 audit 模式的其他内容之前

注意事项（两种模式均适用）

• 不要自动应用。 始终先提交审批。仅进行精准编辑，绝不整文件写入。
• 不要臆造项目背景。 阅读 package.json / pyproject.toml / Cargo.toml / Gemfile / README.md，确保建议以实际项目数据为依据。
• 不要自动建议拆分到 .claude/rules/。 可以提出建议，由用户决定。
• 不要轮换密钥或清理 git 历史。 审计负责报告泄漏并提供指引；由用户负责轮换密钥和清理历史。
• 不要在各个代码仓库中强行推行特定风格。 尊重每个代码仓库现有的表达风格。改进模式重写的是结构，而非风格。
• 不要标记完全没问题的行。 未通过可移除性测试的行确实必须未通过，不能只是“或许还能更精简”。
• 不要在错误首次出现时就添加规则。 将其记录在 MEMORY.md 或临时清单中。错误第二次出现后，才将其提升到 CLAUDE.md。这样可以提高信噪比，减少那些会让文件臃肿、却无法避免实际错误的规则。（来源：Redreamality，2026 年 4 月。）
• 不要硬编码用户路径。 使用 $TARGET、$HOME、$1。绝不要使用 /Users/<name>/...。

更新日志

V2（2026-05-27）

通过 skillforge optimize 优化（基于 AI 原生代码仓库 / AGENTS.md 最佳实践的结果研究）。

• 支持 AGENTS.md — 审计 / 改进跨 Agent 通用标准，而不只是 CLAUDE.md；标记 CLAUDE.md / AGENTS.md 中的重复内容，并建议采用单一事实来源。
• 基于对照研究证据，加入“绝不自动生成”反模式（精心编写的内容效果提升 +4 个百分点，而自动生成内容效果下降 0.5–2%，成本增加 20–23%）。进一步强化现有的精简而非添加原则。
• 目标成效：该技能现在会改进那些真正能跨不同运行环境改变 Agent 行为的文件，并主动防止降低其效果的臃肿内容。来源：AGENTS.md 效率研究（arXiv 2026）；agents.md 标准；Augment Code AGENTS.md 指南。

相关技能

技能	适用场景
/claude-md improve	单个文件，按最佳实践进行结构性重写
/claude-md audit	多个文件，检查整洁度 / 偏差 / 密钥泄漏
/init（Anthropic 内置）	根据当前项目状态生成初始 CLAUDE.md
compound-engineering:ce-compound-refresh	理念相同，目标不同 — 刷新 docs/solutions/

参考资料

Anthropic 一手资料：

• Claude 如何记住你的项目
• Claude Code 最佳实践
• Anthropic 团队如何使用 Claude Code（PDF）
• Claude Code 高级模式（PDF）

社区资料（与一手资料一致）：

• HumanLayer — 编写优秀的 CLAUDE.md
• zodchiii — 让我的输出提升 10 倍的 CLAUDE.md 文件（130 万次浏览）
• abhishekray07/claude-md-templates
• Augment Code — OpenClaw 上的 Karpathy 技能（2026 年 4 月） — 实证反例：在已经对齐的系统提示词之上叠加 Karpathy 规则后，Claude Code 的质量下降了 −0.07。
• Fraser — 将 Claude Code 工作流提升 10 倍的 Claude.md 设置技巧（Medium，2026 年 5 月） — Karpathy 的 4 条规则加上 8 项补充内容，包括避免 CLI 冗余和在文件内设定优先级顺序。
• “Dep”（@0xdepressionn）— Karpathy CLAUDE.md 规则汇编（X，2026 年 5 月） — 病毒式传播的 14 条规则（7 条沟通规则 + 7 条行为/安全规则），扩展了 Karpathy 的 4 项行为准则；其中的高影响力语句已纳入上方菜单。⚠️ 标题中的数据（82k 星标、准确率从 65% 提升到 94%、每周费用数据）是没有来源的营销说法——规则措辞有价值，数字则不可引用。
• Redreamality — CLAUDE.md 和 AGENTS.md 深入解析（2026 年 4 月） — 二次出现时的晋升规则；关于建议内容上限约为 80% 的综合分析。

相关原则：

• Strunk 与 White — 风格要素 — 第 17 条规则（“删去不必要的词语”）是 Anthropic 可移除性测试背后的根本原则

测试

运行结构评估：

bash tests/eval.sh

端到端验证行为：

1. 改进：在任意项目中运行 /claude-md improve — 验证评分表列出 R1–R10 的每一项，每处更改均注明对应规则，“否”的回复不会写入任何内容，“是”的回复会精准应用更改
2. 审核：运行 /claude-md audit all — 验证存在泄漏时，P0 LEAK 部分会首先出现；偏差发现会引用具体代码位置；按文件报告指令预算
3. 自动检测：在包含 CLAUDE.md 的项目中运行 /claude-md（不带参数）→ 运行 improve；在没有本地文件的 ~/ 中运行 → 运行 audit
4. 模式覆盖：/claude-md audit ./CLAUDE.md → 单文件审核（audit 的子集，仅针对单个目标）