Plan it first. Build it second.

This video teaches you how to ship faster by planning before building. The key insight: agents produce dramatically better results when you give them rich context upfront rather than dribbling instructions over multiple messages.

The Core Principle: Context-First Prompting

Most people interact with AI agents like they’re chatting with a colleague — one message at a time, gradually revealing what they want. This approach wastes tokens and produces worse results.

Context-first prompting means: give the agent everything it needs in the first message. The who, what, why, and where. All the constraints, preferences, and background. Then let it work.

Why This Matters

Agents build a mental model from what you tell them. When you:

• Dribble context over time → The agent constantly has to revise its understanding, leading to wasted work and confusion
• Give everything upfront → The agent builds a coherent model immediately and executes with confidence

The difference in output quality is dramatic. A well-contexted agent produces code that matches your patterns, follows your conventions, and solves the actual problem — not some approximation of it.

Building Context Before Building Code

The Folder is Your Foundation

Before typing a single prompt, set up your folder structure:

1. Add relevant files — The agent can see and understand your existing code, tests, and documentation
2. Include reference examples — Show, don’t just tell, how you want things done
3. Attach external resources — API docs, design files, requirements documents

Every file in the folder becomes part of the agent’s working memory. Use this.

Writing the Context-Rich Prompt

A context-first prompt follows this structure:

**Goal**: [What you want to achieve]

**Background**: [Why this matters, business context, user needs]

**Current State**: [What's already done, what the agent will be working with]

**Constraints & Preferences**:
- [Technical constraints]
- [Style preferences]
- [Non-negotiable requirements]

**Reference Examples**: [Point to specific files showing patterns to follow]

**Success Criteria**: [How you'll know it's done right]

Example: Before and After

❌ Poor (context-dribbling)

> Add a button to the dashboard
> Actually make it blue
> And it should open a modal
> The modal should have a form
> Use the same pattern as the user settings page

✅ Good (context-first)

Add a "Generate Report" button to the analytics dashboard at
/src/pages/dashboard.tsx.

Follow the pattern used in /src/pages/settings.tsx for the
"Update Profile" button — same styling, same modal behavior.

The modal should contain a simple form with:
- Date range picker (use the existing DatePicker component)
- Report type dropdown (options: summary, detailed, export)
- Generate button that POSTs to /api/reports

Styling should match our design system — see /src/styles/components.md
for color tokens and spacing rules.

The feature is for marketing managers who need to pull weekly
performance data without engineering help.

Using Plan Mode for Complex Tasks

Plan Mode is the ultimate context-first tool. Instead of jumping straight to code, the agent:

1. Explores your codebase to understand existing patterns
2. Researches any gaps in its understanding
3. Builds a detailed plan of what it intends to do
4. Presents it to you for review before executing

This is powerful because:

• The planning phase fills the token window with rich context
• You can catch misunderstandings before they become code
• The resulting plan becomes a specification the agent follows

The Planning → Execution Flow

When you enter Plan Mode (press Shift+Tab until you see Plan in purple), here’s what happens:

1. Agent asks clarifying questions — Answer these to fill gaps in context
2. Agent explores your code — It reads relevant files, builds understanding
3. Agent creates a detailed plan — Step-by-step breakdown of what it will do
4. You review and refine — Approve, reject, or modify the plan
5. Agent executes — Now with full context, it writes the actual code

This flow consistently produces better results than going straight to execution.

When to Apply Context-First Prompting

Use this approach whenever:

Situation	Why context-first wins
New feature development	Agent needs to understand existing architecture and patterns
Refactoring	Agent must know why current code exists before changing it
Bug fixes	Full context prevents “fixing” symptoms instead of causes
Working with APIs	Agent needs schema, auth patterns, rate limits upfront
Multi-file changes	Coherent plan prevents inconsistencies across files
Learning a new codebase	Planning phase lets agent map the terrain

Practical Tips for Richer Context

1. Create an agent.md File

For projects you work on repeatedly, create an agent.md file in your folder:

# Project Context

## Tech Stack
- Next.js 14 with App Router
- TypeScript (strict mode)
- Tailwind CSS for styling
- Prisma ORM with PostgreSQL

## Code Patterns
- Use server actions for mutations
- Prefer async/await over .then()
- Error handling: always log, then throw user-friendly messages

## File Organization
- Components: /src/components
- Server actions: /src/actions
- Types: /src/types

## Design References
- See /docs/design-system.md for components
- Color palette: use CSS variables from globals.css

The agent automatically reads this and applies the patterns throughout its work.

2. Reference Specific Files

Instead of describing patterns, point to them:

Follow the authentication pattern in /src/lib/auth.ts —
specifically the `requireAuth()` function and how it handles
session validation.

3. Include Error Cases

Don’t just describe the happy path:

When the API returns a 429 (rate limited), show a toast notification
and disable the submit button for 5 seconds. See the error handling
pattern in /src/components/ApiForm.tsx.

4. State Your Non-Goals

Clarify what’s out of scope to prevent over-engineering:

This is a temporary admin tool for internal use only. Don't worry
about mobile responsiveness or advanced error recovery for this
first version.

Key Takeaways

• Context-first beats conversation — Give everything upfront rather than dribbling it over multiple messages
• Your folder is your prompt — Add files, docs, and examples before you start typing
• Plan Mode is your friend — Use it for anything non-trivial; the planning phase builds critical context
• Reference beats description — Point to existing code rather than describing patterns
• Clear constraints produce clear code — State what you don’t want, not just what you do

The agents you use are only as good as the context you provide. Invest in building that context first, and you’ll ship better code, faster.

---

Next: Plan Mode: Think Before You Act