codebase-readiness

代码库就绪度评估

运行 Agent 就绪代码库评估，对代码库支持 AI Agent 自主工作的程度进行评分，并以 Stripe 每周生成 1,000 多个 AI 生成拉取请求的基准为参照。

请按顺序完成以下阶段。

---

阶段 1：代码库侦察

启动评估 Agent 前，先运行侦察脚本收集项目元数据。直接运行，无需 Agent。

bash scripts/recon.sh

脚本位于相对于此技能目录的 scripts/recon.sh。

查看输出后，整理一份代码库快照：

## Codebase Snapshot: [Project Name]

- **Primary language/framework**: [detected]
- **Language tier**: [statically-typed | dynamically-typed | gradually-typed]
  - Statically-typed: TypeScript, Go, Java, Scala, Rust, C#, Kotlin
  - Dynamically-typed: Ruby, Python (unannotated), JavaScript/Node.js, PHP
  - Gradually-typed: Python with mypy/Pydantic, TypeScript with strict:false
- **Commit count**: [X]
- **Contributors**: [X]
- **Source files**: [X]
- **Test files**: [X] (ratio: X%)
- **CI/CD**: [platform(s) found or none]
- **Agent instructions**: [AGENTS.md / CLAUDE.md / both, with canonical path and symlink status / absent]
- **Domain context**: [CONTEXT.md / CONTEXT-MAP.md / docs/DOMAIN.md / absent; ADR location and count]
- **Linting config**: [tools found or none]
- **Quality gates**: [copy the `Suggested Gate Maturity Level: Lx -- ...` line from recon output, e.g. "L0 -- no complexity, duplication, or dead-code tooling detected"]
- **README**: [present, X lines / absent]

必须包含 Quality gates 行。 recon.sh 会在其 === QUALITY GATES === 部分末尾输出 Suggested Gate Maturity Level: Lx -- <reason>。将该级别和原因复制到快照的 Quality gates 行。然后阅读 references/quality-gates.md，根据其上方的详细证据核对建议（L0 无，L1 仅报告，L2 阈值，L3 感知回归的阻断，L4 治理）；只有当证据与启发式判断相矛盾时才修改该行，并说明原因。不要向评估 Agent 提供缺少此行的快照——Agent 只会为各自负责的质量门证据部分评分，并从快照读取级别；如果缺少此行，每个 Agent 都会独立重新推导级别，导致四个维度的评分不一致。

根据快照确定 PRIMARY_LANGUAGE 和 LANGUAGE_TIER。这些值决定要加载哪个语言参考文件。

支持的语言： ruby、python、php、typescript、javascript、go、java、scala、rust。

如果主要语言不在支持列表中，请告知用户支持哪些语言。如果用户同意，可使用最接近的受支持语言文件继续评估；也可以不使用语言专属标准，按通用标准评估各维度。

---

阶段 2：并行启动 4 个评估 Agent

提示词组合

每个 Agent 都会收到一份组合提示词，该提示词由参考文件构建而成：

1. 读取语言文件——references/languages/{PRIMARY_LANGUAGE}.md
2. 读取维度文件——每个 Agent 都会获得与其相关的 references/dimensions/ 中的维度文件
3. 读取共享质量门参考文件——references/quality-gates.md 会提供给测试与 CI、代码质量和架构 Agent（每个 Agent 评分不同部分；归属表可防止重复计分）
4. 组合提示词——角色前言 + 代码库快照 + 维度内容 + 质量门内容 + 语言内容 + 输出说明

使用 Read 工具加载每个参考文件，然后将其内容内联到 Agent 提示词中。包含语言文件时，指示每个 Agent 仅参考与其分配维度相关的章节。

Agent 提示词

发送一条消息，其中包含 4 个 Agent 工具调用（subagent_type：general-purpose），同时启动所有 Agent。

---

Agent 1：测试与 CI Agent

需要读取并纳入的维度文件：

• references/dimensions/test-foundation.md
• references/dimensions/feedback-loops.md
• references/quality-gates.md（仅反馈循环部分：可操作性、可复现性、门禁测试）

提示词：

You are a senior engineering consultant specializing in test infrastructure and developer feedback loops. Assess how well this codebase's testing and CI/CD setup supports autonomous AI agent work.

Codebase Snapshot:

[INSERT FULL CODEBASE SNAPSHOT]

LANGUAGE_TIER: [static | dynamic | gradual]
PRIMARY_LANGUAGE: [Ruby | Python | TypeScript | Go | etc.]

## Assessment Instructions

Use the dimension guides and language-specific criteria below to assess two dimensions: **Test Foundation** and **Feedback Loops**. Run the evidence-gathering commands from both the dimension guides and the language file to collect data. Score each dimension 0-100 following the scoring bands, then apply any score modifiers.

Reference only the Test Foundation and Feedback Loops sections from the language file.

### Dimension Guide: Test Foundation

[INSERT CONTENT OF references/dimensions/test-foundation.md]

### Dimension Guide: Feedback Loops

[INSERT CONTENT OF references/dimensions/feedback-loops.md]

### Shared Reference: Regression-Aware Quality Gates

Use the Gate Maturity Level from the snapshot. Score only the Feedback Loops slice from the credit-ownership table (actionability, reproducibility, gate tests). Do not credit tool coverage or blocking behaviour here.

[INSERT CONTENT OF references/quality-gates.md]

### Language-Specific Criteria

[INSERT CONTENT OF references/languages/{PRIMARY_LANGUAGE}.md]

Return the full scored assessment for both dimensions in the output format specified in each dimension guide. Be specific — reference actual files, counts, and statistics.

---

Agent 2：文档 Agent

需要读取并纳入的维度文件：

• references/dimensions/documentation.md

提示词：

You are a senior engineering consultant specializing in developer experience and knowledge management. Assess how well this codebase's documentation enables AI agents to work autonomously without constant human clarification.

Codebase Snapshot:

[INSERT FULL CODEBASE SNAPSHOT]

LANGUAGE_TIER: [static | dynamic | gradual]
PRIMARY_LANGUAGE: [Ruby | Python | TypeScript | Go | etc.]

## Assessment Instructions

Use the dimension guide and language-specific criteria below to assess one dimension: **Documentation & Context**. Run the evidence-gathering commands to collect data. Score 0-100 following the scoring bands.

Reference only the Documentation sections from the language file.

### Dimension Guide: Documentation & Context

[INSERT CONTENT OF references/dimensions/documentation.md]

### Language-Specific Criteria

[INSERT CONTENT OF references/languages/{PRIMARY_LANGUAGE}.md]

Return the full scored assessment in the output format specified in the dimension guide. Be specific — reference actual files found. Treat the project's canonical agent instruction entrypoint as primary: AGENTS.md when CLAUDE.md is its symlink, otherwise the existing root instruction file. Assess conflicting duplicate files as a coherence risk.

---

Agent 3：代码质量 Agent

需要读取并纳入的维度文件：

• references/dimensions/code-clarity.md
• references/dimensions/consistency.md
• references/quality-gates.md（代码清晰度部分：结构覆盖；一致性部分：lint 债务处理）

提示词：

You are a senior engineering consultant specializing in code quality and developer tooling. Assess how navigable and consistent this codebase is for AI agents — agents perform better in codebases with small, focused files and enforced conventions.

Codebase Snapshot:

[INSERT FULL CODEBASE SNAPSHOT]

LANGUAGE_TIER: [static | dynamic | gradual]
PRIMARY_LANGUAGE: [Ruby | Python | TypeScript | Go | etc.]

## Assessment Instructions

Use the dimension guides and language-specific criteria below to assess two dimensions: **Code Clarity** and **Consistency & Conventions**. Run the evidence-gathering commands from both the dimension guides and the language file to collect data. Score each dimension 0-100 following the scoring bands.

Reference only the Code Clarity and Consistency sections from the language file.

### Dimension Guide: Code Clarity

[INSERT CONTENT OF references/dimensions/code-clarity.md]

### Dimension Guide: Consistency & Conventions

[INSERT CONTENT OF references/dimensions/consistency.md]

### Shared Reference: Regression-Aware Quality Gates

Use the Gate Maturity Level from the snapshot. Code Clarity credits which structural properties (complexity, duplication, dead code) are covered and whether each is blocked at L3+. Consistency credits lint/format enforcement and how lint legacy debt is treated. Do not credit CI ergonomics or baseline governance in either dimension.

[INSERT CONTENT OF references/quality-gates.md]

### Language-Specific Criteria

[INSERT CONTENT OF references/languages/{PRIMARY_LANGUAGE}.md]

Return the full scored assessment for both dimensions in the output format specified in each dimension guide. Be specific — reference actual files and line counts.

---

Agent 4：架构 Agent

需要读取并纳入的维度文件：

• references/dimensions/type-safety.md
• references/dimensions/architecture-clarity.md
• references/dimensions/change-safety.md
• references/quality-gates.md（仅变更安全部分：阻断语义和基线治理）

提示词：

You are a senior engineering consultant specializing in software architecture and developer safety systems. Assess how safely and predictably AI agents can modify this codebase — guard rails vary by language: type systems for statically-typed languages, contract/test systems for dynamically-typed ones.

Codebase Snapshot:

[INSERT FULL CODEBASE SNAPSHOT]

LANGUAGE_TIER: [static | dynamic | gradual]
PRIMARY_LANGUAGE: [Ruby | Python | TypeScript | Go | etc.]

## Assessment Instructions

Use the dimension guides and language-specific criteria below to assess three dimensions: **Type Safety**, **Architecture Clarity**, and **Change Safety**. Run the evidence-gathering commands from both the dimension guides and the language file to collect data. Score each dimension 0-100 following the scoring bands, then apply any score modifiers. Apply the language-appropriate Type Safety rubric based on LANGUAGE_TIER.

Reference only the Type Safety, Architecture, and Change Safety sections from the language file.

### Dimension Guide: Type Safety

[INSERT CONTENT OF references/dimensions/type-safety.md]

### Dimension Guide: Architecture Clarity

[INSERT CONTENT OF references/dimensions/architecture-clarity.md]

### Dimension Guide: Change Safety

[INSERT CONTENT OF references/dimensions/change-safety.md]

### Shared Reference: Regression-Aware Quality Gates

Use the Gate Maturity Level from the snapshot. Score only the Change Safety slice: whether CI blocks new or worsened structural debt (L3+) and how the baseline is governed. Do not credit tool selection or CI ergonomics here.

[INSERT CONTENT OF references/quality-gates.md]

### Language-Specific Criteria

[INSERT CONTENT OF references/languages/{PRIMARY_LANGUAGE}.md]

Return the full scored assessment for all three dimensions in the output format specified in each dimension guide. Be specific — reference actual files, line counts, and git statistics.

---

等待所有 4 个 Agent 完成后再继续。

---

阶段 3：分数计算

权重会根据语言动态调整。根据代码库快照中的 LANGUAGE_TIER 选择相应的表格。

动态类型语言（Ruby、Python、JavaScript、PHP）

在动态类型语言中，测试就是类型系统。测试基础的权重更高；类型安全反映的是契约和接口清晰度，而非类型检查器。

维度	权重	Agent 分数	加权分数
测试基础	25%	XX/100	XX
文档与上下文	15%	XX/100	XX
代码清晰度	15%	XX/100	XX
架构清晰度	15%	XX/100	XX
反馈循环	10%	XX/100	XX
类型安全*	10%	XX/100	XX
一致性与约定	5%	XX/100	XX
变更安全	5%	XX/100	XX

*动态类型语言的类型安全 = 契约（dry-rb、Pydantic）、ActiveRecord/Eloquent 验证、Form Requests、PHPStan/Larastan、Result 模式的一致性。不会因缺少编译型类型检查器而扣分。

静态类型语言（TypeScript、Go、Java、Scala、Rust）

维度	权重	Agent 分数	加权分数
类型安全	20%	XX/100	XX
测试基础	15%	XX/100	XX
文档与上下文	15%	XX/100	XX
代码清晰度	15%	XX/100	XX
架构清晰度	15%	XX/100	XX
反馈循环	10%	XX/100	XX
一致性与约定	5%	XX/100	XX
变更安全	5%	XX/100	XX

总分 = 各项（Agent 分数 × 权重）之和

分数区间：

• 85-100：适合 Agent——代码库支持 Agent 自主工作
• 70-84：Agent 辅助——Agent 可以高效工作，但需要人工监督
• 50-69：Agent 监督——Agent 需要经过严格审查后才能合并
• 30-49：谨慎使用 Agent——需要先进行基础改进
• 0-29：不适合 Agent——在 Agent 工作之前需要大量投入

---

第 4 阶段：组装报告

从 assets/report-template.md 读取报告模板。使用 Agent 的结果以及与第 3 阶段代码库 LANGUAGE_TIER 匹配的权重表填写模板。

在报告中原样包含提供给 Agent 的 Codebase Snapshot，包括 Quality gates 行，并在 Quality Gate Maturity 部分逐字重复该行。Snapshot 与该部分绝不能相互矛盾。

**重要提示：**使用第 3 阶段相应表格中的准确权重（动态权重或静态权重）。不要使用硬编码的权重——不同语言等级的权重有所不同。

输出完整报告。

---

第 5 阶段：询问是否保存报告

展示报告后，询问：

“您希望我将此评估保存为项目根目录中的 AGENT_READY_ASSESSMENT.md 吗？它可以作为跟踪改进情况的基线，并且便于与团队分享。”

如果用户确认，将完整报告写入当前目录中的 AGENT_READY_ASSESSMENT.md。

---

第 6 阶段：CI 集成建议

保存后（或用户拒绝保存时），如果 Gate Maturity Level 为 L0-L2，请说明 agent-ready 插件的 quality-gates 模式可以使用项目的原生工具安装一个具备回归意识的门禁（包含 report / check / baseline 命令、基于 merge-base 的 CI、经过审核的基线和测试）：

您的质量门禁得分为 [Lx]。运行 agent-ready 的 quality-gates 模式，安装一个门禁，在不强制先清理历史遗留债务的情况下，阻止复杂度、重复代码和死代码新增或恶化。

然后说明：

**持续跟踪：**考虑将 btar 添加到 CI 流水线。它可以快速、确定性地测量您的验证基础设施（类型错误、lint 违规、测试覆盖率），并在分数回退时阻止 PR 合并。此评估提供战略性基线；btar 则通过 CI 每日强制执行最关键的指标。

npm install -g btar
btar analyze .          # 快速评分：类型 + lint + 覆盖率
btar context generate agents-md  # 自动生成包含构建/测试命令的 AGENTS.md