大型代码库Claude Code设置指南

AI模型价格对比 | AI工具导航 | ONNX模型库 | Vibe Coding教程 | PLC在线仿真器 | Tripo 3D | Meshy AI | ElevenLabs | KlingAI | ArtSpace | Phot.AI | InVideo

如果你正在处理一个大型本地代码库，一个包含数十个服务的单体架构、多个后端组件和客户端应用程序全部存放在一个巨大仓库中，你已经知道那种痛苦。编码智能体有有限的上下文窗口，只有当这个窗口被刻意使用时它们才能发挥最佳效果。大型单体代码库如果没有为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需要在你的内部wiki中查找才能理解某事，把它放在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. 项目名称（蓝色，粗体）

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）。

提示：对于实现任务，提前告诉智能体你的目标或成功标准，或测试场景。这样智能体会反复迭代测试用例直到满足成功标准。这比在单独的智能体会话中进行测试好得多。

阶段1 — 计划

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

我需要实现一个新API getTransactions，以分页格式检索事务事件，供上游UI显示。

阶段2 — 实现

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

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

提示：将plan.md视为活文档。随着工作进展更新它，并将其传递给未来的智能体（例如用于bug修复或后续任务），这样它们从完整的上下文开始，而不是从零开始。

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

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