A smaller context file for the next coding session

A coding agent context file can begin as a helpful note and slowly become a cupboard: setup instructions, old debugging advice, architectural history, and reminders nobody remembers adding. Before adding another paragraph, try a simpler question: does the agent need this information for most tasks?

Treat the file as a short orientation, not a complete account of your project. Aim to help the agent start in the right place, follow important boundaries, and check its work.

§ Start with the file your tool reads

A context file is a plain-text document containing instructions for a coding agent. Codex uses AGENTS.md for persistent project guidance. Its documentation describes how instructions are collected from different directory levels, so location matters as well as content. ([developers.openai.com](https://developers.openai.com/codex/guides/agents-md))

Claude Code uses CLAUDE.md for project instructions. Its guidance recommends keeping that file concise and removing material the agent can discover by reading the code. ([code.claude.com](https://code.claude.com/docs/en/best-practices))

Gemini CLI uses GEMINI.md for instructional context and supports context discovery at different scopes. Do not assume that every tool loads the same filenames or directories in the same way. Check the tool you actually use. ([github.com](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md))

For a beginner, start with one file for one tool. Avoid maintaining three near-identical copies before you have a practical reason to support three workflows.

§ Keep the instructions that change a decision

For a first draft, choose a modest editing budget, such as one screen of text. This is a writing constraint, not a technical limit. Give each sentence a job:

• Orientation: explain what the project does in one sentence.
• Commands: name the verified setup, test, and formatting commands.
• Boundaries: identify generated files or sensitive areas that should not be edited casually.
• Local conventions: record unusual rules that are not obvious from nearby code.
• Further reading: point to the document needed for a particular kind of change.

Prefer a concrete instruction over a general ambition. Instead of “write excellent tests,” specify the relevant test command and any project-specific requirement. Copy commands from your working setup; do not invent commands simply to fill the section.

Try a deletion test: if removing a sentence would not change a useful action, leave it out. Claude Code's documentation recommends pruning instructions and checking whether behavior actually changes. ([code.claude.com](https://code.claude.com/docs/en/best-practices))

§ Separate permanent guidance from today's task

Put the current bug, acceptance criteria, and temporary investigation notes in the task prompt or issue. Reserve the context file for guidance you expect to remain useful next week.

For example, “checkout currently fails after a discount” belongs with the bug report. “Payment changes require the checkout integration tests” is a candidate for lasting guidance, provided that rule reflects your actual process.

Keep long explanations in ordinary project documentation. In the context file, name the document and explain when to consult it: “Before changing database tables, read docs/migrations.md.” Treat that as a reading instruction, not proof that the document has already been loaded.

§ Trim it after a real session

After a small coding task, review the result before expanding the instructions. Did the agent miss a command, edit a generated file, or misunderstand a local convention? Add a short correction only when it addresses a repeatable problem.

Review stale commands and duplicated rules alongside code changes. Keep credentials out of the file, and use tests and permission controls for boundaries that must be enforced.

§ Keep project guidance separate from API access

Vana API provides one endpoint for accessing multiple model families. That connection is a separate concern from the instructions you maintain in your repository. ([vanaapi.com](https://vanaapi.com/)) Keep provider configuration outside the context file unless the project genuinely needs an explanation of it.

If you want to try Vana API with your coding workflow, create an account. Start with one small task and a short context file, then revise the instructions from what you observe. The goal is not the shortest possible file. It is a file where every instruction earns its place.