我把代码排查流程做成了一个 Codex Skill

摘要

把常用代码排查流程沉淀成 Codex Skill，可以减少重复提示词，让排查从证据、调用链、修改到验证保持一致。它适合本地多仓库项目、接口问题、前端状态问题和提交支付链路排查。

问题背景

日常开发里，很多问题并不是"代码不会改"，而是每次排查都要重新提醒一遍上下文。

比如：

先看当前目录是不是聚合目录
不要只看页面显示，要看真实接口 payload
支付问题要确认有没有真正走到原生支付调用
前端弹框问题要检查同模块的兄弟弹框
修完以后要说清楚验证了什么，哪些还没真机验证

这些要求如果每次都写在对话里，会很长，也容易漏。更麻烦的是，代码排查通常有很强的路径依赖。前面少看一步，后面就可能修到表象上。

我最后采用的方案是：把"项目排查流程"做成一个独立的 Codex Skill，再把"以后排查默认使用这个 Skill"写入记忆。

Skill 负责可复用流程，记忆负责长期偏好和项目经验。两者分开之后，既不会让 Skill 变得臃肿，也能让项目经验持续积累。

为什么原始做法不够好

原始做法通常是靠长提示词约束模型：

text 复制代码

帮我排查这个问题，先看 git status，不要覆盖我的改动；
要看真实接口参数，不要只看 UI；
支付问题要看 requestPayment；
弹框问题要检查同类弹框；
最后要跑检查并说明未验证项。

这类提示词短期能用，但长期会有几个问题。

第一，重复成本高。每次新会话都要重新写一遍。

第二，容易不完整。临时描述往往只覆盖当下问题，忘记一些长期积累的坑。

第三，流程和项目经验混在一起。比如"排查 bug 要先看证据"是通用流程，而"某类移动端支付问题重点看金额、数量、支付单号"是项目经验。全部写进一段提示词里，后续维护会很乱。

所以更合适的拆法是：

Skill：固化通用排查流程
Memory：记录个人偏好和项目经验
当前 prompt：只描述这一次具体问题

最后采用的方案

我创建了一个个人级 Skill，名称是：

text 复制代码

project-debugging

它的触发场景覆盖本地代码排查中最常见的几类问题：

yaml 复制代码

name: project-debugging
description: Repo-grounded debugging workflow for Codex. Use when investigating or fixing project bugs, incorrect UI state, wrong API payloads, payment or submit-flow failures, frontend page behavior, build/startup issues...

这个 description 很重要。Codex 判断是否启用 Skill，主要靠这里。它不能只写"debug helper"，而要写清楚具体触发场景。

Skill 的核心目标很简单：

text 复制代码

Drive bug work from evidence to a verified fix.
Prefer current code paths, real request payloads, screenshots, logs, and runtime behavior over titles, assumptions, or surface UI state.

也就是让排查从证据开始，而不是从猜测开始。

关键流程设计

我把流程拆成 6 步：

text 复制代码

1. Orient in the workspace.
2. Treat user evidence as primary.
3. Trace the real execution path.
4. Edit narrowly.
5. Verify with the strongest available checks.
6. Report precisely.

这 6 步分别解决不同问题。

1. 先确认工作区

很多本地项目不是单仓库，而是一个聚合目录。直接在顶层跑命令，可能会误判项目结构。

所以 Skill 里第一步要求：

text 复制代码

Confirm cwd, repository boundaries, and whether the folder is an aggregate workspace with subrepos.
Run git status before editing. Preserve user changes and do not revert unrelated files.
Use rg or rg --files first for searches.

这个约束能减少两类事故：

在错误目录里查代码
不小心覆盖用户已有改动

2. 用户证据优先

真实排查里，用户给的截图、请求体、报错日志往往比标题更可靠。

Skill 里写的是：

text 复制代码

Read screenshots, request bodies, error text, terminal logs, and named files before hypothesizing.
For API or submit bugs, compare visible UI state with the actual payload-building path.
Do not call a fix complete just because the UI displays success.

这个规则尤其适合接口、提交、支付类问题。页面显示成功，不代表真实链路成功。真正要看的是：参数怎么组、接口怎么调、返回怎么处理、有没有进入最终执行路径。

3. 追真实执行路径

很多前端 bug 看起来是 UI 问题，本质是状态或生命周期问题。

所以流程里要求定位：

text 复制代码

page entry
shared helpers
state mutation
payload assembly
API wrapper
response handling

如果是支付问题，还要检查：

text 复制代码

amount
quantity
payment method
pay-order id extraction
native payment call path

这个设计的价值在于，它把"看起来像什么问题"和"代码真实怎么执行"分开了。

Skill 和记忆怎么配合

Skill 不适合塞太多历史细节。否则它会变成一份又长又难维护的内部知识库。

我只在 Skill 里保留少量项目提示，比如：

text 复制代码

In D:\workspace\project, distinguish backend, web, and mobile subprojects.
For popup bugs, check sibling popups in the same feature.
For payment bugs, verify amount, quantity, pay-order id, and native payment call path.

而记忆里只写一条长期偏好：

text 复制代码

For future code development debugging tasks, default to using the personal project-debugging Codex skill when available.
Combine that skill's workflow with cwd-specific memory before investigating bugs, submit-flow issues, payment problems, frontend state issues, startup/build errors, or repo-grounded troubleshooting.

这样设计以后，维护成本会低很多：

通用排查方法变了，改 Skill
某个项目踩了新坑，写 Memory
当前问题的特殊要求，写在当前对话

常见坑

description 写得太泛

如果 description 只写：

yaml 复制代码

description: Debug project issues.

触发效果会很差。更好的写法是把场景写具体：

yaml 复制代码

description: Use when investigating project bugs, incorrect UI state, wrong API payloads, payment failures, submit-flow failures, frontend page behavior, or build/startup issues.

Skill 的正文只有触发后才会加载，所以"什么时候用"必须放在 description 里。

把项目知识都塞进 Skill

这会让 Skill 越来越重。更稳的方式是：

Skill 写流程
Memory 写项目经验
具体任务写当前证据

只做 Skill，不写记忆

Skill 能让流程稳定，但它不知道你希望以后默认优先使用它。写一条轻量记忆，可以让后续代码排查更容易进入同一套工作流。

没有校验 Skill

创建完 Skill 后，最好跑一次校验：

powershell 复制代码

python path\to\quick_validate.py path\to\project-debugging

如果在 Windows 上遇到编码问题，可以用 UTF-8 模式重试：

powershell 复制代码

$env:PYTHONUTF8='1'
python path\to\quick_validate.py path\to\project-debugging

实际工作流里的价值

这个 Skill 最适合下面几类任务：

接口参数和页面显示不一致
支付或提交链路没有走到真实执行路径
前端按钮禁用、弹框滚动、页面返回状态异常
本地启动、依赖安装、包管理器不匹配
多仓库项目里分不清真实代码目录

它不会替代具体判断，但能把排查起点固定下来。每次 Codex 接手问题时，先看证据、再追调用链、再小范围修改、再验证。这比每次靠临时提示词提醒要稳定。

最后总结

我对这类开发效率工具的判断是：先沉淀高频流程，再考虑外部增强。

对代码开发者来说，最先值得做的不是找一个复杂插件，而是把自己每天都在重复强调的排查规则变成 Skill。它足够轻，不依赖第三方服务；也足够贴近实际项目，能直接减少沟通成本。

这次的核心做法可以概括成一句话：

text 复制代码

用 Skill 固化排查流程，用 Memory 保存项目经验，用当前 prompt 描述具体问题。

这样 Codex 才更像一个熟悉你工作方式的开发助手，而不是每次都要重新入职一次。