<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Haolin Dai on Medium]]></title>
        <description><![CDATA[Stories by Haolin Dai on Medium]]></description>
        <link>https://medium.com/@haolindai?source=rss-2e9b8421fdf2------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/2*ZauYftDCuiKZ4D0tgOCxmw.jpeg</url>
            <title>Stories by Haolin Dai on Medium</title>
            <link>https://medium.com/@haolindai?source=rss-2e9b8421fdf2------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 23:45:58 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@haolindai/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[I scanned 1000 popular AI / agent repos. Here is the structural picture.]]></title>
            <link>https://medium.com/@haolindai/i-scanned-1000-popular-ai-agent-repos-here-is-the-structural-picture-03b04c1b32da?source=rss-2e9b8421fdf2------2</link>
            <guid isPermaLink="false">https://medium.com/p/03b04c1b32da</guid>
            <category><![CDATA[agentops]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[devex]]></category>
            <category><![CDATA[llm]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Haolin Dai]]></dc:creator>
            <pubDate>Tue, 05 May 2026 23:20:19 GMT</pubDate>
            <atom:updated>2026-05-06T06:57:54.348Z</atom:updated>
            <content:encoded><![CDATA[<p>Visit <a href="https://github.com/harrydaihaolin/agent-readiness#agent-readiness">agent-readiness github page</a> to scan for own repo.<br>Visit <a href="https://harrydaihaolin.github.io/agent-readiness-leaderboard/">agent-readiness-leaderboard</a> for details.</p><h3>What “agent readiness” means</h3><p>When a coding agent opens a repo for the first time, agent-readiness cli scans four problems at once:</p><ul><li><strong>Cognitive load</strong> — can it figure out what this project <em>is</em> without reading every file? (AGENTS.md, README structure, token budget for orientation, entry-point discoverability.)</li><li><strong>Feedback</strong> — when it makes a change, does the project tell it whether the change works? (CI configured, tests runnable headlessly, lockfiles present.)</li><li><strong>Flow</strong> — can it iterate without stepping on its own toes? (Workflow concurrency guards, .gitignore hygiene, manifest detection.)</li><li><strong>Safety</strong> — will it accidentally commit a secret, or trip a brittle pre-commit hook? (Secrets-scan config, .env.example parity, large-file checks.)</li></ul><p>The scanner has 38 checks across these four pillars, scores each repo 0–100, and grades on an S/A/B/C/D scale. A passing repo is one an agent can orient itself in within its context budget and run end-to-end without a human in the loop.</p><h3>Headline finding</h3><p><strong>77.7% of 994 popular AI / agent repos (772 of them) are missing the canonical agent doc</strong> — no AGENTS.md at the project root, the path the ecosystem has converged on through 2025–2026.</p><p>That’s <strong>77.7% of repos that <em>self-identify</em> as </strong><strong>topic:agent, </strong><strong>topic:llm, </strong><strong>topic:rag, etc.</strong> — the population where agent docs should be most expected. Two checks measure this gap:</p><ul><li>The strict-presence check — is AGENTS.md present at root? <strong>77.7%</strong> missing.</li><li>The permissive check — does <em>any</em> recognised agent doc exist (AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md, .cursor/rules/*.mdc)? <strong>10.2%</strong> missing.</li></ul><p>Two-thirds of the cohort miss the canonical path; one in ten miss <em>every</em> form of agent doc.</p><h3>Top-12 findings, by fire rate</h3><p>The checks the rules pack flagged most often across the 994-repo cohort:</p><ul><li><strong>large files</strong> — 88.1%</li><li><strong>churn hotspots</strong> — 80.8%</li><li><strong>canonical agent doc missing</strong> — <strong>77.7%</strong></li><li><strong>secrets-scan config missing</strong> — 63.4%</li><li><strong>.gitignore covers junk missing</strong> — 60.0%</li><li><strong>README run instructions missing</strong> — 48.8%</li><li><strong>CI configured missing</strong> — 35.2%</li><li><strong>entry-point detected missing</strong> — 28.8%</li><li><strong>lockfile present missing</strong> — 22.3%</li><li><strong>token budget exceeded</strong> — 17.8%</li><li><strong>workflow concurrency-guard missing</strong> — 16.3%</li><li><strong>headless end-to-end runnability missing</strong> — 16.2%</li></ul><p>Three of these are worth dwelling on:</p><ul><li><strong>Secrets-scan config (63.4%).</strong> Not “they leaked secrets” — they have nothing in place to <em>catch it</em> if they do.</li><li><strong>Workflow concurrency-guard (16.3%).</strong> One in six push-on-push workflows can race themselves on rapid pushes.</li><li><strong>Headless end-to-end runnability (16.2%).</strong> One in six repos has no path for an agent to run the project end-to-end without manual setup prompts.</li></ul><h3>Stratified findings</h3><p>With N=1000 we can slice the headline three ways.</p><h3>By star band</h3><p>Each entry: <strong>band — n / median score / % missing canonical agent docs</strong>.</p><ul><li><strong>stars:200..1000</strong> — n=667, median 75.0, <strong>82.3%</strong> missing</li><li><strong>stars:1001..5000</strong> — n=186, median 75.0, 74.2% missing</li><li><strong>stars:5001..20000</strong> — n=86, median 75.0, 67.4% missing</li><li><strong>stars:20001..200000</strong> — n=55, median 75.0, <strong>49.1%</strong> missing</li></ul><p>The gap closes with stars but never goes away. <strong>Even at 20k+ stars — effectively the most-watched repos in the AI ecosystem — 49% have no </strong><strong>AGENTS.md.</strong> Stars predict structural readiness in absolute terms, but in <em>agent-doc adoption</em> specifically there is a 33-point spread between the smallest and largest star bands.</p><h3>By language (top 10 by count)</h3><p>Each entry: <strong>language — n / median score / % missing canonical agent docs</strong>.</p><ul><li><strong>Jupyter Notebook</strong> — n=49, median 75.0, <strong>95.9%</strong> missing</li><li><strong>Shell</strong> — n=17, median 75.0, 88.2% missing</li><li><strong>Python</strong> — n=457, median 75.0, 83.4% missing</li><li><strong>HTML</strong> — n=12, median 75.0, 83.3% missing</li><li><strong>C++</strong> — n=14, median 75.0, 71.4% missing</li><li><strong>JavaScript</strong> — n=36, median 75.0, 69.4% missing</li><li><strong>Java</strong> — n=15, median 75.0, 66.7% missing</li><li><strong>TypeScript</strong> — n=190, median 75.0, <strong>63.2%</strong> missing</li><li><strong>Go</strong> — n=51, median 75.0, 60.8% missing</li><li><strong>Rust</strong> — n=44, median 75.0, <strong>56.8%</strong> missing</li></ul><p>Two surprises. <strong>TypeScript, Go, and Rust agent projects are materially better at agent docs than Python ones</strong> (~57–63% vs ~83%), even though the popular-AI cohort is dominated by Python. And <strong>notebook-first projects (Jupyter) are by far the worst</strong> at 95.9%, consistent with the pattern that notebooks are written for humans-in-a-tab and never for headless tools.</p><p>A pillar-by-language breakdown shows that <em>cognitive load</em> is the weakest pillar across every language (median 87.0–89.3) while <em>feedback / flow / safety</em> hold above 95.0. The cohort is structurally <strong>orientation-poor</strong>, not pipeline-poor.</p><h3>By topic</h3><p>Grouped by the seed topic that surfaced the repo. The average cohort repo carries ~1.3 seed topics (a project tagged both topic:llm and topic:agent shows up in both rows), so counts sum above 994 — they are <em>appearances</em>, not unique repos. The (no seed topic) row collects 205 repos that entered via curated anchors and carry none of the nine seed topics.</p><p>Each entry: <strong>seed topic — n / median score / % missing canonical agent docs</strong>.</p><ul><li><strong>llm</strong> — n=208, median 75.0, 84.6% missing</li><li><strong>agent</strong> — n=203, median 75.0, 73.9% missing</li><li><strong>ai-agents</strong> — n=185, median 75.0, <strong>63.8%</strong> missing</li><li><strong>agents</strong> — n=178, median 75.0, 66.9% missing</li><li><strong>mcp</strong> — n=104, median 75.0, 77.9% missing</li><li><strong>langchain</strong> — n=72, median 75.0, 84.7% missing</li><li><strong>llms</strong> — n=72, median 75.0, 91.7% missing</li><li><strong>rag</strong> — n=51, median 75.0, 92.2% missing</li><li><strong>llmops</strong> — n=14, median 75.0, <strong>92.9%</strong> missing</li><li><strong>(no seed topic)</strong> — n=205, median 75.0, 82.9% missing</li></ul><p>topic:agents, topic:agent, and topic:ai-agents repos <em>over-index</em> on agent-readiness because they self-identify as agent-oriented (canonical-doc miss-rate 64–74%, vs the cohort average of 77.7%). topic:llm, topic:rag, and topic:llmops catch infrastructure where agent-readiness is more accidental: they cluster at 85–93%. The 30-point spread between the agent-self-aware end and the LLM-infra end is the strongest &quot;topic predicts behaviour&quot; signal in the cohort.</p><h3>Score distribution</h3><p>Of 994 cleanly-scanned repos:</p><ul><li><strong>S (≥95)</strong> — 100 repos, 10.1%</li><li><strong>A (80–94)</strong> — 824 repos, 82.9%</li><li><strong>B (60–79)</strong> — 0 repos, 0.0%</li><li><strong>C (40–59)</strong> — 0 repos, 0.0%</li><li><strong>D (&lt;40)</strong> — 70 repos, 7.0%</li></ul><p>Median score: <strong>75.0</strong>. Mean: 73.8. The distribution is bimodal: a wide A-grade plateau and a sharp D-grade pocket of “unrunnable” repos that miss multiple high-weight checks at once. The 7% D-grade pocket is the rules pack’s signal that <strong>one in fourteen popular AI repos is structurally non-orientable</strong> for an agent without manual handholding — three or more of the 37 checks fire simultaneously.</p><p>The composite <strong>headless end-to-end runnability</strong> rule fires on 162 repos (16.3%) and is one of the strongest predictors of D-grade membership.</p><h3>Three takeaways from the cohort</h3><ol><li><strong>Top exemplars cluster in Python infrastructure.</strong> apache/airflow (97.3, S), langchain-ai/langchain (97.2, S), bentoml/OpenLLM (96.7, S), ajndkr/lanarky (96.7, S), namuan/dr-doc-search (96.5, S). All five are Python and all five ship under-100-token AGENTS.md surrogates (READMEs with explicit install / run / test fenced blocks); the agent-doc check passes via the permissive permission, not the canonical path.</li><li><strong>D-grade anti-patterns are language-diverse.</strong> hkuds/autoagent (Python), argoproj/argo-workflows (Go), prefecthq/prefect (Python), yusufkaraaslan/Skill_Seekers (Python), decodingai-magazine/llm-twin-course (Python). The common thread is not language; it is <em>every</em> one of them missing AGENTS.md, having ≥ 3 multi-finding checks fire, and having token budget over the 50k-token threshold.</li><li><strong>The cohort’s cognitive-load floor is consistent across languages.</strong> Python / TypeScript / Go / Jupyter / Rust / JavaScript all sit in the 87.0–89.3 median band. Cognitive load is where the ecosystem under-invests, regardless of language. The maintainer playbook below targets that pillar first.</li></ol><h3>Honest noise</h3><p>Three caveats about the rules pack worth flagging up-front:</p><ul><li><strong>Large files (88.1% fire rate).</strong> At 88% fire rate the check has stopped discriminating. Recalibration is on the open backlog.</li><li><strong>README run instructions (48.8% fire rate).</strong> The check requires explicit install / run / test headings with fenced commands, not just the words appearing in prose.</li><li><strong>Secret-shaped strings (7.0% fire rate).</strong> A basic secrets scan. We report the rate but <strong>do not</strong> claim it as production leakage — the rule is pattern-based and finds fixture data, examples, and test harnesses. Two of the four case studies below are scarred by this.</li></ul><h3>Case studies</h3><p>Four picks from the cohort: two top exemplars and two D-grade anti-patterns. Selection criteria: maintainers have publicly discussed agent docs / structural readiness so the writeup is fair use of public discourse.</p><h3>Exemplar A — apache/airflow (97.3, S, Python)</h3><ul><li>Pillars: cognitive load 93.4 / feedback 100.0 / flow 97.7 / safety 100.0.</li><li>Three findings, none structurally damning: large files (479 instances; this is a 14-year-old monorepo), token budget (~42k tokens — over budget but not catastrophic), and missing workflow concurrency-guard.</li><li>Public posture: Airflow’s release process and contributor guide are extensively documented; the repo lacks a canonical AGENTS.md but its [UPDATING.md](https://github.com/apache/airflow/blob/main/UPDATING.md) and PR-template scaffolding satisfy the permissive agent-doc check.</li><li>Take-away: a multi-thousand-file monorepo can still hit the 95+ band on <strong>flow</strong> and <strong>feedback</strong> if its CI is comprehensive and its release process is documented. Its cognitive-load floor of 93.4 is the highest in the cohort for a repo of its size.</li></ul><h3>Exemplar B — langchain-ai/langchain (97.2, S, Python)</h3><ul><li>Pillars: cognitive load 94.6 / feedback 97.4 / flow 99.7 / safety 98.7.</li><li>Two findings: large files (94 instances, all in .github/ tooling) and a manifest-detection miss (the <em>root</em> has no manifest — they live one directory deeper).</li><li>Public posture: LangChain has been <a href="https://github.com/langchain-ai/langchain/issues">public about agent-doc adoption</a> and ships [docs/docs/](https://github.com/langchain-ai/langchain/tree/master/docs/docs) scaffolding. The permissive agent-doc check passes via the docs/ doc tree; the canonical check fails because there is no root-level AGENTS.md yet.</li><li>Take-away: even the project that helped popularise the agent-doc conversation hasn’t shipped the canonical file. Five-minute fix.</li></ul><h3>Anti-pattern A — argoproj/argo-workflows (30.0, D, Go)</h3><ul><li>Pillars: cognitive load 89.2 / feedback 100.0 / flow 98.7 / safety 69.6.</li><li>Seven multi-instance findings, including a basic secrets scan on PEM private keys (likely fixtures, but raises Gemfile-style alarm), large files on a 470 KB CHANGELOG, and the canonical agent-doc miss.</li><li>Public posture: argo-workflows is a CNCF-graduated project with exceptional CI (the 100.0 feedback score is real), but <strong>safety</strong> drops to 69.6 because two PEM-shaped strings sit in the test fixture tree without a .gitleaks.toml allow-list to dismiss them.</li><li>Take-away: a CNCF-graduate, top-50-stars-in-its-niche project can still grade D because <strong>safety + cognitive load combined miss the threshold</strong>, even when its operational CI is among the best in the cohort.</li></ul><h3>Anti-pattern B — prefecthq/prefect (30.0, D, Python)</h3><ul><li>Pillars: cognitive load 90.7 / feedback 99.5 / flow 94.3 / safety 78.3.</li><li>Seven findings, including a basic secrets scan on three Slack tokens (test fixtures, almost certainly), large files (230 instances; the docs site bundles a 123 KB JSON catalog), token budget over <strong>197k tokens</strong> (3.5× the threshold; far past any practical agent context window), and an .env.example parity miss.</li><li>Public posture: Prefect’s <a href="https://github.com/PrefectHQ/prefect/discussions">agent-readiness discussion thread</a> has been a friendly back-and-forth on agent-doc tooling.</li><li>Take-away: token budget is the killer. Repos over the 50k-token orientation budget force agents into chunked indexing that defeats the purpose of an agent doc. Splitting docs/docs.json out of the repo (or shipping docs/agents.md as an index) would push Prefect into the A band immediately.</li></ul><h3>Maintainer playbook</h3><p>Concrete priority-ordered fix list, each backed by an exact rule the pack fires for the listed problem on this cohort. Order is by inverse cost (cheap fixes first):</p><ol><li><strong>Ship </strong><strong>AGENTS.md</strong> at the project root — fires on 77.7% of cohort. Five-minute task: copy the <a href="https://github.com/harrydaihaolin/agent-readiness-rules/blob/main/templates/AGENTS.md">recommended template</a> and fill the four sections.</li><li><strong>Add a </strong><strong>.gitleaks.toml allow-list</strong> — fires on 63.4%. Even a one-line [allowlist] paths = [&quot;tests/**&quot;] satisfies the check and lets real secret regressions actually surface.</li><li><strong>Fill out </strong><strong>.gitignore</strong> — fires on 60.0%. The check looks for 12 standard groups (__pycache__/, dist/, build/, node_modules/, etc.); cover ≥ 11 to pass.</li><li><strong>Add </strong><strong>install / </strong><strong>run / </strong><strong>test headings to README</strong> — fires on 48.8%. The check is header-and-fence based; explicit fenced commands matter more than prose.</li><li><strong>Add a CI test step that doesn’t no-op</strong> — fires on 35.2%. A make test invocation in any .github/workflows/*.yml satisfies it.</li><li><strong>Detect an entry point</strong> — fires on 28.8%. main.py, index.js, cmd/, bin/, __main__.py are all recognised; this is a directory-layout fix, not a document fix.</li><li><strong>Add a top-level </strong><strong>concurrency: block to push-on-push workflows</strong> — fires on 16.3%. Three lines: concurrency: { group: ${{ github.workflow }}-${{ github.ref }}, cancel-in-progress: true }.</li><li><strong>Add a </strong><strong>headless smoke step</strong> — fires on 16.2%. One Makefile target that runs the project end-to-end without manual prompts.</li></ol><p>Every percentage above is from the released dataset.</p><h3>Try it on your own repo</h3><ul><li><strong>Scan it yourself:</strong> pip install agent-readiness then agent-readiness scan path/to/repo. The output is a JSON score card with per-pillar breakdowns and per-rule fire reasons.</li><li><strong>Disagree with a rule?</strong> Open an issue on [agent-readiness-rules](https://github.com/harrydaihaolin/agent-readiness-rules) with a reproducer.</li><li><strong>Want your repo on the leaderboard?</strong> Open a PR adding it to ([scripts/scan.py](https://github.com/harrydaihaolin/agent-readiness-leaderboard/blob/main/scripts/scan.py)).</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=03b04c1b32da" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Introducing Agent Readiness: scoring repos for the agent era]]></title>
            <link>https://medium.com/@haolindai/introducing-agent-readiness-scoring-repos-for-the-agent-era-11cbfa2dbb7c?source=rss-2e9b8421fdf2------2</link>
            <guid isPermaLink="false">https://medium.com/p/11cbfa2dbb7c</guid>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[devex]]></category>
            <category><![CDATA[agentic-workflow]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[agentops]]></category>
            <dc:creator><![CDATA[Haolin Dai]]></dc:creator>
            <pubDate>Mon, 04 May 2026 16:23:25 GMT</pubDate>
            <atom:updated>2026-05-04T16:25:04.005Z</atom:updated>
            <content:encoded><![CDATA[<h3>You bought the seats. Your team is on Claude Code, Cursor, Copilot, and Cline. The agents look astonishing in the demo videos and then quietly fail on <em>your</em> codebase.</h3><p>The model is the variable you can’t change. The repository is the one you can.</p><p>agent-readiness is a small, MIT-licensed CLI that puts a number on how ready a codebase is for autonomous coding agents — across cognitive load, feedback loops, flow, and safety — and hands you a prioritised punchlist of fixes. Like Lighthouse, but for agentic accessibility.</p><p>This post is about why we built it, what we’re measuring, and the research that says the same things that hurt human developers hurt agents twice as hard.</p><h3>What the research actually says</h3><p>There is a well-trodden body of work on what makes humans productive in software. The current standard is the <strong>DevEx framework</strong> — Forsgren, Storey, Maddila, Smith, and Houck (2024), <em>DevEx: What Actually Drives Productivity</em>, ACM Queue / Communications of the ACM. The paper distils developer experience into three dimensions:</p><ol><li><strong>Feedback loops</strong> — how fast and clear the signal is after a change. Slow CI, flaky tests, and silent failures aren’t annoyances; they’re the variable that explains the gap between “we shipped” and “we’re stuck.”</li><li><strong>Cognitive load</strong> — how much a developer has to hold in their head to make a correct change. Cluttered repo roots, missing docs, ambiguous naming, gigantic files. The framework explicitly calls this out as the dimension teams underestimate the most.</li><li><strong>Flow state</strong> — the ability to make progress without unplanned interruptions. Onboarding friction, mid-task tool failures, broken local dev environments — the accumulated tax that turns a forty-five-minute change into a four-hour one.</li></ol><p>The paper’s central claim is that these three dimensions are the <em>measurable</em> substrate underneath every higher-level productivity discussion (DORA, SPACE, your favourite OKR). It’s not abstract. The authors give concrete examples — a slow build that lengthens cycle time, an unclear codebase that lengthens the time to first commit — and show that small improvements in any one dimension compound.</p><blockquote><em>“Optimising for developer experience requires understanding the friction developers experience in their day-to-day work and systematically removing it.” — Forsgren et al., DevEx</em></blockquote><p>Now read that quote again, with one substitution: replace <em>developers</em> with <em>agents</em>.</p><h3>Agents are headless developers</h3><p>Your AI coding agent is a developer with a small set of unusual constraints:</p><ul><li><strong>It is headless.</strong> No browser, no dashboard, no clickable buttons. If important state is reachable only through a UI, it’s invisible to the agent.</li><li><strong>It cannot ask a senior engineer for help.</strong> When stuck, a junior on your team pings someone in Slack. The agent guesses, hallucinates, or thrashes.</li><li><strong>Its working memory is a context window.</strong> Cognitive load isn’t a metaphor for the agent — it’s a hard constraint. Past a certain point, the agent literally cannot see the whole picture at once.</li><li><strong>It treats every signal as gospel.</strong> Slow tests don’t just frustrate; they actively confuse the agent into believing nothing happened.</li></ul><p>In other words, an agent experiences DevEx friction the same way a developer does, but with the worst possible coping strategy: it keeps going. Where a human notices the friction and works around it, the agent commits half-broken changes, opens malformed pull requests, or quietly gives up after burning a hundred dollars of inference.</p><p>The DevEx paper’s three dimensions map almost one-to-one onto what makes a repo agent-friendly:</p><p><strong>Feedback loops: </strong>Are tests discoverable and fast?</p><p>Is make test enough, or does the agent have to read three READMEs to find out?</p><p><strong>Cognitive load: </strong>Are files and modules sized for the context window?</p><p>Is there an AGENTS.md / CLAUDE.md / .cursorrules so the agent doesn&#39;t have to reverse-engineer house style?</p><p><strong>Flow state: </strong>Can the agent run the project headlessly, end-to-end, without a manual setup step that requires a human to click something?</p><p>We added a fourth dimension because agents have one failure mode humans don’t: confidently committing AWS credentials.</p><p><strong>Safety: </strong>Are secrets gitignored? Are destructive scripts (rm -rf, force-push hooks) gated? Is the agent kept inside a sandbox?</p><p>That’s the rubric. Four pillars. One score.</p><h3>What agent-readiness actually does</h3><p>The CLI is a static analyser plus an optional sandboxed runtime check. Run it on a repo and you get this:</p><pre>$ agent-readiness scan .</pre><pre>AI Readiness  62 / 100</pre><pre>  Cognitive load     70 / 100<br>  Feedback loops     40 / 100   ← biggest drag<br>  Flow &amp; reliability 75 / 100<br>  Safety             OK</pre><pre>Top friction (fix these first):<br>  1. test_command.discoverable — no test invocation found in Makefile,<br>     package.json, or pyproject.toml<br>  2. agent_docs.present — no AGENTS.md / CLAUDE.md / .cursorrules at root<br>  3. headless.no_setup_prompts — README mentions &quot;log in to the dashboard&quot;<br>     during setup; agents can&#39;t traverse this</pre><p>A few design choices, all consequences of the DevEx framing:</p><p><strong>Agents are headless. So is the tool.</strong> No interactive prompts, no required dashboards, stable JSON via --json, exit codes that mean things, machine-readable findings via SARIF. If the tool itself violated headlessness, it&#39;d be hypocritical.</p><p><strong>Code quality counts only where it predicts agent success.</strong> Mega-files, ambiguous names, dead code, missing types — those have direct lines to agent failure modes and get measured. We don’t reproduce the full SonarQube taxonomy. Other tools do that well.</p><p><strong>Untrusted code runs in Docker, always.</strong> Any check that executes scripts from the target repo runs inside a sandboxed container. Safety is a cap on the score, not a soft warning.</p><p><strong>Each finding has a one-line action and a verify command.</strong> Not “this is bad” but “here is the file, here is the change to make, here is the shell command that returns 0 when you’ve made it.” The same checks that score the repo also tell an agent (or a human) the exact next move that raises the score.</p><h3>What you do with the score</h3><pre>pip install agent-readiness<br>agent-readiness scan .</pre><pre># Or in CI, gate merges below a threshold:<br>agent-readiness scan . --fail-below 70</pre><pre># Or generate an HTML report for the team:<br>agent-readiness scan . --report report.html</pre><pre># Or output SARIF for GitHub code scanning:<br>agent-readiness scan . --sarif findings.sarif</pre><p>The score is not the point. The <em>delta</em> is. Add an AGENTS.md, watch cognitive load go up. Add a discoverable test command, watch feedback loops go up. The DevEx paper&#39;s whole argument is that these are the right dimensions to measure precisely because they&#39;re the ones you can move.</p><p>The companion <a href="https://harrydaihaolin.github.io/agent-readiness-leaderboard/">public leaderboard</a> runs this scan daily against ~140 of the most-watched AI/agent infrastructure repos in the world. We’ll write up what we found there in the next post — the short version is that it’s worse than you’d guess.</p><h3>Closing</h3><p>Forsgren and her co-authors weren’t writing about coding agents. They were writing about humans, in 2024, before agentic coding was a serious production workload. The framework holds up anyway, and we think that’s the most interesting thing about this whole project: the friction that hurts you is the same friction that hurts your tools, and a tool that measures it well measures both.</p><p>If your team has agents in production and they’re failing on your repo, the codebase is the variable you can change.</p><pre>pip install agent-readiness<br>agent-readiness scan .</pre><p>We’ll wait.</p><p><strong>Citations</strong></p><ul><li>Forsgren, N., Storey, M.-A., Maddila, C., Smith, T., Zimmermann, T., &amp; Houck, B. (2024). <em>DevEx: What Actually Drives Productivity.</em> Communications of the ACM / ACM Queue. <a href="https://queue.acm.org/detail.cfm?id=3595878">https://queue.acm.org/detail.cfm?id=3595878</a></li><li>agent-readiness source: <a href="https://github.com/harrydaihaolin/agent-readiness">https://github.com/harrydaihaolin/agent-readiness</a></li><li>Public leaderboard: <a href="https://harrydaihaolin.github.io/agent-readiness-leaderboard/">https://harrydaihaolin.github.io/agent-readiness-leaderboard/</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=11cbfa2dbb7c" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>