How to give your AI coding agent the context it needs
Before an agent plans a change, it needs a short, current description of the product. Write down who it is for, how it is built, which rules matter and how changes get checked, then keep it somewhere every session can read.
Before an agent plans a change, it needs to know what it is changing. Not everything you have ever discussed, and not a fresh explanation at the start of every session. A short, current description of the product: who it is for, how it is built, which rules matter, and how changes get checked.
That description is the context. It is worth writing down once and keeping somewhere your agent can read it, because the alternative is retyping the same background into every new chat and hoping you remember the same details each time.
This article covers what belongs in that reference, what does not, and how to tell when it has gone stale. The example throughout is a hiking app that helps people find and compare trails.
What belongs in the product reference
Four things earn a place. They are the same four areas a product proposal covers. That is not a coincidence. The proposal is where you work them out, and the reference is where you keep the answers.
Product information. What the app is, who it is for, and what the first version should do. Two or three sentences is usually enough. “A trail finder for people planning day walks. Browse trails, search by name, compare distance and difficulty. No accounts in the first version.” That tells an agent more than a page of feature ideas.
Tech stack. The languages, frameworks, storage and services actually in use. Name what is installed, not what you considered. If the app is a static site with a JSON file of trails, say so. An agent that assumes a database will propose a migration you do not need.
Architecture. How the parts fit together and the conventions you want followed. Where the data comes from, how the interface talks to it, and any rule that would be expensive to break later. Keep it to what a new contributor would need on their first day.
Testing. How you expect changes to be checked. Whether tests come before code, what a passing run looks like, and which failures matter most. Without this, an agent will invent its own standard and you will find out at review.
Write it in plain language. You are describing your own product to someone competent who has not seen it before, not producing a specification for a procurement process.
What does not belong
Two kinds of information are easy to mix up. One describes the product and stays useful across many changes. The other describes one change you want now, and it is finished once that change ships. “Add search by trail name” is the second kind. It belongs in the message you send today, not in the description you keep. If requests go into the description, it stops describing the product and becomes a list of everything you have ever asked for, and the agent has to guess which parts still apply.
Old conversation transcripts do not belong either. They are long, they repeat themselves, and they contain decisions you have since reversed. If a decision still matters, write the decision. Leave the discussion out.
Nor does everything you know. A reference that tries to capture every detail becomes another thing to maintain, and a stale detail is worse than a missing one, because the agent has no way to tell which is which.
The hiking app example
Here is what the split looks like in practice. The reference stays stable across many changes. The request changes every time.
In the reference: A trail finder for people planning day walks. Browse trails, search by name, compare distance and difficulty. Static site, trail data in a JSON file, no accounts. Tests run with the existing test command. A change is done when the list still loads and search returns partial matches.
In the request: Add a difficulty filter next to the search field. Keep the existing list behaviour and don’t change the trail data.
Notice what the request does not repeat. It does not explain what the app is, where the trail data lives, or how the interface is built. Those are already in the reference. The request only says what is different about this change.
That gives you a test for whether something belongs in the reference. Will it still be true after this change ships? If yes, it is context. If no, it is a task.
Spotting context that has gone stale
Every reference drifts. You change a database, drop a framework, or decide the first version will have accounts after all. The description does not update itself.
Three habits keep it honest:
- Update it in the same session as the change. When a decision changes the stack or the architecture, edit the reference before you close the session. It takes a minute, and it is when you still remember why.
- Read it before you brief. Skim the reference before writing the request. You will catch the line that no longer matches what you built.
- Watch for the agent asking. If an agent keeps asking a question the reference should answer, the answer is either missing or wrong. Both are worth fixing.
We get it. You get busy, and this kind of administration is easy to put off until it becomes exhausting. That is the argument for a tool that reminds you and makes the update quick, rather than one more document you have to remember to maintain.
One quick check is to ask your agent to read the reference and describe the app back to you in a few sentences. If the description surprises you, the reference is out of date.
Where to keep it
The simplest option is a file in the repository, such as a short product note or a section in your agent instructions. It travels with the code, it is versioned, and any tool can read it.
The limitation is that a file only helps if the agent is told to read it, and different tools load different files by default. If you work across more than one coding tool, you end up maintaining the same description in several places, or repeating it in each session.
Giljo HQ, a structured workspace for AI software builders, keeps the reference with the product instead. Product information, tech stack, architecture and testing are stored as product context. During staging, that context helps the orchestrator prepare the mission and the work assignments, so the plan starts from the same description every time.
Context Settings control what gets included. Product information and the project description are always on. Tech stack, architecture and testing are toggles. Depth is adjustable too: vision documents at 33, 66 or 100 percent, 360 Memory from the last 1, 3, 5 or 10 projects, and Git history from 5 to 100 commits when Git integration is on.
Keeping it current is the part most people drop, so Giljo HQ helps with that too. When the stored context drifts from the real code, you can generate a tuning prompt from the product card. Pick the sections to refresh, paste the prompt into your coding tool, and the agent compares the context with the codebase, shows its findings section by section, and applies only the changes you approve. You are still the one deciding what is true about your product; the comparison is the part you no longer have to do by hand.
Giljo HQ keeps count for you. Every ten finished projects, a banner offers a context review, with a button that takes you straight there. The banner also shows how many projects have finished since the context was last updated, so you can see how far it has drifted. Dismiss it and it returns after another ten.
Two things worth knowing. Turning a category off does not delete its records; it only leaves them out of the starting brief. And 360 Memory is not the same as the product reference. It holds what previous projects built, decided and found, so the next project starts with that history instead of rediscovering it.
If you would rather not use a tool for this, the file approach works. The discipline is the same either way. One current description, kept outside the chat, updated when the product changes.
Start with one page
You do not need a complete reference before the next change. Write the four sections on a page, fill in what you know, and mark what you are unsure about. Then brief the change and see whether the agent had what it needed.
If it asked for something the reference should have covered, add it. If it repeated a question you already answered, the answer was not specific enough. Two or three rounds of that and you have a reference that earns its place.
Our guide to writing a product proposal covers how to work out those four sections with an agent in the first place. If you are still deciding what to build next, the focus guide covers briefing a single change.
Was this useful?
A cookie remembers your mark. Feedback privacy.