AI 编程 Agent 很容易把一个简单需求扩展成一套新框架：只有一个实现却先建接口，只有一种策略却加工厂，为一个固定值增加配置中心，或者为了未来可能出现的场景提前设计多层抽象。代码可以运行，但维护成本、测试范围和故障面都被放大。

Ponytail 是一套面向编程 Agent 的最小实现规则、生命周期 Hook 和 Skills。它要求 Agent 先理解真实调用链，再依次判断能否不做、复用现有实现、使用标准库、平台原生能力或已有依赖，最后才编写完成当前需求所必需的最少代码。

本文从 Codex 安装和模式切换开始，结合供应链系统中的库存释放、采购审批、报表导出和幂等消费，讲清楚如何使用 Ponytail 控制改动范围，以及哪些正确性和安全能力绝对不能被“精简”。

一、Ponytail是什么

Ponytail 不是模型、代码搜索引擎、静态分析器或自动重构工具。它主要由三部分组成：

1. 行为规则：定义 Agent 写代码前应经过的最小实现决策阶梯。
2. 生命周期 Hook：在会话启动和子 Agent 启动时注入当前规则。
3. Skills：提供模式切换、过度设计审查、全仓审计和技术债清单等命令。

它解决的是“Agent 应该构建多少东西”，而不是“Agent 是否理解整个代码库”。如果 Agent 没有先读懂业务调用链，Ponytail 也可能让它在错误位置提交一个很小但不完整的补丁。因此其核心原则是：

1
2
3

先完整理解问题
  -> 再选择最省的正确方案
  -> 保留必要的校验、安全和测试

在供应链系统里，这一点尤其重要。一条库存释放逻辑可能由订单取消、支付超时、售后退款和人工关闭共同调用。最小正确改动可能是在共享领域服务增加一次幂等控制，而不是只在某个 Consumer 里增加一行判断。

二、Ponytail的决策阶梯

Ponytail 要求 Agent 在编码前从上到下判断，命中第一种可行方案后停止继续扩展：

1. 需求是否真的需要实现：纯推测需求遵循 YAGNI，暂不构建。
2. 项目里是否已有实现：优先复用现有 Helper、领域服务、约束和团队模式。
3. 标准库是否支持：使用 JDK、框架标准 API 或语言内置能力。
4. 平台原生能力是否支持：数据库约束、HTML 原生控件、操作系统能力优先。
5. 现有依赖是否支持：复用已安装依赖，不为几行逻辑新增库。
6. 是否一行即可完成：一行足够就不创建新的层次。
7. 最后才编写最小可用实现。

例如“采购单号不能重复”，不应该先写一个分布式锁框架。决策阶梯可能得到：

1
2
3
4
5

需求需要存在
  -> 项目没有统一防重组件
  -> JDK不能跨实例保证唯一
  -> 数据库唯一约束可以原子保证
  -> 使用UNIQUE KEY，不新增分布式锁

对应的数据库迁移：

1
2
3

ALTER TABLE purchase_order
ADD CONSTRAINT uk_purchase_order_tenant_no
UNIQUE (tenant_id, purchase_order_no);

应用层仍然需要把唯一键冲突转换为明确的业务错误，但不需要自己实现一套先查后写的锁协议。

三、在Codex中安装Ponytail

1. 安装插件

在终端执行两个独立命令：

1
2

codex plugin marketplace add DietrichGebert/ponytail
codex plugin add ponytail@ponytail

Ponytail 的 Codex 插件使用轻量生命周期 Hook，因此 node 需要位于非交互 Shell 的 PATH 中：

1
2

node --version
Get-Command node

如果 Node.js 不可用，Skills 仍可能被发现，但会话自动激活与规则注入不会完整工作。

2. 检查并信任Hook

启动 Codex 后打开：

1

/hooks

审阅 Ponytail 注册的 Hook 脚本和路径，确认来源是已安装插件后再授权。Hook 能在会话生命周期中注入指令，属于高信任扩展，不应该对来源不明的插件直接点击允许。

Codex 桌面版安装后需要重启应用，再新建一个任务，使插件和 Hook 按新会话加载。

3. 验证插件

在 Codex 中调用帮助 Skill：

1

@ponytail-help

然后查看当前模式：

1

@ponytail

Codex 使用 @skill-name 方式调用 Skill。其他 Agent 可能使用 /ponytail 斜杠命令，文章或截图里的命令需要按实际宿主转换。

4. 卸载

1

codex plugin remove ponytail

插件可能在用户配置目录保留模式配置或状态文件。需要彻底清理时，应先按官方卸载说明运行仓库提供的清理脚本，再移除插件，避免插件删除后脚本也消失。

四、选择lite、full、ultra和off

Ponytail 提供三个工作强度和一个关闭状态：

在 Codex 中可以这样表达：

1
2
3

@ponytail lite
@ponytail full
@ponytail ultra

关闭时使用：

1

stop ponytail

或者在支持斜杠命令的宿主中使用 /ponytail off。

供应链核心链路建议默认使用 full，不要把 ultra 当作常驻模式。库存、支付、采购金额和对账逻辑通常存在大量非功能约束；过于激进地追求删除，可能把必要的并发控制、审计和补偿路径误判为冗余。

五、配置默认模式

默认模式是 full。临时设置环境变量：

1
2

$env:PONYTAIL_DEFAULT_MODE="lite"
codex

Linux 或 macOS：

1
2

export PONYTAIL_DEFAULT_MODE=lite
codex

也可以写入用户配置。Windows 默认位置：

1

%APPDATA%\ponytail\config.json

内容：

1
2
3

{
  "defaultMode": "full"
}

macOS 和 Linux 默认位置：

1

~/.config/ponytail/config.json

优先级为：

1
2
3

PONYTAIL_DEFAULT_MODE环境变量
  > config.json的defaultMode
  > full

团队不应把个人的全局模式当作项目规则。项目必须保留自己的 AGENTS.md，明确哪些校验、事务和测试属于业务底线，无论 Agent 使用什么模式都不能删除。

六、供应链案例：导出采购到货差异报表

需求如下：

在采购到货差异页面增加 CSV 导出，字段与当前列表一致，最多导出 5000 条。

普通 Agent 容易新增：

• ReportExporter 接口。
• CsvReportExporter 实现。
• ExporterFactory。
• 新的 CSV 第三方依赖。
• 异步任务、进度表和下载中心。
• 为未来 Excel 和 PDF 格式预留策略。

但当前需求只有一个格式、固定字段和明确上限。Ponytail full 应先检查项目已有能力：

1
2
3
4

使用 Ponytail full 完成采购到货差异CSV导出。
先搜索项目现有导出实现和已安装依赖，再决定是否新增代码。
不得改变列表筛选口径，最多5000条，保留权限与CSV注入防护。
先给出最小方案，确认后实现。

如果订单模块已经使用 Apache Commons CSV，那么最小方案通常是复用该依赖和现有响应工具，不再新增抽象：

1
2
3
4
5
6

@GetMapping(value = "/arrival-differences/export", produces = "text/csv")
public void export(ArrivalDifferenceQuery query, HttpServletResponse response) throws IOException {
    permissionService.checkCanViewProcurement(query.tenantId());
    List<ArrivalDifferenceRow> rows = reportService.query(query.withLimit(5000));
    csvResponseWriter.write(response, "arrival-differences.csv", rows);
}

这里的“最小”不是把所有逻辑塞进 Controller。reportService.query 和 csvResponseWriter 已存在，所以直接复用。权限校验、数据上限、编码、转义和 CSV 公式注入防护不能为了减少行数而删掉。

什么时候才引入异步导出？可以设定可观测触发条件：

• 单次导出超过同步网关超时时间。
• 数据量从 5000 增长到百万级。
• 用户明确需要历史任务、重试和下载留存。
• 导出计算明显影响在线数据库。

触发前不构建任务中心，就是 YAGNI；触发后仍坚持同步导出，则变成忽视真实约束。

七、供应链案例：修复重复库存释放

假设 OrderCancelledConsumer 重复收到消息，导致库存释放两次。最危险的“最小补丁”是只在 Consumer 内用内存 Set 记住事件 ID：

1

private final Set<String> processed = ConcurrentHashMap.newKeySet();

它代码很少，但多实例、重启和事务回滚后都不可靠。Ponytail 明确要求先理解完整调用链，最小方案必须是最小正确方案。

应该先问：

1
2
3
4

使用 Ponytail full 修复重复库存释放。
先追踪 OrderCancelledConsumer 到库存余额和流水的真实调用链，查找项目已有幂等组件。
不得使用JVM本地集合，不新增分布式锁，除非现有事务方案无法满足。
同一事件只能释放一次，并且幂等记录、库存余额、库存流水必须原子提交。

如果项目已有 ProcessedEventExecutor，应复用它：

1
2
3
4
5
6
7
8

@Transactional
public void onMessage(OrderCancelled event) {
    processedEventExecutor.runOnce(
        "ORDER_CANCELLED",
        event.eventId(),
        () -> inventoryReleaseService.release(event.orderId())
    );
}

数据库层保留唯一约束：

1
2

CREATE UNIQUE INDEX uk_processed_event_consumer_id
ON processed_event (consumer_name, event_id);

这比新建 Redis 锁服务更小，也比 JVM 内存 Set 更正确。还必须验证：

• runOnce 与库存写入是否在同一个事务传播范围。
• 唯一键冲突是否按“已经处理”返回，而不是重试失败。
• 业务异常回滚时幂等记录是否一起回滚。
• 同一订单的不同合法事件是否不会互相阻塞。
• 至少有重复事件和事务回滚测试。

Ponytail 的“Bug fix = 修根因，不修症状”在这里体现为：公共幂等边界的一处正确修复，比在每个 Consumer 增加不同判断更少、更稳定。

八、用AGENTS.md建立不可精简的底线

在供应链项目根目录加入：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# Supply Chain Engineering Rules

## Minimal Implementation
- 优先复用项目已有领域服务、Validator、Repository和测试工具。
- 不为单一实现新增接口、工厂或策略注册中心。
- 不为固定值增加配置项，不为推测需求搭建扩展框架。
- 新增依赖前必须证明JDK、Spring、数据库和现有依赖无法解决。

## Never Simplify Away
- 租户、仓库、数据权限和信任边界输入校验。
- 库存非负约束、幂等键、唯一键和并发条件更新。
- 采购单与订单状态机校验。
- BigDecimal金额计算、舍入规则和币种口径。
- 本地事务、Outbox事件、审计流水和防数据丢失错误处理。
- 核心逻辑至少一个可运行测试，公共契约必须保留回归测试。

## Change Scope
- 修改前追踪真实调用链和全部调用者。
- 每次只完成当前需求，不顺便重构无关模块。
- 删除公共能力前，先证明没有生产调用者和反射、配置入口。

这份文件负责业务安全边界，Ponytail 负责实现风格。两者组合后，Agent 不会把“最短 diff”误解为“删掉所有看起来复杂的东西”。

九、ponytail-review：检查当前改动

完成编码后调用：

1

@ponytail-review

这个 Skill 只关注过度设计，常见标签包括：

• delete：死代码、未使用扩展点和推测功能。
• stdlib：手写了标准库已有的能力。
• native：依赖或代码重复平台原生能力。
• yagni：单实现接口、没人设置的配置和只有一个调用者的层。
• shrink：同一逻辑可以明显减少代码。

供应链 PR 中可以这样调用：

1
2
3
4
5
6
7

@ponytail-review
只审查当前 git diff 是否存在：
1. 单实现接口和只有一个产品的工厂；
2. 重复已有幂等组件或CSV导出组件；
3. 为未来格式、未来仓库类型建立的未使用扩展点；
4. 可由数据库唯一约束替代的应用层防重代码。
不要把事务、权限、审计、幂等和必要测试标记为可删除。

必须再执行一次普通代码审查。官方 Skill 明确把正确性、安全和性能问题排除在 Ponytail Review 范围之外。因此完整顺序是：

1
2
3
4

Ponytail审查过度设计
  -> 普通审查正确性与回归
  -> 安全与数据一致性审查
  -> 运行测试

不要因为 @ponytail-review 没有发现问题，就判断代码可以上线。

十、ponytail-audit：审计整个仓库

@ponytail-audit 会扫描整个代码库，按可删除规模排序，适合治理历史过度设计：

1
2
3
4

@ponytail-audit
审计 procurement-service 的过度设计，只输出报告，不修改代码。
优先寻找单实现接口、纯转发包装器、未使用配置、重复工具类和已有标准能力的手写实现。
排除数据权限、审计、事务、补偿、幂等和外部系统适配层。

对于大型供应链仓库，不建议第一次就扫描全部模块。可以按域分批：

1. 采购询报价模块。
2. 采购订单模块。
3. 库存预占模块。
4. 仓储作业模块。
5. 对账与结算模块。

每个发现都要验证真实调用者、运行时配置和生产流量。审计报告只是候选删除清单，不会自动证明代码无用，也不会自动应用修改。

十一、用ponytail-debt管理有边界的简化

有些需求可以先采用简单方案，但必须写清容量上限和升级触发条件。例如补货任务当前只有单实例，可以使用全局锁：

1
2
3
4

// ponytail: 单实例全局锁；部署多实例或任务等待超过30秒时升级为数据库租约锁
synchronized void generateReplenishmentSuggestions() {
    generator.generate();
}

这条注释不是鼓励永久留下临时实现，而是记录：

• 简化了什么。
• 当前上限在哪里。
• 什么指标触发升级。
• 下一步应该采用什么方案。

调用债务 Skill：

1

@ponytail-debt

它会读取 ponytail: 注释并形成清单，同时标记没有触发条件的高腐化风险条目。需要持久化时，可以要求写入 PONYTAIL-DEBT.md，再由团队在迭代计划中评审。

以下注释不合格：

1

// ponytail: 以后优化

它没有容量上限、指标或升级路径，等同于不可执行的 TODO。

十二、建立团队级Ponytail工作流

阶段1：先理解需求和调用链

1
2

读取需求、AGENTS.md和相关源码，追踪入口到数据库或外部系统的真实流程。
列出业务不变量、信任边界和现有可复用组件。只分析，不编码。

Ponytail 不负责代码索引。大型项目可以配合 CodeGraph，或者使用 Codex 内置搜索和读取工具完成这一步。

阶段2：逐级判断

要求 Agent 输出简短的决策记录：

1
2
3
4
5
6
7

按 Ponytail 阶梯判断：
- 是否需要实现；
- 项目内已有能力；
- JDK/Spring/数据库原生能力；
- 已安装依赖；
- 最小新增代码。
说明命中的最高层以及被跳过的抽象。

阶段3：限定改动范围

1
2
3

只修改 inventory-service 内与幂等消费直接相关的文件。
不升级依赖，不创建新框架，不重构无关命名。
保留事务、唯一约束、库存流水和现有日志。

阶段4：验证

非简单一行代码至少留下一个可运行检查。供应链核心逻辑通常不应只满足这个最低标准，而要按风险增加测试：

• 重复消息测试。
• 并发库存扣减或释放测试。
• 事务回滚测试。
• 多租户和越权测试。
• 金额边界和舍入测试。
• 数据库迁移兼容性测试。

阶段5：双重审查

1

@ponytail-review

然后再执行：

1

按正常代码审查标准检查当前diff，重点检查正确性、并发、事务、幂等、权限、日志泄密和测试缺口。

十三、哪些东西不能为了少写而删除

以下能力通常看起来“啰嗦”，但在供应链系统中属于真实复杂度：

1. 信任边界校验

来自 API、消息队列、Excel 导入和外部 ERP 的数据都不可信。租户、仓库、SKU、数量、币种和状态必须校验。

2. 防止数据丢失的错误处理

库存写入成功但事件发送失败、采购单更新成功但审计记录失败，都会形成不可追踪状态。Outbox、本地事务和可重试错误分类不能为了减少文件数而删除。

3. 安全与权限

数据权限、审计、脱敏、SQL 参数化和密钥隔离不是过度设计。即使只有一个调用者也必须保留。

4. 必要的业务抽象

单实现接口不一定都多余。外部 WMS、ERP、支付网关的 Adapter 接口可以隔离外部契约；领域端口也可能承担依赖倒置和测试替身职责。判断依据是它是否形成真实边界，而不是实现数量。

5. 可运行验证

金额、解析器、分支、循环、并发和安全逻辑必须有测试。最少代码不等于没有回归证据。

十四、何时暂停Ponytail

以下场景可以暂时切换到 lite 或 off：

• 架构探索阶段需要比较多个方案，而不是立即实现。
• 法规、审计或客户合同明确要求完整文档和控制措施。
• 系统正处于故障处置，需要先保守止损再讨论最小重构。
• 迁移任务要求双写、影子流量和回滚通道，代码增量本身就是风险控制。
• 用户明确要求一个完整扩展框架，并且已确认多个真实实现方。

暂停规则不是放弃工程约束。即使 Ponytail 关闭，也应继续限制无关改动并运行完整验证。

十五、常见问题

安装后没有自动生效

检查 Node.js 是否在 PATH，在 /hooks 中审阅并信任 Hook，然后重启 Codex 并新建任务。

Agent仍然创建很多文件

明确使用 full，并在提示中列出禁止项：

1

使用 Ponytail full。禁止单实现接口、工厂、未来配置和新依赖；先复用项目现有模式。

同时检查需求本身是否真的要求跨模块改动。有时文件多是业务边界造成的，不是过度设计。

Agent删掉必要校验

这是错误使用，不是合格的 Ponytail 结果。把不可删除项写入 AGENTS.md，恢复校验并补充回归测试。Ponytail 官方规则明确禁止精简信任边界校验、安全和防数据丢失错误处理。

Review报告与普通Review冲突

Ponytail Review 只讨论复杂度。正确性、安全和性能结论应以普通代码审查与测试证据为准。

ultra模式一直拒绝需求

切回 full 或 lite。ultra 适合挑战推测需求，不适合所有生产开发。如果用户已经明确坚持完整需求，Agent 应执行，而不是反复争论。

十六、评估是否产生价值

可以连续统计十个真实 PR：

• 每个需求新增和删除的有效代码行。
• 修改文件数量。
• 新增依赖数量。
• 新增接口、工厂、配置项数量。
• Code Review 中的过度设计意见数量。
• 正确性缺陷和回滚次数。
• 从任务开始到测试通过的时间。

评价标准不能只有“代码行更少”。如果行数下降但缺陷增加，说明团队把最小实现误用了。理想结果是：改动范围更小、依赖更少、验证不下降、生产缺陷不增加。

总结

Ponytail 提供的是一套可持续执行的 YAGNI 与复用优先机制。它让 Agent 在新增代码前先检查项目、标准库、平台和现有依赖，并通过 review、audit 和 debt Skills 把过度设计治理延伸到提交之后。

在供应链项目中，正确用法是“完整理解，最小实现，保留业务底线”。库存幂等、事务、权限、金额精度、状态机、审计和测试不是可以随意裁剪的复杂度。Ponytail 应减少人为制造的复杂度，而不是否认业务本身的复杂度。

参考资料

• Ponytail官方仓库
• Ponytail决策阶梯与模式说明
• Ponytail Codex安装说明
• Ponytail Agent可移植性说明

AI 编程 Agent 在小项目里可以靠搜索文件和阅读源码完成任务，但到了供应链系统，订单、库存、采购、仓储和结算往往跨越多个模块。Agent 如果只看到一个 Controller 或一个报错堆栈，很容易在错误的位置打补丁，遗漏调用者、异步入口和回归测试。

CodeGraph 的作用，就是先把代码库索引成可以查询的关系图。Agent 不再从零开始遍历目录，而是通过 MCP 一次获取相关符号、源码、调用路径和改动影响范围。本文从安装、索引和查询开始，逐步讲到 Java 供应链项目的调用链分析、影响评估、测试选择、团队治理和常见故障。

本文介绍的是 colbymchenry/codegraph 项目。CodeGraph 不是大模型，也不会替代编译器、测试和人工业务审查；它是部署在本机的代码索引与查询层。

一、CodeGraph解决什么问题

传统 Agent 理解代码一般经过以下过程：

1. 使用文件搜索找到可能相关的类。
2. 打开文件并查找方法名。
3. 继续搜索调用者和实现类。
4. 猜测跨文件依赖和影响范围。
5. 上下文不足时重复搜索和读取。

CodeGraph 会预先提取以下信息并写入本地 SQLite 图数据库：

• 文件、类、接口、方法、函数和变量等符号。
• import、引用、调用者和被调用者等关系。
• 接口到实现、回调等动态分派线索。
• 与符号关联的原始源码和行号。
• 全文搜索索引。
• 修改某个符号时可能传播到的影响范围。

它把工作模式变成：

1
2
3
4
5

用户问题
  -> Agent调用codegraph_explore
  -> CodeGraph查询本地SQLite知识图谱
  -> 返回相关源码 + 调用路径 + 影响范围
  -> Agent基于完整上下文制定修改方案

CodeGraph 默认只向 MCP 客户端展示一个工具：codegraph_explore。这是有意设计的，避免 Agent 在多个粒度相近的工具之间选错。CLI 仍然提供 query、node、callers、callees、impact 和 affected 等细分命令，适合人工排查和 CI 脚本。

二、安装CLI并接入Codex

1. 选择安装方式

Windows 可以运行官方 PowerShell 安装器：

1

irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

生产办公环境不建议直接执行未审阅的远程脚本。已经安装 Node.js 时，可以使用更容易审计和固定版本的 npm 方式：

1
2

npm install -g @colbymchenry/codegraph
codegraph version

macOS 和 Linux 也可以使用 npm，或者使用官方安装器：

1
2

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
codegraph version

独立 CLI 带有自己的运行时；只有把 CodeGraph 作为 JavaScript 库嵌入应用时，才需要满足它对 Node.js 运行时的额外要求。

2. 把MCP服务接入Codex

安装 CLI 不等于已经接入 Agent。执行：

1

codegraph install --target=codex --location=global --yes

这一步会配置 Codex 启动 codegraph serve --mcp，并写入一小段带标记的使用说明。也可以直接运行交互式安装器：

1

codegraph install

在交互界面选择 Codex，以及全局或当前项目配置。全局配置适合个人开发机；项目级配置适合团队希望随仓库统一管理的场景。

安装完成后重启 Codex。不要手工启动 MCP Server，正常情况下由 Agent 客户端按配置启动。

3. 为项目创建索引

进入供应链项目根目录：

1
2
3

cd D:\projects\supply-chain-platform
codegraph init
codegraph status

codegraph init 会创建 .codegraph/ 并完成第一次全量索引。codegraph install 是每台机器执行一次，codegraph init 则是每个项目执行一次，两者不要混淆。

一个 Maven 多模块项目可以从共同根目录索引：

1
2
3
4
5
6
7

supply-chain-platform/
  pom.xml
  order-service/
  inventory-service/
  procurement-service/
  warehouse-service/
  supply-chain-common/

如果每个微服务是独立仓库，就分别在各仓库执行 codegraph init。Agent 查询另一个已索引项目时，可以向 MCP 工具传递 projectPath。

三、验证索引是否可用

首先查看统计信息：

1

codegraph status

然后使用 CLI 做三组最小验证：

1
2
3

codegraph files --max-depth 3
codegraph query InventoryReservationService --kind class --limit 10
codegraph node InventoryReservationService

接着进行一次结构化查询：

1

codegraph explore "订单取消后，调用如何到达库存预占释放和库存流水写入"

正确结果应包含相关源码片段、文件位置和调用关系，而不是只返回文件名。如果提示没有初始化，确认当前目录或 projectPath 指向含有 .codegraph/ 的项目。

最后在 Codex 中输入：

1
2
3

使用 CodeGraph 分析订单取消到库存释放的完整调用路径。
列出入口、应用服务、领域服务、Repository、数据库写入点和相关测试。
只分析，不修改文件。

这一步验证 Agent 确实能够调用 MCP，而不是退回普通文件搜索。

四、掌握常用查询命令

1. 搜索符号

1
2

codegraph query reserveInventory
codegraph query OrderCancelledConsumer --kind class --json

query 适合名称已知但位置未知的情况。供应链项目中常用于寻找库存预占、采购审批、波次生成和对账入口。

2. 查看一个符号的上下文

1
2

codegraph node InventoryReservationService
codegraph node inventory-service/src/main/java/com/example/inventory/InventoryReservationService.java

参数是符号时返回源码和关系；参数是文件时返回带行号源码。

3. 查看调用者和被调用者

1
2

codegraph callers releaseReservation
codegraph callees cancelOrder

callers 回答“谁依赖它”，callees 回答“它内部继续调用谁”。重构公共库存方法之前，必须先看调用者；分析一条业务链路时，则从入口向下查看被调用者。

4. 查询完整业务流

1

codegraph explore "OrderCancelApplicationService如何调用库存释放，失败后如何回滚"

自然语言查询要包含业务动作和至少一个真实符号，结果通常比“解释库存模块”更稳定。例如：

1
2
3
4
5

分析 PurchaseOrderApprovalService.approve：
1. 它如何校验供应商和采购金额；
2. 如何更新采购单状态；
3. 如何写入Outbox事件；
4. 哪些调用者和测试依赖该方法。

5. 分析改动影响

1

codegraph impact releaseReservation --depth 4

影响分析适合修改公共领域方法、DTO、Mapper 和事件对象之前使用。深度越大，结果越多；应该从 2 或 3 开始，确认方向后再扩大，而不是一次把整个图塞进上下文。

五、供应链案例：定位重复库存释放

假设线上出现以下问题：同一条 OrderCancelled 消息被重复消费后，库存流水出现两条释放记录。

不要直接让 Agent 修改 Consumer。先要求建立事实：

1
2
3
4
5
6
7
8

使用 CodeGraph 分析 OrderCancelledConsumer.onMessage 到库存预占释放的调用链。
重点回答：
1. 事件ID和订单ID在哪里进入系统；
2. 幂等校验发生在哪一层；
3. 库存余额和库存流水是否在同一事务；
4. 还有哪些入口会调用同一个 release 方法；
5. 现有项目里是否已有 ProcessedEventExecutor 或类似组件。
只返回证据和文件位置，不修改代码。

理想的分析输出应形成类似链路：

1
2
3
4
5

OrderCancelledConsumer.onMessage
  -> InventoryReleaseApplicationService.release
  -> InventoryReservation.release
  -> InventoryReservationRepository.updateReleasedQty
  -> InventoryLedgerRepository.append

然后反向查询公共方法：

1
2

codegraph callers InventoryReleaseApplicationService.release
codegraph impact InventoryReleaseApplicationService.release --depth 4

如果结果显示超时关单、人工取消和售后退款都调用该方法，那么只在 Kafka Consumer 外层增加临时判断并不完整。应该继续确认真正共享的幂等边界。

再搜索已有能力：

1

codegraph explore "项目中哪些消息消费者使用 ProcessedEventExecutor 保证幂等，它与本地事务如何组合"

如果采购模块已有经过验证的幂等执行器，复用它通常比新建 Redis 锁、分布式锁框架或第二套消费记录表更可靠。但必须确认它是否把幂等记录和业务变更放在同一个本地事务中，不能只因为类名相似就直接套用。

六、把CodeGraph融入Agent开发流程

一套可靠的工作流可以分成五个阶段。

阶段1：结构探索

1
2
3

使用 CodeGraph 定位本需求的入口、核心符号、调用路径、持久化点和测试。
如果某段关系来自配置、消息Topic或运行时反射，明确标记为待人工确认。
不修改代码。

阶段2：影响评估

1
2
3

对计划修改的每个公共方法执行影响分析。
列出直接调用者、间接调用者、跨模块依赖和可能受影响的测试。
将确定关系与推测关系分开。

阶段3：制定小步方案

1
2
3

基于已确认的调用链给出最小实施方案。
说明为什么修改这个边界，而不是只修改报错入口。
保留库存非负、状态机、幂等和审计流水等业务不变量。

阶段4：实施和同步

CodeGraph 默认监听文件变化并增量更新。保存代码后等待短暂的 debounce 时间，再执行：

1

codegraph status

如果状态显示待同步文件，或者运行环境禁用了后台进程，可以手工执行：

1

codegraph sync

阶段5：验证

1
2
3

根据当前 git diff 和 CodeGraph 影响范围选择测试。
先运行被修改模块的单元测试，再运行跨模块集成测试。
最后进行普通正确性、安全和数据一致性审查。

CodeGraph 提供证据，但不会证明实现正确。编译、测试、数据库约束和业务验收仍然是发布门禁。

七、使用affected选择回归测试

codegraph affected 会沿 import 依赖寻找可能受改动影响的测试文件：

1
2

git diff --name-only origin/master...HEAD |
  codegraph affected --stdin --filter "**/*Test.java" --quiet

也可以直接传入文件：

1
2
3

codegraph affected inventory-service/src/main/java/com/example/inventory/InventoryReservationService.java `
  --depth 5 `
  --filter "**/*Test.java"

在 Java 多模块项目里，建议把输出路径映射为 Maven 模块，再运行对应模块测试。例如：

1
2

inventory-service/.../InventoryReservationServiceTest.java
order-service/.../OrderCancellationIntegrationTest.java

可以转换为：

1

mvn -pl inventory-service,order-service -am test

测试选择只能减少无关测试，不能替代核心业务测试集。库存并发、幂等消费、事务回滚和金额计算应保留固定回归套件，即使依赖图没有选中也要执行。

八、索引范围与项目配置

CodeGraph 默认排除依赖、构建和缓存目录，也会遵循 .gitignore，并跳过大文件。对于已提交但不应该索引的生成代码，可以在项目根目录创建 codegraph.json：

1
2
3
4
5
6
7

{
  "exclude": [
    "**/target/**",
    "warehouse-service/src/generated/**",
    "frontend/static/vendor/**"
  ]
}

如果某些真实源码因为其他版本控制系统被 .gitignore 排除，可以显式包含：

1
2
3
4
5
6

{
  "include": [
    "legacy-erp-adapter/src/",
    "local-contracts/"
  ]
}

非标准扩展名也可以映射到受支持语言：

1
2
3
4
5
6

{
  "extensions": {
    ".tpl": "php",
    ".dota_lua": "lua"
  }
}

修改扩展映射后运行全量索引：

1

codegraph index --force

索引范围应覆盖真实业务代码，但不要把 target/、生成客户端、压缩资源和第三方 SDK 全部塞进去，否则结果会被噪声淹没。

九、在AGENTS.md里约束使用方式

CodeGraph 安装器会写入基础说明，供应链项目还应补充团队自己的规则：

1
2
3
4
5
6
7
8
9
10
11
12
13

## CodeGraph Workflow
- 回答结构、调用链和影响范围问题时，优先使用 codegraph_explore。
- 修改公共 Java 方法前，必须检查调用者和影响范围。
- CodeGraph 返回待同步提示时，直接读取该文件的最新内容。
- Kafka Topic、Spring 运行时代理、反射和外部系统调用必须额外核对配置。
- 图中没有关系不等于业务上没有关系。

## Supply Chain Invariants
- 可用库存不得小于 0。
- 同一幂等键只能产生一次库存流水。
- 采购单状态只能按状态机迁移。
- 金额、税额和数量计算禁止使用浮点数。
- 写业务数据和 Outbox 事件必须处于同一本地事务。

这样可以防止 Agent 把图查询结果当成绝对真相，也能确保它在供应链场景中检查真正重要的业务不变量。

十、隐私、安全与遥测

CodeGraph 索引和查询本身在本机完成，数据库使用 SQLite，不需要上传源码到 CodeGraph 服务。但还要区分两个数据路径：

1. CodeGraph 本地解析源码并返回查询结果。
2. Agent 把返回的源码片段放进模型上下文。

第二步是否离开本机，取决于 Codex 使用的模型和企业数据策略。因此“CodeGraph 本地运行”不等于“源码永远不会进入远程模型”。敏感仓库仍应使用组织允许的模型、网络策略和凭证隔离。

CodeGraph 会询问是否启用匿名使用统计。需要关闭时执行：

1
2

codegraph telemetry off
codegraph telemetry status

CI 中也可以设置：

1
2

$env:CODEGRAPH_TELEMETRY="0"
$env:DO_NOT_TRACK="1"

不要让 Agent 索引或读取 .env、密钥、生产数据导出、供应商银行信息和客户隐私数据。索引工具不是权限边界，文件系统权限和仓库治理才是。

十一、能力边界

CodeGraph 擅长静态结构和源码关系，但以下场景必须谨慎：

• 通过字符串拼接决定的类名、方法名和路由。
• Spring 容器运行时选择的 Bean 和复杂代理链。
• Kafka Topic、RabbitMQ Routing Key 等仅靠字符串连接的异步链路。
• MyBatis 动态 SQL、存储过程和数据库触发器。
• 跨仓库、跨语言、外部 SaaS 和 ESB 流程。
• 运行时生成代码、脚本注入和反射调用。

遇到这些边界，应把 CodeGraph 结果与配置文件、日志、链路追踪、数据库 Schema 和集成测试结合，而不是让 Agent 补全它想象中的链路。

十二、常见问题排查

codegraph命令不存在

重新打开终端，检查安装目录是否进入 PATH：

1
2

Get-Command codegraph
codegraph version

Codex里没有CodeGraph工具

重新执行安装并重启 Codex：

1

codegraph install --target=codex --location=global --yes

确认 Agent 配置中的命令是 codegraph serve --mcp。不要在另一个终端长期手工运行 Server。

提示项目没有初始化

1
2
3

cd D:\projects\supply-chain-platform
codegraph init
codegraph status

修改后找不到新符号

先等待自动同步，再检查：

1
2

codegraph status
codegraph sync

确认文件没有被 .gitignore、默认排除目录或 codegraph.json 排除。

Windows和WSL共用项目出现锁问题

不要让 Windows 与 WSL 同时使用同一个 .codegraph/ SQLite 索引。可以为 Windows 设置独立目录：

1
2

$env:CODEGRAPH_DIR=".codegraph-win"
codegraph init

WSL 保留默认 .codegraph/，或者把 Linux 项目放在 WSL 原生文件系统中。

后台进程不稳定

在受限环境中可以禁用共享后台进程：

1

$env:CODEGRAPH_NO_DAEMON="1"

此时每个会话独立运行，并在必要时手工执行 codegraph sync。

十三、团队落地建议

建议按以下顺序推广：

1. 先在一个中型 Java 服务中试点，不要一次索引所有历史仓库。
2. 选择三类真实任务：调用链解释、公共方法重构、线上问题定位。
3. 记录 Agent 工具调用数、理解阶段耗时、遗漏调用者数量和回归缺陷。
4. 建立统一的 AGENTS.md 规则和索引排除项。
5. 把影响分析接入 PR 检查，但保留固定核心回归测试。
6. 定期运行 codegraph upgrade --check，先在试点仓库验证再统一升级。

不要只用“节省了多少 Token”评价 CodeGraph。对供应链系统更有价值的指标，是是否少漏掉一个库存入口、是否在修改前发现了共享调用者、是否把回归测试选到了正确模块。

总结

CodeGraph 的价值不是替 Agent 写代码，而是让 Agent 在写代码前拥有更接近工程师的项目地图。它通过本地预索引，把符号、调用关系、源码和影响范围组合成可查询上下文。

在供应链项目中，推荐固定采用“查询业务流、检查公共调用者、评估影响范围、实施小步修改、运行核心回归”的闭环。图谱负责缩短发现路径，编译、测试、数据约束和人工审查负责证明结果可信。

参考资料

• CodeGraph官方仓库
• CodeGraph CLI与MCP工具说明
• CodeGraph项目配置说明
• CodeGraph Telemetry完整说明

为什么单次 Agent 还不够

这两年大家使用 AI 编程助手的方式变化很快。最开始是 prompt engineering：想办法把一句提示词写得更清楚。后来是 context engineering：想办法把项目背景、代码结构、接口文档、错误日志都给到 AI。再往后是 skill：把重复的工作流沉淀成 SKILL.md，让 AI 在合适场景自动调用。

到了 2026 年，越来越多人开始讨论 Loop engineering。它不是一个单独的插件，也不是某个固定命令，而是一种新的 AI 协作方法论：不再由人一轮一轮地提示 AI，而是设计一个循环，让 AI 能围绕目标持续执行、观察结果、修正策略，直到达到停止条件。

一句话说，Loop engineering 就是把 AI 编程从“一次性生成代码”，变成“目标、执行、验证、反馈、修正、停止”的工程闭环。

Loop engineering 是什么

Loop engineering 可以理解为“设计 AI agent 的工作循环”。一个好的 loop 至少包含五个部分。

目标：明确这次循环要完成什么，什么情况下算完成。

上下文：告诉 AI 当前项目规则、代码结构、业务背景、历史决策和约束。

行动：让 AI 执行一个小步骤，比如读代码、写 spec、改一个切片、跑一个测试。

观察：把测试结果、错误日志、diff、接口响应、CI 状态反馈给 AI。

停止条件：测试通过、验收清单完成、连续失败、超出预算、需要人工确认时停止。

如果没有观察和停止条件，所谓 loop 只是“让 AI 一直跑”。这很危险。真正的 Loop engineering 强调的是可验证、可回滚、可暂停、可复盘。

它和几个相近概念的区别也很清楚：

1
2
3
4

Prompt engineering：优化单次输入。
Context engineering：准备更好的上下文。
Skill engineering：把重复动作沉淀成技能。
Loop engineering：把多个动作组织成持续运行的反馈闭环。

所以 Loop engineering 不是替代 prompt、context、skill，而是把它们组织起来。

Loop engineering 怎么用

一个最小可用的 loop 可以这样设计：

1
2
3
4
5
6
7

1. 明确目标：我要修复某个 bug，或者完成某个业务切片。
2. 准备上下文：项目规则、相关代码、测试命令、验收标准。
3. 执行一小步：只改一个模块或一个测试。
4. 运行验证：测试、构建、接口调用、diff review。
5. 反馈结果：把失败日志或 diff 交给 AI。
6. 修正策略：继续改、回滚、拆小、提问或停止。
7. 达成条件：所有验收通过后结束。

这里最重要的是“小步”。很多人用 AI 失败，不是因为模型不行，而是一次给了太大的任务。比如“重构库存系统”就太大了，应该拆成：

1
2
3
4
5
6
7

库存锁定模型
库存释放流程
库存流水表
订单幂等键
并发扣减测试
异常回滚测试
报表口径调整

每个小切片都能单独验证，loop 才不会失控。

我会把常用组件这样组合：

OpenSpec/OPSX：负责把需求变成可追踪的规格。

Superpowers skills：负责澄清、计划、TDD、调试、review。

Codex：负责读代码、改代码、跑命令、看 diff。

持续目标：在支持目标管理的 Codex 界面中使用对应能力；其他环境则用普通任务说明明确目标、预算和停止条件。

Automations：负责让某些 loop 定时运行，比如每天检查失败测试、未处理 issue、CI 错误。

Git worktree：负责隔离多个并行 loop，避免互相改乱。

状态文件：负责记录做过什么、失败过什么、下一步是什么。

用 Codex 实践 Loop engineering

用 Codex 做 Loop engineering，关键不是让它“无限执行”，而是把目标和停止条件写清楚。

一个比较实用的 Codex loop 可以长这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

目标：
完成采购到货差异处理的第一阶段：差异可记录。

上下文：
- 读取 AGENTS.md、README.md、pom.xml；
- 读取采购、到货、质检、库存相关模块；
- 参考已有 Controller、Service、Mapper、DTO、测试写法；
- 严格遵守项目现有风格。

循环步骤：
1. 先用 /opsx:propose 生成 change artifacts；
2. 用 brainstorming skill 澄清差异类型；
3. 用 writing-plans skill 拆任务；
4. 用 test-driven-development skill 先写测试；
5. 实现一个切片；
6. 运行相关测试；
7. 用 requesting-code-review skill 审查 diff；
8. 失败时用 systematic-debugging skill 修复；
9. 全部验收后 /opsx:verify、/opsx:sync、/opsx:archive。

停止条件：
- 差异记录相关测试全部通过；
- diff 只包含计划内文件；
- 验收清单全部完成；
- 如果连续两轮同一测试失败，停止并输出阻塞原因。

如果当前 Codex 界面支持持续目标，可以把目标写成可验证条件；否则直接把同样的内容作为普通任务说明。不要假设 /goal 是所有 Codex 版本都支持的通用命令：

1
2
3
4
5
6
7
8
9

请持续推进下面的目标，并在满足停止条件时结束：
持续推进采购到货差异处理第一阶段，直到满足：
1. 已生成 OpenSpec change；
2. 已完成差异类型、差异记录表、差异登记逻辑；
3. 相关单元测试和集成测试通过；
4. 当前 diff 已通过 requesting-code-review skill 检查；
5. 没有无关重构和未说明的新依赖。

如果遇到业务口径不确定、测试连续失败或需要凭证访问外部系统，请停止并总结阻塞点。

这类目标说明的重点是“直到满足什么”，而不是“帮我一直做”。没有停止条件的 loop 容易造成成本失控，也容易让变更逐渐偏离原始范围。

供应链系统案例

假设供应链系统要做“采购到货差异处理”。业务背景是：采购单下了 100 件，实际只到了 80 件，或者到了 110 件，或者其中 10 件质检不合格。系统需要记录差异，并影响库存、财务暂估和报表。

这个需求如果一次性让 AI 实现，很容易失控。我们可以设计三层 loop。

第一层，规格 loop。

1
2
3
4
5
6
7
8
9
10

/opsx:propose purchase-receipt-discrepancy

请先生成 proposal、design、tasks、specs，不写业务代码。
必须覆盖：
少到、多到、不合格；
到货单、差异单、质检结果；
库存入库和待处理区；
财务暂估数量；
报表统计口径；
幂等、事务、并发、回滚。

这一层的 loop 不是写代码，而是让需求变清楚。它的停止条件是：spec 能回答接口、数据、状态、异常、验收。

第二层，计划 loop。

1
2
3
4

请使用 writing-plans skill 细化 tasks.md。
每个任务控制在 2 到 5 分钟可完成。
每个任务必须包含：
文件路径、修改内容、验证方式、回滚风险。

计划 loop 会把大需求拆成：

1
2
3
4
5
6
7
8
9
10

任务1：新增差异类型枚举。
任务2：新增差异记录表。
任务3：新增差异记录 Mapper。
任务4：补少到场景测试。
任务5：实现少到差异登记。
任务6：补多到场景测试。
任务7：实现多到差异登记。
任务8：补不合格品测试。
任务9：实现不合格品待处理逻辑。
任务10：审查财务暂估和报表影响。

第三层，实现 loop。

每个任务都走同样的循环：

1
2
3
4
5
6
7

取一个任务
-> 先写或确认测试
-> 最小实现
-> 跑测试
-> 看 diff
-> code review
-> 通过后进入下一个任务

以“少到差异登记”为例：

1
2
3
4

请使用 test-driven-development skill 实现少到差异登记。
先写测试：
采购单数量 100，实际到货 80，应生成少到差异 20。
测试先失败后，再写最小实现。

如果测试失败：

1
2
3

请使用 systematic-debugging skill 分析失败。
不要直接改代码。
先输出失败断言、实际值、相关 SQL、可能根因和最小修复方案。

实现后：

1
2
3
4
5
6
7

请使用 requesting-code-review skill 审查当前 diff。
重点看：
1. 是否只改了少到差异相关文件；
2. 是否影响多到和不合格逻辑；
3. 事务边界是否正确；
4. 重复请求是否会重复生成差异；
5. 测试是否覆盖异常场景。

这个过程看起来慢，但大需求最怕的不是慢，而是一路快到错误方向。Loop engineering 的价值，就是让每一轮都有证据。

Loop engineering 的局限性

第一，成本会变高。

loop 会反复读代码、跑测试、审 diff、修错误，token 和时间成本都比一次性生成高。解决办法是控制 loop 粒度：只让它处理一个切片；给出最大轮数；失败两次就停；不要把整个仓库都塞进上下文。

第二，停止条件很难写。

“把库存做好”不是停止条件，“库存预占相关 12 个测试通过，diff 不包含无关文件，review 没有 P0/P1 问题”才是停止条件。解决办法是把完成定义写成可检查清单，最好能对应测试、命令或具体文件。

第三，AI 会产生理解债。

loop 跑得越快，人越容易不看代码，最后系统变了但自己没理解。解决办法是每个 loop 结束必须输出变更摘要、设计决策、风险点和人工验收清单；关键业务代码必须人工 review。

第四，错误会被自动放大。

如果 spec 一开始错了，loop 会持续围绕错误目标努力。解决办法是把 propose、plan、apply 分开，在 spec 阶段用 requesting-code-review 审查，必要时先暂停。

第五，环境依赖会卡住。

外部系统、数据库权限、测试数据、接口凭证都可能让 loop 无法继续。解决办法是提前定义阻塞条件：缺凭证、缺数据、连续失败、外部系统不可达时停止，并输出需要人工补充的内容。

第六，并行 loop 会互相干扰。

多个 agent 同时改同一个模块，很容易冲突。解决办法是使用 git worktree 隔离，按业务边界拆任务，并限制每个 loop 的文件范围。

总结

Loop engineering 的本质，是把 AI 编程从“人不断提示 AI”，升级成“人设计一个可验证的循环系统”。这个系统会发现任务、执行任务、观察结果、修正错误，并在满足条件时停止。

对 Codex 来说，Loop engineering 可以落到很具体的实践：用 OpenSpec 写规格，用 Superpowers skills 管过程，用 /goal 维持目标，用测试和 diff 做反馈，用人工 review 控住业务风险。

但它不是银弹。loop 越自动，越需要明确目标、边界、验证和停止条件。真正可靠的 Loop engineering，不是让 AI 替你思考，而是让 AI 在你设计好的工程轨道里持续前进。

参考资料

• Loop Engineering - Addy Osmani
• What Is Loop Engineering? The New Meta for AI Coding Agents
• OpenSpec OPSX commands
• obra/superpowers
• OpenAI Codex best practices

效率提升来自流程而非单次生成

前面几篇文章里，我写了 AI 编程助手、AI Agent 工作流，以及普通开发者使用 AI 时需要守住的边界。写到 Codex 这一篇时，我更想把它写成一篇可以反复翻回来的实践笔记。

Codex 这类工具和普通聊天机器人不太一样。普通聊天机器人更像一个问答窗口，你问一句，它答一句；Codex 更像一个可以进入项目、阅读代码、修改文件、运行命令、解释结果的开发协作者。OpenAI 官方把 Codex 描述为用于软件开发的 coding agent，可以帮助写代码、理解陌生代码库、review 代码、调试问题和自动化开发任务。

但工具越强，越不能随便用。很多人第一次用 Codex，会把它当成“高级代码生成器”：给一句需求，期待它马上给出完美代码。这样当然偶尔能成功，但不稳定。真正稳定提升效率的方法，是把 Codex 放进一套清楚的工程流程里：准备上下文、明确任务、让它先计划、让它小步实现、跑测试、看 diff、复盘沉淀。

下面这 10 个技巧，是我理解里最适合普通开发者落地的用法。

技巧一：把需求写成一个小 issue，而不是一句口号

很多人对 Codex 的第一句提示是：“帮我优化一下代码。”这句话的问题不是太短，而是没有验收标准。什么叫优化？是性能变快、代码更短、结构更清楚，还是减少重复？如果没有边界，Codex 只能猜。

更好的写法，是把任务写成一个小 issue：

1
2
3
4
5

目标：给订单列表增加按状态筛选功能。
范围：只改订单列表页和相关查询参数，不调整全局路由。
验收：页面出现状态筛选框；选择状态后列表刷新；刷新页面后筛选条件保留。
验证：运行 npm test，并手动检查订单列表页。
限制：不要重构无关组件，不要修改接口返回结构。

这种写法看起来啰嗦，但它会显著降低返工。Codex 最怕的不是任务复杂，而是任务含糊。你越能把“想要什么”和“不要什么”说清楚，它越容易给出可 review 的结果。

我的经验是：凡是超过十分钟的开发任务，都值得先写成小 issue。即使最后不是交给 Codex 做，这个过程也能帮自己想清楚。

技巧二：为仓库准备 AGENTS.md，把长期规则沉淀下来

如果每次都在提示里重复“项目用 pnpm”“测试命令是 npm test”“不要改 public 目录”“提交前要跑 lint”，时间久了会很烦，而且容易漏。

Codex 支持通过 AGENTS.md 这类仓库说明文件获得项目规则。你可以把它理解成给 AI 看的 README：告诉它项目结构、常用命令、代码风格、测试方式、哪些目录不能动、遇到失败时如何处理。

一个简单的 AGENTS.md 可以这样写：

1
2
3
4
5
6
7

# 项目规则

- 文章源码在 source/_posts。
- 静态资源放在 source/images。
- public 是生成目录，非必要不要手写修改。
- 修改文章后需要运行生成命令，并检查 archives 页面。
- 保持 Markdown front matter 格式：title/date/tags。

这类规则越早沉淀，后面越省心。Codex 做得不稳定，很多时候不是模型能力问题，而是项目没有把“好结果长什么样”告诉它。

技巧三：先让 Codex 读代码和写计划，不要直接开改

面对一个真实项目，我不建议第一步就让 Codex 修改文件。更稳的方式是先让它做两件事：

第一，阅读相关代码并总结当前结构。

第二，给出准备修改的计划。

比如可以这样说：

1
2

先不要修改代码。请阅读和用户登录相关的文件，说明当前登录流程、
token 存储位置、错误处理方式，然后给出最小修改计划。

这一步的价值很大。它能让你提前发现 Codex 是否找对了入口、是否理解了业务、是否准备改错层级。如果计划已经偏了，就不要让它继续实现。

对复杂任务来说，“先计划再实现”比“直接生成代码”慢几分钟，但通常能省掉半小时返工。

技巧四：一个任务只聚焦一个目标，控制变更范围

人类开发也一样，一个 PR 同时做登录、样式、数据库迁移、依赖升级，review 会非常痛苦。Codex 更是如此。

好的任务应该是可切分、可验证、可回滚的。比如：

不太好的任务：

1

帮我把后台系统整体优化一下，顺便修几个 bug，再加点测试。

更好的拆法：

1
2
3

任务1：修复用户列表分页参数丢失问题。
任务2：给用户列表补充分页相关测试。
任务3：整理用户列表组件里重复的状态判断。

每个任务都有一个焦点，Codex 就不容易迷路。你也更容易 review 它的输出。

技巧五：让 Codex 小步实现，并要求解释关键取舍

Codex 能一次性生成很多代码，但“大量生成”不等于“高效”。我更喜欢让它小步推进：

1
2
3
4
5

先完成最小可运行版本，不要做额外抽象。
完成后说明：
1. 改了哪些文件；
2. 为什么这样改；
3. 哪些地方可能需要后续优化。

这样做有两个好处。

第一，你能快速看到方向是否正确。

第二，Codex 会被迫解释自己的取舍，而不是只给结果。

当它解释“为什么这样改”时，你很容易看出它有没有理解项目。如果解释含糊，就继续追问；如果解释清楚，再进入下一步。

技巧六：把测试命令写进任务，而不是事后才想起来

Codex 的一个重要价值，是它可以帮你运行测试、构建、类型检查、格式检查等命令。但前提是它知道应该跑什么。

所以在任务里直接写：

1
2
3
4
5
6

完成后请运行：
- npm test
- npm run lint
- npm run build

如果某个命令失败，请说明失败原因、是否和本次改动有关，以及你如何处理。

如果项目没有自动化测试，也可以写手工验证标准：

1
2
3
4

没有单元测试。请生成后检查：
1. archives 页面出现 2026 年分组；
2. 新文章页面能打开；
3. 中文标题和标签显示正常。

这比“你看着办”可靠得多。Codex 可以帮你执行验证，但验证标准应该由人来定。

技巧七：把 Codex 用在阅读和定位上，不只是写代码

很多人低估了 Codex 的阅读能力。实际工作里，最耗时间的不一定是写代码，而是弄清楚代码在哪里、数据怎么流、为什么这个 bug 会出现。

有些特别适合交给 Codex 的阅读任务：

1

请梳理这个接口从路由到数据库查询的调用链。

1

请找出用户头像上传失败可能经过的所有错误处理分支。

1

请比较这两个组件的重复逻辑，说明是否值得抽公共组件。

这类任务风险低，收益高。即使最后不让 Codex 改代码，它也能帮你节省大量翻文件的时间。

我的习惯是：先让 Codex 当“代码导游”，再决定要不要让它当“代码作者”。

技巧八：用 /review 或明确 review 指令，让它站到审查者角度

写代码和审代码是两种不同心态。让 Codex 生成代码之后，最好再让它切换角色：

1
2
3
4
5
6

请以 code review 的角度检查刚才的改动，重点看：
1. 是否有无关文件改动；
2. 是否有未处理的异常路径；
3. 是否有兼容性风险；
4. 是否缺少测试；
5. 是否引入了过度抽象。

OpenAI 的 Codex 最佳实践也强调，不要只让 Codex 改代码，还要让它创建测试、运行检查、确认结果并 review 工作。这个思路非常重要：Codex 不应该只是“生产代码”，还应该帮助发现代码里的风险。

当然，AI review 不能代替人类 review。它更像第一道自动筛查，可以提前发现低级问题、遗漏分支和不一致风格。最终是否接受，仍然要人判断。

技巧九：权限要克制，默认从安全配置开始

效率和权限不是一回事。给 Codex 越多权限，它能做的事越多，但风险也越高。

比较稳的原则是：

第一，默认使用沙箱和审批。

第二，不把生产密钥、真实用户数据、内部敏感信息交给它。

第三，危险命令必须先说明目的，再由人确认。

第四，部署、删除、迁移、批量替换这类任务要格外谨慎。

官方最佳实践里也提到，如果刚开始使用 coding agent，应该从默认权限开始，保持 approval 和 sandboxing 收紧，等你理解工作流之后，再对可信仓库或特定流程放宽。

这点我很赞同。AI 工具最容易制造一种错觉：既然它能做，就让它全做。但工程里真正可靠的方式，是最小权限、可观察、可回滚。

技巧十：每次用完都复盘，把经验写回项目

Codex 用得好不好，不只取决于一次提示词，还取决于你有没有把经验沉淀下来。

每次任务结束后，可以复盘几个问题：

第一，哪些上下文给得有效？

第二，Codex 哪一步误解了？

第三，哪些测试命令必须写进下次任务？

第四，哪些规则应该放进 AGENTS.md？

第五，有没有可以沉淀成固定提示模板？

比如你发现 Codex 总是忘记运行某个检查，就把它写进 AGENTS.md。你发现某类任务总要提醒“不要修改生成目录”，也写进去。你发现某种 review checklist 很有效，就整理成 code_review.md，以后让 Codex 引用。

这就是复利。第一次用 Codex，可能只是省一点时间；第十次之后，如果规则、模板、测试、权限都沉淀好了，它省下的就不只是写代码时间，而是整个工程流程的沟通成本。

一个完整的使用模板

下面是我比较推荐的一段 Codex 任务模板，可以按项目改：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

请完成以下任务：

目标：
- ...

范围：
- 允许修改：
- 不要修改：

上下文：
- 相关文件：
- 当前现象：
- 期望行为：

实现要求：
- 先阅读相关代码并给出计划。
- 计划确认后再修改。
- 保持改动最小，不做无关重构。

验证要求：
- 运行：
- 如果无法运行，请说明原因。
- 最后总结改动、验证结果和剩余风险。

这个模板看起来很普通，但它能解决大部分“AI 写偏了”的问题。因为它把目标、范围、上下文、实现、验证都拆开了。

总结

Codex 提高效率的关键，不是让开发者少思考，而是把重复、明确、可验证的工作交出去，让开发者把精力放在判断、设计和质量把关上。

我认为最值得记住的是这 10 点：

1. 把需求写成小 issue。
2. 用 AGENTS.md 沉淀项目规则。
3. 先让 Codex 读代码和写计划。
4. 一个任务只做一个焦点。
5. 小步实现，并解释关键取舍。
6. 把测试命令写进任务。
7. 让 Codex 帮你阅读和定位。
8. 用 review 指令检查风险。
9. 默认收紧权限和沙箱。
10. 每次用完都复盘沉淀。

用 Codex 最好的状态，不是“我完全不管，它自动完成”，而是“我把任务定义清楚，它帮我推进，我负责判断和验收”。这样才是真正稳定的软件工程效率提升。

参考资料

• OpenAI Codex
• OpenAI Codex best practices
• OpenAI Codex announcement

为什么能力越强越需要边界

AI 工具变强之后，最容易出现两种极端看法。一种是觉得它什么都能做，开发者很快就不重要了；另一种是觉得它经常出错，所以完全不值得用。

我的感受比较中间：AI 很有用，但它不是魔法。它能帮我们节省大量搜索、整理、样板代码和重复验证的时间，也会在上下文不足、需求模糊、边界复杂时犯错。关键不是用不用，而是知道在哪些边界内用。

对普通开发者来说，我认为最重要的是三条边界：成本边界、隐私边界、正确性边界。只要这三条边界想清楚，AI 就会从一个让人焦虑的新东西，变成一个可以稳定使用的工具。

成本、隐私与正确性三条边界

AI 的能力越强，越需要基于风险进行判断。因为它不只是生成文本，还可能参与代码修改、文档总结、日志分析、数据处理，甚至操作开发环境。

一个成熟的使用方式，不是问“AI 能不能做这件事”，而是问三个问题：

第一，这件事交给 AI 做，成本是否划算？

第二，交给 AI 的上下文里，有没有不该暴露的信息？

第三，AI 给出的结果，能不能被验证？

如果这三个问题都能回答清楚，就可以大胆用。如果回答不清楚，就应该缩小任务范围，或者干脆自己处理。

可执行的安全使用方法

先说成本边界。AI 的成本不只是钱，还包括时间和注意力。一个简单命令、一个熟悉 API、一个五分钟能写完的函数，如果反复和 AI 解释背景，可能反而更慢。比较适合交给 AI 的，是那些信息量大、重复性高、需要整理但风险可控的任务，比如读一批代码总结结构、补测试用例初稿、整理迁移步骤、生成文档草稿。

再说隐私边界。不要把密钥、生产数据库、用户隐私数据、公司内部敏感信息直接贴给 AI。即使工具声称有企业级保护，也应该遵守最小暴露原则。能脱敏就脱敏，能用样例数据就不用真实数据，能描述结构就不要贴完整内容。

最后是正确性边界。AI 的回答必须可验证。代码要能跑测试，SQL 要能解释执行计划，配置要能在测试环境验证，技术结论要能找到官方文档或源码依据。对于无法验证的内容，最多只能当成思路，不能当成结论。

我自己比较喜欢把 AI 任务分成三类。

第一类是低风险任务，可以直接让它做，比如整理 Markdown、解释报错、生成脚手架、翻译英文文档。

第二类是中风险任务，可以让它做初稿，但必须 review，比如修改业务代码、补单元测试、调整配置。

第三类是高风险任务，只能让它辅助分析，不能直接执行，比如生产数据修复、权限策略、支付金额计算、安全漏洞处理。

这样分层之后，使用 AI 会稳很多。不是每次都纠结“能不能信”，而是先判断任务风险，再决定让它参与到什么程度。

容易被忽视的风险

第一个坑是把“说得像真的”当成“真的”。AI 很擅长组织语言，所以它的错误也可能很顺。遇到版本号、API 行为、兼容性、法律合规、安全策略这些问题，最好看官方资料。

第二个坑是把完整代码库一次性丢给 AI。上下文越多不一定越好，关键是相关。给太多无关信息，既增加成本，也可能让它抓错重点。

第三个坑是用 AI 掩盖自己没想清楚的问题。如果需求本身模糊，AI 只能扩大这种模糊。比较好的做法是先让它帮你把需求拆清楚，再进入实现。

第四个坑是跳过复盘。每次 AI 帮你完成一个任务，都可以回头看一下：哪些提示有效，哪些地方它误解了，哪些验证步骤必不可少。用 AI 也需要积累经验。

总结

普通开发者使用 AI，不需要追每一个新模型，也不需要把所有工作都交出去。真正重要的是建立边界感。

成本边界提醒我们：不是所有问题都值得用 AI。

隐私边界提醒我们：不是所有上下文都可以交给 AI。

正确性边界提醒我们：不是所有回答都能直接相信。

把这三条边界守住，AI 就会是一个很好的放大器。它放大的不是偷懒，而是开发者已经具备的判断力、表达能力和工程习惯。

参考资料

• OpenAI Codex announcement
• OpenAI Agents docs
• GitHub Copilot cloud agent docs