Project Context Files

Configure AGENTS.md, .cursorrules, and CLAUDE.md to improve AI agent output — define conventions, architecture rules, and design system constraints before agents write code.

Project context files are the single highest-leverage tool for improving AI agent output. These files live at the project root and tell agents about conventions, architecture, and constraints before they write any code. Most popular AI coding tools (Cursor, Claude Code, GitHub Copilot) read from a standard context file automatically.

What to include

Section	What it covers
Project overview	What this project is, who the audience is, tech stack summary
Code style	TypeScript strict mode, naming conventions, export patterns, file structure
Architecture rules	Server/client component boundaries, data flow patterns, routing conventions
Design system	Token usage rules, component library in use (shadcn/ui, Radix), variant patterns
Accessibility requirements	WCAG 2.2 AA baseline, semantic HTML requirements, ARIA patterns
Testing standards	Testing framework, required coverage, test location conventions
Git workflow	Conventional Commits, branch naming, PR conventions

Template

AGENTS.md — minimal template for design engineer projects

# Project

[Project name and one-liner]

## Stack

- Framework: Next.js 16 App Router, TypeScript strict mode
- Styling: Tailwind v4 + CVA + clsx/tailwind-merge
- Component library: shadcn/ui (components in src/components/ui/)
- State: TanStack Query (server) + Zustand (client) + URL params
- Testing: Vitest + Testing Library + Playwright

## Architecture rules

- Default to Server Components. Only add "use client" for state,
  effects, event handlers, or browser-only APIs.
- Data fetching happens in Server Components or route handlers.
  Client-side fetching uses TanStack Query.
- All colors, spacing, and fonts come from CSS variables in globals.css.
  No inline color or spacing values.

## Code style

- PascalCase for component files and exports
- Props interface: ComponentNameProps
- Export named functions, not default exports
- Co-locate tests and types with components

## Accessibility

- WCAG 2.2 AA is the baseline
- Use semantic HTML: <button> not <div onClick>
- Every interactive element needs visible focus styles
- Respect prefers-reduced-motion

Multi-agent orchestration

For complex work, use multiple agents with different specialisations in a pipeline:

Agent role	Responsibility	Handoff condition
Architect	Designs component structure, prop interfaces, data flow, file layout	Returns a written spec
Implementer	Writes component code from the architect's spec, following AGENTS.md conventions	Returns working files
Reviewer	Checks for a11y, token compliance, edge cases, bundle impact	Returns a review report
Tester	Generates test files covering all states (loading, empty, error, success)	Returns passing tests

Multi-agent prompt pattern

Step 1 — Architect:
"Design the component tree and data flow for a project dashboard
that shows active projects, team members, and recent activity.
Output: a spec with component names, prop interfaces, and file layout."

Step 2 — Implementer:
"Following the spec above and the conventions in AGENTS.md,
implement each component. Use shadcn/ui Card, Badge, and Button.
Output: complete files."

Step 3 — Reviewer:
"Review the implemented components for:
1. WCAG 2.2 AA compliance
2. Design token usage (no inline values)
3. Server/Client component boundary correctness
4. Edge case handling (loading, empty, error states)
Output: list of issues to fix."

Step 4 — Tester:
"Generate test files for each component covering all states
listed in the review. Output: .test.tsx files."

The context file that governs agent behaviour is the most important file in your project that has no runtime impact. Invest time in keeping it accurate. Every time you change a convention, update the context file. Outdated context files produce confidently wrong code that matches the old convention.

What to include

Template

Multi-agent orchestration

On this page