Back to Details

agent-readiness

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Readiness

Agent就绪度

"The agent is not broken. The environment is." — Factory.ai
Measure how well a repository supports autonomous AI coding agents, and report what to fix first. Based on Factory.ai's Agent Readiness framework — 9 pillars, ~80 criteria, scored as a pass-rate and mapped to 5 gated maturity levels. The criterion catalog in references/pillar-briefs.md is reverse-engineered from Factory's public reports (
factory.ai/agent-readiness/fastapi_fastapi
, 
cockroachdb_cockroach
, …).
This is an investigation, not a checklist run. A score from file-existence alone is shallow — a linter nobody runs, a stale 
.env.example
, or snapshot-only tests all "exist" yet leave the environment broken for an agent. So you delegate a deep, qualitative investigation of each pillar to a dedicated subagent, then you (the orchestrator) cross-reference their reports into a single, defensible score.
Why fan out: each pillar needs real reading — is the linter wired into CI and pre-commit, or just a dangling config? Are the docs accurate against the code, or stale? Do tests assert behavior, or are they filler? One agent can't hold nine deep investigations at once. Subagents keep each one thorough and independent; you stay the synthesizer.
  • Framework background (pillars, failure modes, levels): references/factory-framework.md
  • Per-pillar investigation briefs (what each subagent must dig into): references/pillar-briefs.md
“Agent没有问题，问题出在环境上。” —— Factory.ai
衡量代码仓库对自主AI编码Agent的支持程度，并输出优先修复项。基于Factory.ai的Agent就绪度框架——包含9大支柱、约80条评估标准，以通过率计分，并映射到5个阶梯式成熟度等级。references/pillar-briefs.md中的标准目录是根据Factory的公开报告（
factory.ai/agent-readiness/fastapi_fastapi
、
cockroachdb_cockroach
等）反向整理而来。
这是深度调查，而非简单的清单核对。 仅通过文件存在与否得出的分数是肤浅的——无人运行的linter、过时的
.env.example
、仅包含快照的测试都“存在”，但会导致Agent无法正常使用环境。因此你需要将每个支柱的深度定性调查委派给专门的子Agent，然后你（作为编排者）交叉比对它们的报告，得出一个可靠、有依据的评分。
为什么要拆分任务：每个支柱都需要实际调研——linter是接入了CI和pre-commit，还是只是一个孤立的配置文件？文档与代码是否匹配，还是已经过时？测试是验证实际行为，还是凑数的？单个Agent无法同时开展9项深度调查。子Agent能保证每项调查的彻底性和独立性，而你负责综合汇总。
  • 框架背景（支柱、失败模式、等级）：references/factory-framework.md
  • 各支柱调查概要（每个子Agent需要调研的内容）：references/pillar-briefs.md

Workflow

工作流程

Step 0 — (optional) fast inventory

步骤0 —（可选）快速盘点

Run the bundled helper for a quick map of which configs/files exist:
bash
bash scripts/readiness.sh <repo-path>
This is a starting signal only, not the score — a convenience to hand the subagents so they don't start blind. Skip it if you prefer; the verdict comes from the investigation, not this script.
运行附带的辅助工具，快速梳理现有配置/文件：
bash
bash scripts/readiness.sh <repo-path>
这仅作为起始参考，并非最终评分——只是为了方便子Agent开展工作，避免盲目启动。你也可以跳过这一步；最终结论来自调查，而非这个脚本。

Step 1 — fan out: one subagent per pillar

步骤1 — 任务拆分：每个支柱对应一个子Agent

Spawn 9 subagents in parallel (Task/Agent tool — 
Explore
or 
general-purpose
), one per Factory pillar:
Style & Validation · Build System · Testing · Documentation · Dev Environment · Debugging & Observability · Security · Task Discovery · Product & Analytics
Give each subagent its pillar's criterion table from references/pillar-briefs.md plus the repo path. If you ran Step 0, hand each subagent its own pillar's presence line framed as "confirm or refute" — e.g. "a presence-only scan scored this pillar 4/4; verify with quality judgment." This anchors the investigation and surfaces both false positives (scored present but hollow) and false negatives (scored absent but real in another form). Each subagent must:
  1. Investigate deeply — read the actual configs, sample real source/test/doc files, inspect CI workflows and hooks. Not file-existence; behavior.
  2. Verdict every criterion 
    pass
    / 
    fail
    / 
    skip
     — 
    skip
    only when the criterion genuinely doesn't apply to this repo type (library has no DB → skip 
    database_schema
    ; say why). 
    skip
    is excluded from the score, not a penalty. Do the bold cross-checks in the brief (diff 
    env_template
    against env reads; open ≥3 test files; verify 
    agents_md
    claims resolve; grep for committed secrets) — that's where the real findings come from.
  3. Return a structured report (schema below) with per-criterion verdicts and one-line evidence (file path). (Verdict your own criteria; don't compute the overall score — that's the orchestrator's job.)
并行启动9个子Agent（使用任务/Agent工具——
Explore
或
general-purpose
类型），每个对应Factory框架的一个支柱：
风格与验证 · 构建系统 · 测试 · 文档 · 开发环境 · 调试与可观测性 · 安全 · 任务发现 · 产品与分析
为每个子Agent提供references/pillar-briefs.md中对应支柱的标准表以及仓库路径。如果你执行了步骤0，请将对应支柱的存在性扫描结果以“确认或证伪”的形式发给子Agent——例如“仅扫描文件存在性的话，该支柱得分为4/4；请结合质量判断进行验证”。这能为调查提供锚点，同时发现误报（标记为存在但实际空洞）和漏报（标记为不存在但以其他形式存在）。每个子Agent必须：
  1. 深度调查 — 阅读实际配置文件，抽样查看真实的源码/测试/文档文件，检查CI工作流和钩子。不是检查文件是否存在，而是检查实际运行行为。
  2. 对每条标准给出
    pass
    /
    fail
    /
    skip
    的判定     — 仅当标准确实不适用于该仓库类型时才标记
    skip
    （例如库项目没有数据库 → 跳过
    database_schema
    ；需说明原因）。
    skip
    不计入评分，不会扣分。必须完成概要中加粗的交叉检查项（对比
    env_template
    与实际环境变量读取逻辑；打开至少3个测试文件；验证
    agents_md
    中的声明是否属实；grep检查已提交的密钥）——真实的问题往往来自这些检查。
  3. 返回结构化报告（格式见下文），包含每条标准的判定结果和一行证据（文件路径）。（只需判定你负责的支柱的标准，不要计算整体评分——那是编排者的工作。）

Step 2 — cross-reference + score (you, the orchestrator)

步骤2 — 交叉比对 + 评分（你作为编排者）

Collect the 9 reports. Then synthesize — your judgment overrides any single subagent:
  1. Reconcile overlaps and contradictions. Examples: the Docs agent found an 
    AGENTS.md
    the Style agent didn't see; the CI agent counted a "test" the Testing agent judged meaningless. Resolve to one truth; don't double-count. Also sanity-check 
    skip
    s: a criterion one agent skipped may actually apply.
  2. Pass rate = passing / applicable (applicable = pass + fail; skips are excluded from the denominator). Compute it per pillar (e.g. "Testing 5/7 = 71%") and overall (e.g. "31/59 = 53%"). This is the headline metric, Factory-style.
  3. Level (1–5), gated. Criteria are level-tagged in the catalog. Regroup all applicable criteria by level tag and find the highest level where its criteria mostly pass (~75%+) and every lower level does too. Observed bands as a sanity check: Level 3 ≈ 53–59% overall, Level 4 ≈ 65–74%. The pass rate and the level are different lenses — report both.
Worked example (FastAPI, from Factory's public report). 31/59 applicable criteria pass = 53%. L1–L2 criteria nearly all pass, L3 clears its bar but L4 criteria (coverage automation, observability, security scanning) mostly fail → Level 3. Several criteria are 
skip
(no database → 
database_schema
, 
n_plus_one_detection
; library → 
dast_scanning
, 
health_checks
) and don't count against it. A repo can post a "low" pass rate yet still be Level 3 because the unmet criteria are advanced (L4–L5), not foundational.
收集9份报告，然后进行综合——你的判断优先级高于任何单个子Agent的结论：
  1. 协调重叠和矛盾之处。例如：文档Agent发现了
    AGENTS.md
    ，但风格Agent没有看到；CI Agent将某一项算作“测试”，但测试Agent认为它没有意义。要统一结论，不要重复计数。同时也要检查
    skip
    项是否合理：某个Agent跳过的标准可能实际上是适用的。
  2. 通过率 = 通过数 / 适用数（适用数 = 通过数 + 未通过数；跳过项不计入分母）。分别计算每个支柱的通过率（例如“测试 5/7 = 71%”）和整体通过率（例如“31/59 = 53%”）。这是Factory风格的核心指标。
  3. 等级（1-5），阶梯式。 目录中的每条标准都带有等级标签。将所有适用标准按等级标签重新分组，找到满足以下条件的最高等级：该等级的标准大多通过（约75%以上）且所有更低等级的标准都已通过。可参考以下区间作为合理性校验：3级 ≈ 整体通过率53-59%，4级 ≈ 65-74%。通过率和等级是两个不同的评估维度——需要同时报告。
示例（FastAPI，来自Factory公开报告） 59条适用标准中31条通过 → 53%。1-2级标准几乎全部通过，3级达标，但4级标准（覆盖率自动化、可观测性、安全扫描）大多未通过 → 3级。有几条标准被标记为
skip
（无数据库 → 
database_schema
、
n_plus_one_detection
；库项目 → 
dast_scanning
、
health_checks
），这些不扣分。一个仓库的通过率看起来“低”，但仍可能达到3级，因为未满足的是高级（4-5级）标准，而非基础标准。

Step 3 — report

步骤3 — 输出报告

The report is about what was investigated and what was found — a readiness assessment of the repo, not a story about your method. Don't frame it as "investigation vs. a script" or dwell on how the score was computed; just report the findings. Structure:
  1. Result + scorecard — the level reached, the overall pass rate (passing/applicable), and a per-pillar table (pass rate + one-line status).
  2. Per-area detail (the body) — one section per pillar. For each: its failure mode in one line, and a table of 
    criterion · verdict (✓/✗/—) · evidence (file path)
    — every criterion, with the 
    —
    skips marked "N/A: <why>" — plus a one-line finding. This is the detail a reader wants: which specific things were checked in each area and what came back.
  3. Level + what blocks the next — the failing criteria of the lowest incomplete level.
  4. What to fix first — those failing criteria, each with a specific, concrete fix ("add 
    playwright.config.ts
    + one smoke E2E", not "improve testing"). Order by leverage: gating + cheap wins first (a missing 
    LICENSE
    can hold a rich repo at Level 0).
Keep it honest: note where a verdict was inferred vs verified, and where subagents disagreed and how you resolved it — but inline, not as a meta-section.
报告的核心是调查了什么、发现了什么——是对仓库的就绪度评估，而非你的工作方法说明。不要把报告写成“调查 vs 脚本”的对比，也不要赘述评分计算过程；直接呈现调查结果即可。报告结构：
  1. 结果 + 计分卡 — 达到的等级、整体通过率（通过数/适用数），以及各支柱的表格（通过率 + 一行状态说明）。
  2. 各领域详情（正文） — 每个支柱对应一个章节。每个章节包含：一行失败模式说明，以及一个
    标准 · 判定结果（✓/✗/—） · 证据（文件路径）
    的表格——覆盖所有标准，
    —
    的跳过项需标注“N/A: <原因>”——再加上一行调查结论。这是读者想要的细节：每个领域具体检查了哪些项，结果如何。
  3. 当前等级 + 升级阻碍 — 最低未完成等级中的未通过标准。
  4. 优先修复项 — 上述未通过的标准，每条都要有具体、可落地的修复方案（例如“添加
    playwright.config.ts
    + 一个冒烟E2E测试”，而不是“改进测试”）。按影响力排序：阶梯阻碍项 + 低成本收益项优先（缺少
    LICENSE
    可能会让一个功能完善的仓库卡在0级）。
保持客观：标注哪些判定是推断的、哪些是验证过的，以及子Agent存在分歧的地方和你的解决方式——但要放在对应内容里，不要单独开一个元信息章节。

Step 4 — persist the report (dated)

步骤4 — 保存报告（标注日期）

Readiness is a trend, not a one-off — Factory's whole point is the compounding loop (better env → more productive agents → time to improve env). So save the report with the date so progress is trackable:
  • Prefer the team's knowledge base if one is configured (a gbrain / wiki / notes MCP) — write a dated page (e.g. slug 
    …/readiness/<repo>-<YYYY-MM-DD>
    ).
  • Otherwise (or additionally) write a versioned file in the repo: 
    docs/agent-readiness/<YYYY-MM-DD>.md
    .
Save the full report from Step 3 — the per-area detail (what was evaluated + what was found, with evidence), the scorecard, the level + blocker, and the fix-first list. On re-runs, link back to the previous dated report so the trend is visible.
就绪度是一个趋势，而非一次性结果——Factory的核心理念是复利循环（更好的环境 → 更高产的Agent → 更多时间改进环境）。因此请保存报告并标注日期，以便追踪进展：
  • 如果团队配置了知识库（gbrain / wiki / 笔记MCP），优先存在那里——创建一个带日期的页面（例如路径
    …/readiness/<repo>-<YYYY-MM-DD>
    ）。
  • 否则（或同时）在仓库中保存一个带版本的文件：
    docs/agent-readiness/<YYYY-MM-DD>.md
    。
保存步骤3的完整报告——包括各领域详情（评估了什么 + 发现了什么，附带证据）、计分卡、等级 + 阻碍项，以及优先修复清单。重新运行时，链接到上一次带日期的报告，以便直观看到趋势。

Subagent report schema

子Agent报告格式

Ask each pillar subagent to return exactly this (use the Task tool's structured-output / schema option if available):
yaml
pillar: <name>
criteria:
  - id: <criterion snake_case, e.g. "pre_commit_hooks">
    verdict: pass | fail | skip
    evidence: <one line: file path + why; for skip, "N/A: <reason>">
  # ... one per criterion in this pillar's table
quality_note: <1-2 sentences: genuinely solid, or present-but-hollow? the real failure mode here?>
top_fixes:
  - <concrete, specific fix>
要求每个支柱的子Agent严格按照以下格式返回（如果任务工具支持结构化输出/格式定义，请使用该功能）：
yaml
pillar: <name>
criteria:
  - id: <criterion snake_case, e.g. "pre_commit_hooks">
    verdict: pass | fail | skip
    evidence: <one line: file path + why; for skip, "N/A: <reason>">
  # ... one per criterion in this pillar's table
quality_note: <1-2 sentences: genuinely solid, or present-but-hollow? the real failure mode here?>
top_fixes:
  - <concrete, specific fix>

Notes

注意事项

  • Scale to the repo. A tiny repo can group several pillars into fewer subagents; a monorepo may need each subagent to cover every app, or one subagent per app per pillar — decide and say so.
  • The script is a convenience, never the authority. The score is your synthesis of the investigations.
  • Stay honest: presence ≠ quality, and "Level N" is a claim you should be able to defend from the evidence.
  • 根据仓库规模调整。 小型仓库可以将多个支柱合并给少数子Agent；单体仓库可能需要每个子Agent覆盖所有应用，或者每个应用的每个支柱对应一个子Agent——自行决定并说明。
  • 脚本只是辅助工具，绝非权威依据。 评分是你对所有调查的综合判断。
  • 保持客观：存在 ≠ 质量，“N级”是你需要能用证据支撑的结论。

Credits

致谢

Framework © Factory.ai (Agent Readiness). The 9-pillar / ~80-criterion catalog is reverse-engineered from Factory's public Agent Readiness reports (e.g. 
factory.ai/agent-readiness/fastapi_fastapi
, 
cockroachdb_cockroach
, 
streamlit_streamlit
); the orchestration and the subagent investigation are original work. MIT.
框架版权归 Factory.ai 所有（Agent就绪度）。9大支柱/约80条标准的目录是根据Factory的公开Agent就绪度报告（例如
factory.ai/agent-readiness/fastapi_fastapi
、
cockroachdb_cockroach
、
streamlit_streamlit
）反向整理而来；任务编排和子Agent调查部分为原创工作。MIT协议。