CLAUDE.md 上下文治理指南（复杂项目）
目标：在复杂项目中降低
CLAUDE.md对上下文窗口的占用，同时提升 Claude Code 的稳定性与执行质量。
一、核心结论
- 不要继续“优化一个很大的 CLAUDE.md”，应改为：主文件极简 + 模块化规则 + 按需加载。
CLAUDE.md只保留高频、稳定、不可从代码直接推断的规则。- 低频/领域化内容下沉到
.claude/rules/，并通过paths做条件生效。 - 对“必须每次执行且不能遗漏”的动作，优先使用 hooks，而不是文本提醒。
二、关键问答沉淀
Q1：@path/to/import（可控导入）是什么意思？
在 CLAUDE.md 里写 @某个路径，相当于将该文件内容一并导入上下文。
示例：
# CLAUDE.md
@README.md
@docs/git-instructions.md
@~/.claude/my-project-instructions.md说明：
- 支持相对路径、绝对路径、
~家目录。 - 导入文件可继续
@import其他文件（递归导入）。 - 递归链路有深度上限（官方提到最多 5 层），用于防止无限嵌套。
“可控”体现在：
- 主文件可保持很薄（入口索引）
- 按模块决定导入哪些规则
- 避免单文件膨胀导致指令稀释
Q2：.claude/rules 是按需加载吗？
分两类：
- 无
paths的 rules：通常作为项目规则默认生效。 - 带
paths的 rules：仅在处理匹配路径文件时生效（按需加载/按需注入上下文）。
示例：
---
paths: src/api/**/*.ts
---
# API Rules
- ...当 Claude 在处理 src/api/**/*.ts 时，这份规则才参与。
Q3：可从代码推导的信息，要不要写进 CLAUDE.md？
原则：写“高频且稳定的推导结果”，不写“易过期代码事实”。
可执行判断：
- 高频 + 推导成本高 + 稳定 → 写入
CLAUDE.md/ rules - 低频 + 推导成本高 → 放 rules（最好加
paths）或 skills - 变化快 → 不写死，交给实时读取/搜索
三、推荐目录结构（可直接采用）
.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.mdCLAUDE.md 只保留四类内容
- 高风险硬约束（禁改目录、危险操作）
- 标准执行入口（lint/typecheck/test）
- 团队协作约定（分支/PR/提交）
- 模块入口（
@import）
建议控制在 80~150 行。
四、可复制模板
1) CLAUDE.md（薄入口）
# 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.md2) 条件规则模板（paths）
---
paths: src/api/**/*.ts
---
# API Rules
- 返回体字段使用 camelCase
- 分页接口必须包含 page/pageSize/total
- 新增接口必须补齐契约测试五、“内容分层清单”（决策表）
A. 放在 CLAUDE.md
- 高频、稳定、全局适用、不可推断的硬规则
B. 放在 .claude/rules/*.md
- 领域规则、模块规则、团队规范细节
- 能加
paths的尽量加（减少无关上下文）
C. 放在 hooks
- 必须每次执行且不能漏的动作（如 lint、敏感目录保护）
D. 放在 skills
- 低频但复杂、篇幅长、流程化的任务（发布、排障 runbook 等）
E. 不建议写入
- 易过期实现细节
- 大段教程/背景材料
- Claude 可快速从代码得出的事实
六、会话治理（防上下文污染）
- 任务切换前执行
/clear - 长任务中段执行
/compact <focus> - 大规模调查先用 subagents，主会话保留结论与决策
- 若同一问题已纠偏 2 次仍失败：
/clear后用更具体提示重启
七、实施计划（1周内）
Phase 1（1天）：瘦身
- 现有
CLAUDE.md标记为：必须 / 可迁移 / 可删除 - 先删 30%~50% 冗余
Phase 2（1~2天）：模块化
- 建立
.claude/rules/并分主题拆分 - 给高噪声规则加
paths
Phase 3（1天）：强制化
- 将“不能漏”的要求迁移到 hooks
Phase 4（2~3天）：评估迭代
- 指标：
- 规则相关重复追问是否下降
- 单任务纠偏次数是否下降
- 长会话后半段质量是否更稳定
八、维护原则
- 像维护代码一样维护规则：小步、可回滚、可验证
- 规则不是越多越好，而是单位 token 产出越高越好
- 定期删减低价值规则，保持主文件“短、硬、准”
参考（官方文档方向）
- Claude Code docs sitemap: https://code.claude.com/docs/sitemap.xml
- 重点页面（中文）：
best-practicesmemory（CLAUDE.md 相关）skills/hooks/sub-agents