This is the first part of a series of opinionated articles on how to design better file structures. The goal is to provide a clear and concise guide to help you design better file structures. Here are the other parts:
What is a good file structure?
A good file structure is one that gets out of your way. It reduces friction and scales properly as your project grows. The goal of a good file structure is clarity, momentum, and shared understanding when working in a team.
Principles and goals
- Mirror the work, not the org chart.
Organize by concerns (docs,assets,work,exports) and what ships (features,episodes,deliverables), not by who did it. - Optimize for clarity and reduce cognitive load.
Saving a file should feel automatic and effortless. If you have to think about it, you need to improve your system. - Decide once, reuse, and adjust.
Codify naming, versions, and systems. If you need to change something, update your templates first. - Separate concerns.
Keep related files together and unrelated files apart. - Make it readable, sortable, and searchable.
Your file names should contain information that is both readable and searchable by humans and properly sorted by the operating system.
Document your system
Documentation is essential for communicating your file structure and providing a quick overview of the project. Whether you use a README, a wiki, or your team's preferred documentation tool, make sure it's easily accessible to everyone.
Good file structure documentation typically includes:
- Naming convention cheat sheet – one-line rules for each token (date, noun, version, state).
- Folder map – an indented tree or quick diagram explaining where things live and why.
- Ownership & contacts – whom to ping when something feels out of place.
- Update procedure – how to propose changes to the template so everyone stays in sync.
- Templates – a set of templates for your file structure. For this, you can use File Architect and write the templates in plain text.
Audit, enforce and iterate
Once you have a good file structure, you need to audit it and enforce it. You can use File Architect to audit your file structure and enforce your naming conventions. You can also use it to generate your file structure documentation.
If a new teammate can ship on day one without asking where things go, your structure works. If not, simplify or improve your system until it becomes self-evident.
Momentum goes where friction is low, so make the right path the easy path.