How to give an AI coding agent your project context so it stops guessing

What the agent knows about the project at the start

Nothing beyond what is in the folder. It does not remember yesterday’s conversation, does not know that this service is deprecated, that server is production, or that you dislike extra dependencies. If it is not in the files, the agent infers it from the code and may get it wrong.

Signs that context is missing:

• the agent studies the project structure from scratch every time and spends the limit on it;
• it proposes solutions the project banned long ago;
• it asks what you already explained in the last session.

Put the essentials into CLAUDE.md or AGENTS.md

Claude Code reads CLAUDE.md in the project root at start, Codex reads AGENTS.md. That is the place for what every task needs:

• what the project is and who it is for, in two lines;
• how to run, build and check it: exact commands;
• where to look: which folders do what;
• bans: what not to touch and why;
• where the detailed docs live.

Keep the file short. It goes into the context of every conversation in full, and an extra page there costs tokens on every turn. Move details into separate docs and keep links to them in the main file.

If you work with both agents, keep the same content in both files or make one point to the other.

Do not spend the project file on agent manners

A common mistake: half of CLAUDE.md is “be brief”, “do not make things up”, “do first, write after”. Those are behaviour rules, not project knowledge.

Hedoq already has such rules. Every agent gets a starter set: answer briefly, no greetings, do the work first, say plainly when it does not know or did not check. The set is on by default and is turned off with “Brief agent answers” in the settings. So the project file can go entirely to the project.

Keep detailed docs in the repository

Architecture notes, decisions and their reasons, how deployment works: keep them in a docs/ folder next to the code, not in a chat or personal notes. Then:

• the agent reads them when needed, not on every turn;
• docs are updated in the same change as the code;
• a new person or a new agent reads the same thing.

A good habit: at the end of a task, ask the agent to update the relevant doc. Describe how things work now, not a dated log.

Hedoq uses the same idea in automations: the agent leaves a description and a summary of what was done in the folder, and the next agent reads them first.

Give exact paths, not descriptions

“Fix the form on the checkout page” makes the agent search. “Fix src/pages/checkout/Form.tsx” goes straight to the point. In Hedoq you insert a path without typing:

• drag a file from Finder onto the session: its path lands in the field;
• in the file tree, each row has a button that inserts the path into the session;
• an image from the clipboard (⌘V) is saved as a file and its path is inserted;
• in the built-in browser, “Show the model”: point at an element on the page, click and add a note. The session gets a link to the element description and a screenshot.

Keep context between sessions

A conversation with an agent ends; the project does not. When the conversation gets long, it matters not to lose what you explained along the way.

In Hedoq, “Refresh session” asks the agent for a note before clearing: the project and where it lives, your standing rules and bans from the conversation, what is done, what is next, and a “Read” section with full paths of the docs it needs. The new conversation starts from that note. More: long tasks without losing the thread.

Where projects live: in Hedoq, the project for a new session is picked from the Hedoq Space folder in your home folder, or Hedoq creates a new one there. Keep your working projects there and they are at hand in the “New session” window.

If a rule from the conversation will matter later too, ask the agent to move it into CLAUDE.md or AGENTS.md. Then you never repeat it.