Your Project Context File¶
From Brainstorm to Real¶
You've got your house-sitter note — the bullet points your team just brainstormed. Now you're going to ask your AI coding assistant to turn that into a real project context file it reads automatically.
Here's what makes a good project context file:
What goes in: - Project purpose — one sentence about what this is and who it's for - Main parts of the application — the danger scale, the weather section, the gear checklist, etc. - Data sources — where the live data comes from - Domain rules — standards the application must follow (like using the official danger scale colors) - AI behavior rules — how your AI assistant should work with you (like saving and syncing when asked, or pushing back when you don't provide clear acceptance criteria) - Pointers — where to find more details about the project
What doesn't go in: - Long explanations — keep it brief and point to existing documentation instead - Things AI can figure out on its own — it's smart enough to understand your project by looking at it - Every decision you've ever made — only include what AI needs to get started
Why rules matter most: AI has seen millions of projects in its training. Without your rules, it defaults to whatever patterns are most common — which may not match your project's decisions. A rule like "always use the official North American Avalanche Danger Scale colors" seems obvious to your team, but AI doesn't know your team's decisions unless you write them down. The rules in your context file steer AI toward the right choices from the very first prompt.
Remember: table of contents, not the whole book.
Try It: Create Your Project Context File¶
Format: Mob Session Time: ~10 minutes Setup: Gather around the computer your team has been using to build your runs — the one with the Coder Terminal. One person drives, everyone else navigates.
Step 1 — Ask AI to create the file
Take the house-sitter note your team brainstormed in the last section and give it to your AI coding assistant. You might say something like:
Create a project context file for this project. Here's what I want it to include:
[paste or type your brainstormed bullet points]
Keep it short. Point to existing documentation rather than duplicating content. This should be a quick reference, not a manual.
Your AI assistant will create the right file for your tool — it knows what to name it and where to put it. You don't need to worry about the details.
Your AI assistant will create a file called CLAUDE.md in your project. Claude Code reads this file automatically at the start of every conversation.
Your AI assistant will create a file called AGENTS.md in your project. Codex CLI reads this file automatically at the start of every conversation.
Your AI assistant will create a file called AGENTS.md in your project. pi.dev reads this file automatically at the start of every conversation.
Step 2 — Review what it created
Ask your AI assistant to read back what it created:
Read back the project context file you just created.
Look it over as a team. Is it short? Does it cover the essentials from your brainstorm without going overboard? If it's too long or includes too much detail, push back:
This is too long. Shorten it — just cover the essentials. Where documentation already exists, point to it. Where it doesn't, create the documentation and point to that instead of putting everything directly in the context file.
Step 3 — Test it with a fresh start
This is the moment of truth. Close your AI coding assistant and reopen it from the Coder Terminal. You're starting a completely fresh conversation.
Now, without explaining anything about your project, ask:
What is this project and what does it do?
If the context file is working, AI should know. It read the file automatically when the conversation started — no prompting from you.
Step 4 — Try building something
Still in this fresh conversation, give AI a simple task without any project context in your prompt:
As a backcountry skier, I want to see when the forecast was last updated so that I know if I'm looking at today's conditions or stale data.
AI should know what you're talking about, what data sources are available, and how to make the change — all from the context file.
Step 5 — Save and sync
You know the drill:
Save my progress and sync it.
Team Activity: Before and After¶
Format: Team Discussion Time: ~3 minutes
Think about the difference between Run 2 (without a context file) and what you just experienced:
Discuss: - How much time did you spend in Run 2 re-explaining your project to AI? - How did it feel when AI "knew" your project in the fresh conversation? - What would you add to your context file now that you've tested it?
Your context file will keep evolving as your project grows. Any time you add a new data source, build a new feature, or make an important design decision, tell your AI assistant to update the context file to match. It takes seconds and saves minutes every conversation.
Key Insight¶
A project context file turns your AI coding assistant from a stranger into a teammate who always shows up prepared. Write it once, keep it short, and point to your documentation instead of duplicating it. In Run 3, you'll see the difference — with context in place, you can focus on building ambitious new features instead of re-explaining what you've already done. Every conversation picks up where the last one should have left off.