Context Engineering

Overview

AI coding tools are only as useful as the context they have access to. An AI assistant that knows nothing about the project's conventions, constraints, and architecture makes generic suggestions. An AI assistant that has been given accurate, well-structured context makes suggestions that fit the codebase — the right library choices, the right naming conventions, the right patterns.

Context engineering is the practice of designing, writing, and maintaining the files that provide this context: CLAUDE.md, AGENTS.md, .cursorrules, and equivalent configuration for other tools. These files are not documentation for humans who will read them carefully; they are instructions for AI systems that will load them at the start of every session. That difference in audience changes how they should be written.

For how AI tools are adopted and governed, see AI Governance. For standards on using AI code assistants day-to-day, see AI Code Assistants. For agentic workflows that rely on well-maintained context, see Agentic Workflows.

Why It Matters

Context files reduce the cost of every AI interaction. Without good context, every developer using AI assistance in a given repo starts from scratch — re-explaining conventions, re-specifying constraints, re-linking to relevant documentation. Good context files make this setup automatic and consistent across the team.

Context files capture team conventions that are otherwise implicit. The conventions that senior engineers apply automatically — use this auth library, not that one; write comments explaining why, not what; avoid mutable globals in this module — are not visible to AI tools without being made explicit. Context files are the mechanism for making implicit conventions explicit.

Outdated context is worse than no context. An AI tool that is told "use the v2 auth API" but the codebase has moved to v3 will confidently produce wrong code. Context files that are not maintained actively mislead. They require the same maintenance discipline as any other documentation.

Context window management determines quality at scale. A context file that grows without limit, with everything in it given equal weight, eventually exceeds the model's effective context window. At that point, the model cannot attend to all the instructions, and earlier context is effectively ignored. Context quality (what is included and how it is prioritised) matters as much as quantity.

Standards & Best Practices

Context files are first-class project artefacts

Context files (CLAUDE.md, AGENTS.md, .cursorrules, etc.) belong in source control, alongside the code they describe. They are reviewed, updated, and treated with the same discipline as any other developer documentation.

Standards:

• Context files are checked into the repository root (or the directory they apply to for scoped files)
• Changes to project structure, conventions, or tooling that affect AI context require a corresponding update to the context file
• Context file changes are included in PRs that change the conventions the file describes
• Ownership of the context file is explicit — someone on the team is responsible for keeping it accurate

Write for an AI reader, not a human reader

Context file writing is a different discipline from documentation writing. A human reader will skim, infer from context, and ask questions when confused. An AI reader takes instructions literally, does not infer from context it was not given, and does not ask for clarification.

Practical implications:

• Be explicit, not allusive. "Use the standard auth pattern" is insufficient — the file must describe what the standard auth pattern is, or link to where it is described.
• Prefer commands over descriptions. "Always import from @/lib/db, never from lib/db" is clearer than "We prefer using the aliased import path for the database module."
• State what NOT to do. AI models are trained on broad patterns; the exceptions and local anti-patterns are not inferrable. Explicitly listing "don't use X, use Y instead" is high-leverage.
• Prioritise ruthlessly. Every instruction competes for attention in the context window. If something can be derived from the code without explicit instruction, leave it out. Context files should contain what cannot be inferred — constraints, decisions, local conventions.

Context file structure

A well-structured context file has distinct sections that answer distinct questions:

# Project context file

## What this project is

[One paragraph on the purpose and user of the system]

## Stack and key dependencies

[Language, framework, major libraries — with any version constraints or preferred alternatives]

## Conventions

[Naming conventions, file organisation, import patterns, coding style decisions not captured by the linter]

## What to avoid

[Anti-patterns, deprecated approaches, libraries we explicitly do not use and why]

## Key commands

[How to run, build, test — the commands a developer needs in the first session]

## References

[Links to architecture docs, design decisions, external context the AI should know about]

The structure may vary by project type and tool, but the principle is the same: distinct sections with clear scope, ordered by frequency of relevance (most-used first).

Scope context files to the right level

A context file at the repository root applies to the whole repo. A context file in a subdirectory applies to that directory and its children. Use this scoping deliberately:

• Root-level context: project-wide conventions, stack, team norms
• src/ or app/: application-level patterns (component structure, state management conventions)
• infra/ or terraform/: infrastructure-specific conventions (module naming, variable patterns)
• scripts/: scripting conventions and safety requirements

Avoid putting everything in the root context file. Over-scoped context instructions apply to every interaction and crowd out the instructions that are actually relevant.

Context window management

The AI model's attention is finite. Context files that are too long push early instructions out of effective context. Management strategies:

• Keep the root context file under 300 lines. If it is longer, it contains things that should be in subdirectory files, linked documentation, or removed entirely.
• Link, do not inline. If a convention is well-described in a design document, link to it rather than pasting it into the context file. The AI tool can follow links when needed.
• Remove outdated instructions immediately. An instruction that no longer applies is not neutral — it actively misleads. Removal is maintenance.
• Use headers and structure so the model can locate the relevant section for a given task.

Versioning and freshness

Context files should include a "last reviewed" date or a reference to the event that prompted the last update:

<!-- Last reviewed: 2026-03 after migration to v3 auth API -->

This is not a formal requirement but a lightweight signal to the next person who reads the file: when was this last known to be accurate?

How to Implement

Writing a context file for a new project

Start with a minimal file covering the highest-leverage content:

1. What the project does (one paragraph)
2. The stack (language, framework, critical dependencies)
3. Three to five conventions that AI tools would otherwise get wrong
4. The key commands to run and build

Add to it when the AI tool makes a mistake that better context would have prevented. This is the most efficient way to build up a useful context file: iteratively, based on actual gaps.

Auditing an existing context file

Signs that a context file needs work:

• The AI tool consistently suggests imports, patterns, or libraries the file says to avoid
• The file references libraries, APIs, or conventions that no longer exist in the codebase
• The file is longer than 400 lines without subdirectory scoping
• No one on the team can say when it was last reviewed

A quarterly audit (or an audit triggered by a major stack change) is a reasonable maintenance cadence for a stable project.

Common Pitfalls

Writing context files for humans, not AI tools. Long prose explanations, conversational asides, and background narrative consume context window without giving the model actionable instructions. Write in commands and constraints.

Including everything "just in case." A context file that covers every possible scenario becomes too long to be effective. Focus on what is non-obvious, local, or likely to be done wrong without guidance.

Not removing outdated content. An AI tool that is told to use a library that was removed two months ago will confidently suggest it. Removal is maintenance; context files are not append-only.

One context file for the whole monorepo. A context file that tries to capture the conventions of twelve different services in one file will either be too long (effective context exhausted) or too shallow (no per-service guidance). Scope files to the right level.

Treating context files as a one-time setup. Context files are living documents. A codebase that changes without updating its context file becomes a codebase where AI suggestions are increasingly misaligned with current reality.

No team ownership. If no one is responsible for keeping the context file accurate, it will drift. Assign ownership explicitly.