Documentation for AI Code Agents

You're using Cursor or GitHub Copilot. You ask it to add a feature. It generates code that looks reasonable—but uses patterns your codebase doesn't follow, calls functions that don't exist, and ignores your established architecture.

You spend the next twenty minutes fixing the AI's output. At some point you wonder if you should have just written it yourself.

This is the context problem. AI coding assistants are powerful, but they're working blind. They see the file you're editing, maybe a few related files, but they don't understand your codebase as a whole. They don't know your patterns, your conventions, or your architecture.

Give them that context, and everything changes.

Why AI Assistants Hallucinate

When you ask an AI to write code, it draws on its training data—millions of codebases, Stack Overflow answers, documentation sites. It knows how code generally works.

But it doesn't know how your code works.

So it guesses. It generates code that would work in a generic codebase. Sometimes that matches your patterns. Often it doesn't.

The AI suggests a React class component. Your codebase uses only functional components with hooks.

The AI imports from @/utils. Your codebase uses ~/lib.

The AI creates a new service. Your codebase has an established pattern for services it didn't follow.

These aren't AI failures—they're context failures. The AI doesn't have the information it needs to make good suggestions.

The Context Solution

Modern AI coding tools support context files—documentation you provide that tells the AI about your specific codebase. Cursor uses .cursorrules. GitHub Copilot reads from designated documentation. Claude looks for context in your project files.

When these context files exist and are good, AI suggestions improve dramatically. The AI stops guessing and starts following your actual patterns.

The problem: writing and maintaining these context files is tedious. Most developers don't do it. So most developers get generic AI suggestions.

What AI Context Files Look Like

Code Summary generates context files specifically designed for AI coding assistants. Here's what they contain:

Project Overview:

# Project Context for AI Assistants

## Project Type
E-commerce backend API built with Node.js, Express, and TypeScript.

## Architecture Summary
- Monorepo with services in `packages/`
- Shared utilities in `packages/common/`
- API gateway in `packages/gateway/`
- Each service has its own database

## Key Technologies
- Runtime: Node.js 20
- Framework: Express with TypeScript
- Database: PostgreSQL with Prisma ORM
- Queue: BullMQ with Redis
- Testing: Jest with Supertest

## Directory Conventions
- `src/routes/` - Express route definitions
- `src/handlers/` - Request handlers (thin, delegate to services)
- `src/services/` - Business logic
- `src/repositories/` - Database access via Prisma
- `src/types/` - TypeScript interfaces and types

Code Patterns:

# Code Patterns

## File Naming
- Use kebab-case: `order-service.ts`, `user-repository.ts`
- Test files: `*.test.ts` next to source files
- Types: `*.types.ts` for shared interfaces

## Function Style
- Use arrow functions for handlers and callbacks
- Use regular functions for service methods
- Always use async/await, never raw Promises
- Return early for guard clauses

## Error Handling
```typescript
// Use Result type for expected failures
type Result<T> = { ok: true; value: T } | { ok: false; error: AppError };

// Throw only for unexpected failures
if (!user) {
  return { ok: false, error: new NotFoundError('User not found') };
}

API Response Format

// Success
{ success: true, data: { ... } }

// Error
{ success: false, error: { code: 'NOT_FOUND', message: '...' } }

Database Queries

Always use Prisma, never raw SQL
Use transactions for multi-step operations
Include only needed fields with select

**Common Tasks:**

```markdown
# Common Development Tasks

## Adding a New API Endpoint

1. Define route in `src/routes/index.ts`:
```typescript
router.post('/orders', validateBody(CreateOrderSchema), orderHandlers.create);

Create handler in src/handlers/order-handlers.ts:

export const create = async (req: Request, res: Response) => {
  const result = await orderService.createOrder(req.body);
  if (!result.ok) return sendError(res, result.error);
  return sendSuccess(res, result.value, 201);
};

Implement service method in src/services/order-service.ts
Add repository method if new DB access needed
Write tests in src/handlers/order-handlers.test.ts

Adding a Database Field

Update Prisma schema in prisma/schema.prisma
Run pnpm prisma migrate dev --name add_field_name
Update TypeScript types if not auto-generated
Update relevant services and repositories

Creating a Background Job

Define job in src/jobs/:

export const processOrderJob = async (job: Job<OrderJobData>) => {
  const { orderId } = job.data;
  // job logic
};

Register in src/jobs/index.ts
Queue jobs via jobQueue.add('processOrder', { orderId })

**Architecture Context:**

```markdown
# Architecture Context

## Service Communication
- Gateway handles auth, routes to services
- Services communicate via HTTP internally
- Async operations use BullMQ job queues
- No direct service-to-service database access

## Authentication Flow
1. Client sends credentials to `/auth/login`
2. Gateway validates, returns JWT
3. Subsequent requests include JWT in Authorization header
4. Gateway validates JWT, adds user context to request
5. Services receive authenticated requests with user data

## Data Ownership
- User Service: users, profiles, preferences
- Order Service: orders, order_items, order_history
- Product Service: products, categories, inventory
- Payment Service: payments, refunds (Stripe integration)

## Event Patterns
- Services publish events for cross-cutting concerns
- Events follow pattern: `{service}.{entity}.{action}`
- Examples: `orders.order.created`, `payments.payment.failed`

These files give AI assistants the context they need. Instead of guessing, they follow your actual patterns.

The Difference Context Makes

Without context:

You: "Add an endpoint to get order history for a user"

AI generates code that:

Uses a different folder structure
Creates raw SQL queries instead of Prisma
Returns data in a different format
Doesn't follow your error handling pattern

You spend 15 minutes fixing it.

With context:

You: "Add an endpoint to get order history for a user"

AI generates code that:

Creates files in the right locations
Uses Prisma with your established patterns
Returns data in your standard format
Handles errors using your Result type

You review, make minor tweaks, and merge.

The difference isn't AI capability—it's AI information. Same model, dramatically different results.

Automatic Context Generation

Writing context files by hand is work nobody does. It's one more documentation task that gets deprioritized indefinitely.

Code Summary generates these context files automatically. It analyzes your codebase, identifies patterns, and creates documentation specifically structured for AI consumption.

When your codebase changes, the context files update. Your AI assistant always has current information about how your code actually works.

Get Started

Your AI coding assistant is working with one hand tied behind its back. Give it the context it needs.

Install on GitHub

Connect your repositories, and AI context files generate automatically. Your next Cursor session or Copilot suggestion will understand your codebase, not just code in general.