1. Instruction files in every repository
Each project has a short, version-controlled instruction file that both tools read at the start of every task: AGENTS.md for Codex and CLAUDE.md for Claude Code. It records the stack, how to build and test, coding conventions and hard rules. It is reviewed in pull requests like any other code, so the AI’s understanding of the project improves as the project does.
# Project context for AI assistants (example)
## Stack
- API: Python 3.12, FastAPI, PostgreSQL 16
- Web: React + TypeScript
## Commands
- Tests: make test Lint: make lint
## Conventions
- Every API change updates the OpenAPI spec and adds tests
- Configuration comes from environment variables, never from code
## Never
- Edit migrations that have already shipped
- Add a dependency without explaining why in the PR
2. A spec before a prompt
AI works from the ticket, not from memory. Every task starts with a clear description, acceptance criteria and links to the relevant design notes or API contract. If we can’t write the spec, the task isn’t ready for AI, or for a person.
3. One task, one session
Long conversations drift: early instructions get diluted and old assumptions linger. We keep sessions focused on a single task and start fresh for the next one. When a session does get long, we summarise what matters and continue from the summary rather than dragging the whole history along.
4. Curate, don’t dump
We point the AI at the modules, interfaces and tests that matter for the task instead of pasting entire repositories or thousands of log lines. Secrets, credentials and personal data are never part of the context.
5. Decisions live outside the chat
Anything worth remembering goes somewhere durable: architecture decision records, pull-request descriptions and short hand-off notes at the end of each AI-assisted task. The next engineer, or the next AI session, starts from that record, not from a chat history.
6. Connect tools deliberately
Agents can connect to issue trackers, documentation and other systems (for example through the Model Context Protocol). We only connect what a task needs, with the least access that works, and only where the client has agreed.
7. Let tests close the loop
Good context tells the AI what to build; tests tell it whether it worked. Agents run the project’s tests and linters as part of each task, and CI stays the single source of truth.
Why it matters to you: well-managed context is the difference between AI that saves days and AI that creates rework. It is also why our AI-assisted work comes with better documentation: the context we write for the AI is useful to your team too.