Context Engineering Guide

Prompt Engineering (crafting the email):
  "Write a React component that displays user
   profiles in a grid with Tailwind CSS..."

Context Engineering (building the briefing package):
  System instructions  → Your project conventions
  Codebase context     → Existing component patterns
  Dependencies         → React 19, Tailwind v4, TypeScript
  Architecture         → App Router, Server Components
  Git history          → Recent refactoring decisions
  Test patterns        → Vitest + Testing Library setup

  Then the prompt: "Add a user profile grid to the dashboard"

2023  Prompt Engineering
      → Carefully craft each individual prompt
      → Copy-paste instructions into every conversation
      → Results vary wildly between sessions

2025  Context Engineering
      → Configure persistent project context
      → AI automatically loads relevant conventions
      → Consistent results across every interaction

2026  Agentic Engineering
      → AI agents orchestrate multi-step workflows
      → Context files define roles, tools, and guardrails
      → Humans direct; agents execute with full context

Layer 1 — System Instructions (you control this)
  AGENTS.md, CLAUDE.md, .cursor/rules/, .windsurfrules,
  copilot-instructions.md, GEMINI.md
  → Project conventions, coding standards, architecture

Layer 2 — Codebase Context (you influence this)
  Files the agent can see or has indexed
  → Existing patterns, implementations, types

Layer 3 — Git History (you influence this)
  Recent commits, diffs, branch context
  → Prevents undoing intentional decisions

Layer 4 — Dependencies (you influence this)
  package.json, lock files, framework versions
  → Ensures compatible API usage

Layer 5 — Conversation History (tool-managed)
  The current chat session and prior messages
  → Maintains continuity within a task

Layer 6 — Retrieved Context (tool-managed)
  Documentation lookups, web search, RAG results
  → Supplements knowledge beyond training data

Layer 7 — Tool Outputs (tool-managed)
  Linter results, test output, build logs, terminal
  → Grounds the agent in real project state

Layer 8 — Auto-Memory (tool-managed)
  Learned patterns from corrections and feedback
  → Adapts over time without manual updates

Good Context:
  ✓ AI follows your naming conventions without reminders
  ✓ Generated code matches existing patterns in your codebase
  ✓ AI uses the correct framework APIs and versions
  ✓ Tests follow your project's testing patterns
  ✓ Imports use your project's path aliases

Poor Context:
  ✗ AI generates generic code that doesn't match your style
  ✗ Every conversation requires re-explaining your stack
  ✗ AI uses deprecated APIs or wrong framework versions
  ✗ Generated patterns conflict with existing architecture
  ✗ You constantly correct the same mistakes

Tool              Config File                  Location
─────────────     ──────────────────────────   ──────────────────────────
Cross-tool        AGENTS.md                    Project root (+ subdirs)
Claude Code       CLAUDE.md                    ~/, project root, subdirs
Cursor            .cursor/rules/*.mdc          .cursor/rules/
GitHub Copilot    copilot-instructions.md      .github/
Windsurf          .windsurfrules               Project root
Gemini CLI        GEMINI.md                    ~/, project root, subdirs

# AGENTS.md

## Project Overview
E-commerce platform built with Next.js 15, TypeScript,
Prisma ORM, and Stripe for payments.

## Build & Run
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`
- Tests: `pnpm test` (Vitest)

## Architecture
- `src/app/` — Next.js App Router pages and layouts
- `src/components/` — Shared React components
- `src/lib/` — Utilities, database client, API helpers
- `src/actions/` — Server Actions for mutations
- `prisma/` — Database schema and migrations

## Code Style
- Use TypeScript strict mode. Never use `any`.
- Prefer Server Components. Use `"use client"` only when
  the component needs browser APIs or event handlers.
- Use named exports for components and functions.
- Use Tailwind CSS v4 for styling. No CSS-in-JS.

## Testing
- Write tests for all new features and bug fixes.
- Use Vitest + Testing Library for component tests.
- Place test files adjacent to source: `*.test.ts(x)`.

# CLAUDE.md hierarchy (all are loaded and merged)
~/.claude/CLAUDE.md          # Global preferences (all projects)
./CLAUDE.md                  # Project-level (team-shared, git-tracked)
./.claude.local.md           # Local overrides (gitignored, personal)
./.claude/rules/*.md         # Modular topic-specific rules

# CLAUDE.md

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev` (runs on port 3000)
- Test all: `pnpm test`
- Test single: `pnpm test -- path/to/file.test.ts`
- Lint: `pnpm lint`
- Type check: `pnpm typecheck`

## Architecture
App Router project. Pages in src/app/, components in
src/components/, server actions in src/actions/.

## Code Style
- TypeScript strict mode, never use `any`
- Named exports only, no default exports
- Use `import type` for type-only imports
- Server Components by default; `"use client"` only when needed

## Key Files
- src/lib/db.ts — Prisma client singleton
- src/lib/auth.ts — Authentication helpers
- src/middleware.ts — Auth and redirect logic

# Cursor rules structure
.cursor/rules/
├── project-standards.mdc     # alwaysApply: true
├── typescript-patterns.mdc   # globs: "*.ts,*.tsx"
├── react-components.mdc      # globs: "src/components/**/*.tsx"
├── api-routes.mdc             # globs: "src/app/api/**/*.ts"
└── testing.mdc                # globs: "*.test.ts,*.spec.ts"

---
description: "TypeScript coding standards"
globs: "*.ts,*.tsx"
alwaysApply: false
---
# TypeScript Standards

- Use strict mode. Never use `any` — use `unknown` and narrow.
- Prefer `interface` over `type` for object shapes.
- Use explicit return types on exported functions.
- Use `import type` for type-only imports.
- Group imports: external → internal → types.

# Copilot instructions structure
.github/
├── copilot-instructions.md            # Repository-wide
└── instructions/
    ├── react-components.instructions.md   # Path-specific
    └── api-routes.instructions.md         # Path-specific

# .github/copilot-instructions.md

## Project
Next.js 15 e-commerce app with TypeScript, Prisma, and Stripe.

## Conventions
- Use TypeScript strict mode. Never use `any`.
- Prefer Server Components. Mark client components with
  `"use client"` only when they need interactivity.
- Use named exports. No default exports.
- Use Tailwind CSS v4 utility classes for styling.

## Testing
- Use Vitest and Testing Library.
- Place test files next to source files.
- Name test files `*.test.ts` or `*.test.tsx`.

# .windsurfrules

## Project
Next.js 15 app with TypeScript, Prisma ORM, and Stripe.

## Architecture
- src/app/ — App Router pages and API routes
- src/components/ — Shared UI components
- src/lib/ — Utilities, database, and API helpers

## Standards
- TypeScript strict mode. No `any` types.
- Server Components by default.
- Named exports only.
- Tailwind CSS v4 for styling.
- Vitest + Testing Library for tests.

# GEMINI.md hierarchy
~/.gemini/GEMINI.md          # Global preferences
./GEMINI.md                  # Project-level
./packages/api/GEMINI.md     # Sub-directory (monorepo)

# Useful commands
/memory show                 # See all loaded context
/memory reload               # Reload after editing
/memory add "instruction"    # Append to global file

                 AGENTS.md  Own Format   Hierarchy   Glob Matching
                 ─────────  ──────────   ─────────   ─────────────
Claude Code      ✓ reads    CLAUDE.md    3 levels    ✗
Cursor           ✓ reads    .mdc files   4 levels    ✓ (frontmatter)
GitHub Copilot   ✓ reads    .github/     2 levels    ✓ (path-specific)
Windsurf         ✓ reads    .windsurfrules  2 levels ✗
Gemini CLI       ✓ reads    GEMINI.md    3 levels    ✗
Codex CLI        ✓ reads    AGENTS.md    —           ✗
Amp              ✓ reads    —            —           ✗
Devin            ✓ reads    —            —           ✗

# Descriptive (73% application rate)
This project uses TypeScript with strict mode.
The team prefers interfaces over type aliases.
We use CSS Modules for component styling.

# Imperative (94% application rate)
Always use TypeScript strict mode. Never use `any`.
Prefer `interface` over `type` for object shapes.
Use CSS Modules for all component styling.
Import styles as `import styles from './Name.module.css'`.

# Structure your files with priority positioning

## Commands (FIRST — most critical)
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`

## Architecture (high priority)
...

## Code Style (high priority)
...

## Nice-to-Have Conventions (lower priority — middle)
...

## Critical Warnings (LAST — also high attention)
- Never commit .env files
- Never delete migration files
- Always run tests before committing

# Wasteful — your linter/formatter already handles this
- Use 2-space indentation
- Add semicolons at the end of statements
- Use single quotes for strings
- Maximum line length: 80 characters

# Valuable — judgment that tools can't enforce
- Prefer Server Components. Only add "use client" when
  the component needs browser APIs or event handlers.
- Use optimistic updates for mutations that affect the
  current user's data. Use await for shared state changes.
- When adding a new API route, follow the pattern in
  src/app/api/products/route.ts as the canonical example.

# Problematic — focuses attention on the wrong pattern
- Do NOT use default exports
- Do NOT use the `any` type
- Do NOT use inline styles
- Do NOT use var for variable declarations

# Better — states the desired behavior directly
- Use named exports for all components and functions
- Use `unknown` with type guards instead of `any`
- Use CSS Modules or Tailwind for all styling
- Use `const` by default, `let` only when reassignment
  is needed

# Vague — open to interpretation
Create well-structured components with proper typing and
clean separation of concerns.

# Concrete — shows exactly what you want
When creating React components, follow this pattern:

```tsx
interface ProfileCardProps {
  user: User;
  onEdit: (id: string) => void;
}

export const ProfileCard = ({ user, onEdit }: ProfileCardProps) => {
  return (
    <div className={styles.card}>
      <h2>{user.name}</h2>
      <button onClick={() => onEdit(user.id)}>Edit</button>
    </div>
  );
};
```

# Fragile — this code will go stale
When creating an API route, use this exact pattern:
[50 lines of copied code...]

# Durable — always refers to the latest version
When creating a new API route, follow the pattern in
`src/app/api/products/route.ts`. This is the canonical
reference for error handling, validation, and response
formatting.

# Broad — loaded even when working on backend code
alwaysApply: true
→ "Use Tailwind CSS v4 utility classes..."

# Scoped — only loaded when editing component files
globs: "src/components/**/*.tsx"
→ "Use Tailwind CSS v4 utility classes..."

# Copilot equivalent — path-specific instructions
.github/instructions/frontend.instructions.md
→ applyTo: "src/components/**"

# Maintaining all of these separately is fragile
your-project/
├── AGENTS.md                          # Codex, Amp, Devin
├── CLAUDE.md                          # Claude Code
├── .cursor/rules/standards.mdc        # Cursor
├── .github/copilot-instructions.md    # GitHub Copilot
├── .windsurfrules                     # Windsurf
└── GEMINI.md                          # Gemini CLI

# When conventions change, you'd need to update 6 files.
# Inevitably, some fall out of sync.

# Recommended: AGENTS.md as the shared base
your-project/
├── AGENTS.md                          # Shared base (all tools read this)
├── CLAUDE.md                          # Claude-specific overrides only
├── .cursor/rules/                     # Cursor-specific (glob patterns)
│   └── react-components.mdc           # Auto-attaches to .tsx files
└── .github/
    └── instructions/
        └── api.instructions.md        # Copilot path-specific rules

AGENTS.md (shared by all tools):
  ✓ Project overview and tech stack
  ✓ Build, run, and test commands
  ✓ Architecture and directory structure
  ✓ Universal coding standards
  ✓ Key files and entry points

Tool-specific files (only when you need tool-unique features):
  ✓ Cursor .mdc — glob-based activation patterns
  ✓ Copilot .instructions.md — path-scoped overrides
  ✓ CLAUDE.md — Commands section (Claude Code's priority)
  ✓ GEMINI.md — @imports for modular context

# Create AGENTS.md as the source of truth
# Then symlink for tools that need a specific filename

ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md

# Now editing AGENTS.md updates all three automatically
# .windsurfrules also reads AGENTS.md natively, no symlink needed

Layer 1: AGENTS.md (everyone)
  → Project-wide conventions and architecture
  → Version-controlled, reviewed in PRs
  → The single source of truth for project context

Layer 2: Tool-specific configs (per tool)
  → Only contains tool-unique features
  → Cursor: glob patterns, activation modes
  → Copilot: path-specific instruction files
  → Claude: memory hierarchy, local overrides

Layer 3: Personal preferences (per developer)
  → Global user-level config (not project-specific)
  → ~/.claude/CLAUDE.md, Cursor user rules, etc.
  → NOT version-controlled

# Directory structure
my-saas/
├── AGENTS.md                          # Shared context
├── .cursor/rules/
│   ├── project.mdc                    # alwaysApply: true
│   ├── components.mdc                 # globs: "src/components/**"
│   └── database.mdc                   # agent-requested
├── src/
│   ├── app/
│   ├── components/
│   └── lib/
├── prisma/
└── package.json

# AGENTS.md (kept short — under 50 lines)

## Project
SaaS invoicing app. Next.js 15, TypeScript, Prisma, Stripe.

## Commands
- `pnpm dev` — Start dev server (port 3000)
- `pnpm test` — Run Vitest test suite
- `pnpm db:push` — Push Prisma schema changes
- `pnpm db:studio` — Open Prisma Studio

## Architecture
- src/app/ — App Router (pages, layouts, API routes)
- src/components/ — Shared components (Server by default)
- src/lib/ — Database client, auth, utilities
- src/actions/ — Server Actions for all mutations
- prisma/schema.prisma — Database schema

## Standards
- TypeScript strict. No `any`.
- Server Components by default.
- Server Actions for mutations (no API routes for forms).
- Tailwind CSS v4 for styling. No CSS-in-JS.

# Directory structure
design-system/
├── AGENTS.md                              # Shared base
├── .cursor/rules/
│   ├── components.mdc                     # globs: "src/components/**"
│   ├── tokens.mdc                         # globs: "src/tokens/**"
│   ├── testing.mdc                        # globs: "*.test.tsx"
│   └── documentation.mdc                  # agent-requested
├── .github/
│   ├── copilot-instructions.md            # Copilot base
│   └── instructions/
│       └── components.instructions.md     # Copilot path-specific
├── src/
│   ├── components/
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.test.tsx
│   │   │   ├── Button.module.css
│   │   │   └── index.ts
│   │   └── ...
│   └── tokens/
├── docs/
└── package.json

# AGENTS.md

## Project
Shared design system component library. React 19,
TypeScript, CSS Modules, Storybook.

## Commands
- `pnpm dev` — Start Storybook (port 6006)
- `pnpm test` — Run Vitest tests
- `pnpm build` — Build library for publishing
- `pnpm lint` — ESLint + Stylelint

## Architecture
- src/components/ — One directory per component
  (ComponentName/ComponentName.tsx, index.ts, test, styles)
- src/tokens/ — Design tokens (colors, spacing, typography)
- docs/ — Storybook documentation pages

## Component Pattern
Every component follows this structure:
- ComponentName.tsx — Implementation (see src/components/Button/)
- ComponentName.module.css — Scoped styles
- ComponentName.test.tsx — Unit and integration tests
- index.ts — Named re-export

Follow `src/components/Button/` as the canonical reference.

## Standards
- All components must accept a `className` prop for composition.
- All interactive components must support keyboard navigation.
- All components must have at minimum one unit test.
- Use design tokens from `src/tokens/` — never hardcode values.
- Export types for all component props.

# Directory structure
platform/
├── AGENTS.md                          # Root — overall architecture
├── packages/
│   ├── web/
│   │   ├── AGENTS.md                  # Frontend-specific context
│   │   └── src/
│   ├── api/
│   │   ├── AGENTS.md                  # Backend-specific context
│   │   └── src/
│   └── shared/
│       ├── AGENTS.md                  # Shared utilities context
│       └── src/
├── .cursor/rules/
│   └── monorepo.mdc                   # alwaysApply: true
└── package.json

# Root AGENTS.md

## Project
Multi-package platform with web frontend, REST API, and
shared utilities. Turborepo monorepo with pnpm workspaces.

## Commands
- `pnpm install` — Install all dependencies
- `pnpm dev` — Start all packages in dev mode
- `pnpm build` — Build all packages
- `pnpm test` — Run tests across all packages

## Architecture
- packages/web — Next.js 15 frontend
- packages/api — Express + Prisma backend
- packages/shared — Shared types, utilities, and validators

## Cross-Package Rules
- Shared types live in packages/shared/src/types/
- Never duplicate type definitions across packages.
- Import shared code as `@platform/shared`.
- Database schema changes require a migration file.

# packages/api/AGENTS.md

## Package: API
Express REST API with Prisma ORM and PostgreSQL.

## Commands
- `pnpm dev` — Start API server (port 4000)
- `pnpm test` — Run API tests
- `pnpm db:migrate` — Run Prisma migrations
- `pnpm db:seed` — Seed development data

## Patterns
- Route handlers in src/routes/ (one file per resource)
- Business logic in src/services/ (never in route handlers)
- Validation with Zod schemas in src/schemas/
- Follow src/routes/products.ts as the canonical example

## Standards
- All routes must validate input with Zod before processing.
- All service methods must return typed Result objects.
- All database queries go through service layer, never in routes.
- Write integration tests for every route.

Problem:
  Massive context files (1,000+ lines of rules) that try
  to cover every possible scenario. The model's attention
  is spread thin, and critical rules get lost in the noise.

Fix:
  Start minimal. Add rules only when you notice repeated
  mistakes. A focused 50-line AGENTS.md outperforms a
  500-line kitchen-sink file. Remove rules that the AI
  already follows without being told.

Problem:
  Restating rules that your linter, formatter, or type
  checker already enforces. These waste tokens without
  adding value — the AI's output will be auto-corrected
  by the tool regardless.

  "Use 2-space indentation"        ← Prettier handles this
  "Add semicolons"                 ← ESLint handles this
  "Sort imports alphabetically"    ← eslint-plugin-import

Fix:
  Only include judgment calls that automated tools can't
  enforce: architectural decisions, pattern preferences,
  domain-specific conventions, and "when to use what."

Problem:
  Writing context files like README documentation rather
  than clear instructions. Description informs but doesn't
  direct. The AI may acknowledge the description without
  acting on it.

  "This project uses React Server Components and follows
   the App Router conventions from Next.js 15."

Fix:
  Use imperative language that leaves no ambiguity:

  "Use Server Components by default. Only add the
   'use client' directive when the component needs browser
   APIs, event handlers, or React state."

Problem:
  Context files are local-only and not committed to git.
  Each team member has different (or missing) context,
  causing inconsistent AI output across the team.

Fix:
  Commit AGENTS.md, .cursor/rules/, and
  .github/copilot-instructions.md to version control.
  Treat context file changes like code changes — review
  them in pull requests.

  Use .claude.local.md (gitignored) for personal
  preferences that shouldn't be shared.

Problem:
  You write rules but never verify the AI actually follows
  them. Syntax errors in YAML frontmatter, wrong file
  locations, or overly vague descriptions can silently
  prevent rules from loading.

Fix:
  After adding or changing a context file:
  1. Start a new conversation
  2. Ask the AI to describe the conventions it sees
  3. Ask it to generate a small example and verify it
     follows your stated patterns
  4. In Cursor: check the Rules indicator in the chat panel
  5. In Gemini CLI: run /memory show to see loaded context

Problem:
  Setting every rule to alwaysApply or placing everything
  in a single AGENTS.md that loads on every interaction.
  Backend rules load when you're working on CSS. Database
  rules load when you're writing documentation.

Fix:
  Use scoping wherever possible:
  - Cursor: globs to match file patterns
  - Copilot: path-specific .instructions.md files
  - Monorepos: nested AGENTS.md per package
  - Keep alwaysApply for genuinely universal rules only
    (project overview, commands, core standards)