用途
claude-md-manager 用于创建和維護有效的 CLAUDE.md 文件，这些文件用于配置 Claude Code 的项目行为。它适用于两种模式：
- 创建新的 CLAUDE.md：分析项目结构、技术栈和约定，使用 WHAT/WHY/HOW 框架生成聚焦文档，目标控制在 100 行以内（最多 300 行）。
- 刷新已有 CLAUDE.md：审计当前内容是否存在臃肿、过时和反模式，识别应外部化的指令，并优化简洁性与相关性。
主要能力
项目分析（针对新文件）
检查以下内容：
- package.json、Cargo.toml、pyproject.toml 等以确定技术栈
- 目录结构以了解架构模式
- 现有 README.md 以获取项目背景
- .github/、Makefile、scripts 以了解工作流
- 测试目录以了解测试约定
WHAT/WHY/HOW 框架
- WHAT——技术现实：技术栈与关键依赖、目录结构与架构、关键文件与入口点。
- WHY——背景与目的：项目做什么、为什么存在某些模式、目录的功能用途。
- HOW——实践工作流：构建命令（包管理器相关）、测试执行、开发工作流、部署流程。
验证审查
创建或刷新 CLAUDE.md 后，使用 OSGrep 对照实际代码库验证其声明，捕获过时命令、错误路径和偏离的约定。验证步骤包括：验证命令、验证目录结构、验证 @import 引用、验证约定。验证报告格式示例：
## 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/
深度验证（可选）
对于大型代码库或季度审计，可运行多智能体审查：
/compounding-engineering:workflows:review CLAUDE.md
这会调用 architecture-strategist 和 pattern-recognition-specialist 智能体，彻底验证结构声明和约定准确性。
简洁性规则
上下文预算：Claude 的上下文窗口是共享的，CLAUDE.md 中的每一行都会与对话历史和系统提示竞争。LLM 可以持续遵循约 150-200 条指令，系统提示已占用约 50 条。
目标：
- 理想：60 行以内（如 HumanLayer 的生产文件）
- 良好：100 行以内
- 最大：300 行（超过则重构）
技巧：使用 file:line 引用而非复制代码；将任务特定文档外部化到 agent_docs/；移除 Claude 能从代码推断的内容；删除显而易见的指令。
渐进式披露模式
当 CLAUDE.md 超过 100 行时，拆分为聚焦文件：
agent_docs/
├── building.md # 构建过程细节
├── testing.md # 测试约定与执行
├── code-conventions.md # 风格与模式
├── architecture.md # 系统设计决策
└── deployment.md # 发布流程
在 CLAUDE.md 中引用：
# Detailed Guides
- Building: @agent_docs/building.md
- Testing: @agent_docs/testing.md
- Architecture: @agent_docs/architecture.md
Claude 仅在相关时加载这些文件。
除 agent_docs/ 外，还有三种补充机制：
.claude/rules/*.md——路径范围的模块化指令，带有 YAML frontmatter paths: globs，在匹配文件进入上下文时条件加载。- Skills（
.claude/skills/）——仅有时相关的领域知识，按需加载，未激活时零上下文成本。 - 自定义子智能体（
.claude/agents/*.md）——智能体特定指令应放在智能体定义中，而非 CLAUDE.md。智能体文件支持工具限制和模型选择。
文件导入语法
CLAUDE.md 支持 @path/to/file 导入：
@README.md——从项目根导入@docs/guide.md——从子目录导入@~/.claude/personal.md——个人偏好（不提交）- 递归工作最多 5 层
- 不在代码块内求值
- 导入文件应以 ## 标题级别开头，避免与主 CLAUDE.md 的层级冲突
需避免的反模式
- 通过 LLM 进行 lint——CLAUDE.md 指令是建议性的，应使用 hooks 保证执行。
- 自动生成的 CLAUDE.md——/init 产生的结果不理想，应手动编写。
- 详尽风格指南——Claude 从现有代码模式学习。
- 根文件中的任务特定指令——应使用 agent_docs/。
- 内联代码片段——应使用保持最新的 file:line 引用。
- 机密或凭证——CLAUDE.md 应视为公开。
- 仅否定约束——每个“never X”应结尾附带“— do Y instead”。
- 裸文件引用——没有上下文的裸 @path 导入会被忽略，应说明何时以及为何阅读。
模板结构
# 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/？
- 是否没有 lint/风格强制（应使用 hooks）？
- 是否没有凭证或机密？
- 是否没有显而易见/可推断的指令？
- 所有命令是否确实有效？
- 架构信息是否仍然准确？
- 是否运行了 OSGrep 验证（命令、目录、约定）？
- 文件引用是否仍然有效？
- 否定指令是否附带替代方案？
- 文件导入是否说明了阅读时机/原因？
- 路径特定指令是否在 .claude/rules/ 而非根 CLAUDE.md？
全局注册
创建或刷新项目 CLAUDE.md 时，确保项目在 ~/.claude/agent_docs/active-projects.md 中有条目，包含其目录和活动计划。
分层文件
对于 monorepo，在多个层级使用 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——自动化项目结构分析