The situation
The right document exists, but it is named notes-final-2.md inside an archive beside three older
copies. A fresh session reads the wrong one and acts on a decision you already replaced.
The idea in one paragraph
Project layout is navigation for both people and agents. Predictable names, clear ownership and a short entry path reduce the amount of searching needed before work can begin. The goal is not a perfect folder tree. It is making the current truth easier to find than the stale alternatives.
| Signal | Helpful | Costly |
|---|---|---|
| Name | PROGRESS.md | latest-notes-v3.md |
| Location | Plans beside their index | Plans mixed with exports and logs |
| Depth | A few purposeful layers | Six folders before the first useful file |
| Status | Active pointer at the top | Current state hidden in history |
How it actually works
A cold session begins with no private map of your repository. It searches names, follows links and infers conventions from nearby examples. Stable names turn those guesses into a repeatable route. A small architecture note can explain which directory owns content, UI, tests and deployment; it should link to sources rather than duplicate them.
Generated maps help when they can be recreated from code. Human decisions should stay in human-owned records. Mixing the two makes regeneration overwrite judgment or makes a machine-produced index look more authoritative than the source it summarises.
What this changes for you
- Give recurring roles recurring names: instructions, plan, progress, decisions and tests.
- Put an active pointer near the entry, with history behind it rather than above it.
- Archive stale material away from the normal discovery path.
Where it breaks
Renaming a mature project to satisfy an imagined ideal can break imports, links and habits without improving discovery. Learn the existing convention first. Add one clear entry map when needed; do not rearrange working code only to make the tree look tidy.
Terms used on this page
- Cold session: a new conversation that has not read the project's earlier chat.
- Topology: a compact map of the important parts of a project and their relationships.
- Convention: a repeated naming or placement rule that makes the next location predictable.
- Discoverability: how easily the current source can be found from a normal entry point.
Read next
One bounded session uses that readable project shape to finish one coherent piece of work and leave a clean return path.