很多人开始用 AI 写代码以后，会自然形成一个工作方式：在聊天里描述问题，让 Codex 或其他 coding agent 读代码、改文件、跑测试。

这在个人小项目里够用。但一旦进入长期项目、多人仓库、生产系统，聊天就不够了。

真正的问题不是“AI 会不会改代码”。真正的问题是：AI 凭什么知道这次任务的边界？谁判断它可以自动执行？它改完以后留下了什么证据？PR 打开以后谁负责发布？发布以后什么时候才算 done？

我的答案是：不要把 issue 当成 todo。把 issue 写成 AI 可执行合同。

Todo 太弱，合同才够用

普通 todo 往往只有一句话：

修复移动端下单按钮问题

人类工程师看到这句话，可能会主动追问上下文、打开页面、找复现路径、判断风险、补测试、问产品要确认。但 AI worker 没有稳定的长期记忆，也不应该靠猜测补完整个任务。

对 AI 来说，一个可执行 issue 至少要回答这些问题：

  • 用户在什么场景遇到什么问题？
  • 期望行为是什么？
  • 当前行为或证据是什么？
  • 验收标准是什么？
  • 这次明确不做什么？
  • 哪些风险会让 AI 停下来？
  • 是否允许自动实现，还是只允许分析？

这些不是形式主义。它们决定 AI 是在安全边界内工作，还是在模糊任务里自由发挥。

自动化必须 opt-in

AI issue workflow 的第一条规则应该是：默认不自动跑。

只有明确标记为 auto-run 的 issue，才允许 daemon 或 dispatcher 自动 claim、分析、实现、开 PR。没有 opt-in 的 issue，即使写得很清楚，也应该停在人工 triage 或手动执行。

这个规则看起来保守，但很必要。

GitHub issue 里会有很多内容：产品想法、用户反馈、线上事故、运营请求、合规疑问、截图、日志、临时记录。并不是每个 issue 都适合让 AI 自动改代码。

auto-run label 的意义不是“这个任务简单”，而是“这个任务被明确授权进入自动化控制面”。

Issue 应该保留原始证据

另一个容易犯的错误，是为了让 issue 更结构化，就重写用户原始正文。

这很危险。

用户原始描述、截图、附件、日志、复现路径和具体用词都是证据。AI 可以在评论里补充结构化分析，可以追加验收合同，但不应该为了格式漂亮把原始材料覆盖掉。

一个好的 issue-driven workflow 应该区分两层：

  • 原始 issue body：用户证据和初始需求；
  • Codex comments：结构化合同、triage、风险、证据和状态变更。

这样后续 reviewer 才能回到原始事实，而不是只看 AI 整理过的版本。

Issue 合同应该包含停工条件

可执行合同不是授权 AI 一路做到底。

它必须写清楚什么时候停下来。

常见停工条件包括：

  • 需求矛盾；
  • 验收标准缺失；
  • 需要改变核心业务语义；
  • 涉及数据库 schema 或持久化格式；
  • 涉及支付、交易、权限、安全、风控或合规；
  • 需要生产状态变更；
  • 测试或证据门禁失败。

这些条件一旦触发，AI 不应该继续扩大改动，而应该把 issue 切到 needs-input、review-required 或 failed-needs-human 这类状态。

这不是降低 AI 效率。相反，这是让 AI 能长期进入真实工程系统的前提。

Issue 是控制面，不是聊天记录

Issue-driven AI engineering 的核心，是把工程状态放回 GitHub，而不是放在一次聊天里。

聊天适合讨论，issue 适合审计。

一个稳定的 issue 控制面应该记录：

  • 当前状态；
  • 谁 claim 了任务；
  • 哪个 branch 对应这个 issue；
  • triage 结论是什么；
  • 风险等级是什么；
  • PR 在哪里；
  • 测试和证据在哪里；
  • 是否进入 release boundary；
  • 是否已经生产验证。

这样即使某个 Codex worker 退出、某个本地进程重启、某次对话丢失，项目仍然知道任务走到了哪里。

AI 可执行合同的最小模板

一个通用模板可以很简单：

## 任务类型
bug | feature | improvement | test | investigation

## 用户问题
谁在什么场景下遇到什么问题？

## 期望行为
用户或系统应该看到什么结果？

## 当前行为
现在发生了什么？有哪些证据？

## 验收标准
- [ ] 可观察条件 1
- [ ] 可观察条件 2
- [ ] 测试、截图、数据证明或文档要求

## 非目标
这次明确不做什么？

## 风险和停工条件
什么情况下 AI 必须停止并等待人工确认？

这个模板不复杂，但它改变了 AI coding 的协作方式。

任务不再只是“让 AI 帮我改一下”。任务变成了一个可执行、可验证、可停止、可追溯的合同。

这就是 issue-driven AI engineering 的起点。