PM Context Layer: A Practical Guide
Overview
I decided to try and build the thing I actually needed as a PM Lead who oversees a wide range of projects/products, and mentors team members around their own products/features. This is a structured context system for product managers working with AI assistants like Claude, ChatGPT, or similar tools. The system organizes project information into layered files that both you and AI tools can efficiently access.
The fundamental problem: AI tools need context to be useful, but context lives in your head, not in your tools. Decisions happen in Slack threads, thoughts you didn't write down, the "why" behind choices—this context gets stripped away when using traditional tools like Notion, Linear, or Confluence. You can't automate context away. Only you can provide it by capturing how you think and work.
The approach: Think of your day and your brain as a folder structure. This system organizes that thinking into files that serve as your project's memory. It requires a recurring investment (15 minutes to set up, 5-10 minutes daily to maintain), but that investment pays off: AI gets the context it needs to be genuinely helpful, and you get a lightweight system for managing multiple projects.
This system supports your workflow—it doesn't replace it. You still use Notion, Slack, and Linear. This captures the context layer that sits above those tools.
Why This Matters
Context is the fundamental problem with AI tools. Every AI assistant needs context, but context doesn't naturally live in documents. It lives in how you think about problems, the trade-offs you considered, the decisions you made and why.
Traditional PM tools strip context away. A Slack thread captures a decision but not the full reasoning. A Linear ticket shows what to build but not why. A Notion page documents status but not the thinking behind it.
You have to train how you think, not just document what you did. AI can't solve context for you—only you can provide it. Without spending time to structure how you interact and think about your projects, AI will never have what it needs to help effectively.
This system organizes your thinking. The folder structure is a mental model: quick context lives in one place, detailed architecture in another, decisions with their full reasoning in another. Everything has a place. AI loads what it needs when it needs it. You reference what matters when switching contexts.
It's structured moving forward, not arbitrary. Once set up, maintaining context becomes part of your workflow, not a separate documentation task you avoid.
File Structure
project-root/
├── .claude/
│ ├── context.md # Project dashboard (always current)
│ ├── ARCHITECTURE.md # Technical details
│ ├── ROADMAP.md # Timeline and phases
│ ├── DECISIONS.md # Key decisions log
│ └── TEAM.md # Contacts and roles
├── src/ # Your source code
└── docs/ # Detailed documentation
What Each File Does
File | Purpose | When to Update |
|---|---|---|
Project dashboard with TL;DR, current focus, top risks, and key files. Keep under 300 lines. | Weekly (5-10 min) or when focus changes | |
Technical implementation details: tech stack, system architecture, API integrations, data flow. | When architecture changes or tech decisions are made | |
Project timeline, phases, milestones, dependencies, success metrics. Single source of truth for schedule. | When timeline shifts or milestones change | |
Decision log with full context: what you decided, why, alternatives considered, trade-offs. | When making key decisions (document as you go) | |
Key contacts, stakeholders, external resources, related projects. | When team members or stakeholders change |
Start with context.md only. Add other files as your project needs them. Not every project needs all five files.
Getting Started
Initial Setup (15 minutes)
Step 1: Create the folder structure
cd your-project-directory
mkdir .claude
Step 2: Copy the context.md template
Download: templates/context-template.md
Copy to: .claude/context.md
Step 3: Fill in the required sections (15 minutes first time)
TL;DR: Project summary in 20 lines or less
What: Brief description
Why: Problem you're solving
Tech: Core stack only
Timeline: Key dates
Status: Current phase
Risk: Top 1-2 risks
Current Focus: What you're working on this week
Quick Reference: Links to other detail files (if you have them)
Key Files: 3-5 most important files in your codebase
Step 4: Test with your AI assistant
"Load [project-name] context"
The AI should be able to read your context.md and understand your project.
Step 5: Add detail files as needed (optional)
Working with engineers on technical decisions? → Add ARCHITECTURE.md
Managing a timeline with stakeholders? → Add ROADMAP.md
Making important architectural choices? → Add DECISIONS.md
Multiple stakeholders across teams? → Add TEAM.md
Setup Checklist
Create .claude/ folder in project directory
Copy and fill in context.md template (15 min)
Test loading context with AI assistant
Add ARCHITECTURE.md if project has technical complexity
Add ROADMAP.md if managing timeline/milestones
Add DECISIONS.md if making architectural decisions
Add TEAM.md if multiple stakeholders involved
Templates
All templates are ready to copy and customize. Each includes comments showing what to fill in and example content based on real projects.
Available Templates (sample structure)
context-template.md - Project dashboard (required)
ARCHITECTURE-template.md - Technical details (optional)
ROADMAP-template.md - Timeline and phases (optional)
DECISIONS-template.md - Decision log (optional)
TEAM-template.md - Contacts and resources (optional)
Each template uses this format:
Markdown ready to copy
<!-- Comments like this --> showing what to fill in
Example content from Hazel projects as reference
Sections you can keep, modify, or remove
Workflow Guide
Daily: Loading Context
When starting work on a project:
You: "Load [project-name] context"
AI: [Reads .claude/context.md]
When you need detailed information:
You: "Load architecture details"
AI: [Reads .claude/ARCHITECTURE.md]
You: "Load roadmap"
AI: [Reads .claude/ROADMAP.md]
You: "What was the decision on [X]?"
AI: [Reads .claude/DECISIONS.md]
When switching projects:
You: "Switch to [other-project-name]"
AI: [Loads that project's context.md]
Weekly: Maintaining Context (5-10 minutes)
Update context.md every week with:
Current Focus: What you're working on this wee
Blockers: Any issues preventing progress
Top Risks: What could derail the project
Status: Current phase or milestone
Update other files as needed:
Made a key decision? → Log it in DECISIONS.md immediately
Timeline changed? → Update ROADMAP.md
Tech stack changed? → Update ARCHITECTURE.md
New stakeholder? → Update TEAM.md
When to Update Each File
File | Update Trigger | Time Required |
|---|---|---|
Weekly, or when focus changes | 5-10 min | |
Tech decisions, new integrations, architecture changes | 10-15 min | |
Timeline shifts, milestone changes, new phases | 10 min | |
Making key decisions (document as you go, not retroactively) | 5 min per decision | |
Team changes, new stakeholders, new external resources | 5 min |
Best Practices
Keep context.md Lightweight
Target: 200-300 lines maximum
TL;DR section: 20 lines or less
Current Focus: 5-10 bullet points
Link to detailed files instead of including everything
Document Decisions as You Make Them
Don't document retroactively (you'll forget the reasoning)
Template: Context → Decision → Rationale → Alternatives → Consequences
Include enough detail that someone reading 6 months later understands why
Use Consistent Formatting Across Projects
All projects use the same file names (.claude/context.md, not project-context.md)
All projects use the same section headers in context.md
This builds muscle memory for you and patterns for AI
Link Between Files
Reference specific sections: "See DECISIONS.md:42" or "See ARCHITECTURE.md:Authentication"
Link to external resources: "See API Docs"
Cross-reference related decisions or technical details
Update Current Focus Weekly
Set a recurring calendar reminder
Do it Friday afternoon or Monday morning
Takes 5 minutes, keeps everything current
Don't Over-Document
Document what matters, not everything
If a detail lives in your codebase or Notion, link to it
Context files capture what doesn't naturally live anywhere else
FAQ
"How long does setup actually take?"
First project: 15 minutes (learning the system) Additional projects: 5 minutes (just fill in the template) Weekly maintenance: 5-10 minutes
"Do I need all 5 files?"
No. Start with context.md only. Add others as your project needs them:
Small project, solo work → context.md only
Technical project with engineers → Add ARCHITECTURE.md
Multi-phase project with timeline → Add ROADMAP.md
Complex decisions with trade-offs → Add DECISIONS.md
Multiple teams/stakeholders → Add TEAM.md
"What if my project doesn't have architecture or technical complexity?"
Skip ARCHITECTURE.md. Not every project needs every file. Use what's useful.
"How do I update an existing project that already has documentation?"
Create .claude/ folder
Fill in context.md with current status (don't migrate everything)
Link to existing docs in the "Quick Reference" section
Over time, migrate key decisions/architecture if it's useful
"What AI tools work with this system?"
Any AI assistant that can read files:
Claude (desktop app or web)
ChatGPT (with file upload or custom GPTs)
Gemini (with file context)
GitHub Copilot Chat
Other AI coding assistants
The structured format makes any AI more effective.
"Won't this just become another abandoned documentation system?"
This stays current because:
It's lightweight (5-10 min/week)
It's immediately useful (you use it to switch contexts, AI uses it to help)
It's tied to your daily workflow (you reference it constantly)
It forces prioritization (only document what matters)
Traditional docs go stale because they're heavy, not tied to workflow, and nobody reads them.
"Do I need to use the .claude/ folder name specifically?"
No, but it's recommended for consistency. Some AI tools automatically recognize .claude/context.md as project context. You can use any folder name, but keep it consistent across projects.
Each project gets its own .claude/ folder. In context.md, link to related projects:
## Related Projects
"What if my team doesn't want to maintain this?"
Start with just your projects. Demonstrate the value:
Faster context switching
Better AI assistance
Less time explaining project status
Once others see it working, they'll adopt it. Don't force it org-wide until you have examples of success.
"Can I use this for non-software projects?"
Yes. The system works for any project with complexity:
Marketing campaigns (context.md = campaign brief, ROADMAP.md = launch timeline)
Operations projects (ARCHITECTURE.md = process flow, DECISIONS.md = policy decisions)
Research projects (context.md = research question, ROADMAP.md = research phases)
Adapt the templates to your domain.
Next Steps
Pick one active project to start with
Create .claude/context.md using the template (15 min)
Use it with your AI assistant for 1 week
Observe the difference in context switching and AI helpfulness
Roll out to other projects once you see the value
Be honest about the trade-off: This requires a recurring investment of time. It's not automated, it's not effortless. But the investment pays off in better AI assistance, faster context switching, and knowledge that actually stays current.
Questions or Feedback
This is a living system. As you use it, you'll discover what works and what doesn't. Adapt the templates to your needs. The structure matters more than the specific format.
If you find improvements or have questions, document them and share with me!
