agent-ready-codebase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent-Ready Codebase

适配Agent的代码库

Overview

概述

When agents struggle with a codebase, they are reflecting and amplifying the codebase's existing weaknesses. This skill evaluates codebases against five principles that determine agent effectiveness, and provides concrete guidance to improve each one. It adapts to the project's language and stack.

Based on "AI Is Forcing Us To Write Good Code".

当Agent在代码库中运作困难时，实际上是在反映并放大代码库本身存在的缺陷。本Skill会基于决定Agent运作效率的五大原则评估代码库，并提供具体的改进指导。它会根据项目的语言和技术栈进行适配。

本文基于《AI Is Forcing Us To Write Good Code》（https://bits.logic.inc/p/ai-is-forcing-us-to-write-good-code）一文创作。

Mode Selection

模式选择

Determine which mode to operate in based on context:

Audit: The user has an existing codebase and wants to know where it stands. Evaluate all five principles and produce a scorecard with specific findings.
Guide: The user wants to improve a specific principle or set up a new project. Provide targeted, actionable steps for their stack.

If the mode is unclear, ask.

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

审计模式：用户已有代码库，想了解其当前适配状态。评估全部五大原则，并生成包含具体发现的评分卡。
指导模式：用户希望改进某一特定原则，或搭建新项目。针对其技术栈提供有针对性的可操作步骤。

如果模式不明确，请询问用户。

The Five Principles

五大原则

100% Test Coverage -- Force every line of code to demonstrate its behavior with an executable example
Thoughtful File Structure -- Make the filesystem a navigable interface for agents
End-to-End Types -- Eliminate illegal states and shrink the agent's search space
Fast, Ephemeral, Concurrent Dev Environments -- Keep feedback loops short and enable parallel agent workflows
Automated Enforcement -- Remove degrees of freedom from the agent via linters, formatters, and hooks

100%测试覆盖率 —— 用可执行示例验证每一行代码的行为
清晰的文件结构 —— 让文件系统成为Agent可轻松导航的界面
端到端类型系统 —— 消除非法状态，缩小Agent的搜索范围
快速、临时、并发的开发环境 —— 缩短反馈循环，支持Agent并行工作流
自动化强制执行机制 —— 通过代码检查器（linter）、格式化工具和钩子（hook）限制Agent的操作自由度

Audit Workflow

审计工作流

To audit a codebase, work through these steps:

要审计代码库，请遵循以下步骤：

1. Detect the Stack

1. 检测技术栈

Identify the primary language, test framework, build system, and database by examining project files (e.g.

package.json

go.mod

Gemfile

pyproject.toml

Cargo.toml

). This determines which tooling recommendations apply.

通过检查项目文件（如

package.json

、

go.mod

、

Gemfile

、

pyproject.toml

、

Cargo.toml

）识别主要语言、测试框架、构建系统和数据库。这将决定适用哪些工具推荐。

2. Evaluate Each Principle

2. 评估各项原则

Read

references/checklist.md

for detailed criteria per principle. For each principle, determine the current state:

Test Coverage: Run or inspect coverage tooling. Look for CI enforcement. Report the current percentage and whether uncovered lines are identifiable.
File Structure: Sample the directory tree. Measure file sizes. Flag catch-all files (
```
utils
```
,
```
helpers
```
,
```
common
```
). Assess whether filenames communicate domain purpose.
Type System: Check for strict mode, semantic type names, API contract schemas, database constraints. Identify
```
any
```
/untyped gaps.
Dev Environments: Check for single-command setup, test suite runtime, port/DB isolation, worktree or container support.
Automated Enforcement: Check for linter/formatter configs, CI pipelines, git hooks, agent hooks.

阅读

references/checklist.md

获取每项原则的详细评估标准。针对每项原则，确定其当前状态：

测试覆盖率：运行或检查覆盖率工具。查看是否有CI强制执行机制。报告当前覆盖率百分比，以及是否能识别未覆盖的代码行。
文件结构：抽样查看目录树。衡量文件大小。标记通用型文件（如
```
utils
```
、
```
helpers
```
、
```
common
```
）。评估文件名是否能清晰传达领域用途。
类型系统：检查是否启用严格模式、语义化类型名称、API契约 Schema、数据库约束。找出
```
any
```
类型或未类型化的空白区域。
开发环境：检查是否支持一键式搭建、测试套件运行时长、端口/数据库隔离、工作区或容器支持情况。
自动化强制执行：检查是否有代码检查器/格式化工具配置、CI流水线、Git钩子、Agent钩子。

3. Produce the Scorecard

3. 生成评分卡

Present findings as a table with one row per principle:

Principle	Rating	Key Finding
Test Coverage	Strong / Adequate / Weak	e.g. "87% coverage, no CI enforcement"
File Structure	Strong / Adequate / Weak	e.g. "3 files over 500 lines, 2 catch-all utils files"
Types	Strong / Adequate / Weak	e.g. "Strict TS, but no API schema generation"
Dev Environments	Strong / Adequate / Weak	e.g. "Manual 8-step setup, no concurrent support"
Enforcement	Strong / Adequate / Weak	e.g. "ESLint configured but not in CI"

以表格形式呈现发现结果，每行对应一项原则：

原则	评级	关键发现
测试覆盖率	优秀 / 合格 / 薄弱	例如：“覆盖率87%，无CI强制执行”
文件结构	优秀 / 合格 / 薄弱	例如：“3个文件超过500行，2个通用型utils文件”
类型系统	优秀 / 合格 / 薄弱	例如：“启用严格TS模式，但无API Schema生成”
开发环境	优秀 / 合格 / 薄弱	例如：“需手动完成8步搭建，不支持并发”
自动化强制执行	优秀 / 合格 / 薄弱	例如：“已配置ESLint，但未在CI中启用”

4. Prioritize Improvements

4. 确定改进优先级

Rank the weakest principles and suggest concrete next steps for the top 2-3. Each recommendation should reference the project's actual stack and tooling.

对最薄弱的原则进行排序，并针对前2-3项提出具体的下一步改进建议。每项建议都应参考项目的实际技术栈和工具。

Guide Workflow

指导工作流

When guiding improvements to a specific principle:

Read
```
references/checklist.md
```
for the relevant section
Assess current state of that principle in the project
Provide a concrete, ordered list of changes for the project's stack
Where possible, show exact commands or config snippets

当指导用户改进某一特定原则时：

阅读
```
references/checklist.md
```
中的对应章节
评估项目中该原则的当前状态
针对项目技术栈提供具体的、有序的变更列表
尽可能提供精确的命令或配置代码片段

Key Insight: Why 100% Coverage

核心见解：为何需要100%覆盖率

The most counterintuitive principle deserves emphasis. At 100% line coverage:

There is a phase change: uncovered lines are always from recent changes, removing all ambiguity about what needs testing
The coverage report becomes a simple todo list of tests still needed
It is not about proving "no bugs" -- it forces the author to demonstrate how every line behaves
Unreachable code surfaces immediately and gets deleted
Code reviews become easier because reviewers see concrete behavior examples
Once achieved, 100% is remarkably easy to maintain -- the coverage report enumerates exactly what lines need testing

最违反直觉的原则值得重点强调。当达到100%行覆盖率时：

会发生质的变化：未覆盖的代码行始终来自最近的变更，消除了所有关于需要测试内容的歧义
覆盖率报告变成了简单的待办事项列表，明确列出仍需编写的测试
这不是为了证明“无Bug”——而是迫使代码作者演示每一行代码的行为
不可达代码会立即显现并被删除
代码评审变得更容易，因为评审者可以看到具体的行为示例
一旦实现100%覆盖率，维护起来异常简单——覆盖率报告会准确列出需要测试的代码行

Resources

资源

references/

```
checklist.md
```
-- Detailed evaluation criteria for each of the five principles, including stack-specific tooling, key indicators (Strong/Adequate/Weak), and guidance. Load this file when performing an audit or providing detailed guidance on any principle.

```
checklist.md
```
—— 包含每项原则的详细评估标准，包括技术栈特定工具、关键指标（优秀/合格/薄弱）和指导内容。执行审计或提供某一原则的详细指导时，请加载此文件。