CLAUDE.md 指导思想与系统化落地指南
适用场景：复杂项目、多人协作、长会话频繁、上下文成本敏感。
核心目标：在保证执行质量的前提下，最小化上下文占用，最大化单位 token 产出。
0. 总纲（一句话）
把“全局稳定且高频”的信息前置，把“局部复杂且低频”的信息后置，并通过按需加载与强制自动化，建立高信噪比的上下文系统。
1. 第一性原理（Why）
1.1 上下文窗口是稀缺资源
- Claude Code 会把对话、读过的文件、命令输出都放进上下文。
- 上下文越满，性能与稳定性越容易下降。
- 因此应把规则体系当作“资源调度问题”，而非“知识堆叠问题”。
1.2 规则的价值 = 错误预防收益 / token 成本
- 不是规则越多越好，而是每一行都要有防错价值。
- 对每条规则问一句：
- “删掉它，是否会显著增加错误概率？”
- 如果不会，删除或下沉。
1.3 文本约束不是万能，强约束应自动化
- 文字规则依赖模型遵循；hooks 是确定执行。
- “不能漏执行”的要求应迁移到 hooks，不应仅靠 CLAUDE.md 提醒。
2. 总体架构（What）
采用“三层治理架构”：
- 主文件极简层（CLAUDE.md）
- 只放全局高频硬约束 + 导航入口
- 模块规则层（.claude/rules）
- 分领域、分目录、按需生效（
paths）
- 分领域、分目录、按需生效（
- 执行保障层（hooks / skills）
- hooks 处理强制动作
- skills 承载低频复杂流程
目标状态：
- 主文件短（建议 80~150 行）
- 规则模块化
- 会话可控、可清理、可恢复
3. 分层设计原则（How）
3.1 CLAUDE.md（全局入口层）
只保留四类：
- 高风险硬约束（禁改目录、危险操作边界）
- 标准执行入口（lint/typecheck/test）
- 团队协作规范（分支、提交、PR）
- 模块导入（
@import）
不放：
- 大段教程
- 快速变化的实现细节
- 模型可轻易从代码推断的信息
3.2 .claude/rules（知识模块层）
按领域拆分：
- core / workflow / frontend / backend / testing / perf / security
按作用域控制：
- 默认规则：通用场景使用
- 条件规则：通过
paths只在匹配文件时生效（推荐）
3.3 hooks（执行保障层）
适用于：
- 每次必须执行且不能漏
- 漏一次会带来高风险
典型项：
- 保存后或提交前 lint/typecheck
- 禁止写入敏感目录
- 提交前阻断不合规变更
3.4 skills（低频复杂层）
适用于：
- 偶发但复杂的流程
- 说明长、步骤多、跨系统
典型项：
- 发布流程
- 故障排查 runbook
- 特定系统对接/迁移
4. 关于 @import 的指导思想
4.1 作用
- 把单一大文件拆成多个小模块，主文件只做索引。
- 降低维护成本，避免“规则墙”。
4.2 方法
- 在
CLAUDE.md中使用@path/to/file导入。 - 支持递归导入，但应控制深度和复杂度（常见上限 5 层）。
4.3 原则
- 主文件“薄”，模块“专”
- 导入链路“短”，避免深层嵌套
- 用目录语义组织，不用时间堆积组织
5. 关于“可推导信息是否写入”的决策框架
使用三维判断：频率 × 推导成本 × 稳定性
5.1 应写入（前置）
- 高频使用
- 推导成本高（每次重新探索都贵）
- 相对稳定（不易过期）
例：
- 常用命令入口
- 固定架构边界
- 跨团队统一约定
5.2 下沉（按需）
- 低频使用
- 但推导成本高
做法：
- 放 rules +
paths - 或放 skills，按需调用
5.3 不写死（实时读取）
- 变化快
- 易过期
- 细粒度实现事实
6. 会话治理思想（Context Hygiene）
6.1 任务边界清晰化
- 不相关任务切换前使用
/clear - 避免“厨房水槽式会话”（多任务混杂）
6.2 长会话压缩策略
- 中途使用
/compact <focus>保留关键、丢弃噪声 - 聚焦保留：关键决策、改动文件、验证命令
6.3 调查与实现解耦
- 大范围调查交给 subagents
- 主会话只保留结论与决策，减少污染
6.4 失败重启纪律
- 同一问题连续 2 次纠偏仍失败：
/clear+ 更具体提示重启
7. 组织落地方法（从整体到细节）
7.1 Phase 1：瘦身（1天）
- 盘点现有 CLAUDE.md 每一条规则
- 标注：保留 / 下沉 / 删除
- 目标：先减 30%~50% 冗余
7.2 Phase 2：分层（1~2天）
- 创建
.claude/rules/目录树 - 领域化拆分规则
- 对局部规则补
paths
7.3 Phase 3：强制化（1天）
- 把“必须执行”规则迁移到 hooks
- 做最小可用自动化，先保障质量底线
7.4 Phase 4：验证迭代（2~3天）
跟踪指标：
- 规则相关重复追问是否减少
- 单任务纠偏次数是否下降
- 长会话后半段质量是否稳定
8. 模板化基线（可直接执行）
8.1 目录基线
.claude/
CLAUDE.md
rules/
00-core.md
workflow.md
frontend/react.md
backend/api.md
testing/unit.md
testing/e2e.md
perf/budget.md
security/baseline.md8.2 主文件基线
# MUST FOLLOW
- 完成修改后运行：pnpm lint && pnpm typecheck
- 提交前优先跑受影响测试
- 禁止修改：migrations/**
# WORKFLOW
- 先计划后实施
- 同问题两次纠偏失败后建议 /clear 重启
# IMPORTS
@.claude/rules/00-core.md
@.claude/rules/workflow.md
@.claude/rules/frontend/react.md
@.claude/rules/backend/api.md
@.claude/rules/testing/unit.md8.3 条件规则基线
---
paths: src/api/**/*.ts
---
# API Rules
- 返回体使用 camelCase
- 列表接口必须包含分页字段
- 新增接口需补契约测试9. 治理纪律（长期有效的关键）
- 规则即代码：小步修改、可回滚、可验证
- 规则要短：短比全更重要，准比多更重要
- 持续删减：定期移除低收益规则
- 以结果评估：看纠偏次数、复问次数、会话稳定性
- 自动化优先：能 hook 的不靠记忆
10. 最终判断标准（是否做对）
如果你看到以下变化，说明体系有效：
- Claude 更少“忘规则”
- 更少重复提问同类约束
- 长会话后半段质量仍稳定
- 复杂任务中人工纠偏显著下降
即：更少 token 浪费，更多有效产出。
附：本指南来源范围
基于你与助手围绕以下主题的完整问答整理而成：
- CLAUDE.md 过大导致上下文占用
@import分层与递归导入理解- rules 是否按需加载（尤其
paths条件） - 可推导信息的写入策略
- 可直接套用的分层清单与落地计划