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 losing the thread between sessions costs me real time.

How AI Uses Project Brains

This earns its keep 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?”

By the time I’m working in it, the AI already knows the project’s history and the people involved, so its recommendations fit this specific situation instead of falling back on 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 Surprised Me

A well-organized project brain with sparse content beats a folder full of undifferentiated documents every time, because the AI (and future me) can work with structure far more easily than with a pile of files. The decision logs have paid off the most: when someone asks why we didn’t do something, I point to the log instead of reconstructing my reasoning from memory. And while I built this for the AI, I reference these files constantly myself. Staying on top of the context keeps me oriented too, not just the assistant. The structure stays flexible too. Some projects grow extra subfolders like research/customer-interviews/, others need fewer.

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. I’m not trying to get the folder structure perfect. I just want to stop losing context between conversations, so each time I come back to a project I can build on what I already know.

A quick post on LinkedIn about interviewing a candidate who used real-time AI got more engagement than is usual for me. And as often happens when something goes semi-viral, some folks took issue with what I said, so I want to expand on the point I was trying to make (it wasn’t that “AI is cheating”).

Here’s what I wrote:

I had my first experience interviewing a candidate who used real-time AI today. If you’re someone who uses AI daily, it’s so easy to spot. The pause before the answer, the constant eyes flicking to the other screen, the perfectly-manicured 3-point answer…

Friends, just don’t do this. It’s too easy to spot, and it will also set you up for failure, because it might get you a job that you’re not a good fit for, which is bad for everyone.

Use AI in your job, for sure. But don’t use it to get the job. The interview process is about you. Be you.

One response called this “absolutely myopic” (I had to double check I didn’t accidentally post on Hacker News) and asked why candidates shouldn’t use AI if it allows for “a better, more creative answer.” Another suggested that if candidates will use AI on the job anyway, then the “real you” isn’t going to be working, so what’s the difference?

Let’s dig into this.

What interviews are actually for

I don’t interview people to test whether they can produce a good answer to a question. I interview people to understand how they think, what they’ve actually done, and whether we’ll work well together.

When I ask “Tell me about a time you had to make a difficult prioritization decision,” I’m not looking for the theoretically optimal framework. I want to hear your story. The messy details and the trade-offs you wrestled with. The thing you got wrong and what you learned from it. AI can’t give me that. It can only give me a polished summary of what prioritization frameworks exist.

One commenter put it well: “It’s about both the company and the individual, so you will often talk about their real experience, what they did, how they felt, what did they learn, digging deeper into their real experience to find out the interesting things that could make them a good match.”

AI might help you phrase things more clearly. But if it’s generating your answers, you’re hiding the very thing I’m trying to evaluate.

The fit problem

Here’s the part that didn’t seem to land: using AI to get a job you’re not qualified for is bad for you.

Let’s say the AI-assisted interview works. You get hired. Now what? You show up on day one, and the expectations are set based on how you performed in those interviews. But that wasn’t you. That was a performance enhanced by a tool you won’t have in the same way during actual work conversations, whiteboard sessions, and quick chat exchanges where people expect you to just… know things.

I’ve seen what happens when there’s a mismatch between interview performance and actual capability. It’s not a fun experience for anyone, least of all the person who’s now struggling in a role they weren’t ready for. One person called it “artificial buzzword ventriloquism” in the comments. Harsh, but not wrong.

It’s about context, not absolutes

A few commenters suggested that interviews should evolve to assume AI assistance, since that’s how people will actually work. One person wrote: “By prohibiting AI during interviews, the interview environment diverges from actual job conditions and fails to evaluate a critical skill: the ability to effectively use one of the most powerful productivity tools available today.”

I think there’s something to this. In fact, our interview process includes a take-home assessment where we explicitly encourage candidates to use AI. We want to see how they approach a problem, how they structure their thinking, and yes, how they use modern tools to get to a good answer. That’s a legitimate skill worth evaluating.

But that’s different from what happened in my interview, where someone was clearly trying to hide their AI usage while answering questions about their past experience. That’s not “using AI as a tool.” That’s using AI as a mask.

---

I think candidates should absolutely use AI to prepare for interviews: research the company, practice answering common questions, refine their resume.

But in the interview itself, when I’m asking about your experience and your thinking, I need to hear from you. Not because AI is cheating, but because the whole point is to figure out if you are the right fit for this role and this team. If I can’t evaluate that, we can’t make a good hiring decision. And that’s bad for both of us.

This is the hands-on companion to How I Use AI for Product Work and How My AI Product Second Brain Evolved. Those posts explain the philosophy; this one gets you to a working OpenCode setup in 30 minutes.

By the end, you’ll have a folder structure, three working slash commands, and a context file that makes the AI useful.

Prerequisites

You’ll need OpenCode installed and configured. Follow the installation guide to get started. If you can run opencode in your terminal and get a response, you’re ready.

Step 1: Create the Folder Structure

Create a new directory for your product second brain. I recommend keeping it in a git repo so you can version your prompts over time.

mkdir -p product-ai/{context,prompts/pm,.opencode/command}
cd product-ai
git init

Your structure should look like this:

product-ai/
├── .opencode/
│   └── command/       # Slash commands live here
├── context/           # Personal context files
├── prompts/
│   └── pm/            # PM-specific prompts
├── AGENTS.md          # Instructions for OpenCode
└── opencode.jsonc     # OpenCode config

Step 2: Create Your Context File

The context file tells the AI who you are and how you work. Create context/about-me.md:

# About Me

## Role
[Your title] at [Company], working on [your area].

## What I Care About
- [Your product philosophy, e.g., "Start with the problem, not the solution"]
- [Your working style, e.g., "Bias toward shipping and learning"]
- [Your communication preferences, e.g., "Direct feedback, no hedging"]

## Current Focus
- [Project or initiative 1]
- [Project or initiative 2]

Keep this updated as your focus changes. The more specific you are, the more useful the AI becomes.

Step 3: Create AGENTS.md

This file tells OpenCode how to behave in your repo. Create AGENTS.md in the root:

# Product AI Second Brain

Read this file before responding.

## Who I Am
Read `context/about-me.md` for personal context.

## Slash Commands
Run these by typing the command in OpenCode:

| Command | Purpose |
|---------|---------|
| `/prd` | Review a PRD |
| `/debate` | Stress-test a product idea |
| `/okr` | Review OKRs |

Step 4: Add Your First Commands

Slash commands are markdown files in .opencode/command/. Each command file is a thin wrapper that points to a full prompt file in prompts/pm/. This separation keeps commands simple while allowing prompts to be detailed and shareable.

Command 1: /debate (Stress-test an Idea)

Create .opencode/command/debate.md:

---
description: Stress-test a product idea with pro vs skeptic debate
---

# Product Debate

Read these files before proceeding:
- `prompts/pm/debate-product-idea.md` - **REQUIRED: Full debate framework**
- `context/about-me.md` - Your product beliefs and context

## Your Task

$ARGUMENTS

## Instructions

Then create the prompt file prompts/pm/debate-product-idea.md with your full debate methodology. The basic structure: define two personas (a Visionary who argues for the idea and a Skeptic who pokes holes), have them debate, then synthesize the strongest arguments from both sides.

Command 2: /okr (Review OKRs)

Create .opencode/command/okr.md:

---
description: Review OKRs for clarity and outcome-orientation
---

# OKR Review

Read these files before proceeding:
- `prompts/pm/review-okrs.md` - **REQUIRED: Full OKR review framework**
- `context/about-me.md` - Your product beliefs and context

## Your Task

$ARGUMENTS

## Instructions

Then create prompts/pm/review-okrs.md with your OKR criteria. Mine checks for outcome-orientation (are these outputs or outcomes?), measurability, and whether the key results actually ladder up to the objective.

Command 3: /prd (Review a PRD)

Create .opencode/command/prd.md:

---
description: Review a PRD for completeness and clarity
---

# PRD Review

Read these files before proceeding:
- `prompts/pm/review-prd.md` - **REQUIRED: Full PRD review framework**
- `context/about-me.md` - Your product beliefs and context

## Your Task

$ARGUMENTS

## Instructions

Then create prompts/pm/review-prd.md with your PRD review criteria.

Step 5: Try It Out

Navigate to your product-ai directory and run OpenCode:

cd product-ai
opencode

Test each command:

/debate Should we build a self-serve dashboard for customers to debug their own issues?

/okr [paste your OKRs here]

What’s Next

Once you’re comfortable with this setup, consider adding:

• More commands: /retro for retrospectives, /feedback for drafting colleague feedback
• Skills: Methodology files that OpenCode loads automatically based on context (see the skills documentation)
• Daily summaries: A /today command that summarizes what you worked on
• Project-specific context: Folders for major initiatives with their own context files

Start small and add complexity as you identify repeated workflows. If you find yourself doing the same thing more than twice, it’s probably worth automating.

If you build something useful on top of this, I’d love to hear about it!

A couple of weeks ago I wrote about how I use AI for product work: the basic setup of context files, prompts, and the @ mention system in Windsurf. Since then I’ve moved tools, added slash commands, and automated a few things, so here’s the update.

The philosophy has shifted. I still don’t use AI to do my core thinking. I write my own PRDs and strategy docs. But I’ve come to rely on it more as a helpful assistant for the work around the work: reviewing documents before I share them, researching technical questions, summarizing my week, preparing for meetings. These days it feels more like having a colleague on call.

From Windsurf to Claude Code / OpenCode

The biggest shift was moving from Windsurf to Claude Code, Anthropic’s terminal-based AI assistant. Claude Code runs in your terminal and has direct access to your filesystem, which changes how you can structure these workflows.

The key feature that made this worthwhile is slash commands. Instead of manually @-mentioning prompt files, I can type /ask-se and Claude Code automatically loads the right context, reads the relevant files, and knows how to respond. Small thing, but removing that friction is the difference between using these tools and just meaning to.

I also started using OpenCode, an open-source alternative that works similarly. Both tools read from the same instruction files, so I maintain one set of prompts that work in either environment.

Slash Commands

The prompts I described in the original post are now wrapped in slash commands. The files live in .claude/commands/ and look like this:

.claude/commands/
├── prd.md          # Review a PRD
├── okr.md          # Review OKRs
├── debate.md       # Stress-test a product idea
├── ask-se.md       # Research technical questions
├── briefing.md     # Calendar briefing
├── today.md        # End-of-day summary
├── weekly.md       # Weekly summary
└── ...

Each command file contains instructions for the AI, plus a $ARGUMENTS placeholder for any input I provide. When I run /debate should we build a developer portal?, Claude Code reads the debate prompt, substitutes my question for the placeholder, and runs through its process.

The commands I use most often:

• /prd. Reviews a PRD I’ve written and pushes back on vague problem statements, missing success metrics, or unclear scope. I run this before sharing drafts with stakeholders.
• /debate. Simulates a debate between an optimist and a skeptic about a product idea. This is probably the command I reach for most when I’m still forming an opinion about something.
• /ask-se. Helps me answer specific technical questions about our products. For example, today I ran /ask-se On Gateway HTTP Logpush jobs, what would trigger "unknown" as the action? The command uses MCP (Model Context Protocol) servers to search our public documentation and internal wiki, then synthesizes an answer I can actually use. It’s how I get product answers without interrupting engineers or digging through docs myself.

I don’t have to remember file paths or compose context any more. I type the command and start the conversation.

Skills: Persistent Methodology

Commands are things I invoke explicitly. Skills are methodology files that get applied automatically when they’re relevant.

I have three skills set up:

1. pm-thinking. Applies my product philosophy to any PM-related work. When I’m reviewing a PRD, it automatically checks for problem-first thinking, measurable outcomes, and clear non-goals.
2. cloudflare-context. Loads knowledge about Cloudflare’s products and triggers proactive use of internal data sources (more on this below).
3. data-team-context. Specific context about my team’s priorities, current initiatives, and constraints.

The skill files live in .claude/skills/ and contain triggers (when to apply) and behaviors (what to do). For example, the pm-thinking skill flags anti-patterns like “vague success metrics” or “jumping to solutions without understanding the problem.”

This means even when I’m not explicitly running a PM-focused command, the AI still knows to apply my methodology.

Daily and Weekly Summaries

One of the more useful additions is automated work journaling. At the end of the day, I run /today. The command:

1. Finds files I modified that day using filesystem timestamps
2. Reads the key files to understand what I actually worked on
3. Asks if there’s anything else to add
4. Generates a summary focused on outcomes, not tasks
5. Saves it to a structured folder: work/cloudflare/weeknotes/2025/01/week-01/2025-01-06.md

The output follows a consistent format:

# Tuesday, December 16, 2025

## Summary
Focused on Q1 planning and customer research. Clarified success
metrics for data quality initiative and documented common Logpush questions.

## What I Worked On
- **Q1 Planning:** Reviewed OKR drafts, identified gaps in success metrics
- **Customer Research:** Documented Logpush egress IP questions for support docs

Then on Friday (or Monday morning), I run /weekly. It reads all the daily notes for the week and synthesizes them into a summary I use to prep for 1:1s and status updates.

This works because I can never remember on Friday what I did on Tuesday. The daily notes capture the work while it’s fresh, and the weekly summary rolls it up into something useful.

Calendar Briefings

The most custom piece of this system is the calendar briefing. I got this idea from an interview with Webflow’s CPO on Claire Vo’s podcast, about building an AI chief of staff. Following her example I wrote a Python script that:

1. Connects to Google Calendar via OAuth
2. Fetches events for today, tomorrow, or the week
3. Generates a briefing that flags meetings that could be async, suggests prep work, and warns if the day is overloaded

I run /briefing tomorrow before wrapping up for the day. It gives me a head start on thinking about what’s coming and whether I need to prepare anything.

The briefing uses context from my about-me.md file, so it knows things like which recurring meetings are more important than others, and what kind of prep I typically need for different meeting types.

Syncing Between Tools

One wrinkle: Claude Code and OpenCode have slightly different formats for commands. Claude Code uses plain markdown; OpenCode expects frontmatter with a description field.

So I built a sync command. Running /sync-to-opencode compares the two folders and copies any changed commands, adding the frontmatter OpenCode needs. It means I can maintain one set of prompts (in .claude/commands/) and have them work in both tools.

Most people don’t need this. I switch between tools often enough that manual syncing got annoying.

What I’ve Learned Since the First Post

• Automation compounds. The daily notes feed the weekly summary, the skills carry across every conversation, and once the slash commands cut enough friction I actually started using the system instead of just thinking about using it.
• Custom workflows are basically one file now. With slash commands and skills, I can create tools that work exactly how I want to work. The /ask-se command knows my products, our customers, and the kinds of questions I typically need answered. The daily summary knows my file structure and my preferred format. I get to encode my workflow into a tool instead of adapting to whatever the tool prefers.
• Scripts fill the gaps. The calendar briefing couldn’t be a pure prompt because it needed to fetch data from an external API. Having a scripts/ folder for Python code that extends the system has been useful for anything that requires real I/O.
• Keep work output local. The prompts and context files live in a private git repo so I can sync them between machines and version them over time. But the actual work output, like weeknotes, briefings, and anything I’m working on, stays on my local machine, not in the repo. The AI helps me do the work, but the work itself doesn’t need to live in the cloud.

If you’re building something similar, I’d recommend starting with the basics from the first post: context files, opinionated prompts, and a tool that lets you compose them easily. The slash commands and automation came later, once I understood what workflows I actually used repeatedly.

The specific tooling matters less than the approach. Figure out where AI actually helps (reviewing your work, researching questions, reducing busywork) and build the smallest system that makes those things easy to do.