仓库 Agent 可读性评分清单
基于 OpenAI 7 项指标，可直接用于评估现有仓库。
使用方法
- 对每个子项打分（✅ 完全满足 / ⚠️ 部分满足 / ❌ 不满足）
- 汇总分数，查看等级
- 优先修复权重高且评分低的项
指标 1：Bootstrap 自给自足（满分 10 分）
问题：Clone 仓库后，Agent 能否仅凭仓库内容完成环境搭建？
| 检查项 | 权重 | 得分 |
|---|---|---|
| README 中有清晰的安装步骤 | 3 | |
| 安装步骤可以在新机器上成功执行 | 4 | |
| 所有环境变量有示例文件（.env.example） | 3 | |
| 小计 | 10 |
指标 2：明确的任务入口点（满分 10 分）
问题：Agent 能否快速找到 build / test / lint / run 命令？
| 检查项 | 权重 | 得分 |
|---|---|---|
| 有标准构建命令 | 3 | |
| 有标准测试命令 | 3 | |
| 有标准 lint 命令 | 2 | |
| 有标准开发服务器命令 | 2 | |
| 小计 | 10 |
指标 3：验证 Harness（满分 20 分）
问题：Agent 完成任务后，能否通过自动化验证确认输出正确？
这是权重最高的指标，也是最高杠杆的投资。
| 检查项 | 权重 | 得分 |
|---|---|---|
| 类型检查可以自动运行 | 4 | |
| 单元测试覆盖核心业务逻辑 | 5 | |
| 集成测试覆盖关键路径 | 5 | |
| 测试失败时提供明确错误信息 | 3 | |
| 测试运行时间 < 5 分钟 | 3 | |
| 小计 | 20 |
指标 4：Linting 与格式化自动化（满分 15 分）
问题：代码风格和格式是否自动执行？
| 检查项 | 权重 | 得分 |
|---|---|---|
| 有配置好的 Linter | 4 | |
| Linter 可以自动修复大部分问题 | 4 | |
| 有配置好的格式化工具 | 4 | |
| pre-commit hook 自动运行 lint | 3 | |
| 小计 | 15 |
指标 5：代码库地图（满分 15 分）
问题：是否有 ≤100 行的 AGENTS.md 作为 Agent 的导航入口？
| 检查项 | 权重 | 得分 |
|---|---|---|
| 存在 AGENTS.md（或 CLAUDE.md）文件 | 3 | |
| 文件 ≤ 100 行 | 3 | |
| 包含目录结构说明 | 3 | |
| 包含核心术语定义（3-5 个） | 3 | |
| 指向详细文档的链接 | 3 | |
| 小计 | 15 |
指标 6：文档结构化（满分 15 分）
问题：重要的参考文档是否有结构化的存放位置？
| 检查项 | 权重 | 得分 |
|---|---|---|
| 存在 docs/ 目录 | 3 | |
| API 规范有独立文档 | 3 | |
| 架构文档存在 | 4 | |
| 文档中的代码示例与实际代码一致 | 5 | |
| 小计 | 15 |
指标 7：决策记录（满分 15 分）
问题：重要的架构决策是否有记录，解释了"为什么"？
| 检查项 | 权重 | 得分 |
|---|---|---|
| 存在 ADR 目录 | 5 | |
| 主要技术选型有对应 ADR | 5 | |
| ADR 格式包含：背景、决策、原因、后果 | 5 | |
| 小计 | 15 |
总分计算
总分 = ___ / 100
等级判断
| 分数 | 等级 | 建议 |
|---|---|---|
| 85-100 | Agent 友好型 🟢 | 可以放心委派复杂任务给 Agent |
| 65-84 | 基本可用 🟡 | 改善 1-2 个短板后可以大规模使用 |
| 40-64 | 效率低下 🟠 | 先做基础改造，再委派 Agent 任务 |
| < 40 | 不建议使用 🔴 | 从 4-week-roadmap.md 第 1 周开始 |
优先级矩阵
| 权重高 | 权重低 | |
|---|---|---|
| 评分低 | 立即修复 🔴 | 计划修复 🟡 |
| 评分高 | 保持优势 🟢 | 可以忽略 ⚪ |
最高优先级：指标 3（验证 Harness）评分低时，永远是第一优先级。