Part Three · Architecture for Non-Coders · Chapter 08
Software architecture for non-coders
By the end of this chapter you have just enough structure to not get lost in a real project: what a repo, a file tree, and a module are, why organising for easy checking matters, and how a project map makes the AI work better.
AVATAR OPENER · ~90s
Watch: giving a real project a map, and how the AI's work changes because of it
HeyGen avatar · generated, consistent presenter
You now have a terminal you are not afraid of and a companion repo sitting on your machine. This chapter gives you the mental furniture to move around a real project without feeling lost. It is not a computer-science course. It is the handful of structural ideas that let a non-coder direct real builds with confidence, and nothing more.
The promise is deliberately modest: enough architecture to not get lost, not a degree. You will not learn algorithms or data structures. You will learn what the words repo, file tree, and module actually mean, one principle about how to organise things, and why all of it makes the AI you direct noticeably better at its job. That last part is the payoff, so keep it in view: structure is not tidiness for its own sake, it is what lets both you and the model reason about a project without holding all of it in your head at once.
Structure is not about neatness. It is about making a project easy to check.
A pile is something you dig through. A structure is something you reason about. The difference is entirely in whether it was organised to be checked.
THREE WORDS THAT UNLOCK THE REST
Almost all the intimidation in this area comes from three words used casually by people who forgot they once did not know them. Here they are, plainly.
A repo
Short for repository. It is just the project folder, the single place that holds everything for one project: its files, its history, its rules. The companion repo you cloned is exactly this.
A file tree
The folders-inside-folders shape of a project, drawn out. The same nesting you see in any file window, just written as an outline you can read at a glance.
A module
One self-contained piece of a project that does one job. A drawer with a clear label. You can understand it, and check it, without opening every other drawer.
A convention
An agreed way of doing things in this project: where files go, how they are named, what the rules are. Written down once, followed every time, by you and the AI.
That is the vocabulary. A repo is the project folder. A file tree is its shape. A module is one labelled drawer that does one job. A convention is the house rule for how the drawers are arranged. With just those four, you can talk about the structure of any project and follow what people mean when they use these words around you.
DEEP DRAWERS, NOT MANY SHALLOW ONES
There is one design principle worth carrying, and it comes from software thinking made plain by Matt Pocock, tracing back to the computer scientist John Ousterhout. It is about how to divide a project into modules, those labelled drawers. The good way is deep modules: a small number of drawers, each doing a substantial job behind a simple label. The bad way is shallow modules: many tiny drawers, each doing almost nothing, so you have to open twenty of them to follow one thread.
Many shallow drawers
Everything split into tiny pieces that each do almost nothing. To follow one idea you open a dozen files and hold them all in your head. Nobody can check it easily, including the AI.
Result: technically organised, actually a maze.
VS
Few deep drawers
A small number of modules, each doing a real, whole job behind a clear label. You can open one, understand it fully, and check it without touching the rest.
Result: easy to reason about, easy to check, easy to fix.
Why does a non-coder directing AI care about this? Because the model works the same way you do. When a project is a few deep, clearly-labelled modules, the AI can find what it needs, change one thing without breaking three others, and check its own work. When a project is a sprawl of shallow fragments, the model loses the thread exactly as you would, and its mistakes multiply. Organising for easy checking is not a favour to future programmers. It is what makes the AI reliable on your project today.
THE HIGHEST-LEVERAGE FILE: A PROJECT MAP
Here is the single most useful structural thing you can do, and it needs no coding at all. You give the project a map: a short file, kept in the project folder, that tells any AI working there what this project is, how it is organised, and the conventions it must follow. In Claude Code this file has a specific name and is read automatically at the start of every session, so the AI arrives already oriented instead of guessing.
Without a map, the AI starts fresh every time, re-explores, and makes assumptions that may not match how you actually work. With one, it opens the project already knowing the layout and the rules, the way a good new hire would after reading a one-page onboarding note. This is the same idea as the personal constitution from the beginner course, aimed at a single project instead of at you.
Draft a project map (the CLAUDE.md idea)
Help me write a short project map for [my project], the file an AI
should read first whenever it works here.
Interview me briefly, then draft it with these parts, kept tight:
- What this project is, in two plain sentences.
- How it is organised: the main folders and what each is for.
- The conventions: how things are named, where new files go, the
rules this project always follows.
- Never: the things an AI must not do in this project.
- When unsure: ask me one clear question before guessing.
Keep it short enough that reading it takes under a minute. A map,
not a manual.
Before: every session you re-explain where things live and what
your rules are, and the AI still guesses wrong half the time.
After: the AI opens the project already knowing the layout, follows
your naming without being told, and asks instead of assuming when
it hits something the map did not cover.
One honest note on how to build the map, borrowed from the people who designed the feature: do not over-engineer it up front. Start without a map, work on the project for a bit, and notice where you keep correcting the AI. Those corrections are the map writing itself. Then capture them. A map grown from real friction is far better than a long speculative one you guessed at on day one.
NOW YOU TRY · CREATE
Give one real project a map
Take one real project, the companion repo, a folder of your own work, anything with more than a couple of files. Use the prompt above to draft its project map. Be concrete about the conventions you actually follow and honest about the things an AI should never do here. Keep it under a minute to read. Then, if you can, place it in the project folder and start a fresh session to feel the difference.
Right if the map would let a capable stranger, or a fresh AI session, understand your project and its rules in one short read, without you explaining anything out loud.
Show the worked solution
The drill works when the map replaces a conversation you are tired of having. Say the project is a small site you maintain. Without a map, every time you bring an AI into it you re-explain the same things: the pages live here, the styles live there, we never use this library, always write copy in this voice. Draft the map and those become four written lines the AI reads automatically. The "what it is" says a two-sentence description so it knows the purpose. The layout names the two or three real folders and what each holds, so it stops guessing where a new file goes. The conventions capture your actual rules, the naming pattern you use, the voice, the one library you refuse. The never-list catches the specific mistakes you have watched it make, do not touch the config, do not invent copy, do not add dependencies without asking. Now a fresh session opens the project already oriented, and the difference is immediate: fewer wrong assumptions, less re-explaining, and when it does hit something the map did not cover, it asks instead of guessing. The reason this is the highest-leverage structural move is that it costs one short file and it pays back on every single session afterward, which is exactly the compounding you want from anything you build once.
WATCH FOR
✗You split a project into many tiny pieces to seem organised. Shallow modules make a maze. Prefer a few deep, clearly-labelled drawers that each do a whole job and can be checked alone.
✗You skip the project map and re-explain every session. A one-minute map read automatically beats re-orienting the AI by hand every time. Write it once, benefit forever.
✗You write a huge speculative map on day one. Over-engineering. Start without one, watch where you keep correcting the AI, and grow the map from those real corrections.
✗You organise for looks, not for checking. The test of good structure is whether one piece can be understood and verified without opening the rest. Optimise for that.
WHAT YOU LEARNED
The takeaways
The vocabulary is small: a repo is the project folder, a file tree is its shape, a module is one labelled drawer that does one job, a convention is the house rule.
Prefer few deep modules over many shallow ones. Organising so each piece can be checked on its own is the whole point of structure.
Structure helps the AI for the same reason it helps you: it can find things, change one part safely, and check its work when a project is not a sprawl.
The highest-leverage move is a short project map, read automatically, that tells any AI what the project is, how it is laid out, and its rules.
Grow the map from real friction: start without one, capture the corrections you keep making, and keep it short enough to read in under a minute.
Your project · map your project
Give your thread project a real map this week and feel a fresh session arrive already oriented. You now have enough structure to direct real builds without getting lost. Next chapter turns a single run into a system: /goal as the north star you lock, and /loop as what turns a one-time task into something that runs itself.
You do not need a computer-science degree to direct real software. You need four words, one principle, and a one-page map. Give the project a shape that is easy to check, and both you and the machine stop getting lost in it.