readiness-report

Agent 就绪度报告

通过从八个技术支柱和五个成熟度级别进行分析，评估代码库对自主 AI 开发的支持程度。

概览

Agent 就绪度用于衡量代码库为 AI 辅助开发做好了多少准备。反馈循环不佳、缺少文档或缺乏工具，都会导致 Agent 在本可避免的错误上浪费时间。本技能会找出这些差距并确定修复优先级。

快速开始

用户将运行 /readiness-report 来评估当前代码库。随后，Agent 会：

1. 克隆代码库，扫描代码库结构、CI 配置和工具
2. 评估 9 个技术支柱中的 81 项标准
3. 根据每个级别 80% 的门槛确定成熟度级别（L1-L5）
4. 提供按优先级排列的建议

工作流

步骤 1：运行代码库分析

执行分析脚本，从代码库中收集信号：

python scripts/analyze_repo.py --repo-path .

此脚本会检查：

• 配置文件（.eslintrc、pyproject.toml 等）
• CI/CD 工作流（.github/workflows/、.gitlab-ci.yml）
• 文档（README、AGENTS.md、CONTRIBUTING.md）
• 测试基础设施（测试目录、覆盖率配置）
• 安全配置（CODEOWNERS、.gitignore、密钥管理）

步骤 2：生成报告

分析完成后，生成格式化报告：

python scripts/generate_report.py --analysis-file /tmp/readiness_analysis.json

步骤 3：呈现结果

报告包括：

1. 总体得分：通过率百分比和达到的成熟度级别
2. 级别进度：显示 L1-L5 完成百分比的进度条
3. 优势：表现最佳且通过标准的支柱
4. 改进机会：按优先级排列的待实施改进列表
5. 详细标准：按支柱列出的完整明细，显示每项标准的状态

九个技术支柱

每个支柱都针对 AI 辅助开发中的特定故障模式：

支柱	目的	关键信号
风格与验证	立即发现错误	代码检查工具、格式化工具、类型检查器
构建系统	实现快速、可靠的构建	构建文档、CI 速度、自动化
测试	验证正确性	单元测试／集成测试、覆盖率
文档	为 Agent 提供指引	AGENTS.md、README、架构文档
开发环境	实现可复现的设置	Devcontainer、环境模板
调试与可观测性	诊断问题	日志记录、追踪、指标
安全	保护代码库	CODEOWNERS、密钥管理
任务发现	找到待处理的工作	Issue 模板、PR 模板
产品与分析	建立从错误到洞察的反馈循环	错误跟踪、产品分析

完整的 81 项支柱标准列表见 references/criteria.md。

五个成熟度级别

级别	名称	说明	Agent 能力
L1	初始级	基本版本控制	仅限手动协助
L2	管理级	基本 CI/CD 和测试	简单、定义明确的任务
L3	标准化级	已具备供 Agent 使用的生产就绪条件	日常维护
L4	度量级	全面的自动化	复杂功能
L5	优化级	完整的自主能力	端到端开发

级别晋升：要解锁某个级别，必须通过该级别至少 80% 的标准，并通过所有更低级别的全部标准。

详细的级别要求见 references/maturity-levels.md。

解读结果

通过、失败与跳过

• ✓ 通过：符合标准（计入得分）
• ✗ 失败：不符合标准（有待改进）
• — 跳过：不适用于此类代码库（不计入得分）

优先级顺序

按以下顺序修复差距：

1. L1-L2 失败项：阻碍 Agent 基本运行的基础问题
2. L3 失败项：生产就绪方面的差距
3. 高影响的 L4+ 失败项：优化机会

常见的快速改进

1. 添加 AGENTS.md：为 AI Agent 编写命令、架构和工作流文档
2. 配置 pre-commit hooks：在 CI 之前发现风格问题
3. 添加 PR/issue 模板：规范任务发现流程
4. 编写单命令设置文档：实现快速配置环境

资源

• scripts/analyze_repo.py - 仓库分析脚本
• scripts/generate_report.py - 报告生成与格式化
• references/criteria.md - 各支柱的完整标准定义
• references/maturity-levels.md - 详细的级别要求

自动修复

查看报告后，可以自动执行常见修复：

• 根据仓库结构生成 AGENTS.md
• 添加缺失的 issue/PR 模板
• 配置标准的代码检查工具和格式化工具
• 设置 pre-commit hooks

输入“修复就绪度缺口”以开始自动修复未通过的标准。