Giving AI agents useful project context
Clear project instructions help AI agents follow the conventions and constraints of an existing codebase.
Alexander Claes2 min read
When you start working in an unfamiliar codebase, you need to understand its structure, conventions and constraints. An AI agent needs that context too. Without it, even a working implementation can feel out of place.
An AGENTS.md file gives you somewhere to explain how the project should be approached, without repeating the same instructions for every task.
Make expectations concrete
“Keep things simple” sounds useful, but leaves plenty of room for interpretation. Asking an agent to follow an existing implementation, avoid adding dependencies or run specific checks gives it clearer boundaries.
Keep general project instructions in AGENTS.md and refer to more detailed documentation where needed. Relevant skills can provide guidance for specialised tasks.
The goal is to make the project’s expectations easy to find and apply.
Learn from repeated corrections
Over time, I find myself telling agents what not to do as often as what to do. An unnecessary abstraction or unrelated refactor can reveal an expectation I had never written down.
When you make the same correction repeatedly, update the guidance. Also check whether the codebase itself makes the intended approach clear. Conflicting patterns are difficult to resolve with instructions alone.
Useful project context grows out of actual work. A short set of specific instructions that you maintain is more helpful than a long file of rules you no longer read.