大型代码库Claude Code设置指南

如果你正在处理一个大型本地代码库一个包含数十个服务的单体架构、多个后端组件和客户端应用程序全部存放在一个巨大仓库中你已经知道那种痛苦。编码智能体有有限的上下文窗口只有当这个窗口被刻意使用时它们才能发挥最佳效果。大型单体代码库如果没有为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 all1.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.mdClaude会在需要时按需读取。避免过时的会话触发旧/过时会话会尝试用旧/之前的对话刷新缓存这会消耗不必要的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切换到可用的最高模型然后描述你需要的。不要跳到写代码。而是我需要实现一个新APIgetTransactions以分页格式检索事务事件供上游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.md8. 结束语大型实现可以快速吃掉你的上下文窗口并影响交付质量。在规划阶段本身指导claude准备一个多阶段实现计划可以由多个顺序智能体、智能体团队或子智能体调用。原文链接大型代码库Claude Code设置指南 - 汇智网