Back to Details

memory-md-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Memory.md Management

Memory.md 管理

Provides comprehensive project memory file management capabilities including auditing, quality assessment, and targeted improvements. This skill ensures the coding agent has optimal project context by maintaining high-quality documentation files such as 
CLAUDE.md
.
提供全面的项目记忆文件管理能力，包括审计、质量评估和针对性优化。该Skill通过维护
CLAUDE.md
等高质文档文件，确保编码Agent拥有最优的项目上下文。

Overview

概述

Project memory files such as 
CLAUDE.md
are the primary mechanism for providing project-specific context to coding agent sessions. This skill manages their complete lifecycle: 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
这类项目记忆文件是为编码Agent会话提供项目专属上下文的核心机制。该Skill管理其完整生命周期：发现、质量评估、报告输出和优化，遵循5阶段工作流确保文档内容时效性强、可落地、简洁明了。
该Skill会依据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"
  • A project memory file 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 a memory file
Trigger phrases: "audit CLAUDE.md", "check documentation quality", "improve project context", "review CLAUDE.md", "validate documentation"
当出现以下情况时使用该Skill：
  • 用户明确要求「检查」、「审计」、「更新」、「改进」、「修复」或「维护」CLAUDE.md
  • 用户提到「CLAUDE.md质量」、「文档评审」或「项目记忆优化」
  • 需要为新项目从零创建项目记忆文件
  • 用户询问如何提升Claude对代码库的理解
  • 文档已经陈旧或过时
  • 开始开发新代码库，需要理解现有文档
  • 用户在会话中按下
    #
    需要将学习到的内容整合到记忆文件中
触发短语：「audit CLAUDE.md」、「检查文档质量」、「优化项目上下文」、「review 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
monorepo中模块级上下文
子目录配置任意嵌套位置功能/领域专属上下文

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格式）、变更说明
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
用户请求：「Check if my CLAUDE.md is good」
响应：
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]
用户请求：「Create a CLAUDE.md for this React project」
响应：
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
用户请求：「Update my CLAUDE.md with what you learned」
响应：
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. 保持diff精简：仅展示实际变更内容，不要展示完整文件内容
  6. 验证文件路径：记录文件路径前先确认对应文件真实存在
  7. 评分客观：严格遵循评分规则，不要给不完整的文档虚高评分