claude-md-manager

CLAUDE.md 管理器

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

核心工作流

1. 确定模式

创建新的 CLAUDE.md：

• 分析项目结构、技术栈和惯例
• 使用 WHAT/WHY/HOW 框架生成重点明确的文档
• 目标控制在 100 行以内（最多 300 行）

刷新现有 CLAUDE.md：

• 审查当前内容是否冗长、过时或存在反模式
• 找出应外置的指令
• 优化内容，使其简洁且切题

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

检查：

• package.json、Cargo.toml、pyproject.toml 等，了解技术栈
• 目录结构，了解架构模式
• 现有 README.md，了解项目背景
• .github/、Makefile、脚本，了解工作流
• 测试目录，了解测试惯例

3. 应用 WHAT/WHY/HOW 框架

WHAT — 技术现状：

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

WHY — 背景和目的：

• 项目的功能
• 某些模式存在的原因
• 各目录的功能用途

HOW — 实际工作流：

• 构建命令（包括包管理器相关命令）
• 测试执行
• 开发工作流
• 部署流程

4. 验证审查

创建或刷新 CLAUDE.md 后，使用 OSGrep 对照实际代码库验证其中的说法。这样可以发现过时的命令、错误的路径和已发生变化的惯例。

验证步骤

1. 验证命令

# 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. 验证目录结构

# 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. 验证 @import 引用

# Check each @path/to/file reference exists
test -f $REPO/docs/architecture.md && echo "EXISTS" || echo "MISSING"

4. 验证惯例

# Verify conventions match actual code patterns
osgrep "error handling patterns" -p $REPO -m 5
osgrep "state management approach" -p $REPO -m 5

验证报告格式

## Validation Report
- [x] `pnpm dev` - Verified in package.json scripts
- [x] `/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/

使用 /review 深入验证（可选）

对于大型代码库或季度审查，可运行多 Agent 审查：

/compounding-engineering:workflows:review CLAUDE.md

这会调用 architecture-strategist 和 pattern-recognition-specialist Agent，全面核实结构说明和惯例的准确性。

简洁性规则

上下文预算： Claude 的上下文窗口由多方共享。CLAUDE.md 中的每一行都会与对话历史和系统提示词争用上下文空间。大模型通常能稳定遵循约 150–200 条指令；系统提示词本身已占用约 50 条。

目标：

• 理想：少于 60 行（如 HumanLayer 的生产环境文件）
• 良好：少于 100 行
• 上限：300 行（超过则重构）

技巧：

• 使用 file:line 引用，而不是复制代码
• 将特定任务的文档外置到 agent_docs/
• 删除 Claude 能从代码中推断出的内容
• 删除显而易见的指令（Claude 会读取代码模式）

渐进式披露模式

当 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 中引用：

# Detailed Guides
- Building: @agent_docs/building.md
- Testing: @agent_docs/testing.md
- Architecture: @agent_docs/architecture.md

Claude 只会在相关时加载这些文件。

超越 agent_docs/

还有三种渐进式披露机制可与 agent_docs/ 配合使用：

• .claude/rules/*.md — 带有 YAML frontmatter paths: glob 的路径范围模块化指令。当匹配文件位于上下文中时才会按需加载。适用于仅针对特定文件路径的指令。完整规则参考见 references/memory-hierarchy.md。
• 技能（.claude/skills/）— 仅在部分情况下相关的领域知识。CLAUDE.md 会在每次会话中加载；技能则按需加载，在未激活时不占用上下文。
• 自定义子 Agent（.claude/agents/*.md）— 特定 Agent 的指令应放在 Agent 定义中，而不是 CLAUDE.md 中。Agent 文件支持工具限制和模型选择。

文件导入语法

CLAUDE.md 支持 @path/to/file 导入：

• @README.md — 从项目根目录导入
• @docs/guide.md — 从子目录导入
• @~/.claude/personal.md — 个人偏好（不提交到版本库）
• 支持递归导入，最多 5 层
• 代码块中的导入不会被处理
• 导入文件应以 ## 标题级别开始，以避免与主 CLAUDE.md 的层级冲突

应避免的反模式

避免以下模式：

1. 通过 LLM 进行代码检查 — CLAUDE.md 中的说明仅供参考（Agent 可能会在上下文压力下忽略它们）。如需确保执行，请使用钩子：

   # WRONG - Don't add to CLAUDE.md:
   "Always run eslint before committing"
   
   # RIGHT - Use a hook instead (deterministic, runs every time)
   

2. 自动生成 CLAUDE.md — /init 生成的结果并不理想。请手动编写。

3. 详尽的风格指南 — Claude 会从现有代码模式中学习。

4. 在根文件中编写特定任务的说明 — 请改用 agent_docs/。

5. 内联代码片段 — 请使用 file:line 引用，确保内容保持最新。

6. 机密或凭据 — 应将 CLAUDE.md 视为公开内容。

7. 只有否定约束 — 只有禁止事项（“绝不执行 X”）而没有替代方案，会让 Agent 陷入困境。每条“绝不执行 X”都应以“— 改为执行 Y”结尾。

8. 没有说明的文件引用 — 不带说明的 @path 导入会被忽略。应为每个导入说明其用途：解释何时、为何阅读（例如，@agent_docs/testing.md — 测试约定和覆盖率阈值。编写或修改测试时阅读。）。

模板结构

# Project Name

Brief description of what this project does.

## Stack
- [Framework] with [Key libraries]
- [Database/Storage]
- [Key tooling]

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

## Commands
- Dev: `npm run dev`
- Test: `npm test`
- Build: `npm run build`

## Conventions
- [Critical convention 1]
- [Critical convention 2]

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

## Architecture Notes
@docs/architecture.md (if complex)

审核清单（用于更新）

审核现有 CLAUDE.md 时：

• 少于 100 行？若不是，请找出可提取的内容
• 使用 file:line 引用，而非内联代码？
• 特定任务的文档是否位于 agent_docs/ 中？
• 未包含代码检查或风格规范（改用钩子）？
• 不含凭据或机密？
• 不含明显或可推断出的说明？
• 所有命令都能正常运行？
• 架构信息仍准确？
• 是否已运行 OSGrep 验证？（命令、目录、约定）
• 文件引用仍有效？
• 否定说明是否配有替代方案？
• 文件导入是否附有说明（解释何时、为何阅读）？
• 特定路径的说明是否位于 .claude/rules/，而非根目录的 CLAUDE.md 中？

全局注册

创建或更新项目的 CLAUDE.md 时，请确保项目已登记在 ~/.claude/agent_docs/active-projects.md 中，并注明其目录和当前计划。

分层文件

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

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

每个文件都应简洁，并与其适用范围相匹配。

资源

• references/best-practices.md - 深入了解提升效果的模式
• references/memory-hierarchy.md - 说明的放置位置、.claude/rules/、CLAUDE.local.md
• references/templates.md - 特定项目类型的模板（9 种变体）
• scripts/analyze_project.py - 自动分析项目结构