As I’ve become a more AI-Driven developer I’ve started to realize that our software repos need to change. And a big part of that change is around documentation.

Repos were have always been designed around two consumers: 1) human developers and 2) build/deploy pipelines. For the humans, we organized our code, add comments to code, and occasionally left a few TODO files lying around. For the pipelines, we made sure everything needed to independently build the solution was in the repo and had relative references.

But now we have an increasing amount of code being written by AI agents. Sometimes a single agent. But, also, increasingly, multiple agents working independently and occasionally in parallel, designing, researching, planning, reviewing, implementing, testing, and documentng.

All of our agents need a place to think and way to share their thinking without blowing up each other’s context window. Our agents need workspaces for themselves and they need to know how to document knowledge for others (other agents and humans, alike.)

The mistake many teams make is expecting this to happen organically, that the harnesses and models will take of it for them. But what I’ve seen happen too often is that agent thinking spills into the repository itself. Scratch notes, implementation plans, temporary analyses, generated summaries, cached context, and execution logs either become committed accidentally or disappear into random files that future agents can’t distinguish from authoritative documentation. And, at the same time, it’s not clear what is authoritative documentation that agents should rely upon.

You can believe that the code is all the documentation you need. I disagree. I believe that to get the best from your agents they need well structured and well organized documentation.

The solution is to separate knowledge from work. And to create this seperation in your instructions so every agent and human knows how they are supposed to do things.

Three Types of Information

Every file in a repository belongs to one of three categories.

1. Permanent Project Knowledge

This is the long-lived information that explains the app.

Examples include:

  • Architecture
  • API documentation
  • Coding standards
  • Security guidance
  • Architecture Decision Records (ADRs)
  • Deployment documentation
  • Runbooks

All of this belongs in the traditional docs/ folder.

These documents answer the question:

“How does this system work?”

They are the authoritative source of truth for both humans and the agents.

2. Agent Operating Knowledge

AI agents need instructions that humans generally do not.

They need to know:

  • Which documents to read first
  • How work should be performed
  • Where temporary artifacts belong
  • How to coordinate with other agents
  • What workflow to follow when implementing features
  • How permanent knowledge should be updated

This belongs in a dedicated .ai/ directory.

Unlike docs/, .ai/ is not intended to explain the software. It explains how agents should work with the software.

Think of it as an operating manual for contributors.

Example:

.ai/
    prompts/
    standards/
    workflows/

A workflow might say:

Before implementing a feature:

  1. Read the architecture documentation.
  2. Read the coding standards.
  3. Create an implementation plan.
  4. Store temporary work in .work.
  5. Update documentation if architectural decisions change.

Notice that it doesn’t replace project documentation. It tells the agent how to use it.

3. Temporary Work

Humans scribble on whiteboards.

AI agents generate plans.

Those plans should have a home.

.work/

or

.ai/scratch/

These directories are intentionally ignored by Git.

Typical contents include:

  • implementation plans
  • design explorations
  • research notes
  • generated analyses
  • temporary test output
  • experiment results

Once the task is complete, these files can disappear without affecting the project.

They are workspace, not documentation.

A Repository Designed for Humans and AI

A repository using this model might look like this:

/
├── AGENTS.md
│
├── docs/
│   ├── architecture/
│   ├── development/
│   ├── api/
│   ├── operations/
│   └── adr/
│
├── .ai/
│   ├── prompts/
│   ├── standards/
│   ├── workflows/
│   ├── scratch/
│   ├── cache/
│   └── logs/
│
├── .work/
│
├── src/
└── tests/

The intent of every directory is immediately obvious.

The Difference Between docs/ and .ai

This distinction is the heart of the model.

docs/ answers:

How does this software work?

Examples:

  • Architecture
  • APIs
  • Deployment
  • Data model
  • Security model

.ai/ answers:

How should an AI agent work in this repository?

Examples:

  • Read these documents before coding.
  • Follow this implementation workflow.
  • Store temporary notes here.
  • Update architecture documentation when making design changes.
  • Don’t duplicate documentation.
  • Coordinate with other agents this way.

One describes the software.

The other describes the contributor.

Keeping those responsibilities separate prevents duplication while making repositories dramatically easier for AI agents to navigate.

And making it easier for the AI agents to navigate is critical. We know that as context windows fill up it can negatively impact performance and results. We want to allow each instance of an agent to figure out just what it needs - not too much or too little.

Multi-Agent Development

As autonomous development becomes more common, multiple agents will often work simultaneously.

One researching.

One implementing.

One writing tests.

One reviewing.

Each should have an isolated workspace.

Example:

.work/
    architect/
    implementation/
    reviewer/
    testing/

No agent should depend on another agent’s temporary files.

Anything that becomes permanent knowledge should be promoted into committed documentation.

AGENTS.md Should Stay Small

Many repositories attempt to put every instruction into AGENTS.md.

That doesn’t scale.

Instead, AGENTS.md should be the entry point.

Its job is simply to direct agents.

Example:

  1. Read docs/architecture/system-overview.md.
  2. Read docs/development/coding-standards.md.
  3. Follow workflows in .ai/workflows.
  4. Store temporary work in .work.
  5. Never duplicate permanent documentation.
  6. Promote important discoveries into docs/.

Everything else belongs elsewhere.

Why This Matters

This separation produces several benefits.

Developers always know where authoritative documentation lives.

AI agents always know where to work.

Temporary artifacts never pollute project history.

Permanent knowledge becomes easier to maintain.

Most importantly, repositories become understandable.

As AI-generated work increases, I believe this distinction between knowledge and work will become as fundamental as the distinction between source code and build artifacts.

In the agentic world it’s best for everything to be in the repo, it keeps it neat and easy for the agents - allowing them to do their work with the least context pollution and lowest likeliehood of confusion. But if all the docs go in the repo we need a system to keep it from becoming a mess. We have to tell our agents how to work, just as we would tell a new human dev team member how we do our work.

Agent Prompt

I’ve been using the following prompt to prepare a new or existing repository for AI-native development. You are, obviously, welcome to edit it/tweak it to your liking and preferences, this isn’t some hard science/engineering thing - it’s just how I instruct my setup agent to get things started. I’ve found that Sol, Opus 4.8, and Kimi K3 have all done a good job with it for setup. One of the things I like about this approach is that the rigor means less expensive coding model still document well because they don’t have to reason how to document - they already know from the instructions.

In fairness, I’ve not been using this much on its own anymore. I’ve moved on to my Trellis Playbook which incorporate this along with a lot of other opinionated ideas of how a software project and repo should be run in the agentic era. Feel free to check it out and give it a try for new or existing repos.

Prompt

You are preparing this repository for long-term collaboration between human developers and AI agents.

Your objective is to establish a consistent repository structure that clearly separates:

  • permanent project knowledge
  • reusable AI guidance
  • temporary working artifacts

The repository should remain fully backward compatible.

Do not modify application behavior.

Do not move existing source files.

Do not change build or CI/CD behavior.

Repository Structure

Ensure the repository contains:

/
├── AGENTS.md
├── docs/
├── .ai/
│   ├── prompts/
│   ├── standards/
│   ├── workflows/
│   ├── scratch/
│   ├── cache/
│   └── logs/
├── .work/

Create directories only if they do not already exist.

Git Ignore

Update .gitignore without removing existing entries.

Ensure the following are ignored:

.ai/scratch/
.ai/cache/
.ai/logs/
.work/

Preserve Existing Documentation

If the repository already contains a docs/ directory, preserve it.

Do not move or rewrite existing documentation unless necessary to improve organization.

Explain the Difference Between docs/ and .ai

Ensure repository documentation clearly explains this distinction.

docs/ is the canonical documentation describing the software itself.

Examples include:

  • architecture
  • APIs
  • coding standards
  • deployment
  • security
  • operations
  • ADRs

It answers:

How does the software work?

.ai/ is documentation for AI contributors.

It should contain:

  • reusable prompts
  • implementation workflows
  • agent standards
  • contributor guidance

It answers:

How should an AI agent work in this repository?

.ai/ should reference docs/ rather than duplicate it.

AGENTS.md

Create or update AGENTS.md.

Keep it concise.

It should:

  • describe repository conventions
  • direct agents to the appropriate documentation
  • explain where temporary work belongs
  • explain how permanent knowledge should be documented
  • explain multi-agent collaboration

Avoid placing detailed project documentation inside AGENTS.md.

Use it as an entry point into the repository.

Multi-Agent Collaboration

Document that:

  • each agent should use its own directory beneath .work
  • temporary files should never become dependencies
  • permanent knowledge belongs in committed documentation
  • implementation notes belong in temporary workspaces
  • reusable prompts belong in .ai/prompts
  • reusable workflows belong in .ai/workflows

Documentation Philosophy

Document the following principle:

If future developers or future AI agents will benefit from the information, commit it.

If the information is only useful while solving the current task, place it in the temporary workspace.

Quality Checks

Before finishing, verify:

  • repository structure exists
  • ignored directories are ignored
  • documentation clearly distinguishes docs from .ai
  • AGENTS.md is concise
  • no temporary directories are referenced as project dependencies
  • no existing project behavior changed

Finally, summarize every change you made