Codex AI 工程：用最少的代码，把 AI 接进研发流程

一、AI 编码的门槛，不在写代码

很多人把 Codex 当成"更聪明的自动补全"：打开编辑器，敲两行注释，等它补全。这只是最浅的用法。

真正的 AI 工程，是把 Codex 这类模型当成一个可以调用工具、能读写文件、能跑命令的协作方，然后围绕它设计上下文、约束和验证。代码量依然很少，但工程含量完全不同。

下面走一遍完整链路：上下文 → 任务 → 调用 → 验证 → 集成。

二、上下文：别把整个仓库丢进去

模型表现好坏，八成取决于你给了它什么上下文。全仓库塞进去只会稀释注意力，还会撞上 token 上限。

更有效的做法是维护一份约定文件，让工具每次自动读取：

<!-- AGENTS.md -->
## 项目约定
- Python 3.12，依赖用 uv 管理
- 测试：pytest，新增逻辑必须带测试
- 禁止修改 migrations/ 下的历史文件
- 提交前必须跑 `make lint test`

几十行 Markdown，替代了每次对话里重复交代的几百字。这份文件进 Git，团队共享，新人和 AI 都受益。

需要更细的上下文时，再按需检索：

def context_for(task, root="."):
    keywords = set(task.lower().split())
    hits = []
    for p in Path(root).rglob("*.py"):
        text = p.read_text(errors="ignore").lower()
        if keywords & set(text.split()):
            hits.append(p)
    return hits[:10]

粗糙的关键词匹配就够了——给对文件，比给多文件重要。

三、任务：把需求写成可执行规格

"帮我优化一下这段代码"是无效指令。AI 不知道优化的目标是什么。

有效的任务描述包含四件事：

• 目标：把 parse_config 的启动耗时降到 50ms 以内
• 约束：不改公开 API，不引入新依赖
• 验收：pytest tests/test_config.py 全绿，且 bench.py 输出 < 50
• 范围：只动 core/config.py

写成模板就是：

目标：{goal}
约束：{constraints}
验收：{acceptance}
范围：{files}

能自动验收的任务，才适合交给 AI。验收不了的任务，先想办法把它变成能验收的。

四、调用：一个最小的 agent 循环

Codex 这类工具通常提供 CLI 或 API。以 CLI 为例，非交互调用可以短到一行：

codex exec "按 AGENTS.md 的约定，修复 tests/test_api.py 中失败的用例"

如果你想在自己的流程里嵌入，核心就是一个循环：给任务 → 拿动作 → 执行 → 回填结果 → 再问。

import subprocess, json

def run(cmd):
    r = subprocess.run(cmd, shell=True, capture_output=True, text=True)
    return r.stdout + r.stderr

def agent(task, model, max_steps=10):
    history = [{"role": "user", "content": task}]
    for _ in range(max_steps):
        reply = model(history)
        if reply["type"] == "cmd":
            out = run(reply["cmd"])
            history.append({"role": "tool", "content": out[:4000]})
        else:
            return reply["content"]
    return "达到步数上限"

二十行，就是一个能读命令输出、自我纠错的代理骨架。真正的工程在于：限制它能跑什么命令、能改哪些文件、什么时候必须停下来问人。

五、验证：让测试当护栏

AI 写的代码最大的风险不是写错，而是看起来很对。唯一可靠的判断方式是跑测试。

def guard(task, model, tests="pytest -q"):
    patch = model(task)          # 让模型产出改动
    apply(patch)                 # 落到工作区
    if run(tests).returncode != 0:
        rollback()
        return None, "测试未通过"
    return patch, "ok"

这段逻辑的价值在于：失败了自动回滚，人不用介入。你可以把同一个任务重试三次，取第一个通过测试的版本。

再往前一步，把 lint、类型检查、安全扫描都加进 tests 里，护栏就越织越密。

六、集成：让它在 CI 里干活

最有价值的场景，是把 AI 放在人不想做、但规则明确的位置上：

# .github/workflows/ai-review.yml
name: ai-review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: codex exec "审查本次 diff，只报告正确性和安全问题，不要改代码" > review.md
      - run: cat review.md

这类任务的特点：输入明确、标准清晰、结果可人工复核。写 changelog、补测试、修 lint 告警、翻译文档，都符合这个特征。

反过来，架构决策、模糊需求、跨团队协调——这些不适合交给 AI，也不该交给 AI。

七、这套方案的边界

必须说清楚它不适合什么：

• 需求本身模糊：你都不知道要什么，AI 只会更快地给你错的东西；
• 验收标准缺失：没有测试，就没有回滚依据，等于裸奔；
• 强依赖隐性知识：老系统里那些"没人知道为什么这么写"的逻辑，AI 读不出来；
• 安全敏感改动：认证、加密、权限相关，AI 可以提议，人必须终审；
• 超大改动：一次生成几百行，审查成本高于自己写。

AI 工程的核心不是"让 AI 写更多代码"，而是把任务切到足够小、足够清晰、足够可验证。切不好，用再强的模型也是浪费。

八、小结

整条链路的核心代码加起来不到 40 行：

• 上下文约定：一份 Markdown；
• 任务模板：四行文本；
• agent 循环：约 20 行；
• 验证护栏：约 8 行；
• CI 集成：一段 YAML。

Codex 带来的变化，不是"程序员要失业了"，而是编程的瓶颈从写代码转移到了定义问题。谁能把任务描述清楚、把验收标准定死、把护栏织密，谁就能让 AI 真正产出可用的东西。