Overview
Context is the single most important factor in agent code quality. The best SWE agents don't just rely on the prompt — they ingest rich context from the repository, the task source, and team conventions before writing a single line of code. This page documents the state of the art in agent context engineering.
AGENTS.md
Open SWE popularized the AGENTS.md convention: a file at the repository root that encodes conventions, testing requirements, architectural decisions, and team policies. The agent reads it immediately after cloning and treats it with the same authority as the system prompt.
| Project | AGENTS.md Support | Notes |
|---|---|---|
| Open SWE | ✅ Native | Reads AGENTS.md after clone; mandatory rules |
| OpenHands | ⚠️ Plugin | Custom prompts via configuration |
| Cline | ⚠️ Custom | Supports custom instructions in settings |
| Aider | ❌ No | Uses CONVENTIONS.md or custom prompts |
| xCoder | ✅ Native | AGENTS.md is first-class; supports multiple |
Pre-Hydration Strategies
Pre-hydration means assembling context before the agent starts working, rather than letting it discover everything through tool calls. Stripe Minions call this "context pre-loading" and it is a key performance optimization.
- Issue/PR context — Full title, description, comments, and linked issues from Linear/GitHub.
- Slack thread history — Entire conversation thread when triggered from Slack.
- Repo conventions —
AGENTS.md,CONTRIBUTING.md, CI configs, linter rules. - Recent changes —
git log, recent PRs, commit history for context on current work. - Related files — AST-based dependency analysis to find files likely relevant to the task (Aider's repo map approach).
Source Context Assembly
Different triggers require different context assembly strategies:
| Trigger | Context Sources | Assembly Strategy |
|---|---|---|
| Linear issue | Issue title, description, comments, project links, related issues | Fetch via Linear SDK; include full thread |
| Slack mention | Thread messages, shared URLs, referenced files, channel history | Slack API thread resolution; summarize if >50 messages |
| GitHub PR comment | PR description, diff, review comments, CI status | GitHub API; include full PR context + review threads |
| Manual prompt | User text, referenced files, current branch, recent commits | Parse file references; include AGENTS.md |
Repo Maps
Beyond the conventional files, advanced agents build a "repo map" — a semantic graph of the codebase. Aider pioneered this with tree-sitter AST parsing to identify function definitions, imports, and relationships.
- Aider repo map — Tree-sitter AST → tag index → ranked file selection. Best-in-class for finding relevant code.
- Grep-based — Simple text search for symbols mentioned in the task. Fast but misses semantic relationships.
- Embedding-based — Vector search over file embeddings for semantic similarity. Powerful but requires embedding pipeline.
- Import-graph — Static analysis of import/module relationships. Good for typed languages (TypeScript, Rust, Go).
xCoder's Approach
xCoder implements a multi-layer context system:
- Layer 1: AGENTS.md — Read immediately on every run; cached per repo; supports multiple AGENTS.md files for monorepos.
- Layer 2: Trigger context — Pre-hydrated from Linear/Slack/GitHub before the agent loop starts.
- Layer 3: Repo map — Hybrid approach: tree-sitter AST for structure + embeddings for semantic search + import graph for dependency relationships.
- Layer 4: Session memory — Persistent across runs for the same task/thread; stores decisions, failures, and successful patterns.
Research recommendation