Building software with a team of AI agents feels a bit like managing a group of incredibly eager, brilliant, but wildly unpredictable junior developers. They work at lightning speed and possess vast knowledge, but left to their own devices, they tend to lose the plot. Give an agent a simple feature request, and without strict boundaries, it might try to rewrite your entire frontend or introduce a massive relational database you don’t need.
I recently hit this friction point while building Pouta CMS. Because Pouta relies strictly on a serverless architecture within the Cloudflare ecosystem—specifically leveraging Pages, R2 storage, and Worker AI—there is zero room for architectural drift. Furthermore, maintaining the boundary between the GPLv3 open-source core and the SaaS Pro tier is critical.
I needed a way to dictate exactly how my Lean AI team interacts with the repository. The solution was surprisingly simple: an AGENTS.md file.
Dictating the Machine
An AGENTS.md file acts as the single source of truth for any AI agent touching your codebase. Think of it as the ultimate onboarding document. When an agent enters the repository, it reads this file to understand the hard technical constraints, the formatting standards, and the architectural philosophy of the project.
However, writing a comprehensive rulebook manually is tedious and prone to human oversight. Instead of writing it myself, I decided to let the machine dictate to the machine.
Generating the Rules with agy
To create the perfect AGENTS.md, I used Antigravity (agy). The premise was straightforward: an AI agent is only as good as its context.
Instead of typing out isolated instructions, I fed agy my existing, carefully crafted documentation. I provided:
- My input on the desired workflow.
- *The **
README.md(The *What and the Why of Pouta CMS). - *The **
ARCHITECTURE.md(The *How—detailing the strict serverless approach). By synthesizing these documents,agygrasped the exact boundary conditions of the project. It understood that we don’t just write code; we write code specifically optimized for Cloudflare workers and R2. It understood the separation of concerns between the open-source and premium tiers.
What Actually Goes Into AGENTS.md?
The resulting file generated by agy established non-negotiable rules for the rest of my Lean AI team. While the specifics are tailored deeply to Pouta, the core directives look something like this:
Infrastructure Supremacy: All storage solutions must default to Cloudflare R2. Do not suggest or implement traditional relational databases or alternative cloud providers. License Awareness: Any code modifications must respect the GPLv3 license of the core project. Features designated for the SaaS tier must be cleanly separated and not leaked into the open-source repository. Lean Execution: Do not introduce heavy external dependencies unless absolutely necessary. Rely on native web APIs and serverless patterns.
The Result: A Calibrated SDLC
Implementing AGENTS.md completely transformed my Software Development Life Cycle.
The immediate benefit was a drastic reduction in AI hallucinations. I no longer have to spend my mental energy micromanaging the agents’ architectural choices. When I ask an agent to draft a new content management feature, it inherently knows to hook it up to R2 storage rather than asking me how I want to store the data.
Treating your AI agents like a real engineering team means providing them with the structural context they need to succeed. By using agy to synthesize my project’s architecture into an AGENTS.md file, my Lean AI team is finally pulling in the exact same direction.