A few years ago, the worst thing we could do to a codebase was create another random utils folder and pretend it was architecture. We argued about folder structures, component boundaries, service layers, naming conventions, domain models, and whether common meant “shared” or “nobody knows where this belongs.” Then AI-native development arrived and gave us a new category of mess. Now the codebase may be fine, but the Markdown files telling AI agents how to work with it are a disaster.

AGENTS.md, CLAUDE.md, .instructions.md, README.md, rules.md, architecture notes, coding conventions, prompt snippets, examples, old migration plans, half-forgotten decisions from last quarter, all sitting around the repo like sacred scrolls. And the agent reads them. Sometimes automatically. Sometimes only when asked.

Sometimes, according to the path scope. Sometimes in a tool-specific way that looks nothing like the other tool your teammate is using. So congratulations. Your Markdown files are no longer just documentation. They are part of the development system now.

In the past, bad docs mostly annoyed humans. In AI-native development, bad guidance files can affect generated code, refactoring choices, tool usage, test behavior, token cost, latency, and how much you trust the agent’s output. We still need to care about code organization. Now we also need to care about instruction organization.

One Caveat Before We Blame Markdown for Everything

This is not a universal spec for every AI coding tool. Different harnesses load guidance files differently. Codex, Claude Code, Cursor, GitHub Copilot, Aider, and other tools do not all treat Markdown files the same way.

Some tools load specific instruction files automatically. Some support path-scoped rules. Some require manual inclusion. Some concatenate parent and child instructions. Some have size limits. Some support lazy loading. Some just treat whatever you include as normal context. So the structure in this post is a design pattern, not a runtime contract. The principle is portable:

Better organized guidance creates better context.

The mechanics are harness-specific:

Always check how your actual tool loads, orders, scopes, and counts guidance files.

With that out of the way, let’s talk about the mess.

The Problem Is Not “Too Many Markdown Files”

A large project may need a lot of guidance:

frontend/
  AGENTS.md
  docs/
    architecture.md
    components.md
    forms.md
    server-state.md
    accessibility.md
    performance.md
    testing.md

That is not the problem. The problem starts when those files are unstructured, duplicated, stale, always loaded, or written as if the agent can magically infer what matters. A good guidance system has shape.

Some files route. Some files scope. Some files instruct. Some files demonstrate. Some files explain history. When every file tries to do everything, the agent gets a bucket of instructions and has to guess which ones matter. That usually ends exactly how you think it ends.

Bad Practices

1. Turning AGENTS.md Into a Junk Drawer

This is the classic failure mode. It starts small. Someone adds a rule. Then another rule. Then a testing note. Then an architecture explanation. Then five examples. Then a deprecated pattern nobody wants to delete because “maybe it is still useful.”

Six months later, AGENTS.md has become an archaeological site.

# AGENTS.md

Here is the full frontend architecture.
Here is the full backend architecture.
Here are all testing conventions.
Here are all database rules.
Here are all design system examples.
Here are all deployment instructions.
Here are historical decisions.
Here are deprecated patterns.
Here are 40 examples.

Good luck.

A root instruction file should usually not be an encyclopedia. It should be a router. When a frequently loaded file becomes huge, you pay for it in multiple ways. It uses more context when loaded, hides important rules inside a wall of text, mixes current guidance with old decisions, and makes it easier for the model to follow the wrong thing very confidently. A long instruction file is not a knowledge base. Sometimes it is just latency with headings.

2. Loading the Entire Documentation Folder for Every Task

More context is not strategy. It sounds reasonable to say, “Let’s give the agent all the docs so it has everything it needs.” Then the agent is editing a button component while reading deployment notes, database migration history, payment architecture, old Redux decisions, and a performance checklist for virtualized tables.

That is how you make a small task expensive, slow, and weird. Do not make the model read your entire organizational memory to rename a button. Relevant context is better than more context. For a form refactor, the agent may need:

frontend/AGENTS.md
frontend/docs/forms.md
frontend/docs/accessibility.md
frontend/docs/testing.md

It probably does not need:

frontend/docs/deployment.md
frontend/docs/routing.md
frontend/decisions/001-why-we-left-redux.md
frontend/examples/tables/virtualized-grid.md

The point is not to hide knowledge from the agent. The point is to load knowledge when it is relevant.

3. Repeating the Same Rule Everywhere

This one feels harmless until the copies drift.

# frontend/docs/forms.md
Use React Query for submit mutations.

# frontend/docs/server-state.md
Use React Query for all server mutations.

# frontend/features/billing/AGENTS.md
Use the billing mutation wrapper for payment forms.

# frontend/docs/testing.md
Mock submit mutations manually in form tests.

Now the agent has to figure out which rule is general, which one is local, which one is outdated, and which one the team actually follows. Good luck to the model. Also, good luck to the reviewer. A rule should live in one place. Everywhere else should point to it.

# frontend/docs/forms.md
For submit mutations, follow docs/server-state.md.

# frontend/features/billing/AGENTS.md
Billing forms follow docs/forms.md and docs/server-state.md.
Use the billing mutation wrapper only for payment-related flows.

4. Mixing Rules, Examples, History, and Migration Notes

Some Markdown files try to be a constitution, tutorial, changelog, migration plan, architecture decision record, and group therapy session.

# components.md

Current component rules...
Full examples...
Old component patterns...
Why we moved away from the old system...
Temporary migration notes...
Deprecated APIs...
A long debate from last year...

This is where agents get into trouble. Current rules get mixed with historical context. Deprecated patterns look active. Old examples get copied. The model has to infer what is still valid. Do not put active rules, long examples, historical decisions, and migration notes in the same file. Separate them:

docs/components.md
examples/components/good-card.md
examples/components/bad-container-component.md
decisions/003-design-system-first.md
migrations/component-cleanup.md

Current guidance should be easy to find. History should be available, but it should not pretend to be today’s rule.

5. Writing Guidance That Is Mostly Vibes

“Write clean code” is not guidance. It is a wish. The agent cannot turn that into a reliable decision. A reviewer cannot check it. Two developers will interpret it differently, and two models probably will too.

Weak:

Write clean code.
Use best practices.
Make components scalable.
Keep things simple.
Follow good architecture.

Better:

- Keep data fetching out of presentational components.
- Put server state in React Query.
- Keep UI-only state close to the component that owns it.
- Do not create a shared abstraction until there are at least two real use cases.
- Prefer existing design system primitives before adding new UI.

Good guidance is boring in the best possible way. It is specific, reviewable, and actionable. A useful test:

Could a reviewer tell whether this rule was followed?

If not, it is probably too vague.

6. Keeping Deprecated Rules Around Without Labels

Old guidance is dangerous when it looks current.

Use Redux for shared state.
Use Zustand for shared state.
Avoid Zustand.
Use React Query for server state.

This is not documentation. This is a trap. You usually discover this during code review, when the agent follows a rule everyone forgot was still documented. If something is deprecated, remove it or label it clearly.

# Deprecated

Do not use Redux for new shared state.
Redux remains only in legacy checkout flows.

# Current rule

Use local component state for UI-only state.
Use React Query for server state.
Use the approved client store only for cross-page client state.

Old rules do not become harmless just because nobody reads them. Agents read things. That is kind of the point.

7. Assuming Your Harness Understands Your Beautiful Folder Structure

You can organize your docs perfectly:

docs/
  architecture.md
  frontend.md
  backend.md
  testing.md
  decisions/
    001-use-react-query.md

That does not mean your AI tool automatically understands how to use them. Some tools read specific file names. Some tools support scoped rules. Some require manual references. Some ignore your structure unless you explicitly point to it. A good documentation structure is necessary, but not sufficient. You still need to know how your harness works. Otherwise, you may create a beautiful guidance system that the agent never actually reads.

8. Documenting the Architecture You Wish You Had

This might be the most human failure mode.

The docs say:

Keep domain logic out of UI components.
Use clean boundaries.
Avoid duplicated state.
Keep components small.

The code says:

Fetch data in every component.
Mix permissions, formatting, API calls, and rendering everywhere.
Store server state in three different places.

Now the agent has to choose between the documentation and the actual codebase. Sometimes it will follow the docs and produce code that does not fit. Sometimes it will follow the existing code and ignore the docs. Sometimes it will creatively combine both into something nobody asked for. Documentation should guide the real architecture, not describe a fantasy version of it.

Better:

# Client State

Current state:
- Legacy checkout still uses Redux.
- New product flows should not add Redux usage.

Preferred direction:
- Use local component state for UI-only state.
- Use React Query for server state.
- Use the approved client store only for cross-page client state.

Legacy exception:
- Checkout migration is tracked in docs/migrations/checkout-state.md.

That gives the agent reality and direction. Both matter.

What Good Looks Like

Once you stop treating guidance files as a junk drawer, the next question is obvious: where should everything go? The goal is not fewer Markdown files. The goal is to make each file earn its place.

Start With the Harness

Before designing the structure, ask boring but important questions:

Which files does the tool read automatically?
Does it support root-level instructions?
Does it support folder-level or path-scoped rules?
Does it concatenate parent and child instructions?
Does it support lazy-loaded skills, memories, or docs?
Does it require manual file inclusion?
Does it have size limits or truncation behavior?
Does it count imported docs as normal context?

The same repo can behave differently across tools. So use portable organization principles, but adapt the loading strategy to your actual harness.

Make Root Files Small Routers

A root guidance file should usually answer three questions:

What kind of task is this?
Where should the agent look next?
What global rules always apply?

Example:

# Project Agent Instructions

Use this file as the project entry point.

First identify the area of the change:
- For frontend work, read frontend/AGENTS.md.
- For backend work, read backend/AGENTS.md.
- For database changes, read docs/database.md.
- For API changes, read docs/api-guidelines.md.

Global rules:
- Keep changes small and focused.
- Do not edit generated files.
- Prefer existing patterns over new abstractions.
- Run relevant tests when available.
- Update documentation only when behavior, architecture, or conventions change.

Notes:
- Long examples live in examples/.
- Architecture decisions live in decisions/.
- Local feature rules may exist in feature-level AGENTS.md files.

That file is not trying to explain the whole system. It is giving the agent a map.

Use Folder-Level Guidance for Real Scope

If the project has clear areas, give those areas their own guidance.

project/
  AGENTS.md
  frontend/
    AGENTS.md
  backend/
    AGENTS.md
  docs/
    database.md
    api-guidelines.md

For frontend:

# Frontend Agent Instructions

Read only the docs relevant to the task:

- Components: docs/components.md
- Forms: docs/forms.md
- Server state: docs/server-state.md
- Client state: docs/client-state.md
- Accessibility: docs/accessibility.md
- Testing: docs/testing.md
- Styling: docs/styling.md

Always:
- Prefer existing design system primitives.
- Keep presentational components free of data fetching.
- Keep domain logic outside low-level UI components.
- Avoid new abstractions until there are at least two real use cases.

If your harness supports scoped loading, this can reduce irrelevant context. If it does not, the structure still helps humans and agents navigate the repo when files are manually referenced.

Put Topic Guidance in Topic Files

Topic docs should clearly say when they apply.

# Forms

Use this document when:
- Creating a new form
- Changing validation behavior
- Refactoring form state
- Adding submit or error handling
- Working on field-level accessibility

Rules:
- Keep validation schema close to the form boundary.
- Show field-level errors when possible.
- Preserve user input after failed submission.
- Map API errors before passing them into presentational components.

Avoid:
- Duplicating validation rules across components.
- Mixing API error mapping with field rendering.
- Creating a generic form abstraction after only one use case.

Related docs:
- docs/server-state.md
- docs/accessibility.md
- docs/testing.md

Use this document when the section is doing real work. It tells humans and agents when this file is relevant. That is much better than hoping the title is enough.

Separate Rules, Examples, and Decisions

A practical frontend structure might look like this:

frontend/
  AGENTS.md

  docs/
    index.md
    architecture.md
    components.md
    data-modeling.md
    server-state.md
    client-state.md
    forms.md
    routing.md
    styling.md
    accessibility.md
    performance.md
    testing.md
    error-handling.md

  examples/
    components/
      good-card.md
      bad-container-component.md
    forms/
      payment-form.md
      multi-step-form.md

  decisions/
    001-use-react-query.md
    002-avoid-global-form-state.md
    003-design-system-first.md

  features/
    billing/
      AGENTS.md
    onboarding/
      AGENTS.md

The categories matter:

AGENTS.md       Routing and high-level rules
docs/           Active topic-specific guidance
examples/       Longer examples loaded only when needed
decisions/      Historical architecture decisions
features/       Local rules near local code

Do not make one Markdown file carry all of that weight. It will collapse.

Keep Frequently Loaded Files Short

Line counts are not laws, but they are useful pressure. As a rough heuristic:

Root guidance files: 50 to 200 lines
Folder guidance files: 50 to 200 lines
Topic docs: 100 to 400 lines
Examples: as long as needed, but separate
Decision records: short and focused

The real rule is simpler:

The more often a file is loaded, the more disciplined it should be.

Frequently loaded files should be routed and prioritized. Topic files should explain. Example files should demonstrate. Decision files should preserve history. If a file is long, make sure it is long on purpose.

Put Local Rules Near Local Code

Not every rule belongs in the root file. Billing rules belong near billing. Admin table rules belong near admin. Onboarding layout rules belong near onboarding.

Example:

frontend/
  features/
    billing/
      AGENTS.md
# Billing Feature Instructions

Use existing billing domain types from domain/billing.
Do not format currency manually. Use formatCurrency.
For invoice tables, follow docs/table-patterns.md.
For payment forms, follow docs/forms.md and docs/accessibility.md.

Local rules should not pollute the global context. They should live where they matter.

Review Guidance Files Like Code

If a file affects how agents write code, it deserves review. A small checklist is enough:

Is this file likely to be loaded often?
Can it be shorter?
Does it have a clear scope?
Does it say when to use it?
Does it duplicate another file?
Does it contain outdated guidance?
Are examples separated from rules?
Are historical decisions separated from current instructions?
Does this match how our actual harness loads guidance?
Would this help the agent make better decisions?

If a rule matters, give it an owner. If nobody owns it, it will become folklore.

The Short Version

Bad Markdown organization does not just waste tokens. It creates a blurry instruction layer where old rules, local exceptions, vague advice, and unrelated examples all compete for attention. That leads to slower runs, inconsistent code, more review churn, and less trust in the agent. Good Markdown organization creates clearer context. Not perfect context. Not magic context. Just context that has a fighting chance of being useful.

A good rule of thumb:

Route at the root.
Scope by folder.
Instruct by topic.
Demonstrate with examples.
Explain history in decisions.
Load long context only when needed.
Adapt the structure to your harness.

We already learned that codebases need architecture. Now the instruction layer needs architecture too. Because in AI-native development, Markdown files are no longer passive documentation. They are part of the system that shapes the code. And systems without structure eventually become expensive, hard to maintain, and difficult to develop.