Bootstrapping Your Application for AI Development

The first time I handed a feature to an AI agent without any upfront context, it built exactly what I described and nothing like what I wanted. The code was technically correct. It passed the tests I hadn't written yet. But it ignored conventions I thought were obvious, made architectural choices I'd never make, and I spent more time fixing it than if I'd just written it myself.

The problem wasn't the AI. The problem was me, I hadn't done the work of telling it what kind of project we were building. And the fix isn't to throw everything at it. Tokens are expensive, and more context doesn't automatically mean better results. The discipline is knowing exactly what to include, and what to leave out.

Bootstrap First, Maintain Always

In the previous post, I outlined a three-phase lifecycle:

Bootstrap → Execute → Ship

This post is about that first phase, the one that makes everything else work.

Bootstrapping is an upfront investment. You do the heavy lifting at the start of a project, and revisit it only when something fundamental changes - a new pattern, a revised boundary, a technology swap. Done right, it gives every AI agent and every human collaborator a shared understanding of the project before a single line of feature code is written.

The goal is not to write a specification document that nobody reads. The goal is to create living context that agents can actually use.

Five Files, One Source of Truth

There's no shortage of frameworks that promise to solve this problem. Most of them are powerful, and most of them are overkill. They introduce new formats, new conventions, and a learning curve that gets in the way of shipping.

I use five files that developers already know exist in every project: four that any project needs, one for frontend projects:

• README.md — what this project is and how to use it
• ARCHITECTURE.md — how it's built and why
• CONTRIBUTING.md — how to work on it
• DESIGN.md — visual identity and design tokens (frontend projects only)
• AGENTS.md — how AI agents should work with all of the above

No new formats. No proprietary syntax. Just files that any developer, and any AI, already knows how to read.

The obvious question at this point: if AGENTS.md is what agents read, why not just write one comprehensive file and skip the rest? The short answer is that a single file isn't a system, it's a pile. Agents navigate context better when it's structured like a map, with familiar landmarks and clear purposes. README, ARCHITECTURE, and CONTRIBUTING are landmarks that developers have used for decades. Every agent trained on open source code knows what they mean and what to look for in them.

Collapse everything into AGENTS.md and you've created a god instruction file, the same anti-pattern as a god class in software. It starts at 50 lines and quietly grows to 500 as you patch in edge cases and override outdated instructions. Eventually you stop trusting it because you're not sure what's current and what's stale. Worse, those other files aren't just for agents, they're how human developers onboard too. The moment you hollow them out, you've split the project into two parallel truths: one for humans, one for agents. They will drift. They always do.

What Goes In Each File

README.md — Project Identity

README.md is the first thing anyone reads, human or agent. Its job is orientation: what this project is called, what it does, how to install it, and how to use it. Nothing more.

The temptation is to pack it with context: gotchas, decisions, history. Resist that. A bloated README gets skimmed and ignored. A lean README gets read. When an agent loads your project for the first time, it should be able to answer "what am I working on?" in thirty seconds. If it can't, the README isn't doing its job.

Keep it honest and current. A README that describes a project you used to have is worse than no README at all.

ARCHITECTURE.md — The Why Behind the Code

This is the most important file for AI development, and the one most projects don't have.

Code shows you what was built. ARCHITECTURE.md explains what shouldn't be built, and why. It has six sections, each answering a different question an agent will inevitably face:

Overview sets the stage — what the system does and how its major pieces relate. Not implementation detail. Think of it as a map before you zoom in.

Design Principles are the philosophical guardrails. These are the values that break ties when a decision could go either way. Write down the principles your team has actually agreed to follow, because an agent without them will invent its own.

Architecture Patterns describe the structural approach — how the codebase is organized at a high level. When an agent knows the pattern, it builds in a way that extends it. When it doesn't, it introduces something that conflicts with it.

Technology Stacks lists every technology, version, and library in use. Without it, an agent might pull in a second HTTP client because you didn't mention you already had one, or pick a library version that breaks your existing dependencies.

Project Structure explains where things live and why. Agents need this so new files land in the right place, not scattered wherever seemed reasonable in the moment.

Boundaries defines where one component or service ends and another begins. What's allowed to cross a boundary and what isn't. Agents that don't know your boundaries will reach across them and create coupling you'll spend months untangling.

CONTRIBUTING.md — How Work Gets Done

Agents don't just need to know what to build. They need to know how building works on this project.

Linting is the first thing to document. Agents should run it before submitting anything. If they don't know the command exists, they won't run it.

Branching Strategy is a decision you need to make and commit to. Whether you use Gitflow, trunk-based development, or something else entirely doesn't matter as much as being explicit about it. An agent that doesn't know your branching model will guess and it'll guess wrong often enough to cause friction.

Commit Messages is where consistency pays off in ways that aren't obvious until you're reading history six months later. Decide whether you follow Conventional Commits (feat:, fix:, chore:), a looser format, or something else. Write it down. Agents that know your commit convention produce history that's readable; agents that don't produce noise.

Testing documents the command to run the test suite, and — more importantly — the methodology. TDD and BDD both lead to a healthy test suite, but they produce a different rhythm of work. Whatever you choose, the RED → GREEN → REFACTOR cycle belongs here: write a failing test first, write the minimum code to make it pass, then clean it up. An agent that doesn't know this discipline writes tests as an afterthought, or skips them entirely.

This isn't bureaucracy. Consistent conventions are what make it possible for many agents — and many humans — to work on the same codebase without constantly stepping on each other.

DESIGN.md — Visual Identity for Frontend Projects (optional)

DESIGN.md is a plain-text design system document that both humans and agents can read. It captures colors, typography, spacing, and component patterns — the visual identity that needs to live somewhere agents can access.

Traditionally that identity lives in a Figma file, a brand PDF, or a designer's head. None of those are readable by an AI agent. DESIGN.md changes that.

Without it, every screen a design agent generates stands alone visually. With it, they look like they belong together because the agent is working from the same color palette, typography scale, and component rules every time.

Under the hood, DESIGN.md has two layers. The YAML front matter holds machine-readable design tokens exact hex values, font properties, spacing scales that give agents precise values to work with. The markdown body provides human-readable design rationale explaining why those values exist. Both matter: tokens give precision, prose gives intent. Here's a minimal example:

---
name: My App
colors:
  primary: "#2665fd"
  surface: "#0b1326"
  on-surface: "#dae2fd"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
rounded:
  md: 8px
---

## Colors
- **Primary** (#2665fd): CTAs and key interactive elements
- **Surface** (#0b1326): Page backgrounds

## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface-variant background

Like the other files, DESIGN.md is a living artifact. The agent can generate a first version from a prompt or an existing brand URL, you refine it, and it gets re-applied as the design evolves. It's not a one-time export; it's part of the same feedback loop as the rest of your bootstrap documents.

AGENTS.md — The Connective Tissue

The other four files have existed in well-run projects for years. AGENTS.md is the new one, and it's what makes the others work together as a system.

Think of it as an onboarding guide written specifically for agents. It doesn't replace the other files — it interprets them. A good AGENTS.md explicitly maps agents to the right file for the right information:

• Read README.md to understand what this project is and how to run it
• Read ARCHITECTURE.md before making any structural or technology decisions
• Read CONTRIBUTING.md before writing or committing any code
• Read DESIGN.md before generating any UI (frontend projects only)

That mapping matters. Without it, an agent has to guess which file answers which question — or worse, it skims all four and synthesises its own understanding, which may not match yours. With explicit pointers, it knows exactly where to look before it starts.

Beyond the mapping, AGENTS.md is also the place for anything that doesn't naturally fit in the other four: how to prioritise when things conflict, what to do in ambiguous situations, constraints and conventions specific to your workflow, and things that are obvious to you but invisible to an agent reading the codebase cold.

Without AGENTS.md, an agent reads the other files and figures out on its own how they relate. With it, the agent has a guide that says: here's how to use everything you just read. That difference shows up in the quality of the first thing it builds.

The Bootstrap Flow

The process is straightforward:

Bootstrap → Design → Plan → Code → Update

You bootstrap once. Then you design, working out the architecture and key decisions before any implementation starts. Then you plan the work in discrete, agent-friendly chunks. Then you code, with agents executing against the context you've set up. And when something meaningful changes — a new pattern, a revised boundary, a technology swap — agents update README.md and ARCHITECTURE.md to reflect it.

The update step is the one most people skip. Don't. Stale documentation is worse than no documentation, because it actively misleads. Keeping these files current is what makes the bootstrap investment pay off across the entire life of the project.

CI/CD Is Part of Bootstrap

The five files give agents context. CI/CD enforces it. Before any feature work starts, set up a pipeline with automated checks — linting, tests, whatever your project requires.

It doesn't need to be elaborate. Having automated checks in place before you start building means you catch regressions immediately, not after three features have compounded on top of a broken assumption. It also means that when an agent ships something, there's a gate it has to pass, not just your approval.

Fast, continuous delivery removes surprises from production. Set it up while the project is still simple.

Context Is the Constraint

Every problem I've had with AI-generated code traces back to missing context. Wrong patterns, inconsistent conventions, redundant abstractions, all of it happens when an agent is filling in blanks that I should have filled in first.

The bootstrap phase isn't glamorous. There's no feature to demo, no progress bar to watch. But it's the work that determines whether everything that comes after goes smoothly or slowly sideways.

Write the files. Set up the pipeline. Then hand the keyboard to your agents.