Context Engineering for AI Coding Agents

Reference · Updated September 9, 2026

Context engineering is the practice of deciding what an AI model sees before it acts, and building the system that delivers it. For AI coding agents it means turning project knowledge into something explicit, structured, selective, versioned, and portable, rather than hoping a longer prompt covers the gap.

Updated September 9, 2026: Clarified the comparison, linked supporting references, and reviewed current Archcore behavior.

The reason it exists as a discipline is narrow and practical. You cannot retrain the model. You can change almost everything about what it knows when it starts working, and on real codebases that is what separates an agent that fits your system from one that writes plausible code in the wrong place.

Why use context engineering for coding agents?

An agent reads your code. It cannot read the reasoning behind your code.

That gap is not a model weakness, it is an information problem. Nothing in the repository states why the auth module is split the way it is, which migration is half-finished, that the team banned default exports two quarters ago, or that the retry logic in one service exists because of an incident. A model with a perfect understanding of every file still has to guess at all of it.

The observable failures are consistent:

• The agent picks a library you already rejected, because the rejection lives in a closed pull request.
• It puts a new endpoint where its training data says endpoints go, not where yours do.
• It reopens a decision every few sessions, because nothing durable records that it was made.
• It follows a convention correctly on Monday and not on Thursday, because the convention was in a chat message.

Each of these is a context failure with a different shape, and none of them is fixed by a better prompt.

The five properties of engineered context

Context that holds up is not just more text. It has five properties, and dropping any one of them is where most setups fail.

Selective is the property teams skip most often, and it is the one that decides whether the rest is usable. A single instruction file that has grown to a few hundred lines is explicit and versioned and portable, and it is still poor context, because everything in it arrives on every turn whether it applies or not. The agent pays attention budget for the rules about your CSS while it edits a database migration.

Context engineering compared with the neighbours

These terms get used interchangeably and describe different scopes.

Two of these are worth being precise about, because the confusion is expensive.

Retrieval is one part of context engineering. It can retrieve code, decision records, or other documents if they are in its sources. It cannot recover reasoning nobody recorded. Anthropic’s context-engineering guide describes retrieval alongside tool design and context management.

Harness engineering nests inside context engineering. A harness is everything in an agent except the model itself. Building one is a specific form of context engineering, which is what the canonical source says, not a discipline that replaces it.

What belongs in project context

A working rule: include what a new senior engineer would need on their first week and could not get by reading the code.

Include

• Architecture, and the reasoning behind its shape. Not a diagram of what the directories are, an explanation of why the boundaries fall where they do.
• Decisions with rationale. What was chosen, what was rejected, and what would have to change for the decision to be revisited.
• Rules with scope. “Handlers return typed errors” is useful. “Handlers under src/api/ return typed errors, and here is the shape” is applicable.
• Specs for boundaries. The contracts other code depends on, stated so a change can be measured against them.
• Plans in flight. What is half-done, so a new session continues instead of restarting.

Exclude

• Code. The agent can read it.
• Anything secret. Project context is as public as the repository.
• Personal preferences. Those belong in your own tool settings, not in the team’s shared truth.
• Anything you will not maintain. Stale context is worse than absent context, because the agent believes it.

What it looks like in practice

Engineered context is a set of typed documents that the agent loads selectively. Here is a rule scoped to a directory:

---
title: "API handlers return typed errors"
status: accepted
---

## Rule

1. WHEN a handler under `src/api/` fails, the handler MUST return an
   `APIError` with a stable `code` field.
2. The handler MUST NOT return a bare string or a raw driver error.

## Rationale

The client maps `code` to user-facing copy and to retry behaviour. A raw
driver error leaks schema details and has no stable identity to map.

Two things make that usable as context rather than as documentation. It is scoped, so it is delivered when the agent edits something under src/api/ and not otherwise. And it is typed, so the agent knows this is a binding rule rather than a suggestion or a historical note.

How Archcore implements it

Archcore is a git-native context layer for AI coding agents, and it is built directly on the five properties above.

• Explicit and structured. Project knowledge lives as typed Markdown documents in a .archcore/ directory: specs, architecture decisions, rules, plans, and project knowledge, with named relations between them and a draft → accepted → rejected lifecycle.
• Selective. Session hooks inject the documents that apply to the file being edited, at the moment of the edit. Agents pull full documents on demand through MCP rather than receiving everything at session start.
• Versioned. The directory sits in your repository, so a change to a rule is a diff in a pull request and travels on the same branch as the code it governs.
• Portable. The CLI serves the same directory to every MCP-aware agent, and the plugin adds skills, slash commands, and guardrails on the hosts that support them.

curl -fsSL https://archcore.ai/install.sh | bash
cd your-project && archcore init

archcore init scaffolds the directory, detects your agents, wires MCP and hooks, and imports the instruction files you already wrote.

Where to start

You do not need a complete map of your system before this pays off. Start with the smallest useful thing and let it accumulate.

1. Write down the decision you are tired of re-explaining. One ADR, with the rationale and the rejected alternative.
2. Scope one rule to one directory. Pick the convention your agent breaks most often.
3. Record the next decision when it happens, rather than reconstructing history.
4. Review context in pull requests, so it stays true as the code moves.

The measure of success is not how many documents exist. It is whether the agent stops guessing about the things you have already settled.

For a worked comparison of instructions and delivery, read context engineering vs prompt engineering.