Context Injection: Engineering the Agentic Workflow

When AI coding assistants arrived in earnest — Copilot in 2021, a cascade of competitors shortly after — the promise was intoxicating: a tireless pair programmer who had read every public repository ever written. In practice, the experience was more complicated. The AI was brilliant in isolation and oblivious in context.

Ask it to write a function and it would produce something technically impressive. Ask it to write your function — one that fit your codebase’s naming conventions, respected your team’s error-handling philosophy, used the specific internal libraries you had built over years — and it would confidently produce something subtly, sometimes catastrophically, wrong.

The assistant didn’t know you. It didn’t know your project. It didn’t know that you had migrated away from Redux six months ago, or that your team had a strict rule about never catching generic exceptions, or that the internal logging module was @corp/logger and not the three other logging packages it liked to suggest. Every session started from zero. Every conversation was a stranger’s first day on the job.

Developers compensated with elaborate prompts — pasted at the start of every conversation, carefully maintained in personal notes documents, passed around teams as institutional lore. It worked, after a fashion. It was also tedious, inconsistent, and fragile. The moment you forgot to include the preamble, you were back to fighting the assistant’s defaults.

The industry needed a better answer. What emerged — gradually, through community experimentation and then deliberate product design — was the guidance file: a structured, project-local document that gave AI assistants persistent context about who they were working with and what was expected of them.

A Brief History of Telling AI What to Do

2021 — Early Copilot era

Context came entirely from open files and recent edits. Users learned to keep “good examples” open in adjacent tabs to nudge autocomplete in the right direction. Informal and fragile.

2022–2023 — The prompt-pasting era

Chat-based assistants (ChatGPT, then Claude, then Bard) introduced conversational coding. Teams started sharing “starter prompts” — paragraphs describing the tech stack and conventions to paste before each session. Wikis and Notion pages filled with these incantations.

2023 — Custom instructions & system prompts

Platforms began offering persistent custom instruction fields. A step forward, but account-level rather than project-level. Your React project and your Python data pipeline shared the same instructions.

2024 — The file-based revolution begins

Cursor introduced .cursorrules, a project-local file the editor would automatically inject into every AI session. The concept of the guidance file was born. Community-maintained repositories of example rules files sprang up almost immediately.

2025–2026 — Standardisation and agentic context

Anthropic shipped CLAUDE.md for Claude Code. Agents began reading guidance files autonomously as part of their startup sequence. The files evolved from style guides into full operating manuals for multi-step autonomous tasks. This shift is central to the rise of Agentic AI, where models move from responding to acting.

The trajectory is clear in retrospect. As AI assistants became more capable — moving from autocomplete to chat to autonomous agents capable of editing dozens of files, running tests, and managing git history — the need for durable, structured context grew proportionally. The more you trust an AI to act, the more important it becomes that the AI knows what you actually want.

The Anatomy of a Guidance File

Guidance files go by many names depending on the tool: .cursorrules, CLAUDE.md, AGENTS.md, GEMINI.md, copilot-instructions.md. The names differ; the underlying idea is identical. These are plain-text (usually Markdown) documents that live in your repository and are automatically read by the AI assistant before it responds to anything.

Think of them as an onboarding document that never gets stale, for a team member who never needs more than one read-through.

The most effective guidance files tend to share a common structure, even when arrived at independently by different teams. They cover four broad categories of information:

• Project identity: What this codebase is, what it does, who uses it, what phase of development it is in.
• Technical environment: Languages, frameworks, key libraries, infrastructure, CI/CD setup.
• Conventions & standards: Naming, formatting, error handling, testing philosophy, commit message format.
• Agent-specific operating rules: What the AI is allowed to do autonomously, what requires human approval, how to handle ambiguity.

A concrete example from a production TypeScript project illustrates how specific these files can get:

# Project Context

Stack: Next.js 15, TypeScript strict mode, Prisma ORM, PostgreSQL
Style: Prettier defaults, ESLint airbnb-typescript
State: Zustand only — do NOT introduce Redux or Context API

## Conventions

# All new components go in src/components/{feature}/
# Use named exports only — never default exports
# Internal logging: always use @/lib/logger, never console.log
# Database queries: use Prisma transactions for writes > 1 operation

## Agent Behaviour

# Never modify schema.prisma without explicit instruction
# Run `pnpm typecheck` before declaring a task complete
# If a requirement is ambiguous, stop and ask — don't assume

Starter Template: CLAUDE.md / AGENTS.md

To get started immediately, you can copy this template into a file named CLAUDE.md at the root of your project. It follows the best practices discussed above:

# Project Context
 
## Tech Stack
- Framework: [e.g., Next.js 15, FastAPI, etc.]
- Language: [e.g., TypeScript strict, Python 3.12]
- Database: [e.g., PostgreSQL with Prisma]
 
## Development Standards
- Naming: [e.g., PascalCase for components, camelCase for functions]
- Exports: Use named exports only
- Tests: Write Vitest tests for all new utility functions
 
## Agent Instructions
- Planning: Always create a task plan before editing files
- Verification: Run `npm run typecheck` after changes
- Conflict: If requirements are unclear, stop and ask

Notice that last section. “Agent Behaviour” is something that would have been meaningless in 2022 when the assistant couldn’t act autonomously. Today, with agentic tools capable of planning multi-step changes, running terminal commands, and iterating on their own output, telling the AI how to handle uncertainty and what gates require human involvement is just as important as telling it which framework you use.

CLAUDE.md — Anthropic’s Approach

Claude Code, Anthropic’s terminal-based agentic coding assistant, introduced CLAUDE.md as its primary context mechanism. The design philosophy is worth examining because it illustrates how the industry’s thinking has matured.

When Claude Code starts in a directory, it walks the file tree looking for CLAUDE.md files. It reads the one at the project root, and also any scoped to subdirectories — so a monorepo can have a top-level file describing shared conventions and individual package-level files with more specific guidance. This hierarchical reading means context can be layered rather than crammed into a single unwieldy document.

Memory and the CLAUDE.md feedback loop

One of the more interesting patterns that has emerged is using the guidance file as a living document that the AI itself helps maintain. When a developer and Claude Code work through a non-obvious decision together — say, settling on a particular pattern for handling optimistic updates — they can ask Claude to record the rationale in CLAUDE.md. Future sessions inherit that institutional knowledge automatically.

This creates a genuinely novel kind of institutional knowledge management. The file is not just instructions flowing from human to AI. It is a log of decisions made, an artefact of the team’s evolving judgement, maintained in part by the very system it instructs. The AI becomes a participant in its own onboarding documentation.

Anthropic also introduced ~/.claude/CLAUDE.md — a personal file in the user’s home directory — for preferences that should apply across all projects: preferred explanation style, sensitivity to certain kinds of output, habits around asking clarifying questions. The project file and the personal file are read together, with project-level context taking precedence on conflicts.

The Three-Level Hierarchy

Anthropic’s implementation provides a powerful model for layered context. By splitting instructions across different scopes, teams can maintain global standards while allowing for project-specific flexibility.

This three-level hierarchy gives teams fine-grained control:

• Personal Defaults: Applies globally across all projects. Good for preferred explanation style and personal habits around test coverage.
• Project Root: Team-facing, committed to version control. Covers stack, conventions, and agent operating rules.
• Scoped Override: Essential in monorepos where individual packages have different languages or stricter rules.

The Broader Ecosystem — AGENTS.md and Beyond

The guidance file pattern has spread well beyond any single tool. The community has begun converging on a few conventions, even across competing products, because the underlying need is universal.

AGENTS.md emerged from the OpenAI Codex and open-source agent community as a roughly parallel convention — a file specifically designed for autonomous coding agents that need not just style guidance but operational instructions: how to break down tasks, what to verify before committing, when to surface ambiguity to the human. The name reflects the shift in framing: this is not a linting config, it is an operating manual for an autonomous actor.

GitHub Copilot’s workspace-level instructions (.github/copilot-instructions.md) follow the same pattern but integrate with GitHub’s infrastructure, allowing instructions to be scoped to repositories and potentially inherited across an organisation’s repos. Gemini Code Assist reads GEMINI.md. Each tool has its own file name; each reads the same category of information.

The emerging meta-standard

Some teams running multi-agent or tool-agnostic workflows have begun writing a single authoritative context document — sometimes called PROJECT.md or CONTEXT.md — and then maintaining thin, tool-specific files that simply reference it. The intelligence lives in one place; the tool-specific files are just pointers.

# Agent Operating Instructions

## Project context → see CLAUDE.md for full stack details

## Task execution rules
planning:    Always create a task checklist before writing code
scope:       Implement only what is asked; do not refactor adjacent code
validation:  Run tests + typecheck after every logical unit of change
ambiguity:   If requirements conflict, surface the conflict before acting

## Allowed autonomous actions
✓ Edit files within src/
✓ Install packages listed in package.json devDependencies
✓ Run test suite, linter, type checker
✗ Modify infrastructure / deployment configs
✗ Make direct database mutations in production
✗ Push to main branch

This explicit permission model — listing what agents may and may not do autonomously — represents a significant maturation in how development teams think about AI integration. It is the difference between giving someone keys to the office and giving them keys to the office with a clear understanding of which rooms they can enter unaccompanied.

Writing Guidance Files That Actually Work

Not all guidance files are created equal. A file that is too long becomes noise — the AI will still read it, but humans won’t maintain it and it will drift out of date. A file that is too sparse leaves the AI falling back on its training defaults, which may not match your requirements at all.

The most effective files share a handful of characteristics. They are written with the same care as good documentation — specific rather than vague, declarative rather than aspirational. “Use named exports” is more useful than “follow good module patterns.” They distinguish clearly between hard rules (“never use any as a TypeScript type”) and soft preferences (“prefer early returns over nested conditionals”). And they are honest about what the file does not cover, pointing the AI toward other resources when appropriate.

Common antipatterns to avoid

The “aspirational manifesto” antipattern is perhaps the most common failure mode — files full of vague exhortations (“write clean, maintainable code,” “prioritise user experience”) that sound meaningful but give the AI nothing actionable to work with. Related is the “copy-paste from the internet” problem, where teams grab a community template and never adapt it to their actual project, resulting in instructions that contradict each other or reference tools the team doesn’t use.

A subtler problem is writing instructions that were accurate at the time of writing but were never updated as the codebase evolved. A guidance file that still recommends a library you deprecated eight months ago is worse than no guidance at all — it actively misleads the AI into producing code you will have to undo. Treating the guidance file as a living document, with periodic review as part of your engineering rituals, is the discipline that separates teams who get real value from those who give up after a few frustrated sessions.

What This Shift Actually Means

The guidance file is, at one level, a practical engineering artefact — a configuration file for an AI tool. But it represents something more significant in how we think about human-AI collaboration in software development.

For most of computing history, tools did exactly what you told them, each time you told them. A compiler has no memory of your last project. A linter does not care about your team’s history or your personal preferences beyond the config file in the repository. The guidance file is the first widely-adopted mechanism for giving a tool something that looks, functionally, like persistent institutional knowledge.

The AI assistant that reads your CLAUDE.md before responding is not the same as the one that would respond without it. It has been, in a small but meaningful way, situated. It knows where it is. That situatedness — the ability to act in accordance with a specific context rather than defaulting to statistical averages drawn from the whole of public code — is what separates a genuinely useful collaborator from a very impressive search engine.

We are early in understanding how to write these files well, how to maintain them, how to compose them across tools and teams and organisations. The conventions are still settling. But the direction is clear: the future of AI-assisted development is not more powerful models acting on generic context. It is capable models acting on rich, specific, carefully maintained context — and the humble Markdown file sitting in the root of your repository is, for now, the most important part of that equation.

If your team is thinking about how to get more consistent, trustworthy results from your AI tooling — or how to govern agentic AI safely as it takes on more autonomous work — get in touch. This is exactly the kind of architectural thinking we help teams get right.