mcpField

agent-readiness

github.com/supatest-aiAgent 工作流256 次安装2 周前更新
代码仓库

关于 agent-readiness

agent-readiness 用于评估代码仓库能否支持编码 Agent 从任务规格推进到本地验证。脚本可进行静态检查并选配会话日志分析，生成包含评分、缺口和行动建议的 HTML 报告。

主要功能

  1. 01自动评估仓库就绪情况
  2. 02选配编码 Agent 会话日志分析
  3. 03按工程维度评分
  4. 04生成含优先行动项的 HTML 报告

适用场景

  1. 01分配 Agent 任务前识别仓库缺口
  2. 02检查编码 Agent 会话中的重复失败
  3. 03确定本地验证流程的改进优先级

MCP 相关

该评估可从可用会话日志中检测重复出现的 MCP schema 问题；项目未说明 MCP 服务端或客户端功能。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/supatest-ai/supa-skills --skill agent-readiness

安装后在 Claude Code 中输入/agent-readiness确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

scripts/
analyze_sessions.py
compact_sessions.py
render_html_report.py
run_readiness_check.py
sample_sessions.py
session_events.py
test_session_events.py

详细介绍

Agent 就绪度评估

评估代码仓库是否为自主编码 Agent 提供了足够的结构，使其能够在无需人工指导的情况下，从规格说明到实现再到本地验证完成任务。

自动分析（默认）

此技能附带 scripts/ 目录中的分析脚本。如果 Python 3 可用，请使用组合运行器进行完整评估，包括会话日志模式分析：

# Full assessment (with session log analysis)
python3 scripts/run_readiness_check.py \
  --sessions-dir ~/.claude/projects/PROJECT-NAME \
  --repo .

# Static audit only (no session logs needed — fastest)
python3 scripts/run_readiness_check.py \
  --repo . \
  --skip-sessions \
  --output /tmp/agent-readiness-report.html

输出是一份 HTML 报告，位于 /tmp/agent-readiness-report.html，其中包含成熟度级别、各维度评分、失败模式、关键缺口和按优先级排序的行动计划。

会话日志分析

如果会话日志可用（位于 ~/.claude/projects/ 的 Claude Code、Codex、Cursor 等工具生成的 .jsonl 文件），分析器会检测：

  • 分类分布（仅研究、仅验证、受阻、任务完成者等）
  • 失败最多的工具和命令
  • 重复出现的失败模式（浏览器身份验证、测试失败、MCP 架构问题等）
  • 编辑后的验证率
  • 所选会话的精简定性摘要

迭代时，可传入 --max-sessions N，以使用较小的样本。分析器会按文件哈希缓存解析结果，因此重新运行几乎是即时完成的。

评分清单

手动评分时（或用于验证自动分析结果时），请使用以下评分标准：

维度主题检查项缺失时的影响
1规格清晰度包含验收标准、边界情况和非目标的结构化模板没有模板 → 最高 3 分
2Agent 指令根目录中的 AGENTS.md，包含技术栈、路径和命令没有 → 最高 2 分
2Agent 指令记录高风险不变量（迁移、密钥等）缺失 → −1 分
3代码清晰度严格 TypeScript 或同等的静态类型没有 → 最高 2 分
3代码清晰度业务逻辑与框架连接代码分离混杂 → −1 分
4可搜索性可按名称或路由发现功能流程隐蔽 → −1 分
4可搜索性清晰标记生成代码/供应商代码混杂 → −0.5 分
5本地环境已提交依赖锁文件没有锁文件 → 最高 2 分
5本地环境一条命令即可运行的设置脚本需手动操作 → −1 分
6测试存在单元测试、集成测试和 E2E 测试没有 → 最高 1 分
6测试针对各部分的专用测试命令只有通用命令 → −0.5 分
7静态验证已配置并记录代码检查工具没有 → 最高 2 分
7静态验证预提交或 CI 钩子会强制执行代码检查缺失 → −0.5 分
8构建反馈存在针对各包的构建命令只有根目录命令 → −0.5 分
8构建反馈已记录支持 HMR 的开发模式缺失 → −1 分
9可调试性测试会生成诊断产物（截图、跟踪记录）没有 → −1 分
9可调试性结构化错误类型错误被静默处理 → −1 分
10安全性明确说明破坏性迁移的工作流程未明确 → 最高 3 分
10安全性.gitignore 中忽略密钥/环境文件未忽略 → 最高 2 分
11浏览器自动化身份验证绕过机制可避免登录页面需手动登录 → 最高 2 分
11浏览器自动化稳定的选择器（data-testid 或无障碍角色）CSS 类 → −1 分

每个维度从 3 分开始，根据清单向上或向下调整，最高 5 分，最低 1 分。

评估内容
#维度
1代码可理解性 — 强类型、清晰的名称、可预测的结构
2上下文与文档 — AGENTS.md、README、ADR、行内说明原因
3可验证性与测试 — 测试金字塔、类型检查器、代码检查器、CI 门禁
4开发环境可复现性 — 一键设置、锁定依赖、容器化服务
5风格与验证工具 — 严格的代码检查器、格式化工具、提交前钩子
6构建系统 — 确定性构建、快速反馈、HMR
7可观测性与可调试性 — 结构化日志、健康检查、可操作的错误
8安全与治理 — 分支保护、密钥扫描、CODEOWNERS
9任务发现与范围界定 — 问题模板、验收标准、完成定义
10规格与规划质量 — 结构化 PRD、API 契约、可衡量的成功标准
11CI/CD 与部署流水线 — 自动化门禁、预发布环境、回滚文档
成熟度等级
等级分数Agent 能做什么
脆弱<2.0仅探索；需要密切监督
有文档2.0–2.9在严格审查下完成小型更改
标准化3.0–3.9完成范围明确且可在本地验证的任务
优化4.0–4.4完成涉及多个文件的复杂任务，只需少量审查
自主4.5+从规格到经过测试的实现，全程只需策略性监督
手动模式（无 Python）

如果无法使用 Python 3，请使用上述清单手动为每个维度打 1–5 分。生成的报告需包含：总体等级、维度表、关键差距、行动计划和覆盖情况表。输出格式请参阅自动生成的报告。

报告交付

如果团队的制品/文档工具可用，请将报告保存为 HTML 文档制品。否则，请在聊天中显示摘要，并注明完整 HTML 文件的路径：/tmp/agent-readiness-report.html。

更新

此技能来自 supatest-ai/supa-skills 市场。脚本的权威来源是 supatest-ai/aiden 仓库中的 .agents/skills/agent-readiness/scripts/。

评论

支持 Markdown