Building with AI: what belongs in the repo?

Building products recently, I’ve gradually noticed:

once you use coding agents, the documents in a repo are no longer just “records for later.”

I don’t mean engineering scaffolding in the traditional sense.

Engineering scaffolding answers: what framework the project uses, the directory structure, the database, auth, testing and deployment.

This post is more about another layer: once a project is iterating continuously and several agents are taking part in development, where should product facts, current requirements, technical structure and past decisions each live?

The former gets a project running fast; the latter keeps people and agents from getting more and more muddled as they go.

They directly affect how agents understand the product, how they change the code, and which way they guess when something is ambiguous.

With too few documents, the agent has to guess again every time.

With too many, the same question is scattered across several files, and the agent doesn’t know which to trust.

So the real question isn’t:

how many documents should a professional project have?

It’s:

which information needs to be kept long term? Which only holds for the current stage? Where is the source of truth for each kind of information?

1. Product definition: what we’re building

You can use:

PRODUCT.md PRODUCT_DEFINITION.md

It should answer relatively stable questions:

• who the product serves
• what problem it solves
• what the core flows are
• what the main product principles are
• what it explicitly doesn’t do right now

A product definition isn’t a requirements dump.

Don’t stuff each iteration’s page details, temporary solutions and current tasks into it. Otherwise the file keeps growing, and the truly stable product facts get buried.

When to create: when the product direction starts to take shape. When to update: when the target users, core value, main flows or product boundaries change.

2. Stage or feature specs: what specifically we’re doing this time

Can live in:

specs/ stage-05-fit-report.md application-pipeline.md

It covers the scope of execution for the current stage, for example:

• what problem this round solves
• which scenarios are included
• which scenarios aren’t
• how the pages and flows work
• what the acceptance criteria are
• which questions are still undecided

The product definition says:

what the product is now.

The spec says:

what specifically this round is going to implement.

Don’t pile current feature requirements into PRODUCT.md long term, and don’t let the agent understand the feature in progress only from chat history.

When to create: when a task is too big to explain in a few chat messages. When to update: when scope, flows or acceptance criteria change. When it’s done, freeze or archive it; no need to maintain it forever.

3. System documents: how the product is implemented

This kind usually includes:

ARCHITECTURE.md TECHNICAL_DESIGN.md DATA_MODEL.md DESIGN.md EVALS.md

You don’t necessarily need all of them.

ARCHITECTURE.md

Records the current system structure, how modules relate, the main data flows and external dependencies.

The focus is how the system runs now, not explaining code files one by one.

TECHNICAL_DESIGN.md

Better suited to larger features or technical changes:

• how it will be implemented
• which modules are involved
• how the data changes
• what the risks are
• how to migrate and verify

It’s usually tied to a stage; once implemented, ARCHITECTURE.md should reflect the final state.

DESIGN.md

Records the product experience, information structure, visual and component rules, and how much creative latitude agents have in design.

It shouldn’t just be a list of colors, fonts and corner radii.

EVALS.md

When AI output is a core capability of the product, you need to make clear:

• what counts as a good result
• which errors are unacceptable
• which examples to test with
• how to tell model problems, prompt problems and product logic problems apart

When to create: when the relevant system starts getting complex and the code alone can no longer explain the important constraints. When to update: when the real implementation changes, not just when a plan is under discussion.

4. Decision log: why we decided this way

You can use:

DECISIONS.md docs/adr/

It isn’t there to record “what things are now,” but:

• what problem we faced at the time
• which options were considered
• what was finally chosen
• why
• under what conditions it should be re-evaluated

This information matters because months later, both people and agents may look at a solution that seems “not perfect” without knowing what problem it solved at the time.

But not every small decision needs writing down.

Only record the ones that:

• will affect the system long term
• are costly to change
• are likely to be questioned again by people later
• involve clear trade-offs

When to create: the first time an important choice comes up whose reasoning truly needs keeping. How to update: mostly by appending. When a decision is overturned, add a new entry; don’t quietly rewrite history.

5. Agent instructions: how agents should work

You’ll usually see:

CLAUDE.md AGENTS.md

They should tell the agent:

• which files are the canonical sources
• what to read before starting a task
• what conventions the code and directories follow
• what checks must run after changes
• what mustn’t be changed without permission
• which recurring mistakes to avoid

They shouldn’t copy the product definition, the full architecture and every feature requirement again.

A better approach is routing:

Product definition → PRODUCT.md

Current feature → specs/

Architecture → ARCHITECTURE.md

Design rules → DESIGN.md

Decision history → docs/adr/

Agent working rules → AGENTS.md / CLAUDE.md

Agent instructions are responsible for telling the agent where to get the right context, not for swallowing all of it.

Is an iteration log necessary?

Not necessarily.

Code changes can already be tracked through commits, PRs and the changelog.

Only these things are worth recording separately:

• what judgments user feedback changed
• which experiments didn’t make it into the code
• why a certain approach failed
• what problems agents kept running into
• which findings might later be useful for a retrospective or portfolio

Otherwise, a hand-maintained iteration log easily becomes yet another duplicate record.

A practical rule of thumb

Don’t create a dozen empty documents on day one of a project.

First ask:

will this question keep affecting future judgments?

If so, give it a clear source of truth.

If it only affects the current task, put it in the current spec.

If the code itself already explains it well enough, don’t copy it again.

A good documentation system isn’t many files, but:

• each document has a clear job
• each fact is maintained in only one place
• you know when to create a document
• you know when to update it
• outdated content can be archived or deleted

What agents need isn’t more text either.

They need a set of context that’s clear, free of conflicts, and leads to the right answer.