The 3-File Context Kit: Everything Your AI Needs to Understand Your Project

Every time you start a new AI coding session, you re-explain your project. The stack, the conventions, the folder structure, the gotchas. It takes 10 minutes. Every. Single. Time.

Here's how I fixed it with three files that take 15 minutes to set up once.

The Problem

AI assistants have no memory between sessions. Each conversation starts from zero. So you either:

1. Dump your entire codebase (wasteful, confusing)
2. Re-explain everything each time (tedious, inconsistent)
3. Just wing it and hope for the best (chaotic)

None of these work well. Option 3 is why your AI keeps suggesting Express when you use Fastify.

The 3-File Kit

File 1: PROJECT.md — The Identity Card

This tells the AI what your project is. Keep it under 50 lines.

# Project: invoice-api

## Stack
- Runtime: Node.js 22 + TypeScript 5.4
- Framework: Fastify
- Database: PostgreSQL 16 via Drizzle ORM
- Auth: JWT (access + refresh tokens)
- Testing: Vitest

## Structure
src/
  routes/       # Fastify route handlers
  services/     # Business logic
  db/           # Drizzle schema + migrations
  middleware/   # Auth, validation, logging
  types/        # Shared TypeScript types

## Conventions
- Errors: throw HttpError (from src/errors.ts), don't return error objects
- Logging: use req.log (Pino), never console.log
- IDs: UUIDv7 (time-sortable)
- Dates: always UTC, stored as timestamptz

File 2: PATTERNS.md — The Style Guide

This tells the AI how you write code. Include real examples from your codebase.

# Code Patterns

## Route Handler
Always use schema validation. Always return typed responses.

// GOOD:
app.post('/invoices', {
  schema: { body: CreateInvoiceSchema, response: { 201: InvoiceSchema } },
  handler: async (req, reply) => {
    const invoice = await invoiceService.create(req.body);
    return reply.code(201).send(invoice);
  }
});

## Service Layer
Services take plain objects, return plain objects. No Fastify types.

## Error Handling
throw new HttpError(404, 'Invoice not found');
// NOT: return { error: 'not found' }

## Tests
One describe block per function. Use factories for test data.

File 3: BOUNDARIES.md — The Guardrails

This tells the AI what not to do. This file prevents the most common AI mistakes.

# Boundaries

## Don't
- Don't add dependencies without asking
- Don't use classes unless the existing code uses classes
- Don't create abstractions for single-use code
- Don't change the database schema without explicit instruction
- Don't use console.log (use req.log or the logger from src/logger.ts)
- Don't add try/catch in route handlers (the error middleware handles it)

## When Unsure
- Ask before changing folder structure
- Ask before adding new patterns not in PATTERNS.md
- If a task is ambiguous, list your assumptions before coding

How to Use Them

At the start of every AI session, paste all three files. That's it. Total context: ~150 lines, usually under 2K tokens.

Here's my project context:

[paste PROJECT.md]
[paste PATTERNS.md]
[paste BOUNDARIES.md]

Now, help me implement [your actual task].

Why This Works

1. Consistency: The AI follows the same conventions every time.
2. Less editing: Output matches your style from the first attempt.
3. Fewer hallucinations: Explicit boundaries prevent the AI from inventing patterns.
4. Onboarding: New team members can use the same files to get AI help that matches your codebase.

Maintenance

Update these files when you change conventions. I review mine monthly — it takes 5 minutes. The 15-minute setup pays for itself within two sessions.

---

What would you put in your context kit? I'm betting most projects need fewer than 100 lines of context to get dramatically better AI output.