04 — Agent 可读性（Agent Readability）
定义
Agent 可读性指代码库对 AI Agent 的友好程度——Agent 能否在没有外部帮助的情况下，独立完成环境配置、理解项目结构、执行构建与测试、并验证自己的输出。
OpenAI 基于内部实验，提炼出了 7 项可量化的评分指标。
7 项 Agent 可读性指标
指标 1：Bootstrap 自给自足
问题：Agent 能否从零开始，仅凭仓库内的信息完成开发环境搭建？
评分标准：
- ✅ 优秀：
git clone + 一条命令（如 make setup）= 完整可用环境 - ⚠️ 可接受：需要安装 2-3 个明确列出的工具
- ❌ 不合格：依赖未文档化的外部服务或需要"问同事"
指标 2：明确的任务入口点
问题：Agent 能否找到标准的 build / test / lint / run 命令？
评分标准：
- ✅ 优秀：
Makefile或package.json scripts覆盖 build、test、lint、dev - ⚠️ 可接受：在 README 中有明确说明，但不在标准入口
- ❌ 不合格：需要阅读多个文件才能找到如何运行
指标 3：可验证的输出（验证 Harness）
问题：Agent 完成任务后，能否机械化地验证自己的输出是否正确？
这是权重最高的指标（20 分），也是最高杠杆的投资。
评分标准：
- ✅ 优秀：类型检查 + 单元测试 + 集成测试，全部自动运行，结果明确
- ⚠️ 可接受：有测试，但覆盖率低或运行不稳定
- ❌ 不合格：只能通过手动点击 UI 才能验证
指标 4：Linting 与格式化自动化
问题：代码风格和格式是否自动执行，无需人工干预？
指标 5：代码库地图（AGENTS.md）
问题：Agent 能否快速理解代码库的整体结构和关键约定？
- ✅ 优秀：
AGENTS.md≤100 行，包含目录结构、核心术语、关键约束入口
指标 6：文档结构化
问题：详细的参考文档（API 规范、架构决策等）是否有结构化的存放位置？
指标 7：决策记录（ADR）
问题：重要的架构决策是否有记录，解释了"为什么这样做"？
评分表
| 指标 | 得分 | 说明 |
|---|---|---|
| 1. Bootstrap 自给自足 | /10 | |
| 2. 任务入口点 | /10 | |
| 3. 验证 Harness | /20 | （权重最高） |
| 4. Linting 自动化 | /15 | |
| 5. 代码库地图 | /15 | |
| 6. 文档结构 | /15 | |
| 7. 决策记录 | /15 | |
| 总分 | /100 |
分级
- 85-100：Agent 友好型仓库，可以放心委派任务
- 65-84：可用，但需要改善部分短板
- 40-64：Agent 工作效率低下，建议先做基础改造
- <40：不建议直接使用 Agent，先完成基础设施建设
"无聊技术栈"原则
OpenAI 提出了一个反直觉的建议：选择无聊的、被过度使用的技术，而不是新颖的技术。
AI 模型的训练数据由现有的代码仓库构成：
- 流行技术（React、Express、PostgreSQL）：训练数据丰富，Agent 生成质量高
- 新兴框架：训练数据稀少，Agent 频繁出错
在使用小众框架的项目中，Agent 的错误率可能是使用流行框架的 2-3 倍。
Agent 规范的长度约束
OpenAI 的实验建议：
- AGENTS.md：≤100 行
- 单个 Skill 说明：≤60 行
- 单个 ADR：≤30 行（问题 + 决策 + 原因）
- 系统提示（System Prompt）：≤200 词
超过这些长度，信噪比开始下降，Agent 遗漏关键信息的概率显著上升。
实施优先级
如果现在只能做一件事来提升 Agent 可读性，答案几乎总是：
建立可靠的验证 Harness（指标 3）
原因：
- 让 Agent 能自主验证，减少 90% 的"等待人工验证"时间
- 错误能在 Agent 的工作循环内被发现和修复
- 为未来的自动化奠定基础
下一步
- 了解高吞吐率下的合并哲学：→
05-throughput-philosophy.md - 立即给你的仓库打分：→
../practice/repo-readability-checklist.md