claude-md-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CLAUDE.md Manager

CLAUDE.md 管理器

Create and maintain effective CLAUDE.md files that configure Claude Code's behavior for your project.

创建并维护可有效配置Claude Code项目行为的CLAUDE.md文件。

Core Workflow

核心工作流程

1. Determine the Mode

1. 确定模式

Creating new CLAUDE.md:

Analyze project structure, tech stack, and conventions
Generate focused documentation using WHAT/WHY/HOW framework
Target under 100 lines (max 300)

Refreshing existing CLAUDE.md:

Audit current content for bloat, staleness, and anti-patterns
Identify instructions that should be externalized
Optimize for conciseness and relevance

创建新的CLAUDE.md：

分析项目结构、技术栈和约定
使用WHAT/WHY/HOW框架生成针对性文档
目标行数控制在100行以内（最多300行）

更新现有CLAUDE.md：

审核当前内容的冗余、过时问题和反模式
识别应外部化的说明内容
优化内容的简洁性和相关性

2. Project Analysis (for new files)

2. 项目分析（针对新文件）

Examine:

```
package.json
```
,
```
Cargo.toml
```
,
```
pyproject.toml
```
, etc. for stack
Directory structure for architecture patterns
Existing README.md for project context
```
.github/
```
,
```
Makefile
```
, scripts for workflows
Test directories for testing conventions

检查以下内容：

```
package.json
```
、
```
Cargo.toml
```
、
```
pyproject.toml
```
等文件以了解技术栈
目录结构以识别架构模式
现有README.md以获取项目背景
```
.github/
```
、
```
Makefile
```
、脚本文件以了解工作流程
测试目录以熟悉测试约定

3. Apply the WHAT/WHY/HOW Framework

3. 应用WHAT/WHY/HOW框架

WHAT - Technical reality:

Tech stack and key dependencies
Directory structure and architecture
Key files and entry points

WHY - Context and purpose:

What the project does
Why certain patterns exist
Functional purpose of directories

HOW - Practical workflows:

Build commands (package manager specifics)
Test execution
Development workflow
Deployment process

WHAT - 技术现状：

技术栈和关键依赖
目录结构与架构
关键文件和入口点

WHY - 背景与目的：

项目的功能定位
特定模式存在的原因
各目录的功能用途

HOW - 实际工作流程：

构建命令（包管理器特定指令）
测试执行
开发工作流程
部署流程

4. Validation Review Pass

4. 验证评审环节

After creating or refreshing CLAUDE.md, validate claims against the actual codebase using OSGrep. This catches stale commands, incorrect paths, and drifted conventions.

创建或更新CLAUDE.md后，使用OSGrep根据实际代码库验证内容，以捕获过时命令、错误路径和偏离的约定。

Validation Steps

验证步骤

1. Validate Commands

bash

undefined

1. 验证命令

bash

undefined

For each command documented, verify it exists

osgrep "dev server startup configuration" -p $REPO -m 3 osgrep "test runner setup" -p $REPO -m 3 osgrep "build script configuration" -p $REPO -m 3


**2. Validate Directory Structure**
```bash

osgrep "dev server startup configuration" -p $REPO -m 3 osgrep "test runner setup" -p $REPO -m 3 osgrep "build script configuration" -p $REPO -m 3


**2. 验证目录结构**
```bash

Verify directories contain what's documented

osgrep "component definitions" -p $REPO/src/components -m 3 osgrep "API route handlers" -p $REPO/src/routes -m 3


**3. Validate @import References**
```bash

osgrep "component definitions" -p $REPO/src/components -m 3 osgrep "API route handlers" -p $REPO/src/routes -m 3


**3. 验证@import引用**
```bash

Check each @path/to/file reference exists

test -f $REPO/docs/architecture.md && echo "EXISTS" || echo "MISSING"


**4. Validate Conventions**
```bash

test -f $REPO/docs/architecture.md && echo "EXISTS" || echo "MISSING"


**4. 验证约定**
```bash

Verify conventions match actual code patterns

osgrep "error handling patterns" -p $REPO -m 5 osgrep "state management approach" -p $REPO -m 5

undefined

osgrep "error handling patterns" -p $REPO -m 5 osgrep "state management approach" -p $REPO -m 5

undefined

Validation Report Format

验证报告格式

markdown

undefined

markdown

undefined

Validation Report

```
pnpm dev
```
- Verified in package.json scripts
```
/src/components
```
- Contains 23 .tsx files
```
/src/services
```
- EMPTY - No files found
```
@agent_docs/testing.md
```
- MISSING
"No class components" - VIOLATION: Found 2 in /src/legacy/

undefined

```
pnpm dev
```
- Verified in package.json scripts
```
/src/components
```
- Contains 23 .tsx files
```
/src/services
```
- EMPTY - No files found
```
@agent_docs/testing.md
```
- MISSING
"No class components" - VIOLATION: Found 2 in /src/legacy/

undefined

Deep Validation with /review (Optional)

深度验证（可选，使用/review）

For large codebases or quarterly audits, run multi-agent review:

/compounding-engineering:workflows:review CLAUDE.md

This invokes architecture-strategist and pattern-recognition-specialist agents to thoroughly verify structure claims and convention accuracy.

对于大型代码库或季度审核，运行多代理评审：

/compounding-engineering:workflows:review CLAUDE.md

此命令会调用架构策略师和模式识别专家代理，全面验证结构声明和约定的准确性。

Conciseness Rules

简洁性规则

Critical constraint: Claude's context window is shared. Every line in CLAUDE.md competes with conversation history and system prompts. LLMs can follow ~150-200 instructions consistently; the system prompt already uses ~50.

Targets:

Ideal: Under 60 lines (like HumanLayer's production file)
Good: Under 100 lines
Maximum: 300 lines (refactor if exceeded)

Techniques:

Use
```
file:line
```
references instead of copying code
Externalize task-specific docs to
```
agent_docs/
```
Remove anything Claude can infer from code
Delete obvious instructions (Claude reads code patterns)

关键约束： Claude的上下文窗口是共享的。CLAUDE.md中的每一行都会与对话历史和系统提示竞争空间。LLM能稳定遵循约150-200条指令；而系统提示已占用约50条。

目标：

理想状态：60行以内（如HumanLayer的生产环境文件）
良好状态：100行以内
最大限制：300行（超出则需重构）

技巧：

使用
```
file:line
```
引用替代复制代码
将任务特定文档外部化到
```
agent_docs/
```
目录
删除Claude可从代码中推断的内容
删除显而易见的说明（Claude能识别代码模式）

Progressive Disclosure Pattern

渐进式披露模式

When CLAUDE.md grows beyond 100 lines, split into focused files:

agent_docs/
├── building.md          # Build process details
├── testing.md           # Test conventions and execution
├── code-conventions.md  # Style and patterns
├── architecture.md      # System design decisions
└── deployment.md        # Release process

Reference in CLAUDE.md:

markdown

undefined

当CLAUDE.md超过100行时，拆分到专注的文件中：

agent_docs/
├── building.md          # Build process details
├── testing.md           # Test conventions and execution
├── code-conventions.md  # Style and patterns
├── architecture.md      # System design decisions
└── deployment.md        # Release process

在CLAUDE.md中引用：

markdown

undefined

Detailed Guides

Building: @agent_docs/building.md
Testing: @agent_docs/testing.md
Architecture: @agent_docs/architecture.md


Claude loads these only when relevant.

Building: @agent_docs/building.md
Testing: @agent_docs/testing.md
Architecture: @agent_docs/architecture.md


Claude仅在相关场景下加载这些文件。

File Import Syntax

文件导入语法

CLAUDE.md supports

@path/to/file

imports:

```
@README.md
```
- Import from project root
```
@docs/guide.md
```
- Import from subdirectory
```
@~/.claude/personal.md
```
- Personal preferences (not committed)
Works recursively up to 5 levels
Not evaluated inside code blocks

CLAUDE.md支持

@path/to/file

导入：

```
@README.md
```
- 从项目根目录导入
```
@docs/guide.md
```
- 从子目录导入
```
@~/.claude/personal.md
```
- 个人偏好（无需提交）
支持最多5级递归导入
代码块内的导入不会被解析

Anti-Patterns to Avoid

需避免的反模式

Never do these:

Linting via LLM - Use hooks/pre-commit instead:

markdown

# WRONG - Don't add to CLAUDE.md:
"Always run eslint before committing"

# RIGHT - Use a hook instead

Auto-generated CLAUDE.md -
```
/init
```
produces suboptimal results. Craft manually.
Exhaustive style guides - Claude learns from existing code patterns.
Task-specific instructions in root file - Use agent_docs/ instead.
Inline code snippets - Use
```
file:line
```
references that stay current.
Secrets or credentials - CLAUDE.md should be treated as public.

绝对不要做这些：

通过LLM进行代码检查 - 改用钩子/预提交工具：

markdown

# WRONG - Don't add to CLAUDE.md:
"Always run eslint before committing"

# RIGHT - Use a hook instead

自动生成CLAUDE.md -
```
/init
```
命令生成的结果不够理想，建议手动编写。
详尽的风格指南 - Claude可从现有代码模式中学习。
在根文件中添加任务特定说明 - 改用agent_docs/目录。
内联代码片段 - 使用能保持时效性的
```
file:line
```
引用。
包含机密信息或凭证 - CLAUDE.md应被视为公开文件。

Template Structure

模板结构

markdown

undefined

markdown

undefined

Project Name

Brief description of what this project does.

Stack

[Framework] with [Key libraries]
[Database/Storage]
[Key tooling]

[Framework] with [Key libraries]
[Database/Storage]
[Key tooling]

Structure

```
/src
```
- Application code
```
/tests
```
- Test suites
```
/docs
```
- Documentation

```
/src
```
- Application code
```
/tests
```
- Test suites
```
/docs
```
- Documentation

Commands

Dev:
```
npm run dev
```
Test:
```
npm test
```
Build:
```
npm run build
```

Dev:
```
npm run dev
```
Test:
```
npm test
```
Build:
```
npm run build
```

Conventions

[Critical convention 1]
[Critical convention 2]

[Critical convention 1]
[Critical convention 2]

Workflow

Branch naming:
```
feature/description
```
Commits: Conventional Commits format
PR: Rebase before merge

Branch naming:
```
feature/description
```
Commits: Conventional Commits format
PR: Rebase before merge

Architecture Notes

@docs/architecture.md (if complex)

undefined

@docs/architecture.md (if complex)

undefined

Audit Checklist (for refresh)

审核清单（针对更新场景）

When reviewing existing CLAUDE.md:

Under 100 lines? If not, identify extraction candidates
Using
```
file:line
```
refs instead of inline code?
Task-specific docs in agent_docs/?
No linting/style enforcement (use hooks)?
No credentials or secrets?
No obvious/inferable instructions?
All commands actually work?
Architecture info still accurate?
OSGrep validation run? (commands, directories, conventions)
File references still valid?

评审现有CLAUDE.md时需检查：

行数是否在100行以内？若超出，识别可提取的内容
是否使用
```
file:line
```
引用替代内联代码？
任务特定文档是否存放在agent_docs/中？
是否未包含代码检查/风格强制内容（改用钩子）？
是否未包含凭证或机密信息？
是否删除了可推断的明显说明？
所有命令是否均可正常运行？
架构信息是否仍准确？
是否已运行OSGrep验证（命令、目录、约定）？
文件引用是否仍有效？

Global Registration

全局注册

When creating or refreshing a project CLAUDE.md, ensure the project has an entry in

~/.claude/agent_docs/active-projects.md

with its directory and active plan.

创建或更新项目的CLAUDE.md时，确保项目在

~/.claude/agent_docs/active-projects.md

中有条目，包含其目录和当前计划。

Hierarchical Files

分层文件结构

For monorepos, use CLAUDE.md at multiple levels:

/CLAUDE.md              # Repo-wide conventions
/frontend/CLAUDE.md     # Frontend-specific
/backend/CLAUDE.md      # Backend-specific
/services/auth/CLAUDE.md # Service-specific

Each file is concise and scope-appropriate.

对于单体仓库，可在多个层级使用CLAUDE.md：

/CLAUDE.md              # Repo-wide conventions
/frontend/CLAUDE.md     # Frontend-specific
/backend/CLAUDE.md      # Backend-specific
/services/auth/CLAUDE.md # Service-specific

每个文件需简洁且符合其适用范围。

Resources

资源

```
references/best-practices.md
```
- Deep dive on effectiveness patterns
```
references/templates.md
```
- Project-type-specific templates
```
scripts/analyze_project.py
```
- Automated project structure analysis

```
references/best-practices.md
```
- 关于高效模式的深度解析
```
references/templates.md
```
- 针对不同项目类型的模板
```
scripts/analyze_project.py
```
- 自动化项目结构分析脚本