Why .md Files Matter So Much in AI

One of the most surprising things I have discovered since working more seriously with AI is just how important .md files are.

Not because they are technically complicated.

Almost the opposite.

A Markdown file is basically a plain-text document with a lightweight way of adding structure such as headings, lists, links and code blocks. Markdown itself dates back to 2004; it certainly wasn't invented for AI.

What has surprised me is how useful something this simple has become for controlling modern AI agents.

The control layer can be plain English

Before I started building with AI, I had no idea what an .md file was.

I think a lot of people looking at coding agents from the outside would assume there must be some complicated technical language sitting between the human and the agent.

There is obviously enormous technical complexity underneath an LLM.

But the part you use to guide it can be remarkably ordinary.

For example, OpenAI's Codex supports AGENTS.md files inside a project. They can tell the agent how the codebase is organised, which commands it should run, what coding conventions to follow and other instructions relevant to working in that area of the repository. Codex can even use more specific AGENTS.md files deeper within a directory structure for more local instructions.

And those instructions can just be written in normal language.

That still feels slightly crazy to me.

Not every .md file does the same job

The .md extension doesn't give a file any special AI powers.

It is simply a convenient, readable format. What matters is what the file contains and whether the agent knows it should use it.

In my projects, I tend to think about a few different roles.

A README.md is generally useful for orientation: what the project is, how it works and how somebody can get started.

An AGENTS.md is much more explicitly aimed at the coding agent: how it should behave, what standards it should follow, commands it should run, areas it shouldn't casually change and other working rules.

Then I might have something like a PROJECT-OVERVIEW.md explaining the bigger picture: what we are building, who it is for and the direction of the project.

As the project grows, more focused files can earn their place — perhaps a content system, design system or another area with enough rules and decisions to justify its own persistent guidance.

These aren't universal required filenames. They are ways of separating different kinds of context so the agent isn't relying on one enormous prompt every time.

Write for clarity, not politeness

Good agent guidance doesn't need to sound technical.

It does need to be unambiguous.

If something is a hard rule, say so.

If something is a preference, make that clear too.

And if you genuinely haven't decided yet, say that rather than accidentally writing an early idea as though it were a permanent constraint.

For example:

Must: Do not change the existing authentication flow.

Prefer: Keep new components small and readable.

Open decision: The final mobile navigation pattern has not been chosen yet.

That distinction gives the agent much better information than vague language such as “try to keep everything nice and consistent”.

The same applies to negative instructions. If there is something you repeatedly don't want — unnecessary dependencies, over-engineering, certain design patterns, changes to a protected area — write it down.

Keep them current

There is a catch.

Persistent guidance can become persistently wrong.

I have had projects where my current prompts had moved on but the .md files had not. From my own experience, the coding agent appeared to perform noticeably better once I refreshed those files.

That doesn't prove exactly what was happening internally. But asking an agent to work from current instructions while leaving contradictory old guidance in the repo is clearly not helping.

I now think of the core documentation as something worth reviewing when a project changes phase.

Delete what is no longer true. Update established decisions. Add a new file when an area genuinely needs one.

Models are increasingly capable of handling large amounts of context.

But why create the noise?

The remarkable bit is how accessible this is

Markdown matters because it sits in a useful middle ground.

It is readable by humans, easy to edit, works naturally with version control, and gives agents structured text they can use as persistent context.

That means someone who cannot write the eventual application code can still meaningfully shape how the coding agent works on it.

You can discuss an idea in natural language, turn the important decisions into natural-language project guidance, then ask a coding agent — again in natural language — to build within those constraints.

The AI underneath all of this is extraordinarily complex.

The instructions steering it often aren't.

And I think that is one of the most important things for people starting to build with AI to realise.