You should delete most of your docs

You ask your AI tool to change the checkout code. It reads ARCHITECTURE.md first. The doc says: orders live in the billing folder.

But someone moved orders to the commerce folder six months ago. Nobody updated the doc. AI makes the wrong change and you spend twenty minutes fixing it.

Sound familiar? You should delete most of your docs. Not every README, just the docs you trust more than your code (this is a subjective judgement).

The problem is not "no docs at all"

You wrote those files to help AI, that is fine.

The mistake is this: the doc says one thing, the code says another. AI does not know which one is true.

Docs are just text files, they do not run, they do not get tested, so they get old fast. Your code changes every week, your doc stays the same, and soon you have a mismatch between the two.

When the doc and the code do not match, AI has two answers and no way to pick the right one

What you should delete

Delete docs that say the same thing as your code.

Long "how the app works" files. Folder guides that just list file names. Docs you wrote once and never updated.

Question yourself: could you fix this with a better function name instead of a doc? Then delete the doc and fix the code.

A good book to read about keeping your code clean and understandable is "Clean Code" by Robert C. Martin. It is a classic and a must-read for anyone who writes code.

What you should keep

Most of the knowledge should live in your code. Clear names, small files, one job per file.

Keep a few docs for things code cannot say:

Decision notes: why you picked plan A and not plan B. A word list: in your app, is it Order, Purchase, or Cart? A short map: where is checkout, billing, and shipping in the repo?

These docs help AI move faster. They do not replace reading the code.

What about CONTEXT.md?

In my post How to cut your LLM token bill by 60% without losing quality, I wrote about /grill-with-docs and CONTEXT.md. That sounds like the opposite advice. It is not.

Here is the difference. A bad doc tries to explain your whole app in words. CONTEXT.md only stores the things AI cannot guess from code alone.

/grill-with-docs is a skill built by Matt Pocock. You run it once (or when your project changes a lot). It reads your repo and looks for confusing spots. Same idea in three files? Different names for the same thing? Rules that live only in someone's head?

Then it asks you one short question at a time. Not ten questions in one message. Just one. You answer. It asks the next one.

Example: your app calls the same thing Order in one place and Purchase in another. Which word is correct? You pick one. It writes that down.

Another example: you chose Redis for caching and not Memcached. Why? You explain in one sentence. That goes in too.

All of this lands in one small file: CONTEXT.md. Think of it as a cheat sheet for AI. Your word list. Your big decisions. Not a copy of your folder tree.

Why does this help? Without it, AI guesses. You say "fix the order flow." It is not sure if you mean Order, Purchase, or Cart. It picks wrong. You correct it. That back and forth costs time and tokens.

With CONTEXT.md, AI reads your words once and stops guessing. Fewer wrong edits. Fewer "no, I meant the other file" messages.

You should use CONTEXT.md for words and decisions code cannot show. You should not use a huge ARCHITECTURE.md to replace reading your code.

Better code beats better docs, every single time.