---
title: "让仓库达到 Agent-Ready 状态"
description: "实践指南：如何配置任意仓库，使 AI agent 能够进入、理解项目并以最少的人类指导执行有意义的任务。"
lang: zh
pair: en.md
lastUpdated: 2026-04-23
status: draft
---

# 让仓库达到 Agent-Ready 状态

一份实践指南：如何配置任意仓库，使 AI agent 能在其中高效运作。

## Agent-Ready 的含义

Agent-ready 仓库是指 AI agent 能够进入、理解项目并以最少的人类指导执行有意义任务的仓库。这不是关于某个单一文件或工具——而是整个项目的结构性属性。

## 入口点：AGENTS.md

最关键的文件。Agent 进入仓库时首先读取它。将其命名为 `AGENTS.md`，并通过符号链接创建 `CLAUDE.md`、`.cursorrules`、`.windsurfrules`，使所有主流 agent 工具都能自动找到它。应包含：

1. **项目目的** — 一段话说明项目做什么以及为什么
2. **架构地图** — 目录布局及每个文件夹的内容
3. **构建和测试命令** — 构建、测试和运行的确切命令
4. **约定** — 提交信息格式、代码风格、命名模式
5. **指针** — specs、skills、rules 和其他上下文的位置

控制在 200 行以内。每一行都在争夺上下文窗口空间。

## 目录结构

Agent 友好的结构遵循以下原则：

- **可预测的布局**：Agent 按约定导航。标准目录（`src/`、`tests/`、`docs/`）减少探索开销
- **自描述命名**：名为 `specs/` 的目录立即可理解；`misc/` 则不然
- **扁平优于深层**：浅层级更易扫描和引用
- **上下文共置**：将相关文件放在一起（测试紧邻源码，翻译紧邻原文）

## 原子化提交

Agent 在原子化、标签清晰的提交中工作效果最佳：

- 每次提交只做一件事
- 提交信息使用一致的前缀（`feat:`、`fix:`、`refactor:`、`docs:`）
- 提交信息解释为什么，而不仅是做了什么
- 这使 `git log` 和 `git blame` 成为 agent 有用的上下文来源

## SPEC 驱动决策

对于非平凡的决策，实现前先写 spec：

- Spec 捕获架构选择背后的推理
- Agent 可以阅读 spec 来理解约束，无需重新推导
- Spec 防止 agent 在不知情的情况下逆转刻意的决策

## 配置：.claude/settings.json

项目级 agent 配置减少摩擦：

- 常见操作（构建、测试、git）的权限白名单
- 自动化检查的 hook 定义
- 通过 `.claude/settings.local.json` 进行环境特定覆盖

## 故障日志

维护 agent 故障及其解决方案的记录：

- 出了什么问题以及为什么
- 做了什么改变以防止再次发生
- 这使 agent 能够跨会话自我进化