AI-Native Engineering 04: Make the Codebase Agent-Ready | Daniel Oduonye

This is part 5 of 9 in the AI-Native Engineering series. Start with the course index or continue to the next part below.

Audience. You should know one programming language, Git, a shell, HTTP, and how to run tests. The examples use plain files, JSON, HTTP, Git, and shell so the ideas transfer across agent SDKs.

Shared capstone. Every part extends the same shop-agent: a support agent that searches products, inspects orders, and prepares—but never executes—a refund recommendation. The companion repository lives alongside the site source.

Make the Codebase Agent-Ready

Capability. Make a new agent able to understand, change, test, and leave the repository clean without oral history.

OpenAI’s harness-engineering report describes the repository as the system of record: a short map, structured docs, executable plans, strict boundaries, and linters that enforce invariants. The key design target is agent legibility.

Repository contract.

AGENTS.md              # map, commands, safety, definition of done
docs/ARCHITECTURE.md   # domains, layers, allowed dependencies
docs/
  decisions/           # why, alternatives, date, owner
  exec-plans/          # goal, steps, progress, evidence
  runbooks/            # recovery procedures
skills/                # reusable procedures
scripts/               # deterministic checks
tests/evals/           # task cases and graders

flowchart LR
    T[Types and schemas] -->|validate| C[Config]
    C -->|selects| R[Repository]
    R -->|loads| S[Service]
    S -->|runs| U[Runtime]
    U -->|renders| V[UI or agent output]
    P[Explicit providers] -->|cross-cutting access| C
    U -->|violates invariant| L[Lint failure]
    L -->|explains repair| U

Text equivalent: A request moves through types, configuration, repository access, service logic, runtime, and output in that order. Cross-cutting access enters through an explicit provider interface; a reverse dependency is a failure.

Module contract. Starting state: the map in course/shop-agent/AGENTS.md and docs/ARCHITECTURE.md. Add one mechanically checked invariant; run the complete unittest command and python3 -B scripts/verify_repo.py; prove the next agent can resume from progress.md.

Invariants to encode. Parse at boundaries; keep dependency direction explicit; require structured logs; cap file size; require tests for new behavior; forbid secrets in diffs; make error messages tell the agent how to repair the violation.

Long-run handoff. Add init.sh, a progress log, small commits, and a clean-worktree rule. Each session leaves: what changed, evidence, known failures, and the next smallest task.

Before / after test. Ask a fresh agent to add the same feature to an undocumented branch and to the agent-ready branch. Compare time to first correct test, wrong files touched, and recovery after a failed test.

Break it. Delete the architecture map, violate a dependency edge, and leave half a feature in the progress log. The repository checks should catch the drift and the next agent should know how to recover.

Acceptance test. In the pinned companion repo, python3 -B run_labs.py, python3 -B -m unittest discover -s tests -v, and python3 -B scripts/verify_repo.py start from a clean checkout, validate the architecture and security behavior, and leave no generated files. Other stacks may use their equivalent command.

Continue the series

← Previous: Connect Capabilities Through MCP Portals · Next: Review Agent Work with Intent and Evidence →

Return to the course index.