Build for the reader that never sleeps.
- 01
Choose boring, popular technology
A model's competence with a framework tracks how much of it exists in public code. Next.js, Astro, Rails, Django, Hono and Expo are in that set; a six-month-old framework or an in-house one is not. The cost shows up as confident, wrong code that looks right. Novelty belongs in your product, not in your stack.
What it looks like in a repo
- Every dependency has a public docs site and more than one tutorial the agent could have read.
- No in-house framework, DSL or code generator that a new hire would need a week to learn.
- Major versions are current; agents know the latest documented API, not last year's.
- 02
Types at every boundary, schema first
Types are the cheapest reviewer an agent can have. When the database schema, request validation and client types all derive from one definition, a change in one place becomes a compile error everywhere else. Dynamic, untyped edges are where agents introduce the bugs tests do not catch.
What it looks like in a repo
- strict: true, or the language's equivalent, with no escape hatches in committed code.
- A single schema source (Drizzle, Prisma, Pydantic, sqlc) that the ORM, validators and API contract are generated from.
- Zod or an equivalent on every form, route param and external response.
- 03
Keep a feature in one folder
An agent pays in tokens, latency and accuracy for every file it has to open to understand a change. Layered architectures spread one feature across controllers, services, repositories and DTOs; vertical slices keep the handler, the query, the component and the test together. The smaller the working set, the better the change.
What it looks like in a repo
- features/<name>/ containing actions or handlers, components, schema and tests together.
- Fewer than three hops between a route file and the database query behind it.
- No generic "utils", "helpers" or "services" folders that everything imports from.
- 04
Small files, unique names, full words
Agents locate code by searching for names. A dozen files called index.ts, a variable called cfg, or a function called handle waste that search. Domain names such as OrderProcessor or invoiceDueDate are found on the first try and explain themselves. Explicit code that a junior could follow is exactly the code an agent edits correctly.
What it looks like in a repo
- Files under roughly 300 lines; functions that fit on one screen.
- File names that are unique across the repository and say what is inside.
- No metaprogramming, implicit dependency injection or global magic that hides where something is defined.
- 05
Write the conventions down, next to the code
The instruction file is the part of the prompt that every session starts with. It should say how to run, test and lint the project, where things live, and which decisions are settled. Architecture Decision Records capture the why for anything custom. When the architecture changes and the file does not, the agent builds the old thing.
What it looks like in a repo
- AGENTS.md at the root with commands, folder map, conventions and the "never do" list.
- A docs/adr/ folder with one Markdown file per non-obvious decision.
- Updating the instruction file is part of the definition of done for structural changes.
- 06
Tests the agent runs before you do
Agents work best inside a loop: change, run, read the failure, fix. That loop needs tests that are fast, isolated enough to run per file, and honest enough to hit a real database or a real browser. Reproduce a bug with a test before fixing it and the fix stays fixed.
What it looks like in a repo
- One command runs the tests for a single file or folder in seconds.
- Integration tests against a real database (SQLite, testcontainers) rather than mocks of the ORM.
- A smoke test for each flow that makes money, runnable locally.
- 07
Explicit over clever
Idioms that save a few lines cost the model context and confidence. Decorators that rewrite behaviour, implicit conventions that wire things by name, and configuration spread across environment and code all force the agent to infer instead of read. Write the boring version.
What it looks like in a repo
- Configuration in one typed file that validates environment variables at startup.
- Data flow visible in the code: no hidden middleware chains or event buses for simple calls.
- Comments that explain why, and none that restate what.
- 08
Fewer moving parts
Every extra service, tool or runtime is state the agent cannot see and a failure it cannot reproduce. A monorepo with one package manager and one dev command keeps the whole system reachable from one shell. Managed Postgres, managed auth and a queue with a dashboard beat their self-hosted equivalents until scale forces the issue.
What it looks like in a repo
- A lockfile, a pinned runtime version and a single dev command that starts everything.
- One package manager and one test runner across the repository.
- Seed data and a reset script so the agent can get to a known state in seconds.
- 09
Encode repeated workflows as skills
Instruction files hold the always-on context; skills hold the procedures that only matter sometimes: a design system, a refactor checklist, a content job. Installing them into the repository makes the agent's behaviour reproducible across sessions and people, which is the difference between a demo and a workflow.
What it looks like in a repo
- A .claude/skills/ or equivalent folder with one SKILL.md per repeatable procedure.
- Per-stack rules (an AGENTS.md for the framework) installed from a shared source, not hand-copied.
- Skills reviewed in pull requests like any other code.