Back to Details

claude-md-improver

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CLAUDE.md Improver

CLAUDE.md 改进工具

Audit, evaluate, and improve CLAUDE.md files across a codebase to ensure Claude Code has optimal project context.
This skill can write to CLAUDE.md files. After presenting a quality report and getting user approval, it updates CLAUDE.md files with targeted improvements.
审核、评估并改进代码库中的CLAUDE.md文件，确保Claude Code拥有最佳的项目上下文。
该技能可写入CLAUDE.md文件。 在展示质量报告并获得用户批准后，它会对CLAUDE.md文件进行针对性改进。

Workflow

工作流程

Phase 1: Discovery

阶段1：发现

Find all CLAUDE.md files in the repository:
bash
find . -name "CLAUDE.md" -o -name ".claude.md" -o -name ".claude.local.md" 2>/dev/null | head -50
File Types & Locations:
TypeLocationPurpose
Project root
./CLAUDE.md
Primary project context (checked into git, shared with team)
Local overrides
./.claude.local.md
Personal/local settings (gitignored, not shared)
Global defaults
~/.claude/CLAUDE.md
User-wide defaults across all projects
Package-specific
./packages/*/CLAUDE.md
Module-level context in monorepos
SubdirectoryAny nested locationFeature/domain-specific context
Note: Claude auto-discovers CLAUDE.md files in parent directories, making monorepo setups work automatically.
查找仓库中所有CLAUDE.md文件：
bash
find . -name "CLAUDE.md" -o -name ".claude.md" -o -name ".claude.local.md" 2>/dev/null | head -50
文件类型与位置：
类型位置用途
项目根目录
./CLAUDE.md
主要项目上下文（已提交至git，与团队共享）
本地覆盖配置
./.claude.local.md
个人/本地设置（已加入git忽略，不与团队共享）
全局默认配置
~/.claude/CLAUDE.md
所有项目通用的用户级默认配置
包特定配置
./packages/*/CLAUDE.md
单体仓库中的模块级上下文
子目录配置任意嵌套位置功能/领域特定的上下文
注意： Claude会自动发现父目录中的CLAUDE.md文件，因此单体仓库设置可自动生效。

Phase 2: Quality Assessment

阶段2：质量评估

For each CLAUDE.md file, evaluate against quality criteria. See references/quality-criteria.md for detailed rubrics.
Quick Assessment Checklist:
CriterionWeightCheck
Commands/workflows documentedHighAre build/test/deploy commands present?
Architecture clarityHighCan Claude understand the codebase structure?
Non-obvious patternsMediumAre gotchas and quirks documented?
ConcisenessMediumNo verbose explanations or obvious info?
CurrencyHighDoes it reflect current codebase state?
ActionabilityHighAre instructions executable, not vague?
Quality Scores:
  • A (90-100): Comprehensive, current, actionable
  • B (70-89): Good coverage, minor gaps
  • C (50-69): Basic info, missing key sections
  • D (30-49): Sparse or outdated
  • F (0-29): Missing or severely outdated
对每个CLAUDE.md文件，对照质量标准进行评估。详细评分标准请参考references/quality-criteria.md。
快速评估清单：
评估标准权重检查项
命令/工作流文档化高是否包含构建/测试/部署命令？
架构清晰度高Claude能否理解代码库结构？
非显而易见的模式中是否记录了陷阱和特殊情况？
简洁性中无冗长说明或显而易见的信息？
时效性高是否反映了代码库当前状态？
可执行性高说明是否可执行，而非模糊表述？
质量评分：
  • A（90-100分）：内容全面、与时俱进、可执行
  • B（70-89分）：覆盖良好，存在少量漏洞
  • C（50-69分）：仅包含基础信息，缺少关键部分
  • D（30-49分）：内容稀疏或过时
  • F（0-29分）：文件缺失或严重过时

Phase 3: Quality Report Output

阶段3：输出质量报告

ALWAYS output the quality report BEFORE making any updates.
Format:
undefined
在进行任何更新之前，务必先输出质量报告。
格式：
undefined

CLAUDE.md Quality Report

CLAUDE.md 质量报告

Summary

摘要

  • Files found: X
  • Average score: X/100
  • Files needing update: X
  • 找到的文件数量：X
  • 平均得分：X/100
  • 需要更新的文件数量：X

File-by-File Assessment

逐文件评估

1. ./CLAUDE.md (Project Root)

1. ./CLAUDE.md（项目根目录）

Score: XX/100 (Grade: X)
CriterionScoreNotes
Commands/workflowsX/20...
Architecture clarityX/20...
Non-obvious patternsX/15...
ConcisenessX/15...
CurrencyX/15...
ActionabilityX/15...
Issues:
  • [List specific problems]
Recommended additions:
  • [List what should be added]
得分：XX/100（等级：X）
评估标准得分备注
命令/工作流X/20...
架构清晰度X/20...
非显而易见的模式X/15...
简洁性X/15...
时效性X/15...
可执行性X/15...
问题：
  • [列出具体问题]
建议补充内容：
  • [列出应添加的内容]

2. ./packages/api/CLAUDE.md (Package-specific)

2. ./packages/api/CLAUDE.md（包特定配置）

...
undefined
...
undefined

Phase 4: Targeted Updates

阶段4：针对性更新

After outputting the quality report, ask user for confirmation before updating.
Update Guidelines (Critical):
  1. Propose targeted additions only - Focus on genuinely useful info:
    • Commands or workflows discovered during analysis
    • Gotchas or non-obvious patterns found in code
    • Package relationships that weren't clear
    • Testing approaches that work
    • Configuration quirks
  2. Keep it minimal - Avoid:
    • Restating what's obvious from the code
    • Generic best practices already covered
    • One-off fixes unlikely to recur
    • Verbose explanations when a one-liner suffices
  3. Show diffs - For each change, show:
    • Which CLAUDE.md file to update
    • The specific addition (as a diff or quoted block)
    • Brief explanation of why this helps future sessions
Diff Format:
markdown
undefined
输出质量报告后，请求用户确认再进行更新。
更新指南（至关重要）：
  1. 仅提出针对性补充内容 - 聚焦真正有用的信息：
    • 分析过程中发现的命令或工作流
    • 代码中存在的陷阱或非显而易见的模式
    • 不清晰的包依赖关系
    • 有效的测试方法
    • 配置特殊情况
  2. 保持内容精简 - 避免：
    • 重复代码中显而易见的内容
    • 已涵盖的通用最佳实践
    • 不太可能再次出现的一次性修复
    • 能用一句话说明却使用冗长解释
  3. 展示差异 - 每项更改需展示：
    • 要更新的CLAUDE.md文件
    • 具体补充内容（以差异或引用块形式）
    • 简要说明该更改对后续会话的帮助
差异格式：
markdown
undefined

Update: ./CLAUDE.md

更新：./CLAUDE.md

Why: Build command was missing, causing confusion about how to run the project.
diff
+ ## Quick Start
+
+ ```bash
+ npm install
+ npm run dev  # Start development server on port 3000
+ ```
undefined
原因： 缺少构建命令，导致对如何运行项目产生困惑。
diff
+ ## 快速开始
+
+ ```bash
+ npm install
+ npm run dev  # 在3000端口启动开发服务器
+ ```
undefined

Phase 5: Apply Updates

阶段5：应用更新

After user approval, apply changes using the Edit tool. Preserve existing content structure.
获得用户批准后，使用编辑工具应用更改。保留现有内容结构。

Templates

模板

See references/templates.md for CLAUDE.md templates by project type.
按项目类型划分的CLAUDE.md模板请参考references/templates.md。

Common Issues to Flag

需标记的常见问题

  1. Stale commands: Build commands that no longer work
  2. Missing dependencies: Required tools not mentioned
  3. Outdated architecture: File structure that's changed
  4. Missing environment setup: Required env vars or config
  5. Broken test commands: Test scripts that have changed
  6. Undocumented gotchas: Non-obvious patterns not captured
  1. 过时命令：不再有效的构建命令
  2. 缺失依赖：未提及的必要工具
  3. 过时架构：已更改的文件结构
  4. 缺失环境设置：必要的环境变量或配置
  5. 失效测试命令：已更改的测试脚本
  6. 未记录的陷阱：未捕获的非显而易见模式

User Tips to Share

可分享的用户提示

When presenting recommendations, remind users:
  • #
    key shortcut    : During a Claude session, press 
    #
    to have Claude auto-incorporate learnings into CLAUDE.md
  • Keep it concise: CLAUDE.md should be human-readable; dense is better than verbose
  • Actionable commands: All documented commands should be copy-paste ready
  • Use 
    .claude.local.md
    : For personal preferences not shared with team (add to 
    .gitignore
    )
  • Global defaults: Put user-wide preferences in 
    ~/.claude/CLAUDE.md
在提出建议时，提醒用户：
  • #
    快捷键    ：在Claude会话期间，按
    #
    可让Claude自动将会话中的学习内容整合到CLAUDE.md中
  • 保持简洁：CLAUDE.md应易于人类阅读，内容精炼优于冗长
  • 可执行命令：所有记录的命令应可直接复制粘贴使用
  • 使用 
    .claude.local.md
    ：用于存储不与团队共享的个人偏好设置（添加到
    .gitignore
    中）
  • 全局默认配置：将用户级通用偏好设置放在
    ~/.claude/CLAUDE.md
    中

What Makes a Great CLAUDE.md

优秀的CLAUDE.md具备哪些特质

Key principles:
  • Concise and human-readable
  • Actionable commands that can be copy-pasted
  • Project-specific patterns, not generic advice
  • Non-obvious gotchas and warnings
Recommended sections (use only what's relevant):
  • Commands (build, test, dev, lint)
  • Architecture (directory structure)
  • Key Files (entry points, config)
  • Code Style (project conventions)
  • Environment (required vars, setup)
  • Testing (commands, patterns)
  • Gotchas (quirks, common mistakes)
  • Workflow (when to do what)
核心原则：
  • 简洁易读
  • 可直接复制粘贴的可执行命令
  • 项目特定模式，而非通用建议
  • 非显而易见的陷阱和警告
推荐章节（仅使用相关内容）：
  • 命令（构建、测试、开发、代码检查）
  • 架构（目录结构）
  • 关键文件（入口点、配置）
  • 代码风格（项目约定）
  • 环境（必要变量、设置）
  • 测试（命令、模式）
  • 陷阱（特殊情况、常见错误）
  • 工作流（操作时机）