I’ve written before about how I use AI for product work and how that workflow evolved with slash commands and skills. This post focuses on how to maintain context for complex, long-running projects.
The Problem: Context Fragmentation
When I’m working on a major initiative, relevant information ends up scattered everywhere: PRDs in one tool, tickets in another, meeting notes in a third, plus emails and chat threads. Every time I return to a project after a few days, I spend time reconstructing where things stand.
AI assistants can make this worse because each conversation starts fresh. I can reference files, but the model doesn’t know which files matter for this project, what decisions we’ve already made, or what questions remain open. I end up re-explaining context that should be obvious.
Project brains solve this by creating a dedicated folder for each major initiative with a standard structure that both humans and AI can navigate.
What a Project Brain Looks Like
The structure looks like this:
projects/[project-name]/
├── CONTEXT.md # The hub: status, stakeholders, decisions, open questions
├── artifacts/ # PRDs, specs, designs, one-pagers
├── decisions/ # Decision logs with rationale and alternatives
├── research/ # Customer feedback, data analysis, technical investigation
└── meetings/ # Meeting notes related to this project
The CONTEXT.md file is a living document that answers the questions I’d need to answer every time I pick up a project:
- What’s the current status?
- Who are the stakeholders and what do they care about?
- What decisions have we made and why?
- What questions are still open?
- Where are the relevant artifacts?
When I start a conversation about a project, I point the AI to the project folder. It reads CONTEXT.md first, then can drill into specific artifacts as needed. The model immediately knows the project state without me explaining it.
A Real Example
Say I’m working on adding observability to an internal platform—something that needs coordination across multiple teams over several months. The CONTEXT.md includes:
- Quick reference table: Status, PM, engineering lead, target dates, links to the PRD and relevant tickets. Everything I’d need to orient myself.
- Problem statement: A clear articulation of the user pain. In this case: “Platform incidents go undetected until users report them, and debugging takes hours due to lack of visibility.”
- Success metrics with baselines and targets: Things like uptime targets, reduction in mean time to resolution, and alert accuracy. These anchor every conversation about scope.
- Key decisions made: A table showing what was decided, when, why, and what alternatives we considered. When someone asks “why aren’t we including component X in v1?”, the answer is already documented.
- Open questions: A checklist of unresolved issues. This prevents the AI from assuming things are settled when they’re not.
- Links: Direct paths to the PRD, spec, analysis docs, and related pages.
The decisions/ folder contains detailed decision logs for significant choices. The research/ folder holds whatever analysis informed the project direction. The meetings/ folder captures sync notes that would otherwise disappear into Gemini notes in a Google Drive… somewhere.
When to Create a Project Brain
Not every task needs this treatment. I create a project brain when:
- The work spans multiple weeks or months. Short-term tasks don’t need the overhead.
- Multiple stakeholders are involved. If I need to coordinate with other teams, having a single source of context helps.
- Decisions require documented rationale. If someone might ask “why did you do it this way?” later, a decision log is worth the investment.
- The project crosses team boundaries. Cross-functional initiatives benefit from dedicated context that doesn’t live in any one team’s space.
For simpler work, I use a flatter folder structure with documents organized by type. Project brains are for the complex initiatives where context fragmentation is a real cost.
How AI Uses Project Brains
The payoff comes when I’m working with AI on project-specific tasks. A few examples:
- Preparing for a meeting: “Read the CONTEXT.md in the [project] folder. I have a spec review meeting tomorrow. What are the open questions I should raise?”
- Drafting an update: “Based on the project context, draft a status update for leadership. Focus on progress since the start of the month and remaining blockers.”
- Decision analysis: “We need to decide whether to include [component] in scope. Read the research folder and the current CONTEXT.md. What would you recommend and why?”
The AI knows the project history, the stakeholders, the constraints. Its recommendations are grounded in documented context rather than generic best practices.
Maintaining the Project Brain
The value depends on keeping CONTEXT.md current. I’ve found a few practices help:
- Update after significant events. When a decision is made, a meeting happens, or the status changes, update the file immediately. “I’ll do it later” means it won’t happen. LLMs are great at making these updates, so you can simply say “update relevant files based on the session we just concluded.”
- Move open questions to resolved. When a question gets answered, don’t delete it. Mark it resolved and note the answer. This preserves the reasoning trail.
- Link, don’t duplicate. CONTEXT.md should point to artifacts, not contain them. Keep PRDs in the artifacts folder. Keep meeting notes in the meetings folder. The context file is a hub, not a repository.
Scaffolding New Projects
I have a slash command that scaffolds new project brains:
/new-project platform-observability
This creates the folder structure, generates a CONTEXT.md from a template, and fills out a rough draft based on whatever context I provide. Removing the friction of setup means I’m more likely to actually use the system. You can view the command here.
The template includes the standard sections (Quick Reference, Problem Statement, Success Metrics, etc.) with placeholder text. I fill in what I know and mark other sections as TBD. Even an incomplete project brain is more useful than scattered notes.
What I’ve Learned
A few observations from using this approach:
- Structure beats volume. A well-organized project brain with sparse content is more useful than a folder full of undifferentiated documents. The AI (and future me) can navigate structure. It can’t navigate chaos.
- Decision logs compound. Every decision I document now saves time later. When stakeholders ask “why didn’t we do X?”, I can point to a decision log instead of reconstructing my reasoning from memory.
- CONTEXT.md is for humans too. I originally built this for AI assistance, but I reference these files constantly in my own work. The discipline of maintaining project context helps me stay oriented, not just the AI.
- The folder structure is flexible. Some projects need more subfolders (like
research/customer-interviews/). Some need fewer. The template is a starting point, not a requirement.
This approach requires discipline to maintain, and the upfront setup takes time. But for complex initiatives where context fragmentation is a real problem, project brains have been worth the investment. The AI becomes a more useful collaborator when it has access to the same context I do.
I’m still iterating on the structure. I suspect the template will look different six months from now as I learn what sections actually get used and which ones I skip every time. The point isn’t to get the folder structure perfect, but to stop losing context between conversations and start building on what you already know.