HuanCode Docs

让 AI Coding Agent 真正理解你的代码库：分层上下文工程实践

大型仓库中，AI Agent 每次都要重新读文件"了解架构"，浪费 token 又不准确。本文分享一套分层 CLAUDE.md + 按需加载的实践方案，让 Agent 只读它需要的上下文。

问题：Agent 的"健忘症"

在大型代码仓库中使用 AI Coding Agent 时，你大概见过这样的场景：

"让我先阅读一下项目结构..." （Agent 开始读取 20+ 个文件） "现在我对现有架构有了全面了解。让我规划实现方案。"

下次再来一个需求？同样的流程再走一遍。

这带来三个问题：

  • 浪费 Token：每次探索消耗大量输入 token
  • 效率低：读文件、理解架构占了一半时间
  • 准确性差：Agent 自己总结的架构理解可能有偏差

根本原因是：Agent 没有持久的项目认知，每次都从零开始。

业界怎么解决的

调研了 Claude Code、Cursor、Aider、OpenCode 等主流工具，归纳出 5 个层次的方案：

1. 项目级指令文件

最直接的方案。在仓库根目录放一个 CLAUDE.md（或 Cursor 的 .cursor/rules/），写清楚项目架构、编码约定、常用命令。Agent 启动时自动加载。

问题：仓库一大，这个文件就膨胀。全部堆在一个文件里，每次请求都带上全量内容，反而造成新的浪费。

2. 按路径匹配的规则

Claude Code 的 .claude/rules/ 和 Cursor 的 .cursor/rules/ 支持 glob 模式：

# .claude/rules/python-backend.md
---
globs: "backend/**/*.py"
---
Repository 必须继承 BaseRepository[T]，用 read_by() 做查询...

只有当 Agent 操作匹配路径的文件时才加载。粒度比文件级更细。

3. 符号索引（Repo Map）

Aider 的方案：用 tree-sitter 解析整个仓库的类名、函数签名、调用关系，构建压缩的符号图。用图排序算法选出与当前任务最相关的代码片段。

全自动，不需要人维护。但需要工具链支持，且对架构意图的理解不如人写的文档。

4. Subagent 分工

Claude Code 内置了 Explore subagent（用更便宜的 Haiku 模型），专门负责搜索和探索代码库。探索结果在子上下文中消化，只返回摘要给主 Agent。

探索过程不污染主对话的 context window。

5. Skills（按需加载指令）

Agent Skills 已成为开放标准，被 Claude Code、Cursor、OpenCode、Junie、Gemini CLI 等十几个工具支持。Skill 的关键特性：body 只在使用时加载，比始终加载的 CLAUDE.md 更惰性。

我的方案：三层分层上下文

综合以上思路，我在自己的 monorepo 中落地了一套分层按需加载的方案。核心思想：

顶层极简索引 + 子目录按需详情 + 文件级规则自动匹配

第一层：根目录 CLAUDE.md（≤50 行）

只做两件事：目录索引 + 全局不变量。

# CLAUDE.md

> **保持精简**。详细内容在各子目录的 CLAUDE.md 中，按需加载。

## Monorepo 目录索引

| 目录 | 说明 | 详情 |
|------|------|------|
| `backend/` | FastAPI REST API | 见 `backend/CLAUDE.md` |
| `frontend/` | React 管理后台 | 见 `frontend/CLAUDE.md` |
| `huancode-web/` | 官网 (Next.js) | 见 `huancode-web/CLAUDE.md` |
| ... | ... | ... |

## 全局不变量

1. **CLAUDE.md 同步规则**：修改代码时同步更新对应目录的 CLAUDE.md
2. **技术选型必须查官方文档**：引入新依赖时，先去官网确认最新稳定版本
3. **Pre-commit**：提交前必须通过 lint
4. **Conventional commits**：feat: / fix: / docs: / chore:

为什么不超过 50 行？ Claude Code 文档建议每个 CLAUDE.md 不超过 200 行。但根目录文件每次都加载，越短越好。真正的详情下沉到子目录。

第二层：子目录 CLAUDE.md（按需加载）

关键特性：Claude Code 中，子目录的 CLAUDE.md 不会在启动时加载，只有当 Agent 读取该目录下的文件时才会按需加载。

每个子项目维护自己的 CLAUDE.md，内容包括：

  • 技术栈说明
  • 目录结构映射（文件 → 功能）
  • 常用命令
  • 本项目特有的约定
  • ⚠️ 同步规则提醒
# backend/ — FastAPI REST API

## 技术栈
Python 3.12, FastAPI, SQLAlchemy 2.0, MongoDB, APScheduler

## 目录结构
app/
├── api/v1/endpoints/   # HTTP handlers
├── services/           # Business logic
├── repositories/       # Data access (BaseRepository pattern)
├── models/             # SQLAlchemy models
└── schemas/            # Pydantic request/response

## ⚠️ 同步规则
修改 backend 时，涉及以下变更必须更新本文件：
- 新增/删除 model、endpoint、service
- 架构模式变更

这样：

  • Agent 改 backend → 只加载根 42 行 + backend 97 行 ≈ 140 行
  • Agent 改 frontend → 只加载根 42 行 + frontend 64 行 ≈ 106 行
  • 之前的单一大文件 → 每次加载 200+ 行，还不够详细

第三层：.claude/rules/（按 glob 自动匹配）

针对具体文件类型的编码规则，连文件都不用打开就能自动生效：

# .claude/rules/python-backend.md
---
globs: "backend/**/*.py"
---
- 使用 SQLAlchemy 2.0，禁止 relationship() 和 ForeignKey
- Repository 继承 BaseRepository[T]
- 所有响应用 create_response() 包装
- 异常使用 app/exceptions/ 中定义的类
# .claude/rules/backend-tests.md
---
globs: "backend/tests/**/*.py"
---
- 测试分 4 级：unit → integration → functional → e2e
- 单元测试用 AsyncMock，不连数据库
- 遵循 AAA 模式：Arrange → Act → Assert

同步规则：最容易被忽略的关键

方案再好，CLAUDE.md 过时了就比没有更糟——Agent 会按照错误的架构理解写代码。

解决方法：在每层都设置同步提醒。

根目录全局不变量第 1 条：

修改任何子项目的代码时，如果涉及架构、约定、目录结构变更，必须同步更新该子目录的 CLAUDE.md

每个子目录 CLAUDE.md 底部：

⚠️ 同步规则：修改本目录代码时，涉及以下变更必须更新本文件...

这样 Agent 在写代码的同时，如果新增了 model 或改了目录结构，它会意识到还需要更新 CLAUDE.md。

另一条容易忽略的规则：技术选型必须查官方文档

这是一条全局行为准则：

引入新依赖或技术组件时，先去官网确认最新稳定版本，使用前必须查阅官方文档了解正确用法，不要凭记忆猜测 API

AI 模型的训练数据有滞后性。它记忆中的 API 可能是 v2 的，而最新稳定版已经是 v4 了。写进全局不变量，Agent 每次都能看到。

最终的文件结构

my-monorepo/
├── CLAUDE.md                    # 顶层索引 + 全局规则（≤50行）
├── AGENTS.md                    # 跨工具通用指令（Cursor/OpenCode等也读这个）
├── .claude/rules/               # 按文件类型自动匹配
│   ├── python-backend.md        # globs: backend/**/*.py
│   ├── react-frontend.md        # globs: frontend/**/*.tsx
│   └── backend-tests.md         # globs: backend/tests/**/*.py
├── backend/
│   └── CLAUDE.md                # 后端架构详情（按需加载）
├── frontend/
│   └── CLAUDE.md                # 前端技术栈详情（按需加载）
├── my-website/
│   └── CLAUDE.md                # 网站项目详情（按需加载）
└── .cursorrules                 # 详细编码规范（按需参考）

总结

做法Token 消耗准确性维护成本
❌ 让 Agent 每次自己探索高低（靠猜）零
⚠️ 单一大 CLAUDE.md中（全量加载）中低
✅ 分层按需加载低（只加载相关的）高（人写的精确描述）中（需同步维护）

核心原则就三条：

  1. 顶层极简：根目录只放索引和全局规则，50 行以内
  2. 详情下沉：每个子项目维护自己的上下文文件，按需加载
  3. 代码改了文档也改：同步规则写进不变量，让 Agent 自觉维护

这不是什么革命性的创新，本质上就是给 AI 写 onboarding doc——只不过用了分层加载的策略来控制 token 开销。但在实际使用中，效果很明显：Agent 的"探索阶段"从读 30 个文件变成了读 1-2 个文件，而且理解更准确。

On this page

问题：Agent 的"健忘症"业界怎么解决的1. 项目级指令文件2. 按路径匹配的规则3. 符号索引（Repo Map）4. Subagent 分工5. Skills（按需加载指令）我的方案：三层分层上下文第一层：根目录 CLAUDE.md（≤50 行）第二层：子目录 CLAUDE.md（按需加载）第三层：.claude/rules/（按 glob 自动匹配）同步规则：最容易被忽略的关键另一条容易忽略的规则：技术选型必须查官方文档最终的文件结构总结