codebase-readiness

代码库就绪度评估

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

按顺序完成以下阶段。

---

阶段 1：代码库侦察

在评估环节开始前，运行侦察脚本，收集项目元数据。请直接在当前 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 受治理）；只有当证据与启发式建议矛盾时才修改该行，并说明原因。快照缺少此行时，不要开始评估环节——每个环节只评估质量门禁证据中的一个切片，并从快照读取级别；如果缺少该行，每个环节都会各自重新推导，导致四个维度得出的结果不一致。

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

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

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

---

阶段 2：运行 4 个评估环节

提示词组合

每个环节都会收到一份由参考文件组合而成的提示词：

1. 读取语言文件——references/languages/{PRIMARY_LANGUAGE}.md
2. 读取维度文件——每个环节从 references/dimensions/ 中获取相关维度文件
3. 读取共享质量门禁参考——Test & CI、Code Quality 和 Architecture 环节都需要读取 references/quality-gates.md（每个环节评估不同切片；归属表用于避免重复计分）
4. 组合提示词——角色前言 + 代码库快照 + 维度内容 + 质量门禁内容 + 语言内容 + 输出说明

加载每个参考文件，然后将其内容内联到各环节的提示词中。加入语言文件时，应指示每个环节只参考与其指定维度相关的部分。

如何运行各环节

运行以下全部四个环节。运行环境支持并行时，优先并行执行；不支持时，则在当前 Agent 中一次运行一个环节。不要因无法并行而跳过某个环节，也不要要求使用特定供应商的工具。

• 支持时并行执行。 同时启动全部四个环节，并等待每个环节都返回后再进入阶段 3。在 Claude Code 中，发送一条消息并调用四次 Agent 工具（subagent_type: general-purpose）。在 Cursor、Codex 和其他 Agent 中，使用该运行环境的子 Agent 或并行任务机制。
• 顺序执行的回退方案。 如果运行环境不支持子 Agent 或并行任务，则在当前 Agent 中依次运行四个环节。完成一个环节后，保留其评分结果，再开始下一个环节。

无论采用哪种方式，每个环节收到的组合提示词都必须相同。

评估轮次提示词

---

第 1 轮：测试与 CI

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

• 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.

---

第 2 轮：文档

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

• 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.

---

第 3 轮：代码质量

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

• 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.

---

第 4 轮：架构

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

• 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.

---

等待全部四轮完成后再继续。顺序执行时，第四轮完成即满足此条件。

---

阶段 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 读取报告模板。使用各轮检查的结果，以及与代码库在阶段 3 中确定的 LANGUAGE_TIER 相匹配的权重表填写模板。

在报告中原样包含传递给各轮检查的 Codebase Snapshot，包括 Quality gates 行，并在 Quality Gate Maturity 部分逐字重复该行。快照与该部分的内容绝不能不一致。

**重要：**使用阶段 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