Make Your Codebase Agent-Friendly

Tier: Core · Workflow area: Feature development

An afternoon of harness engineering (fast deterministic tests, linters and type-checkers as machine feedback, seed docs) raises the quality of every agent session afterwards — and, not coincidentally, every human's too.

When to use

• •
  Agent sessions in this repo keep going sideways: wrong conventions, "fixed" code that fails CI, agents unable to verify their own work.
• •
  Before adopting agent-heavy workflows (pb-03, pb-08) on a repo.
• •
  You own a service and want it cheap for anyone — human or agent — to change safely.

Skip heavy investment for repos in maintenance freeze that see one change a quarter.

Prerequisites

• •
  Maintainer-level access and buy-in to add dev tooling.
• •
  An honest baseline: time a fresh-clone-to-green-tests run today and write the number down.
• •
  A coding agent to test the improvements against.

The workflow

1. 1.

   Give the agent (and humans) one obvious command per feedback type. Agents discover Makefile/package.json scripts and use them. Target set:

   Copy

   test-fast:   ## unit tests only, no network, < 2 min
    pytest tests/unit -x -q --disable-socket
   lint:        ## style + static errors, auto-fixable
    ruff check . && ruff format --check .
   typecheck:
    mypy app/
   check: lint typecheck test-fast   ## the agent's inner loop
   

   The contract that matters: make check is fast (minutes, not tens of minutes), deterministic (same input, same result), and self-contained (no VPN, no shared staging DB, no secrets).

2. 2.

   Kill nondeterminism in the fast lane. Flaky tests do double damage with agents: they train it to "just rerun", and they mask real regressions it introduces. Quarantine flaky tests out of test-fast (marker + separate CI job), fake the clock, stub the network (pytest-socket, nock, msw), and seed randomness.

3. 3.

   Turn silent conventions into machine feedback. Every rule that lives only in reviewers' heads, an agent will violate. Promote the recurring ones into lint/type config — e.g., ban raw SQL outside the repository layer:

   Copy

   # ruff: flag naked datetime.now() (must use our clock service)
   [tool.ruff.lint.flake8-tidy-imports.banned-api]
   "datetime.datetime.now".msg = "Use app.lib.clock.now() (tz-aware, fakeable)"
   

   Rules the linter cannot express go in the instruction file instead (pb-04); the split is: enforce mechanically what you can, instruct what you cannot.

4. 4.

   Write the seed docs agents actually read. Three short files beat a wiki: CLAUDE.md/AGENTS.md (conventions + the make check contract + exemplar-file pointers), CONTRIBUTING.md (how to run one test, add a migration, where fixtures live), and an architecture sketch listing the load-bearing modules. Keep each under a screen or two.

5. 5.

   Close the loop with a probe task. Give your agent a standard small task ("add field X to endpoint Y with tests") before and after the changes. Watch: does it find make check unaided? Does lint feedback correct it mid-session? Iterate on whatever it still fumbles.

6. 6.

   Guard the fast lane in CI. Add a CI timer assertion or at least a dashboard for make check duration and flake rate — harnesses rot, and a 2-minute loop quietly becoming 9 minutes un-does the whole investment.

Tool variants

• Python stack: ruff (lint+format) + mypy + pytest with -x -q, pytest-socket, freezegun.
• TypeScript/Node: ESLint + tsc --noEmit + Vitest/Jest with msw for network fakes; scripts in package.json (npm run check).
• JVM/Go: the same shape — one fast verify command (Gradle task / go vet + go test -short), strict compiler settings doing the type-feedback job natively.

Verification

• •
  make check (or equivalent) runs green from a fresh clone, offline, in under ~2 minutes, three runs in a row with identical results.
• •
  Probe task (step 5): the agent self-corrected at least one mistake using lint/type/test feedback without you telling it.
• •
  Convention rules fire: introduce a deliberate violation (naked datetime.now()) and confirm the linter catches it.
• •
  New-human onboarding time drops too — ask the next joiner.

Pitfalls

• Making CI fast but local slow. Agents (and humans) live in the local loop; a fast CI with a broken local make check helps nobody mid-session.
• Quarantining flaky tests forever. Quarantine is a queue, not a graveyard — schedule the fixes or delete the tests.
• Doc essays. A 3,000-word ARCHITECTURE.md gets truncated out of context windows. Short files, pointer-heavy, exemplar-first.
• Linting everything at once. Turning on 200 new rules floods agents and humans with noise; add rules that encode your recurring review comments, a few at a time.

Restricted-environment variant

This playbook barely touches external AI — it is repo engineering, so it works fully inside client environments and is often the first thing worth doing on a restricted engagement (it pays off even with humans-only). If no hosted agent is sanctioned for the probe task, use a local model (Ollama + coder model) driven by a simple loop, or run the probe yourself pretending to be the agent: fresh clone, only documented commands, note every point where tribal knowledge was required. Each such point is a fix.

Success criteria

• •
  Fresh-clone-to-green time cut to a fraction of your step-0 baseline.
• •
  Agent sessions in this repo need visibly fewer corrections for conventions and verification.
• •
  make check green predicts CI green ≥95% of the time — the local loop is trustworthy.
• •
  Flake rate in the fast lane is ~0 and stays there for a month.