agent-ready-codebase

面向 Agent 的代码库

概述

当 Agent 难以处理某个代码库时，这反映并放大了代码库现有的弱点。这项技能会根据影响 Agent 效率的五项原则评估代码库，并提供改进每项原则的具体指导。它会适配项目所用的语言和技术栈。

基于《AI Is Forcing Us To Write Good Code》。

模式选择

根据上下文确定要使用的模式：

• 审查：用户已有代码库，想了解其现状。评估全部五项原则，并提供包含具体发现的评分表。
• 指导：用户想改进某项或某几项原则，或搭建新项目。针对其技术栈提供具体、可执行的步骤。

如果无法确定模式，请提问。

五项原则

1. 100% 测试覆盖率 —— 强制每一行代码都通过可执行示例展示其行为
2. 审慎的文件结构 —— 让文件系统成为 Agent 可浏览的界面
3. 端到端类型 —— 消除非法状态，缩小 Agent 的搜索范围
4. 快速、临时、并发的开发环境 —— 缩短反馈周期，支持并行 Agent 工作流
5. 自动化强制执行 —— 通过检查工具、格式化工具和钩子减少 Agent 的自由度

审查工作流

审查代码库时，按以下步骤进行：

1. 检测技术栈

检查项目文件（例如 package.json、go.mod、Gemfile、pyproject.toml、Cargo.toml），识别主要语言、测试框架、构建系统和数据库。这将决定适用的工具建议。

2. 评估每项原则

阅读 references/checklist.md，了解每项原则的详细标准。针对每项原则，判断当前状况：

• 测试覆盖率：运行或检查覆盖率工具。查找 CI 强制检查。报告当前百分比，以及是否能识别未覆盖的代码行。
• 文件结构：抽查目录树。衡量文件大小。标记兜底文件（utils、helpers、common）。评估文件名是否能说明其领域用途。
• 类型系统：检查严格模式、语义化类型名、API 契约模式和数据库约束。找出 any／未类型化的缺口。
• 开发环境：检查是否支持单命令设置、测试套件运行时间、端口／数据库隔离，以及 worktree 或容器支持。
• 自动化强制执行：检查检查工具／格式化工具配置、CI 流水线、Git 钩子和 Agent 钩子。

3. 生成评分表

用表格呈现发现，每项原则占一行：

原则	评级	主要发现
测试覆盖率	强 / 良好 / 弱	例如：“覆盖率为 87%，未在 CI 中强制检查”
文件结构	强 / 良好 / 弱	例如：“有 3 个文件超过 500 行，2 个兜底 utils 文件”
类型	强 / 良好 / 弱	例如：“TypeScript 严格模式，但未生成 API 模式”
开发环境	强 / 良好 / 弱	例如：“需要手动完成 8 个步骤来设置，不支持并发”
强制执行	强 / 良好 / 弱	例如：“已配置 ESLint，但未在 CI 中运行”

4. 确定改进优先级

对最薄弱的原则进行排序，并针对排名最高的 2-3 项提出具体的后续步骤。每条建议都应结合项目实际的技术栈和工具。

指导工作流

针对某项具体原则提供改进指导时：

1. 阅读 references/checklist.md 中的相关部分
2. 评估项目中该原则的当前状况
3. 针对项目的技术栈提供具体、有序的变更清单
4. 尽可能展示确切的命令或配置片段

关键洞见：为何要达到 100% 覆盖率

这个最违背直觉的原则值得强调。在行覆盖率达到 100% 时：

• 会出现阶段性转变：未覆盖的代码行总是来自近期变更，不再有任何歧义，能明确知道哪些内容需要测试
• 覆盖率报告会变成一份简单的待办清单，列出仍需编写的测试
• 这并非为了证明“没有 Bug”——而是迫使作者说明每一行代码的行为
• 不可达代码会立即显现并被删除
• 代码审查会变得更轻松，因为审查者能看到具体的行为示例
• 一旦达到 100%，就很容易维持——覆盖率报告会准确列出需要测试的代码行

资源

references/

• checklist.md —— 针对五项原则中每一项的详细评估标准，包括特定技术栈的工具、关键指标（Strong/Adequate/Weak）和指导。执行审计或就任何原则提供详细指导时，请加载此文件。