一、先理解上下文工程：不是给得越多越好
很多团队第一次用 Codex 分析项目时，会把“上下文充足”理解成“尽量多给文件”。实际效果往往相反：仓库越大，无关代码越多，模型越容易把历史逻辑、废弃模块、测试夹具和当前任务混在一起。输出看起来很完整，但真正能执行的建议并不多。
上下文工程的核心，是让 Codex 看到足够但不冗余的信息。它需要知道任务目标、相关文件、调用链、约束条件、已有测试和不允许触碰的边界。少了这些，它会猜；多了无关内容，它会**扰。
通过灵能API统一接入后，团队可以把 Codex 的使用方式从“临时问答”升级为“按任务组织上下文”。这一步做好了，后续无论是代码**、日志分析、文档生成还是测试补全，输出都会更稳定。
- 上下文太少，模型容易凭空补全。
- 上下文太多，模型容易抓错重点。
- 上下文刚好，输出才更容易复核和落地。
二、统一接入入口：先把链路问题和上下文问题分开
在优化上下文之前，先确认接入链路是稳定的。很多看起来像“模型不理解项目”的问题，其实来自 *ase **L 写错、模型权限不足、Key 失效、网络超时或配置卡混用。链路没稳定，上下文再精细也很难判断效果。
建议团队从 https://www.lnsns.com/ 进入灵能API控制台，确认当前接入说明和可用模型。团队文档中只保留入口、变量名、负责人和复核规则，不写完整密钥。这样能让新成员知道从哪里配置，也能避免敏感信息进入仓库。
链路验证通过后，再进入上下文设计。这样排查时会很清楚：如果最小任务失败，先看接入；如果最小任务成功但复杂任务质量差，再看上下文范围和提示词。
- 连接失败先查入口、Key、模型和网络。
- 连接正常但答案发散，再查上下文。
- 接入配置和任务提示要分开维护。
️ 三、给仓库做分层：哪些文件适合进入上下文
**仓库里的文件并不都适合交给 Codex。业务代码、类型定义、接口文档、测试用例、配置示例通常有价值；依赖目录、构建产物、缓存文件、压缩包、历史导出、真实密钥和大体积日志通常不该进入上下文。
可以把仓库文件分成四层：核心上下文、辅助上下文、排除上下文、敏感上下文。核心上下文直接影响任务判断；辅助上下文用于补充**；排除上下文会干扰分析；敏感上下文必须隔离，不应该被读取或输出。
仓库上下文分层
核心上下文：src/、packages/、api/、sche**s/、tests/
辅助上下文：do**/、README、CHANGELOG、examples/
排除上下文：node_modules/、dist/、*uild/、coverage/、.cache/
敏感上下文：.env、*.pem、secret.*、credentials.json、未打码日志分层之后，提示词就可以写得更精确。比如“只读取 src/modules/order、tests/order 和 do**/api/order.md，不读取 dist、coverage 和任何 .env 文件”。这类约束比一句“请注意安全”有效得多。
- 核心上下文用于判断任务。
- 辅助上下文用于补充**。
- 敏感上下文必须从规则层面隔离。
四、先做索引说明：让 Codex 知道项目地图
在大型仓库里，直接让 Codex 分析具体问题之前，可以先准备一份项目索引说明。索引说明不是复制所有代码，而是告诉模型各目录负责什么、核心模块在哪里、测试在哪里、文档在哪里、哪些目录不要读取。
索引说明最好由团队维护，而不是每次都让模型重新猜。它可以放在 do**/codex-context.md 之类的位置，作为所有 Codex 任务的前置说明。内容保持简洁，重点写目录职责、常见任务入口和禁止读取范围。
## Codex 项目索引
- src/modules/order：订单业务逻辑
- src/modules/payment：支付和退款逻辑
- src/api：接口请求封装
- src/types：前端类型定义
- tests：单元测试和接口测试
- do**/api：接口说明
禁止读取：.env、dist、coverage、node_modules、未打码生产日志- 项目索引说明要短，不要变成完整架构文档。
- 索引中必须写清楚禁止读取范围。
- 目录职责变化后，要同步更新索引。
⚙️ 五、用 CC Switch 固定上下文任务配置
上下文工程也需要配置卡。日常问答、仓库分析、PR 预审、文档生成对模型和权限的要求不同，不应该都走一张默认配置。CC Switch 可以帮助团队把这些场景拆开，减少误用。
配置卡可以命名为 Lingneng-Codex-Context-Read 或 Lingneng-Codex-Repo-Review。备注里写清楚：默认只读、优先读取索引说明、禁止读取敏感文件、输出必须列出引用到的文件范围、无法确认的结论必须标记待确认。
配置卡备注建议
用途：**仓库上下文分析
权限：默认只读
优先读取：do**/codex-context.md
禁止读取：.env、secret.*、credentials.json、dist、coverage
输出要求：列出已读取文件、结论依据、待确认问题
复核要求：涉及权限、账务、生产事故的结论必须人工确认- 配置卡要写用途和禁止范围。
- 上下文分析默认只读。
- 输出要列出依据，方便评审人追溯。
六、最小样本验证：先让 Codex 读一个模块
不要一开始就让 Codex 分析整个仓库。最小样本可以选择一个边界清晰的模块，比如订单、会员、支付、消息通知。让它读取模块代码、对应测试和接口文档，输出模块职责、关键流程、风险点和待确认事项。
最小样本的意义，是测试“给定范围内的理解质量”。如果单模块都输出空泛，说明索引说明、文件选择或提示词还需要调整；如果单模块稳定，再扩展到跨模块调用链会更稳。
最小样本提示词
请只读取以下范围：
- do**/codex-context.md
- src/modules/order/
- tests/order/
- do**/api/order.md
输出：
1. 模块职责
2. 关键调用流程
3. 已覆盖测试
4. 潜在风险点
5. 需要人工确认的问题
限制：不读取 .env、dist、coverage、node_modules，不修改文件。- 先验证单模块，再做跨模块。
- 输出必须列出已读取范围。
- 不确定结论必须进入待确认。
七、提示词结构：用六段式减少误读
上下文任务的提示词不能只写“帮我看看这个项目”。稳定的写法应该包含六段：角色、目标、读取范围、排除范围、输出结构、复核规则。六段都写清楚，Codex 才更容易把注意力放在正确位置。
角色用于限定视角，例如代码**助手、接口文档助手、测试用例助手；目标用于限定任务；读取范围告诉它看哪里；排除范围告诉它不要看哪里；输出结构保证结果可读；复核规则提醒它哪些结论不能直接定稿。
六段式提示词
角色：你是团队仓库上下文分析助手。
目标：理解订单模块的接口、测试和风险点。
读取范围：do**/codex-context.md、src/modules/order、tests/order、do**/api/order.md。
排除范围：.env、dist、coverage、node_modules、未打码日志。
输出结构：模块职责、调用链、测试覆盖、风险点、待确认事项。
复核规则：权限、账务、生产事故相关结论必须标记待确认。- 提示词先写范围，再写任务。
- 排除范围必须明确列出。
- 复核规则要写在提示词里，不靠事后提醒。
八、敏感文件隔离：安全边界必须前置
**仓库里最危险的不是业务代码，而是容易被误读、误传、误输出的敏感文件。比如 .env、证书、账号凭据、生产日志、用户数据导出、内部访问地址。上下文工程必须先定义安全边界，再谈输出质量。
安全边界要落到三层：仓库忽略规则、任务提示词、复核检查。仓库层面不要把敏感文件放进可读范围；提示词层面明确禁止读取和输出；复核层面检查生成内容中是否出现密钥、账号、真实用户数据或内部地址。
敏感隔离清单
[ ] .env 不进入上下文
[ ] 证书和私钥不进入上下文
[ ] 生产日志必须打码后再分析
[ ] 用户数据导出不直接提供给模型
[ ] 输出结果不包含完整密钥、账号凭证和内部地址
[ ] 截图中的敏感字段已遮挡使用灵能API统一入口接入，并不意味着可以忽略本地上下文安全。入口解决调用路径，敏感文件隔离解决输入边界。两者配合，才能让团队放心地把 Codex 放进真实项目流程。
- 敏感文件默认不读。
- 生产日志先脱敏再分析。
- 输出结果也要做残留检查。
九、控制上下文成本：长上下文要按价值使用
上下文越长，成本和等待时间通常越高，输出也不一定更好。团队需要把长上下文作为资源管理，而不是默认选项。短任务只给关键片段，标准任务给模块范围，深度任务才读取更完整的调用链。
可以把任务分成三档：短上下文、模块上下文、跨模块上下文。短上下文用于错误解释和命令说明；模块上下文用于接口、测试、文档；跨模块上下文用于架构分析、复杂事故复盘和发布风险评估。
上下文长度策略
短上下文：日志片段、错误码、单个函数
模块上下文：一个业务模块、对应测试、接口文档
跨模块上下文：调用链、配置、测试、发布说明、历史变更
默认规则：能用短上下文解决的，不升级到跨模块上下文。- 上下文长度要和任务价值匹配。
- 高频任务优先短上下文。
- 跨模块上下文建议手动触发。
十、输出要带依据：让每个结论能回到文件
Codex 输出的结论如果没有依据，复核成本会很高。评审人看到“这里可能有权限风险”，还要回头找是哪个文件、哪段逻辑、哪个接口导致的。上下文任务应要求输出结论时同时列出依据位置。
依据不需要复杂到精确行号，但至少要包含文件名、模块名、相关函数或接口。对于无法确认的内容，要明确标注“没有在当前上下文中找到依据，需要人工确认”。这样可以防止猜测混进确定结论。
结论输出格式
结论：订单取消接口存在状态边界风险
依据：src/modules/order/cancel.ts，tests/order/cancel.spec.ts
说明：测试覆盖了已支付订单，但未看到已发货订单的取消断言
建议：补充已发货状态的接口测试
状态：需要人工确认业务规则- 每条结论都要有依据。
- 没有依据的内容要标记待确认。
- 依据越清楚，复核越快。
十一、建立上下文模板库：让团队不用每次重写提示词
当团队发现某类上下文任务反复出现，就应该把提示词沉淀成模板。比如单模块理解、接口变更分析、测试缺口扫描、错误日志复盘、发布风险评估，都适合放进模板库。
模板库的重点不是堆很多提示词，而是让每个模板都有明确使用场景、输入范围、输出结构和复核要求。模板越清晰，新成员越容易正确使用，历史结果也越容易比较。
模板库目录建议
templates/
module-sum**ry.prompt.md
api-change-review.prompt.md
test-gap-scan.prompt.md
error-log-review.prompt.md
release-risk-check.prompt.md
每个模板包含：适用场景、读取范围、排除范围、输出结构、复核规则模板库可以和 CC Switch 配置卡配合使用。配置卡负责模型和入口，模板负责任务语言和边界。两者分工清楚后，团队不会每次都从零组织提示词。
- 高频任务模板化。
- 模板必须包含排除范围。
- 模板变更要记录版本和原因。
十二、复核与迭代：根据结果修正上下文，而不是只改提示词
当 Codex 输出不理想时，很多人第一反应是改提示词。但上下文工程里，问题可能不在提示词，而在输入范围。也许缺少测试文件，也许给了过期文档，也许包含了废弃目录，也许没有告诉它哪部分是当前版本。
建议每次复核都记录两个问题：这次缺了什么上下文？这次多给了什么干扰内容？前者用于补充索引，后者用于更新排除规则。这样上下文质量会逐步变好，而不是每次靠临场调整。
复核记录模板
任务：订单模块接口变更分析
结果问题：模型把旧接口当成当前接口
缺失上下文：缺少 do**/api/order-v2.md
干扰上下文：读取了 legacy/order-old.ts
修正动作：更新项目索引，标注 legacy 为排除范围
确认人：后端负责人- 输出不好时，先检查上下文范围。
- 缺失内容进入索引，干扰内容进入排除规则。
- 每次复核都让下一次任务更准。
✅ 十三、收尾：上下文工程做好，Codex 才会越用越稳
Codex 接入 Claude中转 后，真正决定长期效果的不是单次提示词写得多漂亮，而是团队能不能持续提供准确、干净、可追溯的上下文。上下文工程做得好，模型会更少猜测，评审人也更容易复核。
落地顺序可以很清楚：先通过灵能API确认统一入口，再建立仓库分层和索引说明，然后用 CC Switch 固定上下文任务配置，接着从单模块样本验证，最后把提示词模板、敏感隔离和复核记录沉淀下来。
当团队不再随手把整个仓库丢给模型，而是按任务选择上下文、按规则排除敏感文件、按依据复核结论，Codex 就会从“偶尔灵光的助手”变成稳定的工程协作能力。
- 先统一入口，再治理上下文。
- 先做单模块验证，再扩展跨模块分析。
- 先隔离敏感文件，再进入团队流程。
