用 Context Engineering 的思路排查线上问题
最近处理一个遗留项目的生产问题，让我对 Claude、Codex 这类 AI Coding 工具在诊断线上环境问题有了一些心得。
背景：一个我并不熟悉的老项目
这次问题来自一个几年前开发完成的项目。项目本身已经不是团队当前主要开发对象，但还有客户在持续使用。
这类项目有几个典型特点：
- 前端、后端、App、固件都有自己的代码和逻辑。
- 部署方式和运行环境可能已经不是团队日常最熟悉的那套。
- 原始开发人员未必随时可问。
- 文档可能不完整，或者已经跟当前线上状态有偏差。
- 客户仍然在用，所以问题必须尽快定位和解决。
我自己并不熟悉这个项目，也没有办法花很多时间从头学习它的完整架构和基本原理。客户遇到的问题：某个用户前一天还能使用，第二天开始页面上没有出现操作按钮。后台配置看起来正常，服务端接口也没有明显报错。最好能快速看现场视频、查日志、理解链路，然后尽快给出判断。
这也是我最想分享的点：在不熟悉项目的情况下，如何让 Claude / Codex 这类 AI Coding 工具快速进入状态，并且真的帮上忙。
第一件事：尽可能提供完整代码上下文
对复杂系统来说，只给后端代码通常不够。
如果问题涉及端到端链路，最好能让 AI 看到所有相关代码：
- 前端代码
- 后端代码
- App 代码
- SDK 代码
- 固件或设备侧协议代码
不用担心AI会一次性读完所有代码，它的能力已经足够在必要时候进行深度搜索、跳转、关联。部署脚本、配置文件、API 文档、历史排查记录 —— 这些其实不需要。因为这些都可以通过代码得出结论。用代码做Single Source of Truth更好。
第二件事：提供客户项目背景和部署方式
代码之外，还需要业务和部署上下文。比如客户的租户名称、账号清单、权限配置情况。但是这些信息提供起来比较麻烦，因为我对客户的一些具体的配置到底是标准化的还是定制化的，我不太了解。我唯一能给出的是这个客户的租户ID和受影响用户ID。其他的需要AI根据代码的使用链路，自己去后台或数据库里查询。当时大概有三种选择。
第一种，是直接让 AI 访问生产数据库。 第二种，是调用生产环境 API。 第三种，是让 AI 使用我的账号登录浏览器，直接查看客户项目配置。
我最后选了第三种，也不是因为哪种更好，而是这种方式最简单，不需要去搞 APIKEY，也不需要搞readonly的数据库账号。
这里用到了Chrome Dev Tools MCP
第三件事：告诉 AI 日志在哪里，并给它 CLI
这次我用的是观测云的 CLI。
排查生产问题，日志位置非常关键。最好明确告诉 AI：后端 API 日志、App 日志、前端监控、设备或固件日志、第三方调用日志分别在哪里，以及日志里的关键字段是什么，request id、user id、device id 怎么关联。
如果日志量不大，可以直接导出给 AI。但真实生产日志往往很大，不可能一次性塞进聊天窗口，这时候 CLI 就很关键。
CLI 的价值在于：AI 不需要我手工复制大量日志给它，而是可以直接查询云端日志仓库。让 AI 从被动阅读，变成主动查询。
AI自动排查的效果：
它很细地查每一段日志：权限预取有没有成功，App 有没有离线，蓝牙扫描有没有发生，有没有识别到目标设备，有没有创建本地 session，有没有建立连接，有没有写入 token，有没有上报最终事件。我把几天的工作量压缩成了半小时，并且给出了非常准确的结论。
一次排查结束后，如果所有结论只留在聊天记录里，很快就会丢失。可以用Compound Engineering的SKILL沉淀solution 文档，形成可复用经验。
核心收获
第一，AI 需要完整上下文：代码、项目背景、部署方式、业务场景、关键概念和时间窗口。 第二，要给 AI 进入现场的工具，尤其是日志查询 CLI。没有日志入口，AI 只能猜；有了 CLI，它才能逐段排除。 第三，不能直连数据库时，可以让 AI 通过 Chrome DevTools MCP 查看后台页面。后台本身就是业务配置的解释层。 第四，尽可能使用视觉模型。很多后台配置不是 JSON，而是表格、标签、状态、按钮和弹窗。 第五，人的作用不是手工查每一行日志，而是补上下文、审查AI的行动路径。 最后，排查结束后要沉淀，把结论写成 solution 文档，让这次上下文变成下次可复用的经验。
