Agents read your repository. That covers most of what they need — but not the decisions that live in people's heads, in a wiki, or in a conversation from two years ago.
Project context is where you put the rest.
What Coroid works out on its own
From the repository alone, agents can see:
- the languages, frameworks and libraries in use
- how the project is built, tested and run
- existing patterns — how errors are handled, how modules are structured, how things are named
- what depends on what
You do not need to document any of this. Restating it is wasted effort and risks going stale against the code, which is the more authoritative source anyway.
What it cannot infer
The code shows what you did, never why:
- a library chosen over an obvious alternative for a reason that still applies
- a pattern that looks like duplication but is a deliberate seam
- a module nobody should touch without talking to a specific team
- conventions you have agreed but not yet enforced anywhere
- constraints from outside the codebase — compliance, contracts, a migration in flight
This is what belongs in project context. The test is simple: could someone reading only the repository work this out? If yes, leave it out. If no, write it down.
Adding context
Attach documents, policies and references under the project's Context section. Architecture notes, decision records, style guides and API contracts all work.
Good context is short and specific. A 40-page onboarding guide written for humans is mostly narrative; the three paragraphs in it that state real constraints are what matter. Extract those.
Per-task context
Context attached to the project applies to everything. For something relevant to one piece of work — a ticket, a design document, a customer report — attach it to the task instead.
Keep project context for what is durably true. A task-specific note in project context becomes noise on every future task.
Keeping it honest
Context that has drifted out of date is worse than no context, because agents treat it as authoritative. When a convention changes, update the context in the same change that changes the code.
If you find yourself repeatedly correcting the same thing in rework comments, that is a signal something is missing from context — or that something in it is wrong.