Skip to content
STACK IT FIRST
Install the skills
Method skill · 03 After you ship

Agent-fit review

Scores an existing codebase against Stack It First's nine principles for agent-built software (boring tech, types at boundaries, locality, small explicit files, written conventions, tests as spec, explicit over clever, fewer moving parts, encoded workflows) and lists the highest-leverage fixes.
v0.5.0 Updated

A read-only review that answers one question: how much does this codebase help or hurt an agent working in it? It scores nine principles with evidence from the repository and ends with a short, ordered fix list.

When to use

  • Before rolling out coding agents on an existing codebase.
  • When agents keep making the same kinds of mistakes in one repo.
  • Periodically, to see whether the codebase is drifting.

Steps

  1. Map the repo. Read the README, AGENTS.md or CLAUDE.md, the package manifests, CI workflows and the top two levels of folders. Note the stack and its versions.

  2. Score each principle from 0 to 2 with evidence (file paths, commands, counts). 0 = works against agents, 1 = partly, 2 = helps.

    #PrincipleLook for
    1Boring, popular technologyIn-house frameworks or DSLs, unmaintained or very new dependencies, outdated major versions
    2Types at every boundaryStrict mode, validated inputs at HTTP/form/env/DB boundaries, any or untyped JSON
    3LocalityFeature folders vs. layer folders; how many folders one feature touches
    4Small, explicit filesFiles over ~400 lines, barrel re-exports, magic auto-registration
    5Written conventionsAGENTS.md exists, is accurate, lists real commands
    6Tests as the specOne verify command, test coverage of core flows, tests that run locally without secrets
    7Explicit over cleverMetaprogramming, decorators that hide control flow, deep inheritance
    8Fewer moving partsServices, queues and infrastructure the product’s tier does not need
    9Encoded workflowsScripts, generators or skills for repeated tasks vs. tribal knowledge

  3. Run what you can (install, verify command, tests) and record whether it worked from a clean checkout. A repo that does not run scores 0 on 5 and 6 regardless of what its docs say.

  4. Rank fixes by leverage: what removes the most agent mistakes for the least work. Usually: a verify command, an accurate AGENTS.md, typed env, then layout.

  5. Report. Do not change code in this skill; hand fixes to agent-ready-repo, vertical-slice-feature or tests-as-spec.

Output

# Agent-fit review: <repo>

Score: 12/18

| Principle   | Score | Evidence                                              |
| ----------- | ----- | ----------------------------------------------------- |
| Boring tech | 2     | Next.js 16, Postgres, Drizzle; no in-house frameworks |
| ...         |       |                                                       |

## Top fixes

1. Add `npm run verify` (lint + typecheck + test) and run it in CI. (agent-ready-repo)
2. ...

Keep the report to one screen: nine rows and at most five fixes.