让仓库达到 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 能够跨会话自我进化