Repo-Context Discipline

The Context Problem

AI coding assistants have limited context windows. Too little context means wrong answers. Too much context means lost focus.

The Goldilocks Zone

What to Include

Always Include

1. The file you're modifying

   • Full content if small
   • Relevant sections if large

2. Direct dependencies

   • Imported types/interfaces
   • Called functions
   • Used components

3. Test files (when they exist)

   • Shows expected behavior
   • Reveals edge cases

Include When Relevant

• Config files - When changing behavior
• Schema files - When touching data structures
• API contracts - When changing endpoints

Rarely Include

• package.json - Unless dependency-related
• Lock files - Almost never
• Build configs - Only for build issues

Context Gathering Patterns

Pattern 1: The Focused View

For small, targeted changes:

markdown
Copy
## Context
File: src/utils/format.ts (full file below)
Related: Uses types from src/types/common.ts

## Task
Add a formatPhoneNumber function

Pattern 2: The Interface View

For changes that span multiple files:

markdown
Copy
## Public Interfaces
From src/types/user.ts:
- User interface (lines 1-15)
- UserRole enum (lines 17-22)

From src/api/users.ts:
- createUser function signature (line 45)
- updateUser function signature (line 78)

## Task
Add email validation to both functions

Pattern 3: The Trace View

For debugging issues:

markdown
Copy
## Call Stack
1. src/pages/login.tsx calls
2. src/api/auth.ts:login() which calls
3. src/lib/session.ts:createSession()

## Error occurs in step 3

## Relevant code
[paste just the createSession function]

Building Context Incrementally

Start small, add as needed:

1. Initial prompt - Just the immediate file
2. If AI asks - Add what it requests
3. If AI is wrong - Add missing context
4. If AI is slow - Trim unnecessary parts

Project-Level Context Files

AGENTS.md

Persistent context that applies to every conversation:

markdown
Copy
# AGENTS.md

## Tech Stack
- Next.js 15 with App Router
- TypeScript strict mode
- Tailwind CSS

## Patterns
- Use server components by default
- Client components only when needed
- Colocate tests with source

## Constraints
- No any types
- No console.log in production
- All functions need JSDoc

.cursorrules

For Cursor users, similar purpose:

markdown
Copy
You are working in a Next.js 15 project.
- Use TypeScript strict mode
- Prefer server components
- Follow existing patterns in src/

Dynamic Context Loading

For large codebases, load context programmatically:

typescript
Copy
// Get relevant context for a file
function getContextFor(file: string): string[] {
  const imports = extractImports(file);
  const tests = findTestFile(file);
  const types = imports.filter(isTypeImport);

  return [file, ...types, tests].filter(Boolean);
}

Signs of Context Problems

Too Little Context

• AI invents function names that don't exist
• Suggests patterns inconsistent with codebase
• Asks many clarifying questions

Too Much Context

• Responses are slow
• AI references irrelevant parts
• Suggestions conflict with different parts

Context Refresh

When to clear context and start fresh:

• Switching to unrelated task
• AI is clearly confused
• Context has drifted from current state

Verification

Your context is well-managed if:

• AI responses reference your actual code
• Suggestions match project patterns
• Responses come in reasonable time
• Minimal clarifying questions needed