Context Files

Agents execute against your codebase. Context files make sure they understand the things your codebase doesn't say out loud.

Architecture decisions, deprecated patterns, service boundaries, external API quirks — the institutional knowledge that lives in engineers' heads, made available to every agent run without any per-engineer setup.

What context files are

Concept

Context files are project-level documents that agents read before claiming an objective. They encode what the codebase doesn't say out loud.

A well-written codebase tells an agent what the code does. Context files tell an agent what the team has decided — and why. Which modules are deprecated. Which service owns authentication. Which patterns were tried and abandoned. Which third-party API has a known rate limit that isn't in the docs. This is institutional knowledge that lives in engineers' heads, not in code, and that agents have no way to infer. Context files make it explicit, at the project level, available to every agent run without any per-engineer setup.

Context files vs. CLAUDE.md

Comparison

CLAUDE.md is per-repo, per-developer. Context files are per-project, per-team.

CLAUDE.md

Checked into the repository. Read by any agent with access to the repo. Scoped to repo-level conventions — commit format, test commands, linting rules, local dev setup. Maintained by whoever controls the repo. Best for technical setup that belongs in the codebase.

Context files

Stored in Planwright at the project level. Read by agents via MCP before claiming an objective. Scoped to strategic and architectural knowledge — decisions, tradeoffs, constraints, deprecated paths, team conventions that aren't enforced by tooling. Maintained by the team in Planwright, independent of any repository. Best for knowledge that doesn't belong in code.

Use both. They complement each other. CLAUDE.md handles the mechanical; context files handle the institutional.

What to put in a context file

Content

Write what a new senior engineer would need to know before touching the project — and that they couldn't figure out from reading the code.

Include

Architecture decisions and the reasoning behind them — especially decisions that look wrong on the surface
Deprecated modules, patterns, or APIs that still exist in the codebase but must not be used
External service quirks: rate limits, undocumented behaviors, auth flows that differ from the official docs
Team conventions not enforced by linting — naming patterns, error handling style, how side effects are handled
Boundaries between services: which service owns what, which team to consult for cross-service changes
Known technical debt that should be worked around, not fixed, until a dedicated objective addresses it

Avoid

Content already in CLAUDE.md — redundancy creates drift when one copy is updated and the other isn't
Step-by-step task instructions — that's an objective, not context
Acceptance criteria for specific features — that belongs on the objective
Content that changes daily — context files are meant to be stable; volatile context belongs in the objective description

How agents consume context files

Agent workflow

Agents read context files at the start of every session, before claiming an objective.

The MCP workflow calls planwright_list_context_files immediately after set_repo, then planwright_get_context_file for each relevant file. This happens before planwright_claim_objective — so the agent is briefed before it posts a plan or writes a line of code. Files are fetched by name; agents can request specific files or read all files in the project. A well-structured context file library with clear file names lets agents pull only what's relevant for a given class of work rather than loading every file on every run.

MCP call order — context before claim

# Typical agent session startup
planwright_set_repo
planwright_list_context_files     # discover what's available
planwright_get_context_file       # read what's relevant
planwright_list_objectives        # find scheduled work
planwright_claim_objective        # claim and begin

Creating and updating context files

Management

Push context files via MCP or from CI. They are versioned in Planwright and the latest version is always what agents read.

Use planwright_push_context_file to create or replace a context file. Files are identified by name within the project — pushing a file with the same name replaces the previous version. There is no branching or staging environment for context files: the live version is what agents read. For teams who want to keep context files in sync with code, push from CI as part of the merge pipeline. A context file that describes the database schema, for example, can be regenerated and pushed automatically when the schema changes.

Push via MCP

planwright_push_context_file(
  name: "architecture-decisions",
  content: "...",
  description: "Key architectural decisions and the reasoning behind them"
)

Naming and organization

Structure

Use descriptive, kebab-case names. Agents use the file list to decide what's relevant — the name is the only signal they get before fetching.

architecture-decisionsHigh-level system design choices and the tradeoffs that drove them

deprecated-patternsCode paths, APIs, and approaches that exist but must not be introduced in new work

service-boundariesWhich service owns what, and where the boundaries between services sit

external-api-quirksThird-party service behavior that isn't in official docs — rate limits, auth edge cases, known bugs

data-modelCurrent schema overview, key relationships, and columns that are semantically important but not self-documenting

testing-conventionsWhat gets unit tested vs. integration tested, how test data is managed, what test helpers exist

← Planning Frameworks AI & Agents →