Tags: ai tech software-engineer published
ARCHITECTURE.md - Save AI Slop
I have faced this recently while helping some juniors being onboarded to a product. The first thing they hit was ‘Building up confidence in changing the code base’.
Why so? Because whenever they want to make change to a code base they are literally new at, it will take them 10x times to figure out where to make the change, ensuring it wouldn’t have affected something else and is ready to go live.
Just like human being, we now have clear understanding Agents are as dumb as a new hire is. No context of where things are, what’s the pattern, what’s the architecture being followed, are there any rules etc. With the passage of time, humans get used to the code base and they already have a map of files, folders, important elements in their mind when they are assigned a task. Agents on the other hand, NOPE, NADA. Every Claude/Codex session is a fresh start, so imagine if there’s no way of letting the agent know about that ‘mind map’ humans have in their mind how messy it will work.
That’s why ARCHITECTURE.md is now as important as any other README.md or CONTRIBUTING.md is. It’s a low-effort and high-leverage way to bridge the gap we just talked about — and it’s the first doc an agent should be able to reach from your CLAUDE.md. If you’re not familiar with that pattern, Harness Engineering - Rethinking AI covers why the map matters more than the manual.
How it should look like?
- Should describe the high-level architecture of the project.
- Keep it short: every recurring contributor will have to read it.
- Rule of thumb for
ARCHITECTURE— only specify things that are unlikely to frequently change. - Don’t try to keep it synchronized with code. Instead, revisit it a couple of times a year.
The codemap should answer “where’s the thing that does X?”. It should also answer “what does the thing that I am looking at do?”. Avoid going into details of how each module works, pull this into separate documents or (better) inline documentation. What’s missing on our side
Do name important files, modules, and types. Do not directly link them (links go stale).
A complete example: https://github.com/rust-lang/rust-analyzer/blob/d7c99931d05e3723d878bea5dc26766791fa4e69/docs/dev/architecture.md