← Volver a las guías

大型代码库长上下文实战：分层索引与增量审查策略

为什么大型代码库不能一次塞进上下文

在单体仓库、微服务仓库或包含多年历史的项目中，AI 最容易犯的错误不是不会写代码，而是缺少足够且正确的局部事实。例如，模型看到一个 Controller 后直接修改字段，却不知道该字段还被消息消费者、数据库迁移和前端 SDK 依赖。长上下文的目标并非把所有文件无差别提交，而是让模型在每一步都获得与当前任务相关、可验证、层次清晰的信息。

一个实用原则是：先给模型“地图”，再给“路径”，最后给“现场”。地图说明仓库结构和架构约束；路径展示调用链与依赖关系；现场则是需要实际修改的文件、测试和错误日志。这样既节省 token，也能降低模型在旧代码与无关模块中误判的概率。

第一步：维护可读的仓库地图

在仓库根目录维护 AI_CONTEXT.md，不要写成冗长的项目介绍，而应记录高频决策信息：模块职责、启动命令、关键边界、代码规范、禁止修改的兼容性接口，以及测试入口。每次架构变化后同步更新它。

例如，可让 Claude Code 或 Codex 先执行类似任务：读取 AI_CONTEXT.md、package.json、根目录配置和 src 下两层目录；输出模块职责表，不修改文件。 接着把生成结果人工校正。一个有效的上下文摘要通常包括：

• apps/api：HTTP 接口、认证和请求参数校验。
• packages/domain：领域模型与业务规则，不允许依赖 Web 框架。
• packages/db：迁移、查询和事务封装。
• packages/events：事件定义与消费者，修改 schema 必须检查兼容性。
• tests/e2e：跨服务回归测试，发布前必须运行。

这份地图应当短小、稳定。模型每次开始复杂任务时先读取它，比反复上传整仓库更可靠。

第二步：按调用链构造任务上下文

假设要为订单增加 cancelReason 字段，不要只提示“给订单加取消原因”。先用搜索工具定位定义、写入、读取、序列化和测试位置，再按依赖顺序提供文件。可以让代理执行：

rg -n "Order|cancelled|status" apps packages tests

然后使用明确的分阶段提示词：先只分析 Order 的类型定义、迁移、取消命令、订单查询接口和相关测试。列出数据流、潜在兼容性问题及需修改的文件，等待确认后再编辑。

确认范围后，再要求模型按最小改动实现：先创建迁移，再更新领域类型与写入逻辑，随后更新 API 响应和测试。每完成一个阶段，要求它说明新增字段是否可空、旧记录如何处理、接口是否保持向后兼容。长上下文真正有价值的地方，是让模型持续保留这些决策，而不是在每个新请求中重新猜测。

第三步：把上下文拆成可复用包

对于经常处理的领域，可建立上下文包，例如 docs/context/orders.md、docs/context/billing.md。每个文件包含领域词汇、状态机、外部依赖、常见查询和不变量。订单包可以明确写出：已支付订单取消必须触发退款事件；cancelReason 只允许由后台审核员写入；事件消费者必须容忍未知字段。

调用 OpenAI 兼容 SDK 时，可以先加载地图与领域包，再附加本次涉及的文件内容。59API 的接口地址为 https://api.59api.com，兼容 OpenAI SDK，因此现有脚本通常只需替换 base URL 和密钥：

from openai import OpenAI
client = OpenAI(base_url="https://api.59api.com/v1", api_key="YOUR_API_KEY")
response = client.chat.completions.create(model="gpt-4.1", messages=[{"role":"user","content":"先阅读仓库地图和订单上下文，再审查以下改动。"}])

实际模型名称应以账户可用列表为准。对于 Claude Code 或 Codex，同样应把仓库地图和领域包作为固定起点，再让工具按需读取具体文件，而不是复制大量无关源码进入对话。

第四步：用增量审查控制上下文漂移

长任务应分为“理解、计划、实施、验证”四轮。每轮结束时要求模型产出简短状态：已确认的事实、未确认假设、已修改文件、下一步验证命令。比如在实施完成后，不要立刻要求继续重构，而是运行 pnpm test --filter orders 和类型检查，并将失败输出作为新的现场上下文提交。

当对话变长、模型开始重复早期结论或忽略新约束时，创建新会话更合适。新会话只带入仓库地图、领域包、已确认计划、git diff 和测试结果。这种“压缩后续接”的方式，比保留数十轮原始对话更精确，也更节约调用成本。

选择适合长任务的模型与网关

大型代码库工作往往需要多次搜索、审查和测试，成本会随上下文长度快速累积。59API 提供按量计费的 Claude Opus、Sonnet、Haiku、Fable 与 GPT 模型，并兼容 Claude Code、Codex 和任意 OpenAI SDK；开发者可以用较经济的模型完成目录扫描、日志归类和测试修复，再把复杂架构决策交给更强模型。其原生官方质量模型和较低价格，适合把“先分析再修改”的流程真正落地，而非因成本跳过必要审查。

建议先用小范围真实任务验证上下文包质量：选一个有测试覆盖的字段变更，记录模型漏掉的依赖，再把这些依赖规则补回领域文档。需要稳定、低成本地接入多种模型时，可注册 59API 并从一个仓库地图开始建立团队的长上下文工作流。

Precios · Docs