Project Context for AI Coding Agents

Reference · Updated August 10, 2026

Project context is the knowledge about a specific codebase that an AI coding agent needs and cannot obtain by reading the code: the architecture and the reasoning behind its shape, the decisions already made, the rules the team enforces, the contracts its boundaries must hold, and the work currently in flight.

It is the answer to a question every agent session asks implicitly and no repository answers: what is already true here?

The gap project context fills

A coding agent arrives at your repository with a good model of programming in general and no model of this system in particular. It can read every file. It still cannot read:

• Why the payments module is split from billing, so it merges them back.
• What was rejected. The library you evaluated and dropped looks like a reasonable choice to a model that never saw the evaluation.
• What is binding. A convention followed in eleven files and broken in two reads as ambiguous.
• What is in progress. A half-finished migration looks like inconsistency to clean up.
• What has scope. A rule that applies to src/api/ and not elsewhere is invisible if it lives in a chat message.

None of this is in the code, because none of it can be in the code. It is the layer above: intent, constraint, and rationale.

What belongs in project context

The useful filter is what a new senior engineer would need in week one and could not get by reading source.

What does not belong: code (the agent reads it), secrets (context is as public as the repository), personal preferences (those are tool settings, not team truth), and anything you will not maintain. Stale context is worse than missing context, because an agent believes it.

Project context and agent memory are different things

These get conflated constantly, and the distinction decides what you should build.

Memory is genuinely useful for personal preferences and session continuity. It is the wrong instrument for the engineering record, because the engineering record has to be authoritative, shared, and reviewable, and a log of past conversations is none of those.

The same logic separates project context from retrieval. Searching the codebase surfaces what the code says. It cannot surface a rationale that was never committed.

Persistence is the hard part

Every team that has tried this arrives at the same problem: the context is easy to write once and hard to keep true.

Three failure modes account for most of it.

The wall of text. One instruction file grows past the point where anything can be found in it. It has no types, so nothing distinguishes a binding rule from a stale note; no scope, so everything arrives on every turn; no lifecycle, so a superseded decision sits next to the one that replaced it.

The parallel copy. A second agent gets its own file. Now two files disagree and neither is authoritative.

The document nobody reads. Context written into a wiki is not delivered to the agent at the moment it matters, so it stops being read and then stops being true.

The fixes are structural, not editorial: typed documents so kind is machine-readable, scope so delivery can be selective, relations so a reader can walk from a file to the rule that governs it, a lifecycle so supersession is visible, and one store that serves every agent.

Where project context should live

In the repository it describes. That is not a stylistic preference, it follows from what the context has to do.

• It changes when the code changes, so it should travel on the same branch.
• It needs review, and the team already reviews diffs.
• It must survive a change of tools, which rules out a vendor’s store.
• It belongs to the team, not to whoever happened to write it in their client.

This is the argument git-native context makes in full.

How Archcore stores and delivers it

Archcore is a git-native context layer for AI coding agents. Project context lives as typed Markdown in a .archcore/ directory inside your repository.

.archcore/
  architecture/
    read-write-split.adr.md        # the decision, with rationale
    session-api.spec.md            # the contract for a boundary
  api/
    typed-errors.rule.md           # scoped to src/api/
  auth/
    migration-q3.plan.md           # work in flight
  run-and-test.guide.md            # how to run this repo

Each document carries a type, a status, and named relations (implements, extends, depends_on, related), so an agent can walk from the file it is editing to the rule that governs it and the decision that explains why the rule exists.

Delivery is the half that makes it context rather than documentation:

• Session hooks inject the applicable documents when the agent edits a file, so guidance arrives at the moment of the edit.
• MCP tools let the agent search, read, and write documents during real work, pulling what it needs rather than receiving everything at session start.
• One store, every agent. The CLI serves the same directory to eight MCP-aware agents; the plugin adds slash commands and guardrails on the four hosts that support plugins.

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 CLAUDE.md, AGENTS.md, and .cursorrules you already wrote as typed documents.

Starting small

The instinct is to document the system. Resist it: a large first pass produces documents nobody validated and nobody maintains.

1. Write the decision you are tired of repeating. One ADR, with the rejected alternative.
2. Scope one rule to one directory. The convention your agent breaks most often.
3. Spec the boundary that breaks other people’s code.
4. Record the next decision as it happens, instead of reconstructing history.
5. Review it in pull requests so it stays true.

You will know it is working when the agent stops asking about the things you already settled, and when a teammate’s session starts from the same understanding as yours.