接手旧项目时怎么让 Codex 读懂仓库？

旧项目最怕“先改了再说”。把仓库上下文整理清楚，再让 Codex 分段阅读和验证，效率会比直接丢一个模糊需求高很多。

用户场景：你刚拿到一个没人敢动的仓库

很多项目没有完整文档，只有一堆目录、脚本、环境变量和历史补丁。新同事接手时，如果直接让 Codex “帮我优化这个项目”，它会缺少边界：不知道哪些文件能改，哪些接口不能动，也不知道应该用什么命令验证。正确做法是先喂给 Codex 可检查的上下文，而不是让它猜。

这里的重点不是让 Codex 一次读完整个仓库，而是建立一个稳定入口。一次只确认一类信息：技术栈、启动方式、配置来源、核心业务流、测试命令和部署位置。每一步都有输出，后续改代码才有依据。

第一步：整理仓库地图

先让 Codex 列出顶层目录、主要语言、框架、入口文件和构建脚本。输出不要太散，建议固定为表格：路径、用途、是否可修改、验证方式。比如 server 负责后端服务，pages 负责静态内容，tests 负责回归检查，scripts 负责部署辅助。仓库地图越清晰，后续任务越不容易越界。

如果项目有 AI API 接入逻辑，还要单独标记模型调用位置：请求封装、模型名配置、错误处理、日志记录和限流策略。很多旧项目的问题不是模型能力不足，而是调用入口散落在多个文件里，排查时找不到统一边界。

第二步：补齐运行和验证命令

让 Codex 找 package.json、requirements、Makefile、PowerShell 脚本或 CI 配置，整理出最小可运行命令。每条命令都要有用途，例如安装依赖、启动开发服务、运行单元测试、检查格式、构建产物。不要只写“运行测试”，要写清楚具体命令和预期结果。

如果仓库涉及 CCSwitch 配置或本机 Codex 接入，记录 API 地址、模型名来源和 Key 的安全位置即可，不要把密钥写进文档。多人协作时，可以结合 团队模型调用管理清单 给每个入口标注负责人。

第三步：把需求拆成可验证任务

旧项目维护最好避免一句话大需求，例如“帮我重构支付模块”或“把后台优化一下”。更稳的表达是：先让 Codex 找到相关文件，再说明要改的行为，再要求它写出验证步骤，最后才允许改代码。一个好任务通常包含四个部分：问题现象、涉及页面或接口、不能破坏的行为、完成后的检查命令。

站长类项目还可以把上线后检查纳入任务闭环。页面状态、sitemap、robots 和乱码检查可以参考 站长日常巡检流程，但代码仓库接手阶段更关注本地验证是否可靠。

接手检查清单

• 仓库地图包含入口文件、配置文件、测试目录和部署脚本。
• 每个 AI 模型接口调用入口都能定位到文件和负责人。
• 开发者 AI 调用不会把密钥写入仓库或提交记录。
• 每个修改任务都有明确验证命令，不只依赖肉眼检查。
• Codex 输出的改动先小范围验证，再进入上线流程。

一个可复用提示词

“请先阅读当前仓库结构，只输出项目地图、运行命令、测试命令、AI API 接入位置和风险点。不要修改文件。每个结论给出文件路径依据，并指出下一步最适合拆成哪些小任务。”这个提示词能让 Codex 先做分析，再进入实现，适合接手旧项目的第一天使用。