Coding agents waste 20 minutes exploring your codebase every session

Your coding agent reads your entire codebase every time it starts a new task. That's 50,000 tokens of context before it writes a single line of code.

The fix isn't a bigger context window. It's a 5-minute setup that pre-seeds your agent with exactly what it needs to know.

The Problem: Cold Start Waste

Every coding session starts the same way. Your agent asks to "explore the codebase structure." It reads package.json, scans directories, opens random files to "understand the patterns." Twenty minutes and $3 in API calls later, it finally starts coding.

This happens because your agent has no persistent understanding of your project. Every conversation is day one.

The Solution: Context Seeding Files

Create four files in your project root that your agent reads on startup:

CODEBASE.md      # Architecture overview, key patterns
FILES.md         # Important files and their purposes  
CONVENTIONS.md   # Code style, naming, structure rules
CONTEXT.md       # Current sprint, known issues, priorities

Your CODEBASE.md should be ruthlessly practical:

# Architecture
- Next.js app in /src
- API routes in /src/pages/api
- Components follow atomic design
- State management via Zustand

# Key Patterns
- All API calls go through /lib/api.ts
- Error handling uses ErrorBoundary wrapper
- Forms use react-hook-form + zod
- Database queries in /lib/db/queries

FILES.md eliminates the "where do I find..." dance:

# Critical Files
/lib/auth.ts - Authentication logic
/lib/db/schema.ts - Database schema
/components/ui/ - Reusable UI components
/utils/validation.ts - All zod schemas
/config/env.ts - Environment variables

The 5-Minute Setup

1. Create these four files in your project root
2. Spend 3 minutes documenting your actual architecture (not what you planned)
3. Add this to your agent's system prompt: "Always read CODEBASE.md, FILES.md, CONVENTIONS.md, and CONTEXT.md before starting any task"

Pro tip: Update CONTEXT.md weekly with current priorities. "Working on user dashboard redesign. Focus on mobile responsiveness. Known bug in Safari with date picker."

What Changes

Before: Agent spends 20 minutes exploring, asks where authentication is handled, rebuilds existing patterns.

After: Agent reads 400 words of context, immediately knows your architecture, starts coding in 30 seconds.

The best part? These files help human developers too. New team members read the same four files and understand your codebase structure immediately.

Your coding agent doesn't need to rediscover your architecture every conversation. Give it a map.