Back to Details

claude-md-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CLAUDE.md Management

CLAUDE.md 文件管理

Provides comprehensive CLAUDE.md file management capabilities including auditing, quality assessment, and targeted improvements. This skill ensures Claude Code has optimal project context by maintaining high-quality documentation files.
提供全面的CLAUDE.md文件管理能力，包括审计、质量评估和针对性改进。该技能通过维护高质量的文档文件，确保Claude Code拥有最佳的项目上下文。

Overview

概述

CLAUDE.md files are the primary mechanism for providing project-specific context to Claude Code sessions. This skill manages the complete lifecycle of CLAUDE.md files: discovery, quality assessment, reporting, and improvement. It follows a 5-phase workflow that ensures documentation is current, actionable, and concise.
The skill evaluates CLAUDE.md files against standardized quality criteria across 6 dimensions: Commands/Workflows, Architecture Clarity, Non-Obvious Patterns, Conciseness, Currency, and Actionability. Each file receives a score (0-100) and letter grade (A-F) with specific improvement recommendations.
CLAUDE.md文件是为Claude Code会话提供项目特定上下文的主要机制。该技能管理CLAUDE.md文件的完整生命周期：发现、质量评估、报告和改进。它遵循一个5阶段工作流，确保文档是最新的、可操作的且简洁的。
该技能从6个维度根据标准化质量准则评估CLAUDE.md文件：命令/工作流、架构清晰度、非显而易见的模式、简洁性、时效性和可操作性。每个文件都会获得一个分数（0-100）和等级（A-F），以及具体的改进建议。

When to Use

使用场景

Use this skill when:
  • User explicitly asks to "check", "audit", "update", "improve", "fix", or "maintain" CLAUDE.md
  • User mentions "CLAUDE.md quality", "documentation review", or "project memory optimization"
  • CLAUDE.md needs to be created from scratch for a new project
  • User asks about improving Claude's understanding of the codebase
  • Documentation has become stale or outdated
  • Starting work on a new codebase and need to understand existing documentation
  • User presses 
    #
    during a session to incorporate learnings into CLAUDE.md
Trigger phrases: "audit CLAUDE.md", "check documentation quality", "improve project context", "review CLAUDE.md", "validate documentation"
在以下场景中使用该技能：
  • 用户明确要求“检查”、“审计”、“更新”、“改进”、“修复”或“维护”CLAUDE.md
  • 用户提到“CLAUDE.md质量”、“文档评审”或“项目内存优化”
  • 需要为新项目从头创建CLAUDE.md
  • 用户询问如何提升Claude对代码库的理解
  • 文档已过时
  • 开始处理新代码库，需要了解现有文档
  • 用户在会话中按下
    #
    键，将所学内容整合到CLAUDE.md中
触发短语：“audit CLAUDE.md”、“检查文档质量”、“改进项目上下文”、“评审CLAUDE.md”、“验证文档”

Instructions

使用说明

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
查找仓库中的所有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
单体仓库中的模块级上下文
子目录任何嵌套位置功能/领域特定上下文

Phase 2: Quality Assessment

阶段2：质量评估

For each CLAUDE.md file, read references/quality-criteria.md and evaluate against these criteria:
CriterionWeightWhat to Check
Commands/workflows20 ptsAre build/test/deploy commands present and working?
Architecture clarity20 ptsCan Claude understand the codebase structure?
Non-obvious patterns15 ptsAre gotchas and quirks documented?
Conciseness15 ptsIs content dense without filler?
Currency15 ptsDoes it reflect current codebase state?
Actionability15 ptsAre instructions executable and copy-paste ready?
Quality Scores: A (90-100), B (70-89), C (50-69), D (30-49), F (0-29)
对于每个CLAUDE.md文件，阅读references/quality-criteria.md并根据以下准则进行评估：
评估准则权重检查内容
命令/工作流20分是否包含可用的构建/测试/部署命令？
架构清晰度20分Claude能否理解代码库结构？
非显而易见的模式15分是否记录了陷阱和特殊用法？
简洁性15分内容是否精炼无冗余？
时效性15分是否反映了代码库的当前状态？
可操作性15分说明是否可直接执行、复制粘贴即可使用？
质量等级： A（90-100）、B（70-89）、C（50-69）、D（30-49）、F（0-29）

Phase 3: Quality Report Output

阶段3：输出质量报告

CRITICAL: Always output the quality report BEFORE making any updates.
Format:
markdown
undefined
重要提示：在进行任何更新之前，务必先输出质量报告。
格式：
markdown
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]
undefined
分数：XX/100（等级：X）
评估准则分数备注
命令/工作流X/20...
架构清晰度X/20...
非显而易见的模式X/15...
简洁性X/15...
时效性X/15...
可操作性X/15...
问题：
  • [列出具体问题]
建议添加内容：
  • [列出应添加的内容]
undefined

Phase 4: Targeted Updates

阶段4：针对性更新

After report output, ask user for confirmation before updating.
Read references/update-guidelines.md for detailed update principles.
Key principles:
  1. Propose targeted additions only - commands, gotchas, patterns, configs
  2. Keep it minimal - avoid obvious info, generic advice, one-off fixes
  3. Show diffs - file, change (diff format), explanation
Diff format:
markdown
undefined
输出报告后，在更新前需征得用户确认。
详细更新原则请阅读references/update-guidelines.md。
核心原则：
  1. 仅建议针对性添加内容 - 命令、陷阱、模式、配置
  2. 保持精简 - 避免明显信息、通用建议、一次性修复
  3. 展示差异 - 文件、变更（diff格式）、说明
差异格式：
markdown
undefined

Update: ./CLAUDE.md

更新：./CLAUDE.md

Why: [Brief explanation of why this helps]
diff
+ ## Quick Start
+
+ ```bash
+ npm install
+ npm run dev
+ ```
undefined
原因：[简要说明此更新的作用]
diff
+ ## 快速开始
+
+ ```bash
+ npm install
+ npm run dev
+ ```
undefined

Phase 5: Apply Updates

阶段5：应用更新

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

Examples

示例

Example 1: Quality Assessment

示例1：质量评估

User request: "Check if my CLAUDE.md is good"
Response:
markdown
undefined
用户请求：“检查我的CLAUDE.md是否合格”
回复：
markdown
undefined

CLAUDE.md Quality Report

CLAUDE.md 质量报告

Summary

摘要

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

File-by-File Assessment

逐个文件评估

1. ./CLAUDE.md

1. ./CLAUDE.md

Score: 65/100 (Grade: C)
CriterionScoreNotes
Commands/workflows10/20Only npm install documented
Architecture clarity15/20Basic tree, missing module relationships
Non-obvious patterns5/15No gotchas documented
Conciseness15/15Concise and dense
Currency10/15Some outdated paths
Actionability10/15Some vague instructions
Issues:
  • Missing test command
  • Missing build command
  • No documentation of auth flow complexity
  • References to old src/structure
Recommended additions:
  • Add Commands section with test/build
  • Document auth module gotcha
  • Update architecture paths
undefined
分数：65/100（等级：C）
评估准则分数备注
命令/工作流10/20仅记录了npm install命令
架构清晰度15/20有基础目录树，缺少模块关系说明
非显而易见的模式5/15未记录任何陷阱
简洁性15/15内容精炼
时效性10/15部分路径已过时
可操作性10/15部分说明模糊
问题：
  • 缺少测试命令
  • 缺少构建命令
  • 未记录认证流程的复杂性
  • 引用了旧的src/结构
建议添加内容：
  • 添加包含测试/构建命令的“命令”章节
  • 记录认证模块的陷阱
  • 更新架构路径
undefined

Example 2: Creating from Scratch

示例2：从头创建

User request: "Create a CLAUDE.md for this React project"
Response:
markdown
I'll create a CLAUDE.md for your React project. Let me first analyze the codebase structure.

[Scans package.json, src/, and key config files]
用户请求：“为这个React项目创建一个CLAUDE.md”
回复：
markdown
我将为你的React项目创建CLAUDE.md。首先让我分析代码库结构。

[扫描package.json、src/和关键配置文件]

CLAUDE.md Quality Report

CLAUDE.md 质量报告

Summary

摘要

  • Files found: 0
  • Creating new CLAUDE.md at project root
  • 找到的文件数量：0
  • 将在项目根目录创建新的CLAUDE.md

Proposed CLAUDE.md Content:

拟创建的CLAUDE.md内容：

Project Name

项目名称

Commands

命令

CommandDescription
npm install
Install dependencies
npm run dev
Start dev server (Vite on port 5173)
npm run build
Production build
npm run test
Run Vitest tests
npm run lint
ESLint check
命令描述
npm install
安装依赖
npm run dev
启动开发服务器（Vite，端口5173）
npm run build
生产构建
npm run test
运行Vitest测试
npm run lint
ESLint检查

Architecture

架构

src/
├── components/    # Reusable UI components
├── pages/         # Route pages
├── hooks/         # Custom React hooks
├── lib/           # Utilities and API clients
└── main.tsx       # Entry point
src/
├── components/    # 可复用UI组件
├── pages/         # 路由页面
├── hooks/         # 自定义React hooks
├── lib/           # 工具类和API客户端
└── main.tsx       # 入口文件

Gotchas

注意事项

  • Vite requires files in 
    public/
    for static assets
  • State updates in 
    useEffect
    need proper dependency arrays

Shall I create this file?
  • Vite要求静态资源放在
    public/
    目录下
  • useEffect
    中的状态更新需要正确的依赖数组

是否创建此文件？

Example 3: Update Proposal

示例3：更新建议

User request: "Update my CLAUDE.md with what you learned"
Response:
markdown
undefined
用户请求：“将你学到的内容更新到我的CLAUDE.md中”
回复：
markdown
undefined

Update: ./CLAUDE.md

更新：./CLAUDE.md

Why: Discovered that tests require database setup which wasn't documented.
diff
undefined
**原因：**发现测试需要数据库设置，但文档中未记录。
diff
undefined

Testing

测试

  • Prerequisites: Start test database first with 
    docker-compose up -d test-db
  • npm run test
    - Run all tests
  • npm run test:unit
    - Unit tests only (no DB required)

Also found issue with API_BASE_URL:

```diff
  • **前置条件：**先使用
    docker-compose up -d test-db
    启动测试数据库
  • npm run test
    - 运行所有测试
  • npm run test:unit
    - 仅运行单元测试（无需数据库）

还发现API_BASE_URL的问题：

```diff

Environment

环境变量

  • API_BASE_URL
    - API endpoint (default: localhost:3000)

Apply these changes?
  • API_BASE_URL
    - API端点（默认值：localhost:3000）

是否应用这些变更？

Best Practices

最佳实践

  1. Always read references before acting: Quality criteria, templates, and update guidelines contain essential details
  2. Report before editing: Never modify CLAUDE.md without first presenting a quality report
  3. Preserve existing structure: When updating, maintain the existing organization and style
  4. Be project-specific: Only add information specific to this codebase, not generic advice
  5. Verify commands work: Before suggesting commands, mentally or actually verify they execute correctly
  6. Use progressive disclosure: Keep SKILL.md lean, reference detailed rubrics in separate files
  7. Score consistently: Apply the same scoring standards across all files for fair comparison
  1. 行动前务必阅读参考文档：质量准则、模板和更新指南包含关键细节
  2. 先报告再编辑：在修改CLAUDE.md之前，务必先提交质量报告
  3. 保留现有结构：更新时，保持现有的组织方式和风格
  4. 贴合项目实际：仅添加与当前代码库相关的信息，不添加通用建议
  5. 验证命令可用性：建议命令前，先确认其可正确执行
  6. 逐步披露信息：保持SKILL.md简洁，详细规则放在单独文件中
  7. 评分一致：对所有文件应用相同的评分标准，确保公平比较

Constraints and Warnings

约束与警告

  1. Never modify without approval: Always get user confirmation before editing CLAUDE.md files
  2. Don't remove content without asking: If suggesting deletions, explicitly mark them and get approval
  3. Respect 
    .claude.local.md
    : These are personal settings; never suggest modifying them in shared docs
  4. Avoid generic advice: Do not add "write good code" type content - focus on project-specific patterns
  5. Keep diffs concise: Show only the actual changes, not entire file contents
  6. Verify file paths: Ensure all referenced files exist before documenting them
  7. Score objectively: Use the rubric consistently; don't inflate scores for incomplete documentation
  1. 未经批准不得修改：编辑CLAUDE.md文件前务必获得用户确认
  2. 删除内容需询问：若建议删除内容，需明确标记并获得批准
  3. 尊重
    .claude.local.md
    ：这些是个人设置；切勿在共享文档中建议修改它们
  4. 避免通用建议：不要添加“编写优质代码”这类内容 - 专注于项目特定模式
  5. 保持差异内容简洁：仅展示实际变更，不展示整个文件内容
  6. 验证文件路径：记录前确保所有引用的文件存在
  7. 客观评分：一致使用评估标准；不为不完整的文档提高分数