The AGENTS.md file has become the canonical way for a code repository to communicate to the AI agents and harnesses context about the repo.
Unsurprisingly, pretty much all AGENTS.md file examples you can find talk specifically about the code in the repo, engineering conventions, and other technical topics.
From my personal experience with Claude and other agents, the AGENTS.md files miss the major trick of talking about the product itself and product standards, not just engineering content.
Product managers (PMs) should also contribute to the AGENTS.md file itself, and contribute linked files.
While building Satisfy CX, the product-specific content after many iterations resides mainly in two sections in AGENTS.md (plus separate documents - see later):
The terminology section is easy: it names and describes the product, the different parts of it, and the internal codenames.
The core tenets are where it gets interesting.
For Satisfy CX, core tenet 0 is literally titled “Humans are in charge”. The opening sentence says “The absolutely most important key product philosophy for Satisfy CX is that it’s AI that helps humans. The human is always in control and the final decider.” and goes on to explain the product philosophy in more detail. The product philosophy is the purview of the product team.
Engineering and product go hand in hand, so more product points also come up elsewhere in the file. Some other core tenets are:
Have these been useful? Massively!
They are regularly cited when brainstorming, and help guide recommendations from agents and the small decisions during the code writing. The consistency and accessibility points have produced better HTML UIs, and are an easy way for a “check against @AGENTS.md” to quickly get better results if a review finds shortcomings.
Because the product team has to be in sync with engineering, it’s important product’s needs be reflected in AGENTS.md. This is even more important when the delivery cadence and volume increase with the help of AI.
Two simple ways to illustrate this are product requirements documents (PRDs) and kanban boards.
Keeping PRDs, and plans and documentation in general, in sync with engineering is a very nice and useful addition to AGENTS.md.
The delivery increase means that important decisions and issues can get lost in history. Importantly, good plans include a very detailed checklist (for the coding agent, but also for humans to keep track) that is updated as the implementation progresses.
The upshot is that AGENTS.md gets a workflow friction point (see later) and a retrospective audit: if a build doesn’t have an attached plan committed to the repo, a loud “THERE IS NO PLAN!!1” message is shown.
Most of the time, the link between the code commit/PR and the plan was forgotten, so it’s a quick fix.
But sometimes a hotfix needs to be deployed ASAP, like the service is down or similar. That’s why it’s a point of friction, not a block. Hotfixes should not spend time on detailed planning (that’s for the post mortem). This means that the planning process encoded in AGENTS.md should make sure the daily work is principled and robust, but never stop engineering.
The retrospective audit is an out-of-process check that runs regularly and flags any code that doesn’t have an associated plan and isn't tagged as a hotfix. This keeps the delivery cadence honest. While it’s easy to bypass the initial friction point during a quick push, the audit ensures accountability catches up.
Like many projects, Satisfy CX uses kanban boards to keep track of delivery. This is where all the product integration from AGENTS.md comes together. The situation that’s now set up is:
The plan<->link is hardcoded in the repo.
The upshot is that another process in AGENTS.md is that the agents create and monitor the card’s column in the Kanban board. This requires custom Github API integrations, and it works beautifully. Note that engineering needs to build this integration.
All that said, this approach of keeping everything in-repo allows PMs and others to answer questions quickly without bothering engineering.
Because each plan comes with an approved checklist that’s kept updated, anyone can check on the status of the work. It’s easy to ask the coding agent AI to verify that the checklist is up to date (against the committed code) and what’s left to do. A good checklist includes human tasks, like “the business needs to decide on this point”, or “someone needs to deploy this to staging” (never give agents direct access to servers!), and the AI can flag these tasks.
This is important: The AGENTS.md file is a core part of the context sent to AI agents, and it eats up part of the AI’s input.
Keeping it short frees up the input for other important parts: your actual prompt, the code files, any images. A PM co-owning the AGENTS.md file must not treat it like a recipe website explaining why your grandmother’s cat inspired you to change the world. Make your words count.
How? Instead of bloating the root AGENTS.md, structure it as a lean index. Keep core product tenets and domain terminology in the root file (say 100–200 words each), but offload active PRDs and task tracking to linked sub-paths or local specs (e.g., docs/specs/ or prompt-driven sub-directories). This preserves precious context windows while keeping product goals top-of-mind for coding agents.