Reducing the unknown with AGENTS.md
Copy-pasting blocks of code into ChatGPT is hopefully long gone, but the first problem I wanted to solve using tools like Claude Code, Cursor, GitHub Copilot, or OpenCode was reducing uncertainty of the outputs. These tools, combined with powerful AI models like Claude 4.5 Opus or GPT-5.2, perform very well on codebases, but bugs and hallucinations still happen.
This is where AGENTS.md comes into the picture: a simple markdown file that gives agents additional static context about the codebase for every prompt.
For reference, here is the AGENTS.md file for skateparks.gr. It contains instructions on the project's tech stack, how to run and test it locally, and how code quality is enforced. Personally, it has mostly replaced the need for a README file, as it is readable and insightful for both humans and agents alike.
The improvements in the quality of the coding agents outputs after the introduction of AGENTS.md are noticeable. To ensure lasting results the AGENTS.md needs to be update as the codebase evolves and interactions with the coding agents reveal pain points. The rule of thumb I try to keep is simple: If I notice the agent continuously failing on a task, AGENTS.md needs to be updated with a specific instruction on how to overcome it.
Links
This article is part of the series: "The Road to an agentic workload system".
