一、大仓接入先定边界，不要一上来全仓扫描

Monorepo、大型业务仓库、前后端混合仓库接入 Codex API 中转站时，最容易犯的错误是把整座仓库直接丢给模型理解。仓库越大，目录越多，历史代码越复杂，模型越需要清晰边界。没有边界的任务会让上下文迅速膨胀，也会让回答变得泛泛而谈。

正确做法是先确定本次任务所属的业务模块、入口目录、相关配置和禁止触碰范围。灵能API提供稳定的 API 中转站入口，CC Switch 负责管理模型和配置卡，但任务边界仍然要由开发者提前设计。

️ 二、先画一张仓库地图

大仓项目里，目录结构本身就是第一份说明书。接入前先整理一张仓库地图，标出应用目录、共享包目录、配置目录、脚本目录、文档目录和测试目录。这样 Codex 在执行任务时不会把无关模块混在一起分析。

这张地图不需要画得复杂，关键是让“本次任务该看哪里”变得明确。后续写提示词、做只读验证、限制修改范围，都要围绕这张地图展开。

如果仓库已经维护多年，还要特别标出废弃目录、迁移中目录和历史兼容目录。大仓里经常存在名字相似但职责不同的模块，模型如果读到了旧入口，可能会把历史实现当成当前方案。仓库地图越清楚，后续上下文裁剪越稳。

• apps：通常放多个前端或服务端应用。
• packages：通常放共享组件、工具函数、SDK 或类型定义。
• services：通常放后端服务、任务队列或接口层。
• configs：通常放构建、格式化、测试和部署配置。
• do**：通常放说明文档，不一定参与真实运行。

三、从灵能API确认接口与模型能力

进入灵能API官网 https://www.lnsns.com/ 后，先确认当前账号可用模型、API *ase、接口说明和额度状态。大仓任务通常比单文件任务更消耗上下文，因此模型选择、超时设置和任务拆分方式都要提前规划。

团队文档中可以把灵能API设置成可点击入口，让成员回到统一页面确认接口信息。不要从旧聊天记录里复制 *ase **L，也不要把某次临时测试的模型名称直接写成长期默认配置。

四、按任务类型建立 CC Switch 配置卡

大仓项目不建议所有任务都使用同一张配置卡。读取结构、解释报错、生成测试、修改局部文件、跨模块分析，这些任务对模型能力和上下文长度的要求不同。CC Switch 的价值就是把这些差异保存为可切换的配置，而不是每次手动改字段。

命名清楚以后，团队成员不用猜当前配置适合什么任务。配置卡也可以写进项目 README 或内部接入文档，方便新成员按用途选择。

• repo-readonly：用于全仓结构扫描和目录说明。
• module-de*ug：用于单模块报错定位。
• module-patch：用于明确文件范围内的小改动。
• cross-module-review：用于跨包影响分析，建议谨慎启用。

五、目录白名单比口头提醒更可靠

如果任务只涉及前端订单页，就不要让 Codex 同时分析支付服务、运营**、构建脚本和历史迁移代码。口头说“只看这个模块”有用，但更好的做法是在提示词里写清楚目录白名单和禁止范围。

本次只允许分析：
apps/we*-order/**
packages/ui/**
packages/shared-types/**

本次不要分析或修改：
services/payment/**
infra/**
do**/archive/**

白名单不是为了限制模型能力，而是为了减少噪声。边界越清晰，Codex 越容易给出可执行的结论，也越不容易把无关模块里的旧逻辑当成当前任务依据。

六、上下文裁剪要围绕问题，而不是围绕文件数量

大仓接入时，很多人会问“最多能读多少文件”。更实际的问题是：哪些文件能解释当前问题？如果一个任务是修复按钮状态错误，入口组件、状态管理、接口类型、相关测试通常比整座仓库更重要。

这样做比一次塞入大量文件更有效。灵能API保证调用入口稳定，真正决定任务质量的是上下文是否围绕问题组织。

实际使用时，可以把上下文分成三层：第一层是必须阅读的入口文件，第二层是可能相关的共享模块，第三层是只有在模型说明理由后才允许继续查看的扩展目录。这样既给了 Codex 足够信息，又不会让它在无关文件里消耗注意力。

• 先给业务现象：用户做了什么，页面或接口发生了什么。
• 再给入口文件：从哪个页面、命令或服务开始看。
• 再给相关目录：共享组件、类型定义、接口封装或测试。
• 最后补充限制：哪些目录不要打开，哪些文件不要改。

️ 七、配置字段要避免混用临时值

大仓任务往往伴随多次模型切换、Key 切换和超时调整。字段越多，越要避免临时值长期留在配置卡里。每次调整都应该知道自己改的是 API *ase、模型、Key 还是 timeout，而不是凭感觉把能填的地方都改一遍。

• API *ase：从灵能API接口说明确认。
• API Key：按项目或任务用途隔离。
• Model：按只读、调试、修改、跨模块分析分层。
• Timeout：只在长任务确实需要时调整，并记录原因。

八、第一次验证只做只读扫描

大仓配置完成后，第一次不要让 Codex 修改文件。先做只读扫描，让它输出仓库结构、关键模块、可能入口和风险点。这个步骤能验证模型是否理解目录边界，也能观察它是否会越界分析无关目录。

请只读分析当前仓库：
1. 总结 apps、packages、services 三类目录职责。
2. 标出与订单模块相关的入口文件。
3. 不要修改任何文件。
4. 不要分析 do**/archive 和 infra 目录。

如果只读扫描就开始泛泛总结整个仓库，说明提示词边界不够清楚；如果它准确聚焦目标模块，再进入下一步局部分析。

只读扫描的结果也可以作为人工审阅依据。你可以先看它列出的入口文件是否正确、是否遗漏关键共享包、是否误把测试工具当成业务入口。这个环节越认真，后面允许修改时越不容易跑偏。

九、第二步再做单模块问题定位

只读扫描通过后，第二步可以进入单模块问题定位。此时不要让 Codex 一次解决所有历史问题，而是给一个明确现象，比如某个按钮不可点击、某个接口返回值类型不匹配、某个测试用例失败。

这种顺序能把“理解仓库”和“修改代码”分开。大仓里最怕模型没看懂边界就开始改文件，最后改动看似合理，却影响了其他模块。

• 输入要包含复现步骤，而不是只有报错截图。
• 输入要说明期望行为和实际行为。
• 输入要限制分析目录，避免跑到无关模块。
• 输出先要求定位原因，不急着写代码。

✍️ 十、允许修改时必须限定文件范围

当你确认 Codex 能理解目标模块后，才适合放开小范围修改。修改范围要写到文件或目录级别，不要只说“尽量少改”。对大仓来说，“少改”是主观判断；文件白名单才是客观边界。

允许修改：
apps/we*-order/src/pages/OrderDetail.tsx
apps/we*-order/src/hooks/useOrderStatus.ts
packages/shared-types/src/order.ts

不允许修改：
services/**
packages/ui/theme/**
lock files

如果任务确实需要改白名单之外的文件，要求 Codex 先说明原因，再由人工确认。这能避免一次小修复扩散成跨模块改动。

十一、让输出包含影响范围和验证方式

大仓项目里，代码改完不等于任务完成。你需要知道这次修改影响哪些模块、哪些测试应该跑、哪些风险需要人工复核。建议在提示词里要求 Codex 输出影响范围和验证方式。

对大仓来说，未处理事项很重要。一次局部修改可能暂时绕过了问题，但相关模块仍有历史债务；模型如果能把这些边界写清楚，代码审阅者就能判断本次是否可以合入，还是需要拆出后续任务。

• 影响范围：说明涉及哪些应用、包、接口或类型。
• 验证命令：给出最小测试、类型检查或构建命令。
• 回归风险：说明哪些功能需要人工点检。
• 未处理事项：说明哪些问题没有在本次范围内解决。

十二、把成功提示词沉淀成项目模板

一旦某个大仓接入流程跑顺，建议把有效提示词沉淀成项目模板。模板不需要很长，但要保留目录白名单、禁止范围、输出格式、验证要求和配置卡名称。这样下一次处理同类问题时，不必重新设计任务边界。

模板字段：
任务**：
涉及目录：
禁止目录：
允许修改文件：
使用配置卡：
期望输出：
验证命令：

模板还能帮助团队形成统一习惯。不同成员使用相同结构描述任务，Codex 的输出也更容易被审阅和复盘。

十三、完整接入顺序

• 第一步：从灵能API官网 https://www.lnsns.com/ 确认 API *ase、模型和账号状态。
• 第二步：为大仓画目录地图，标出应用、共享包、服务、配置和文档目录。
• 第三步：在 CC Switch 里按只读、调试、修改、跨模块分析建立配置卡。
• **步：写清目录白名单、禁止范围和允许修改文件。
• 第五步：先做只读扫描，再做单模块定位，最后放开小范围修改。
• 第六步：每次输出都要求影响范围、验证命令和未处理事项。
• 第七步：把有效提示词沉淀成项目模板，供团队复用。

✅ 十四、结语：大仓不是越多上下文越好

大仓项目接入 Codex API 中转站，核心不是把所有文件一次性喂进去，而是让模型沿着正确边界逐步理解。目录地图、配置卡、白名单、只读扫描、局部修改、验证清单，这些步骤能让灵能API和 CC Switch 的组合更适合真实工程场景。

当你把任务边界设计清楚，Codex 的输出会更稳定，改动也更容易审阅。大仓协作不怕复杂，怕的是边界模糊。先把边界写下来，再让模型在边界内工作，这才是大项目里更可靠的接入方式。