readiness-report

Agent 就绪度报告

评估代码仓库对 AI 辅助自主开发的支持程度。

功能说明

从五大支柱评估代码库，判断 AI Agent 能否在代码仓库中高效工作。输出为一份结构化报告，指出已有和缺失的内容。

五大支柱

支柱	问题	特性
Agent 指令	Agent 知道该做什么吗？	18
反馈循环	Agent 知道自己做得对不对吗？	16
工作流与自动化	流程是否支持 Agent 工作？	15
策略与治理	Agent 知道规则吗？	13
构建与开发环境	Agent 能构建和运行项目吗？	12

共 74 项特性。完整列表、说明和证据示例请参阅 references/criteria.md。

运行方法

第 1 步：运行扫描脚本

五个 shell 脚本会收集文件系统信号，包括文件是否存在、配置模式和目录结构。它们会找出已有内容，这样你就不必手动运行几十条 find 命令。

bash scripts/scan_agent_instructions.sh /path/to/repo
bash scripts/scan_feedback_loops.sh /path/to/repo
bash scripts/scan_workflows.sh /path/to/repo
bash scripts/scan_policy.sh /path/to/repo
bash scripts/scan_build_env.sh /path/to/repo

也可以一次扫描全部五项：

for s in scripts/scan_*.sh; do bash "$s" /path/to/repo; echo; done

重要提示：这些脚本只是辅助工具，不负责评分。它们会查找文件和模式，但不会评估质量。许多特性需要通过阅读实际文件来判断，例如 README 是否包含实际的构建命令，而不只是徽章；内联文档是否系统化，而不是零散分布；AI 使用策略是否明确规定了有意义的边界。

第 2 步：评估每项特性

逐项查看 references/criteria.md 中的五大支柱。对于每项特性：

1. 查看扫描器输出中的相关信号
2. 对于扫描器无法完整评估的特性，自行检查文件
3. 为每项特性标记：✓（已有）、✗（缺失）或 —（不适用）

需要判断的特性（扫描器无法完整覆盖）：

• README 是否确实包含构建／运行／测试命令？（而不仅仅是文件存在）
• 是否系统地为整个公共 API 编写了内联文档？
• 示例是否确实可以运行？
• 贡献指南是否包含代码规范？
• 是否有切实可行的 AI 使用策略？
• 架构文档是否为最新版本？
• 测试文档是否足够完善，能让 Agent 运行测试？

第 3 步：编写报告

按以下结构组织输出：

# Agent Readiness Report: {repo name}

## Summary
- Features present: X / 74
- Strongest pillar: {pillar}
- Weakest pillar: {pillar}

## Pillar 1 · Agent Instructions (X / 18)
✓ Agent instruction file — AGENTS.md at root
✓ AI IDE configuration — .cursor/rules/ with 3 rule files
✗ Multi-model support — only Cursor configured
...

## Pillar 2 · Feedback Loops (X / 16)
...

## Pillar 3 · Workflows & Automation (X / 15)
...

## Pillar 4 · Policy & Governance (X / 13)
...

## Pillar 5 · Build & Dev Environment (X / 12)
...

对于每项通过的特性，简要注明找到的证据。 对于每项未通过的特性，注明缺少的内容。

这些特性为何有用

每项特性都在回答：如果缺少这项，AI Agent 会遇到什么问题？ “Agent 指令文件”和“工具服务配置”等特性之所以存在，是因为 Agent 需要它们。“代码检查器”和“CI 流水线”等特性之所以存在，是因为 Agent 需要快速、明确地获知自己的更改是否正确，而不仅仅是因为它们属于通用最佳实践。

这些标准源自对 123 个真实代码仓库的分析，涵盖五类 AI 就绪度，之后又经过筛选，只保留了会实际影响 Agent 效率的特性。

---

致谢与归属

此技能基于 OpenHands 的出色工作。

原始代码仓库：https://github.com/OpenHands/skills

特别感谢 OpenHands 慷慨提供开源贡献，为打造这套技能提供了帮助。 由 webconsulting.at 改编，用于这套技能