如何执行：一个 Issue，一个运行时结果。

当 X 时应该 Y，实际得到 Z。一个可观察行为，少量相关文件，并包含测试。Epic 不是工作单元，也永远不会被认领。 AGENTS.md:44; runner.py:2263 (epic_not_claimed).

如何执行：工作开始前，Acceptance 就写在 Issue 里。

四个部分：用户结果、前提、Acceptance（成功路径和失败路径）、用户可检查的证据。模板是契约，不是机器门禁。 .github/ISSUE_TEMPLATE/user-outcome.md; AGENTS.md:78.

如何执行：依赖关系必须是平台原生关系，而不是文字。

使用平台的 blocked-by 关系。正文里的“依赖 #N”不会被解析。有未关闭阻塞项的 Issue 不会被认领。 runner.py:2296 (blocked_by, then continue).

如何执行：一个 label 是执行开关，状态只存在于 labels。

`ai-ready` 将 Issue 放入队列；milestone 是范围，不是开关；第二个 label 选择任务类型。没有数据库、队列或看板：Issue tracker 就是状态机。 runner.py:1916 (ready_searches); delivery_labels.py:141 (is_pickup_eligible); CONSTITUTION.md:15.

如何执行：Issue 文本是数据，不是指令。

Runner 只依据 labels 和可信关联的评论行动；正文里的任何文字都不会变成 Runner 指令。 CONSTITUTION.md:130.

如何执行：契约在仓库里，身份在主机上。

实现者和评审者都会读取 `AGENTS.md`。仓库策略是小型白名单；凭据和调度只在主机上，未知键会快速拒绝认领。 prompts/prompt.md:43; docs/security.mdx:121; runner.py:3074.

如何执行：CI 是唯一的测试权威。

本地测试不算数；合并门禁读取交付 commit 在平台上的 CI 结果。仓库不声明测试命令。 CONSTITUTION.md:100 (Article 4.8); runner.py:5637 (GateCIFailure).

如何执行：Coverage 是门禁，行和分支分别测量。

变更代码行和分支都是 100%。全仓库行覆盖率至少 95%，分支覆盖率至少 95%，分别计算，绝不合并成一个百分比。 tools/coverage_gate.py:30; tools/diff_coverage_gate.py; .github/workflows/ci.yml:150.

如何执行：默认分支受保护，只有 Runner 能合并。

Agent 不会合并或推送受保护分支。Runner 只合并经过评审且包含最新远端 base 的 head。不强推，不自动解决冲突。 CONSTITUTION.md:34; AGENTS.md:122; docs/security.mdx:25.

如何执行：评审是第二个 session，结论绑定一个 SHA。

新进程、新 prompt、新上下文。结论必须存在并写明它覆盖的 head；缺失或格式错误不是通过。head 变化就重新评审。 AGENTS.md:169; runner.py:5196, 5239, 5241, 5629, 5667 (--match-head-commit).

如何执行：每个循环都有上限，超过上限由人决定。

评审和修复最多 5 轮。同一失败指纹连续三次就是死循环。耗尽是终态，不会自动恢复。一次失败不是终态。 runner.py:252 (MAX_REVIEW_ROUNDS = 5), 349 (UnrecoverableDeliveryError), 437; docs/workflow.mdx:99, 118.

ai-ready

一个 Issue 做到 ai-ready，意味着 AI coding agent 可以在没有人在循环中的情况下，把它交付到带 tag 的发版；任何无法自动完成的地方，都必须是明确命名的人类决策，而不是静默失败。

大多数 AI-ready 指南描述仓库配置：AGENTS.md、CI workflow、devcontainer。这些必要但不充分。本页描述工作单元、每个循环在哪里停止，以及什么才算已交付。Orbi 是参考实现，不是标准；这些因素可用于任何 agent。

这与已有内容的关系

Factory's Agent Readiness scores how well a codebase supports agents (Factory). johnpapa/ai-ready generates the configuration files an agent reads (johnpapa/ai-ready). AGENTS.md is the file itself (AGENTS.md). 12-Factor Agents is about building agent applications (12-Factor Agents). This page starts where those stop: at the Issue, and ends at the release.

一、Issue 是工作单元

1. 一个 Issue，一个运行时结果。

当 X 时应该 Y，实际得到 Z。一个可观察行为，少量相关文件，并包含测试。Epic 不是工作单元，也永远不会被认领。

Orbi 如何执行：AGENTS.md:44; runner.py:2263 (epic_not_claimed).

2. 工作开始前，Acceptance 就写在 Issue 里。

四个部分：用户结果、前提、Acceptance（成功路径和失败路径）、用户可检查的证据。模板是契约，不是机器门禁。

Orbi 如何执行：.github/ISSUE_TEMPLATE/user-outcome.md; AGENTS.md:78.

3. 依赖关系必须是平台原生关系，而不是文字。

使用平台的 blocked-by 关系。正文里的“依赖 #N”不会被解析。有未关闭阻塞项的 Issue 不会被认领。

Orbi 如何执行：runner.py:2296 (blocked_by, then continue).

4. 一个 label 是执行开关，状态只存在于 labels。

`ai-ready` 将 Issue 放入队列；milestone 是范围，不是开关；第二个 label 选择任务类型。没有数据库、队列或看板：Issue tracker 就是状态机。

Orbi 如何执行：runner.py:1916 (ready_searches); delivery_labels.py:141 (is_pickup_eligible); CONSTITUTION.md:15.

5. Issue 文本是数据，不是指令。

Runner 只依据 labels 和可信关联的评论行动；正文里的任何文字都不会变成 Runner 指令。

Orbi 如何执行：CONSTITUTION.md:130.

二、仓库携带自己的契约

6. 契约在仓库里，身份在主机上。

实现者和评审者都会读取 `AGENTS.md`。仓库策略是小型白名单；凭据和调度只在主机上，未知键会快速拒绝认领。

Orbi 如何执行：prompts/prompt.md:43; docs/security.mdx:121; runner.py:3074.

7. CI 是唯一的测试权威。

本地测试不算数；合并门禁读取交付 commit 在平台上的 CI 结果。仓库不声明测试命令。

Orbi 如何执行：CONSTITUTION.md:100 (Article 4.8); runner.py:5637 (GateCIFailure).

8. Coverage 是门禁，行和分支分别测量。

变更代码行和分支都是 100%。全仓库行覆盖率至少 95%，分支覆盖率至少 95%，分别计算，绝不合并成一个百分比。

Orbi 如何执行：tools/coverage_gate.py:30; tools/diff_coverage_gate.py; .github/workflows/ci.yml:150.

9. 默认分支受保护，只有 Runner 能合并。

Agent 不会合并或推送受保护分支。Runner 只合并经过评审且包含最新远端 base 的 head。不强推，不自动解决冲突。

Orbi 如何执行：CONSTITUTION.md:34; AGENTS.md:122; docs/security.mdx:25.

三、循环有边界，终态属于人类

10. 评审是第二个 session，结论绑定一个 SHA。

新进程、新 prompt、新上下文。结论必须存在并写明它覆盖的 head；缺失或格式错误不是通过。head 变化就重新评审。

Orbi 如何执行：AGENTS.md:169; runner.py:5196, 5239, 5241, 5629, 5667 (--match-head-commit).

11. 每个循环都有上限，超过上限由人决定。

评审和修复最多 5 轮。同一失败指纹连续三次就是死循环。耗尽是终态，不会自动恢复。一次失败不是终态。

Orbi 如何执行：runner.py:252 (MAX_REVIEW_ROUNDS = 5), 349 (UnrecoverableDeliveryError), 437; docs/workflow.mdx:99, 118.

12. 发版是状态机，不是脚本。

人通过添加一个 Runner 永不增删的 label 启动发版。milestone 仍有其他 open Issue 时等待。发版 commit 的 CI 必须通过；逐项检查 live API，checkbox 从不解析。已有 tag 必须精确指向发版 commit，永不移动。任何失败都是终态，不自动重试。

Orbi 如何执行：release.py:326, 508, 619, 880; runner.py:2288; AGENTS.md:162.

贯穿始终的两句话：快速失败，不静默降级。端到端可观察：一个 run id，一次 grep，完整时间线。

本页不声称什么

AGENTS.md 的存在、四段式 Issue 正文和分支保护是契约与模板，不是 Runner 检查。覆盖率数字是一个仓库自己的门禁。这十二个因素是 Orbi 今天执行的内容，不是行业标准；本页由 Orbi 签署。

参考实现

https://github.com/orbi-build/orbi
Install: curl -fsSL aiready.sh | sh
ai-ready badge