What this post is about: Part 1 explains the concepts of AI context files to anyone curious – no code required. Part 2 unpacks the judgment calls embedded in building a context file; this is what separates folks who’ve shipped software vs. those who’ve read about it.
The new employee who forgets everything overnight (and sometimes mid-sentence)
Imagine having a brilliant employee; on the first day, you brief them thoroughly with all the background and context, rules, decision points, outcomes, standards, what to do, what to never do etc. They execute flawlessly. Day two, they show up and you can see they have lost their memory; partially and perhaps fully! Day three: Same thing.
Thats what working with AI can feel like; especially when you do not have a context file. Each new session can be a blank slate and you have to brief it entirely on what you want. Give them vague directions such as: “Please follow best practices” and you end up getting different answers each time. You would hope it all just works but … Hope can’t be a strategy!
A context file is the briefing document you hand every new employee on day 1 – except that now they can use it every single day and can follow it precisely, if you write it precisely.
A well-structured context file covers four things:
- Project context: What the project is and where it is today.
- Data rules: What are your data rules, especially around privacy.
- Coding standards: Enforce the right standards you care about.
- Tools to use: Details on the stack being used to develop. This prevents the system from randomly suggesting new technology mid-devolopment cycle.
The first and second items evolve with the project. The last two items can be reused across multiple projects. The payoff is compounding. You write the rules once. Every future session — any AI tool, any device — starts with the same governance baseline. No drift, no re-explanation, no “it worked last time but not today.” The briefing file is always there.
The judgment calls that many folks miss
Writing a context file sounds like a technical task. It isn’t. Every hard section reveals a decision you hadn’t actually made yet. The file is a mirror — vagueness on the page is vagueness in your own thinking.
Three judgment calls separate experienced product builders from those who have only read about the craft.
- Vagueness in the file is vagueness in thinking: The hardest sections to write aren’t hard because writing is hard. They’re hard because the underlying decision hasn’t been made yet. Where does this product go in two years? What will it handle that it doesn’t handle today? A context file written from a fuzzy product vision will be just that… fuzzy.
- Local first is a product judgment: Running AI inference locally rather than sending each piece of data to the cloud isn’t only cheaper – its a trust decision. For products handling sensitive data keeping computation local by default, and requiring an explicit decision to send items to cloud is the right default. Its not just about cost; its also about liability.
- The context file architecture: Most people write one file containing everything and call it done. The superior move is recognising that some things are universal (coding standards, data rules, tool choices) and some things are project-specific (what the product is, where it is today). Separate them, and your standards compound across every project you build. But the deeper point is this: No generic template will ever fully work. The file has to become yours — argued over, updated as the project grows, refined as you discover what you didn’t know when you started. A file you downloaded and never touched is not a context file. It’s a placeholder.
The signal: The hardest parts of writing a context file aren’t hard because of writing. They’re hard because you if you have not underlying decisions yet, your file will reflect that, and so will your AI’s response. This friction is useful. It’s telling you exactly where your product thinking still has gaps — before the code does.