CORE GUIDE
Repository context
Repository context is the code, conventions, tests, dependency boundaries and local history an AI coding agent needs to make a change that fits the actual system rather than producing plausible isolated code.
Mental model
Treat a repository as an execution environment with contracts, not as a bag of source files. The relevant context is the smallest set of files, interfaces, tests and conventions that constrain the requested change.
Why it matters
Coding models can generate syntactically valid patches while violating architecture, duplicating helpers, ignoring migration rules or changing behavior outside the task. Good repository context gives the agent enough evidence to reason locally without dumping the entire codebase into one prompt.
01
Discover the change boundary before editing
Start from the requested behavior, locate its entry point, tests and nearest contracts, then follow imports or call paths only as far as needed to understand dependencies. Include repository instructions, build commands and relevant recent patterns. After editing, use the diff and targeted tests to discover whether the inferred boundary was too narrow and expand context deliberately.
02
Example: a new API client duplicates an existing retry layer
An agent sees one service file and adds its own retry loop around an HTTP call. Elsewhere the repository already centralizes retries and idempotency in a shared client, so the patch doubles retries in production. Inspecting the shared client, nearby tests and dependency conventions before editing would have made the correct boundary visible.
Common failure modes
- Loading the whole repository without deciding which evidence constrains the task.
- Editing the first matching file while ignoring callers, tests and shared abstractions.
- Treating README-level context as a substitute for executable repository evidence.
Engineering heuristics
- Map entry point, contract, tests and dependencies before modifying code.
- Expand context when evidence reveals a wider change boundary, not by default.
- Use the final diff and regression tests as feedback on whether repository context was sufficient.
Takeaways
- 01Repository context is task-specific evidence about system contracts.
- 02More files are not automatically better context.
- 03A correct patch must fit the repository's architecture and verification path.
Reading evidence
This records actions you actually took; it does not claim mastery, proficiency, or certification.
Used in
This Concept is reused across these canonical learning paths.
Related concepts from the Knowledge Graph
These relationships come from the canonical graph, not a separate Guide taxonomy.