An independent journal. Not a shop, and not affiliated with the tools it writes about. Disclaimer

A map of a repository. The paths app, domain, tests, docs, and scripts are drawn solid. Other branches are dashed and marked not yet.
A map of a repository. The paths app, domain, tests, docs, and scripts are drawn solid. Other branches are dashed and marked not yet.

Programming

A repository map you can say aloud

25 September 2026 ยท 2 min read

Five paths you can name are a map. A tree of folders you cannot explain is a pile the next change will make deeper.

A repository becomes hard to change when nobody can say, without opening it, where a new file would go. Models make this worse by adding a folder for every answer. The map at the top of this article is intentionally small: a few paths are kept, and the rest are marked not yet. Small is the point. A map you cannot say aloud is not a map. It is a listing.

Five paths, said in one breath

You do not have to use these names, but you should be able to finish the sentence. Application code lives here. The rules of the domain live here. Tests live beside the thing they check. Notes a person must read live here. One-off scripts live here and are not imported by the application. If a sixth path exists, you should know what it is for. If you cannot say it, the path is a candidate for deletion or for “not yet.”

Not yet is a real place

Experiments, generated scaffolds, sample configs, and a second README do not have to be destroyed as ideas. They do have to stay out of the kept paths until a later change will still want them. Put them on a branch, or do not commit them. A file in the main tree is a promise that the next person, and the next prompt, should treat it as part of the program. Broken promises accumulate faster than features.

How to use the map when a model adds files

Before you accept a diff, read the new paths against the sentence. A file that does not fit one of the five paths is either a new decision or a mistake. New decisions belong in the commit message in words: “Scripts are now allowed to share one library under scripts/lib, and the application must not import it.” If you cannot write that sentence, delete the path. The model can recreate a file. It cannot recreate a tree you understand.

Keep the map where the work starts

Put the five paths at the top of the contributor note, or in the issue template, in a few lines. Paste them into a chat when you ask for a new module. The map is context of the useful kind: short, stable, and about boundaries rather than about every file that happens to exist today. When the map changes, change it on purpose, the way you would change a public function. Quiet growth is how a repository stops being sayable.

CursorUltra Blogs is an independent journal. It is not affiliated with the tools mentioned in this piece, and nothing on this website is for sale. Read the disclaimer.