AGENTS.md Template
An AGENTS.md template gives AI coding agents the project context a new developer would need: how to set up the repo, which commands to run, the conventions to follow, how to test, and what not to touch. Use this free AGENTS.md template to write one plain markdown file at the root of your repository, so agents work the way your team does.
Download for Word
Claude
ChatGPTI need to write an AGENTS.md. Act as an expert technical writer and draft one for me. Use this structure, keeping each section clear, concise, and genuinely useful to the reader: 1. Project overview 2. Setup 3. Commands 4. Code style and conventions 5. Testing 6. Commits and pull requests 7. Boundaries 8. Architecture notes 9. Where to find more Before you begin, ask me for the details you need: the product, team, or audience this is for, and anything specific I should include. Then write the full AGENTS.md in clean, well-formatted Markdown.
Write an AGENTS.md using the structure below. Keep each section clear, concise, and genuinely useful to the reader. Structure: 1. Project overview 2. Setup 3. Commands 4. Code style and conventions 5. Testing 6. Commits and pull requests 7. Boundaries 8. Architecture notes 9. Where to find more Use rich formatting so it reads well in a knowledge base: - Clear headings and subheadings for each section. - Callout boxes for asides: a Tip callout for advice, a Note callout for helpful context, and a Warning callout for anything a reader must not miss. - Tables for structured or comparison content. - Numbered lists for sequential steps and bulleted lists for options. - Bold for key terms and any values people must not get wrong.
Connected HelpDocs over MCP? Add "save this as an unpublished HelpDocs article" to the prompt and the draft lands in your knowledge base, ready to review.
## The AGENTS.md template ### 1. Project overview Wrap up the project in two or three sentences, covering what it does, the languages and frameworks it runs on, and the layout of the repository. After that, list the top-level folders and describe what each one contains. ### 2. Setup Spell out the precise steps for reaching a working environment: which tool versions you need, how you install the dependencies, which environment variables you set, and which services must be running. Show every command exactly as you'd type it. ### 3. Commands The commands your agent relies on most, with a short note explaining each one. | Task | Command | Notes | | --- | --- | --- | | Install | TODO | TODO | | Build | TODO | TODO | | Test | TODO | TODO | | Lint and format | TODO | TODO | ### 4. Code style and conventions Document the conventions your team sticks to, covering formatting, naming, file layout, the libraries you favor, and the patterns you steer clear of. Link to your config files (linters, formatters) instead of restating their rules, and flag anything a tool can't detect on its own. ### 5. Testing You'll want to cover how to run the whole test suite and a single test, where the tests are kept, and what new code is expected to meet. Also say whether a change counts as done only once its tests pass. ### 6. Commits and pull requests The way you write commit messages, how you name branches, what belongs in a pull request description, and the checks that have to pass before anyone reviews it. ### 7. Boundaries State what the agent isn't allowed to do. Be specific. - Paths you should mark off limits for editing (generated code, vendored libraries, lock files) - Credentials and secret values that must never land in a commit or show up in printed output - Commands the agent shouldn't run (destructive database operations, production deploys) - Any change that has to go through a human review first ### 8. Architecture notes A few things are hard to figure out from the code by itself: how the major pieces communicate, the key design choices, and gotchas people already run into. If you've got one, link to the fuller [technical documentation](/templates/technical-documentation/). ### 9. Where to find more Point at the README, the contribution guide, your internal docs, and any other spot a person or agent should check for background.
The AGENTS.md template
Add an AGENTS.md file to the top level of your repo and use the headings shown below. Fill each section with details specific to your own project rather than the sample guidance. Brief, straightforward instructions land better than lengthy explanations.
1. Project overview
Wrap up the project in two or three sentences, covering what it does, the languages and frameworks it runs on, and the layout of the repository. After that, list the top-level folders and describe what each one contains.
2. Setup
Spell out the precise steps for reaching a working environment: which tool versions you need, how you install the dependencies, which environment variables you set, and which services must be running. Show every command exactly as you’d type it.
3. Commands
The commands your agent relies on most, with a short note explaining each one.
| Task | Command | Notes |
|---|---|---|
| Install | TODO | TODO |
| Build | TODO | TODO |
| Test | TODO | TODO |
| Lint and format | TODO | TODO |
4. Code style and conventions
Document the conventions your team sticks to, covering formatting, naming, file layout, the libraries you favor, and the patterns you steer clear of. Link to your config files (linters, formatters) instead of restating their rules, and flag anything a tool can’t detect on its own.
5. Testing
You’ll want to cover how to run the whole test suite and a single test, where the tests are kept, and what new code is expected to meet. Also say whether a change counts as done only once its tests pass.
6. Commits and pull requests
The way you write commit messages, how you name branches, what belongs in a pull request description, and the checks that have to pass before anyone reviews it.
7. Boundaries
State what the agent isn’t allowed to do. Be specific.
- Paths you should mark off limits for editing (generated code, vendored libraries, lock files)
- Credentials and secret values that must never land in a commit or show up in printed output
- Commands the agent shouldn’t run (destructive database operations, production deploys)
- Any change that has to go through a human review first
8. Architecture notes
A few things are hard to figure out from the code by itself: how the major pieces communicate, the key design choices, and gotchas people already run into. If you’ve got one, link to the fuller technical documentation.
9. Where to find more
Point at the README, the contribution guide, your internal docs, and any other spot a person or agent should check for background.
Tip
Agents only do their best work when the docs they lean on stay fresh. Start a free HelpDocs trial so your internal documentation lives in one searchable home that AI tools can pull from.
How to fill in this AGENTS.md template
Your AGENTS.md file isn’t useful unless it’s accurate. These routines keep it that way:
- Get commands exactly right. An agent won’t fill in gaps, so copy them from a terminal where they already work instead of relying on memory.
- Give rules, not explanations. A line like “use the shared date helper in utils” helps an agent more than a long paragraph on date handling.
- Make limits explicit. Agents follow stated instructions much better than ones left to interpretation.
- Stay concise. Point to the longer docs instead of duplicating them here, so the file stays quick to maintain.
- Keep it in sync with the code. Whenever a command or convention shifts, touch AGENTS.md in that same pull request.
- Try it out. Have an agent work through a small task with just the file, then correct anything it handles wrong.
To see how documentation can work better for AI, check out our guide on how AI uses your knowledge base.
Go further
- HelpDocs MCP server Let Claude, ChatGPT and your agents read and write your docs.
- llms.txt, and whether it's worth publishing What llms.txt is, what the evidence says about whether anything reads it, and when it's still worth having.
- Using MCP with your knowledge base What MCP for documentation changes about the work, what it is genuinely good at, and where to stop.
