> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# 大型代码库Claude Code设置指南
- URL: https://www.hubwiz.com/blog/a-claude-code-setup-guide-for-large-codebases/
- Published: 2026-06-06T04:10:42.000Z
- Updated: 2026-10-13T15:34:31.000Z
- Description: 面向使用大型复杂企业代码库的团队的实用指南。
- Author: admin
- Tags: AGENT, CLAUDE CODE, #Import 2026-10-14 14:41

如果你正在处理一个大型本地代码库，一个包含数十个服务的单体架构、多个后端组件和客户端应用程序全部存放在一个巨大仓库中，你已经知道那种痛苦。编码智能体有有限的上下文窗口，只有当这个窗口被刻意使用时它们才能发挥最佳效果。大型单体代码库如果没有为AI辅助开发正确设置，会很快填满可用上下文，智能体开始产生幻觉，给出不符合预期的响应。

## 1\. 你的CLAUDE.md是你最重要的文件

像任何其他项目一样，设置Claude Code的第一步是创建一个`CLAUDE.md`文件。Claude可以扫描你的项目并通过`/init`命令自动生成一个。根据你的项目需求修改它。

对于大型仓库，这个文件是桥接Claude通用知识和你的项目自定义实现之间差距的关键。

### 1.1 嵌套的CLAUDE.md文件

不要把所有内容塞进一个文件。保持根`CLAUDE.md`精简，大约200到300行，提供足够的上下文来指导Claude。对于大型仓库，使用分层方法：保持根文件在200行以下，使用`@file`引用按需指向Claude更深入的文档。子系统可以有自己`CLAUDE.md`文件。

```
project-root/                    # 服务器/运行时根目录
├── CLAUDE.md                    # 精简入口点（~200行）
├── docs/
│   ├── coding-guidelines.md     # 编码标准和模式
│   ├── architecture.md          # 系统架构概述
│   └── db-schema.md             # 关键表和关系
├── system/                      # 核心系统文件和配置
│   ├── source/                  # 自定义策略/数据模块
│   │   └── CLAUDE.md            # 模块开发规则
├── lib/                         # 共享库
├── header/                      # 头文件
├── bin/                         # 可执行文件和脚本
├── jars/                        # Java库
├── conf/                        # 环境配置
├── integration/                 # 集成框架
│   └── CLAUDE.md                # 集成/评级规则
├── apps/                        # 批处理作业和工具
│   └── CLAUDE.md                # 批处理作业规则和工具
├── 3rdParty/                    # 第三方库
├── logs/                        # 运行时日志目录
└── testing/                     # 集成和回归测试
    └── CLAUDE.md                # 测试约定和运行说明

```

### 1.2 根CLAUDE.md中放什么

我们可以使用`/init`构建初始的CLAUDE.md文件，然后添加Claude不会知道的自定义实现细节。例如项目架构、日志位置、如何编译源代码、如何运行测试用例和需要加载的环境文件。

```
# 项目概述：企业事务平台

## 架构
这是一个5层本地部署系统：
客户端应用 → API层 → 请求网关 → 核心服务模块
  → 数据访问模块 → 关系型数据库

- API层：处理外部API契约、身份验证和请求规范化。
- 请求网关：中央请求路由器。将服务和数据模块作为共享库加载。
- 核心服务模块：领域工作流、验证规则和编排逻辑。
- 数据访问模块：数据库抽象层。主数据库连接器处理所有数据库操作。
- 批处理器：用于定时和高吞吐量工作负载的离线处理引擎。

## 仓库地图
| 目录       | 用途                                             |
|-----------|--------------------------------------------------|
| server/    | 核心服务器运行时根目录                             |
| processing/| 离线数据处理框架                                   |
| apps/      | 批处理应用、工具、自定义脚本                         |
| conf/      | 环境配置：API、模式、SQL、参数                      |

## 关键命令
- 编译模块：`cd $PROJECT_HOME/source/modules/core && make`
- 运行测试：`make test`
- 重启服务：`app restart all`

```

### 1.3 教Claude它不知道的东西

这对于专有或小众系统至关重要。添加Claude无法通过网络搜索找到或没有预训练过的自定义上下文：

> **原则：**`CLAUDE.md`

## 2\. Claude Code CLI中的自定义状态栏

微服务或单体仓库，放置状态栏都很有帮助。

使用内置的`/statusline`命令配置自定义状态栏。快速查看Claude会话的关键统计数据很方便。

提示：让claude生成一个有用的状态栏，类似下面这样

```
// 设置 (~/.claude/settings.json)
"statusLine": {
    "type": "command",
    "command": "bash /home/arijit/.claude/statusline-command.sh"
}

// 脚本显示：
// 1. 模型名称（青色）
// 2. 上下文使用率条 — 20字符，颜色编码
//    绿色（<50%）| 黄色（50-79%）| 红色（80%+）
// 3. 上下文百分比和token计数
// 4. Git分支（品红色，粗体）
// 5. 项目名称（蓝色，粗体）

```

![状态栏](https://www.hubwiz.com/blog/content/images/2026/06/1-QlnjGySwdtybDTe03u_v2Q.png)

## 3\. 像保护生产内存一样保护你的上下文窗口

定期运行`/context`检查利用率。自定义状态栏让上下文使用率始终可见。过多的上下文利用会使智能体产生幻觉并降低会话性能。

### 3.1 什么在消耗你的上下文

**臃肿的CLAUDE.md** — 如果你的根文件有500+行，你在问问题之前就已经在消耗token了。保持它在200行以下并引用更深的文档。

**太多的MCP服务器** — 每个连接的服务器都会向上下文添加工具定义。如果你连接了8个MCP但编码时只用了2个，在开发会话中禁用其余的。

**嵌入整个文件的@-file引用** — 不要写`@docs/full-api-spec.md`如果那个文件有2000行。而是写"有关API规格详情，见docs/full-api-spec.md"，Claude会在需要时按需读取。

避免过时的会话，触发旧/过时会话会尝试用旧/之前的对话刷新缓存，这会消耗不必要的token。如果你不需要旧会话的上下文，就启动一个新会话。

## 4\. 一个会话，一个任务 — 没有例外

每个CC会话应该只有一个目的：

为每个新任务启动一个新会话：设计、构建、调试、研究。对于复杂和较大的任务，使用智能体团队来扩展你的上下文，我们将在后面讨论。

**会话A：** 构建新的评级API端点。 **会话B：** 调试CM在操作码路由上的崩溃。 **会话C：** 审查批处理管道变更的PR。 **会话D：** 回答关于可存储类层次结构的问题。

你*永远不应该*做的是：启动一个会话来构建API，然后让Claude调试一个无关的CM问题，然后粘贴PR进行审查，再问数据库架构——全在同一个会话中。

为什么？**上下文污染。** 当你执行到任务#3时，Claude的上下文充满了任务#1的代码、任务#2的调试日志，而你原始提示中的指令被埋没了。每个后续响应的质量都会下降。

## 5\. 将次要任务委派给子智能体

当你在深入构建会话中意识到需要一个工具函数、测试夹具或配置文件时——不要在主会话中做。委派。

Claude Code支持在自己的上下文中运行的子智能体。主会话保持干净，子智能体只返回最终结果。你可以显式触发这个：

## 6\. 始终以"计划"模式启动会话

这适用于每种类型的任务，构建功能、调试问题、重构模块。始终以/plan模式开始。执行/plan切换到计划模式。

一旦claude完成规划阶段，它创建一个plan.md文件，包含手头任务的蓝图。迭代规划循环直到计划看起来不错，要求claude修改需要纠正的地方。

对于复杂的任务，考虑使用frontier模型（如opus等），配合增加的/effort和开启thinking（通过/config）。

> *这比在单独的智能体会话中进行测试好得多。*

![计划模式](https://www.hubwiz.com/blog/content/images/2026/06/1-8lbVnFUN673q3vE_Ye_-NQ.png)

**阶段1 — 计划**

用`/model opus`切换到可用的最高模型，然后描述你需要的。不要跳到"写代码"。而是：

> `getTransactions`

**阶段2 — 实现**

一旦计划确定，切换到较低模型进行实现`/model sonnet`。Sonnet更快、更便宜，并且完全有能力遵循一个明确定义的计划。阶段1的计划仍然在上下文中。

或者使用`/model opusplan`，它会在智能体退出计划模式后自动切换到sonnet。不过截至我写这篇文章时，提到的模型还不可用1M上下文。

> `plan.md`

## 7\. 保存会话学习：为智能体构建活记忆

在长时间会话后要求CLAUDE保存学习成果。它会通过MEMORY.md文件记住你帮助claude修复的错误。下面是一个记忆示例。

> 如果你不捕获这些关键学习成果，它们会随会话一起消亡。

### 7.1 MEMORY.md文件

Claude Code有一个自动记忆系统，保存到`~/.claude/projects/<repo-hash>/memory/MEMORY.md`。前200行在每次会话开始时加载。以下是调试会话后真实条目的样子：

### 7.2 CLAUDE.md vs MEMORY.md

**架构、约定、命令** → `CLAUDE.md` *（团队共享，版本控制）*

**调试模式、会话学习、陷阱** → `MEMORY.md` *（个人，机器本地）*

**Claude在网上找不到的自定义领域知识** → `CLAUDE.md` *（在引用的文档中）*

**"Claude一直犯这个错误，这是修复方法"** → `MEMORY.md`

## 8\. 结束语

大型实现可以快速吃掉你的上下文窗口并影响交付质量。在规划阶段本身，指导claude准备一个**多阶段实现计划**，可以由多个顺序智能体、智能体团队或子智能体调用。

---

原文链接：[Taming the Monolith: A Claude Code Setup Guide for Large Codebases](https://medium.com/towards-artificial-intelligence/taming-the-monolith-a-claude-code-setup-guide-for-large-codebases-f03220669ea5?ref=hubwiz.com)

汇智网翻译整理，转载请标明出处

> **这是「AI 编程 / Vibe Coding」专题的一部分。**完整地图见：[AI 编程 / Vibe Coding 完全指南](https://www.hubwiz.com/blog/vibe-coding-stack/)