AI Coding 实践之路

Emacs 配置这类小型项目，我直接交给 Codex 处理。由于我对每个功能模块已有良好分层，只需引用文件并说明需求——新增某个包、增加某个功能，或修复某个异常（附上错误日志）——基本能一次搞定。

这类项目涉及 UI 改造，详细过程在 和 Codex 一起重构博客 一文中介绍。

我的做法是一边向 Codex 描述我的想法，一边通过截图告诉他哪里改坏了、哪里不符合预期。由于博客系统本身比较简单，他几下就改好了。

有趣的是，Codex 的调整冲动不限于代码，还会主动修改我的文章，甚至自己写了一篇博文（就是上文，我只是做了校对）。

最复杂的例子是我正在构建的 Org Runbook 项目。出发点来自 Org File as AI Skills System，目标是构建一套围绕 Emacs 的 Harness 工具链。

这个项目本身就是用 AI coding 开发的，沿用原文所说的「围绕 PRD 文件的 Plan-Code-Review 模式」。

让 AI 总结出「当前架构」(CURRENT-ARCH.org) 和「目标架构」(TARGET-ARCH.org)，再比较差异生成 ARCH-GAP.org 和 =MIGRATION-PLAN.org=。关键改变是：不再是泛泛地谈架构差异，而是通过编号逐一列举。

** Gap ID: G-008
- Target rule: "architecture docs are executable governance artifacts"
- Current reality: docs/workflow/architecture-iteration-workflow.org 已创建，PRD 模板和 GAP 模板已就位
- Impact: 每轮改造方法不稳定，审计口径漂移
- Required change: 固化 workflow + 审计表 + gap 模板 + PRD 模板
- Acceptance check:
  - docs 中存在固定流程文件
  - 新 PRD 可直接引用流程文件落地
- Status: **partial** (architecture-iteration-workflow.org 已创建，本轮正在验证)
- Evidence: docs/workflow/architecture-iteration-workflow.org, prd/000-template.org, docs/iterations/000-template.org
- Next minimal fix: 完成首轮 iteration workflow 验证并更新文档

每轮采用固定步骤：

1. 从 Plan 中选取一个 Blocker，生成 PRD 文件，开始编码执行
2. 完成后进行 Review，把结果与 Plan 合并
3. 审查是否满足 Plan 中的 Blocker 检查
4. 按照模板生成 Iteration Review 文件，列举所有检查项并打钩确认，提供相应证据

** 1) Acceptance validation
- Gates checked:
  - bootstrap 不依赖固定 role 字符串 ✅
  - 新增 profile 可在不改 host 代码下接入 dispatch lane ✅
  - ERT 测试验证 capability-first 函数存在 ✅ (7/7 PASS)

** 2) Evidence validation
- Test/grep/trace reproducibility: G-006 ERT 7/7 PASS, full suite 274/275
- Cross-doc consistency: MIGRATION-PLAN G-006 `in_review` → `partial`

** 3) Gap impact review
- Closed: 无
- Reduced: G-006 (Phase 1-2 bootstrap audit done) ✅
- Unchanged: G-001-G-005 (partial), G-007-G-010 (not_started)

** 4) Plan consistency review
- Plan changed? yes
- Changes: MIGRATION-PLAN G-006 status + Phase label; ARCH-GAPS Phase label

** 5) Final decision
- close + rationale: G-006 Phase 1-2 完成，所有验收门通过

1. 所有项目勾选后，回写 PRD 并标记完成，更新 =CURRENT-ARCH.org=。本轮迭代完成。

为了让每轮输出足够稳定，我让 Codex 为每种文件输出 Spec，确保架构描述、Plan 或 Review 文件都按我的设计执行。这没花多少时间——主要是表达「我想要这样一套流程」，告诉 Codex 后让他生成，我检查后觉得哪里不好就让他迭代几轮。

为了让流程能自动运行，我把说明写到了 workflow.org 文件中，每次引用即可开始迭代。

迭代过程中，我发现 Agent 容易产生幻觉：自以为完成了某个 Gate 检查，实际并没有；或在 Worklog 里引用不存在的文件。于是我引入 SubAgent，在 Workflow 开头声明多个角色及其职责、必读输入、必须遵从的输出 Spec，并在每个 Step 中指明由哪个角色的 SubAgent 负责。

在 Codex 建议下，我分了三个角色：

• Architect ：负责架构文档
• Builder ：负责代码和测试
• GateKeeper ：负责独立验证

* Multi-Agent Execution Contract (Default)
:PROPERTIES:
:ID:       3c420a52-5880-4509-bafe-73cbbc30af69
:END:

Role ownership:
- Builder:
  - Tool: =scripts/pi-subagent-supervisor.sh --role builder ...=
  - Model pin: =--provider minimax --model MiniMax-M2.7=
  - Write scope: =elisp/=, =tests/=, =prd/<id>.org=
  - Must not edit architecture docs.
- Architect:
  - Tool: =scripts/pi-subagent-supervisor.sh --role architect ...=
  - Write scope: =docs/CURRENT-ARCH.org=, =docs/ARCH-GAPS.org=, =docs/MIGRATION-PLAN.org=
  - Must not edit runtime code/tests.
- Gatekeeper:
  - Tool: =scripts/pi-subagent-supervisor.sh --role gatekeeper ...=
  - Default read-only review; only allowed write target is =docs/iterations/<yyyymmdd>-<prd-id>-review.org=
  - Must independently rerun key verification commands before close decision.

几轮下来发现 GateKeeper 经常出现幻觉，对不应该放行的门禁直接放行了。向 Codex 反馈后，他的建议是：用门禁脚本而不是 Agent 自我判断。于是 Codex 创建了 iteration-gate-check.sh 脚本，对已知问题进行收集，无法通过门的都设为 Rework 状态，需要重跑 Workflow。

每跑完一轮，我会让一个独立的 Codex 评审这轮运行状态：文档是否齐全、门禁检查是否完整、证据是否提供充分。如果不能通过，就问 Codex 应该如何改进——是优化 Workflow，还是增加 Gate Check 项目。

经过多轮调优后，Agent 基本能稳定跑完整个 Workflow。在完整流程控制下，Code Agent 能轻松打爆 MiniMax 的 Code Plan。