context-engineering

Context Engineering

Overview

Agent performance is determined by the quality of context provided, not just the quality of the model. Context engineering is the practice of structuring project information, task instructions, and session state so agents can do their best work. This applies whether you're writing a project guidance file, structuring a long conversation, or coordinating a multi-step development task.

When to Use

• Setting up a new project for agent-assisted development
• Agent is making mistakes that suggest missing context (wrong conventions, wrong tech stack)
• Writing or updating a project guidance file (CLAUDE.md, AGENTS.md, etc.)
• Planning a complex multi-step development session
• Agent keeps losing track of decisions made earlier in a session

The Context Hierarchy

Context sources (highest to lowest priority):
├── 1. Immediate message — what you just said
├── 2. Conversation history — this session's decisions
├── 3. Project guidance file — persistent project conventions
├── 4. Loaded skills — active behavioral protocols
└── 5. Training data — model's built-in knowledge

The first source wins when there's a conflict. Use this to override defaults: put critical constraints in the immediate message or project guidance file.

The Project Guidance File

Every project that uses agent-assisted development should have a guidance file. In Agent Zero, this is typically read via text_editor:read at the start of a session. Common names: CLAUDE.md, AGENTS.md, .cursorrules, GEMINI.md.

Guidance File Template

# Project: [Name]

## What This Is

One paragraph: what the project does, who it's for, and what problem it solves.

## Tech Stack

- **Runtime**: Node.js 20 + TypeScript 5
- **Framework**: Next.js 15 App Router
- **Database**: PostgreSQL + Prisma
- **Testing**: Vitest + Testing Library + Playwright
- **Styling**: Tailwind CSS
- **Deployment**: Vercel

## Development Commands

```bash
npm run dev          # Start dev server (localhost:3000)
npm test             # Run unit tests
npm run test:e2e     # Run Playwright E2E tests
npm run build        # Production build
npm run type-check   # TypeScript check
npm run lint         # ESLint

Code Conventions

• Components: Functional components, colocated tests in ComponentName.test.tsx
• API routes: In app/api/, use route.ts handlers
• Imports: Use @/ alias for src root
• Error handling: Throw domain errors (NotFoundError, ValidationError), catch in route handlers
• State: React Query for server state, useState for local UI state

Project Structure

app/
  (auth)/        # Auth routes
  api/           # API route handlers
  tasks/         # Task feature routes
src/
  components/    # Shared UI components
  lib/           # Utilities, DB client, auth helpers
  types/         # Shared TypeScript types
prisma/
  schema.prisma  # Database schema

Key Decisions

• Use Prisma (not raw SQL) for all DB access. For complex queries: prisma.$queryRaw.
• All API validation uses Zod schemas defined in src/lib/validation/
• Authentication via NextAuth.js with JWT sessions
• Feature flags managed via src/lib/flags.ts

What Not to Do

• Don't use any in TypeScript (use unknown + type guards)
• Don't bypass Zod validation at API boundaries
• Don't commit .env files (use .env.example as template)
• Don't use useEffect for data fetching (use React Query)