Skip to content

Teaching your coding agent with AGENTS.md

Here's the one meta tip that changes everything: if there's anything you want your LLM coding agent to remember for future sessions, just tell it to "Please update AGENTS.md with..." and then specify what you want it to remember. That's it.

This chapter is adapted from a blog post I wrote that explores how to effectively use AGENTS.md to train your coding agent.

What is AGENTS.md

AGENTS.md is an emerging open standard that's been adopted by over 20,000 repositories on GitHub. Think of it as a README for your AI coding agents. It's a predictable location where you provide context, instructions, and preferences that your agent needs to work effectively on your project.

You might think of this as similar to ChatGPT's memory feature, but there's a crucial difference: AGENTS.md is explicitly curated by you. You decide exactly what the agent remembers and how it applies that knowledge. I prefer this approach because it means I have control over what the agent knows, rather than the agent autonomously deciding what to remember about me and my preferences. It's transparent, version-controlled, and intentional. Best of all, I can use this to steer the agent's behaviour towards the standards I enforce within the repository.

The format emerged from collaborative efforts across OpenAI, Google (Jules), Cursor, Factory, and other major players in the AI development space. It's just standard Markdown, which means it's accessible, portable, and fits naturally into any project structure.

While your README.md is optimized for humans, covering project introductions, contribution guidelines, and quick starts, AGENTS.md serves as machine-readable instructions for your coding agents. Setup commands, testing workflows, coding style preferences, and project-specific conventions all live here.

Training an employee, not programming a bot

I was inspired by NetworkChuck's approach to building Terry, his N8n automation agent. The philosophy framing he uses is both brilliant and yet practical: you're not programming a bot, you're training an employee.

In Terry's case, Chuck teaches the agent by continuously updating its system prompt with new instructions and context. The same principle applies perfectly to AGENTS.md in coding environments.

Here's what makes this powerful: AGENTS.md gets sent with every LLM API call in Cursor, Claude Code, GitHub Copilot, and other modern coding tools. This means you can standardize on AGENTS.md, and as you progress through your project, you effectively teach the LLM what to do by instructing it to update this file with your preferences and learnings.

The beauty is that these instructions persist across sessions. Your agent doesn't forget; it gets smarter as your project evolves.

Enforce markdown standards automatically

One of my first uses for AGENTS.md was ensuring consistent markdown formatting. I asked my coding agent to update AGENTS.md with instructions to always run markdownlint on any markdown files it creates or edits.

The effect is immediate. Now, anytime my agent writes or edits a markdown file, it automatically runs markdownlint and fixes issues. I don't have to remember to ask for this. The agent just knows it's part of the workflow.

In my Llamabot project, I've documented this pattern explicitly. Here's what the AGENTS.md file says:

Markdown Linting: markdownlint is a global tool that can be run directly without the "pixi run" prefix. Use markdownlint filename.md instead of pixi run markdownlint filename.md. If markdownlint is not available, install it using pixi global install markdownlint.

Markdown Linting: Always run markdownlint on any markdown file that you edit. Use markdownlint filename.md to check for issues and fix them before committing.

Documentation Workflow: When editing any markdown file, always run markdownlint after making changes to ensure proper formatting and catch any issues before the user sees them.

This simple instruction means I never have to manually check markdown formatting again.

Specify your testing style

I prefer writing tests as pytest style functions rather than unittest-style classes. Most LLMs default to the unittest approach because it's more prevalent in their training data.

So I instructed my agent to add this preference to AGENTS.md. Now when I ask for tests, I consistently get pytest style functions. The agent is steered toward my preferred approach without me having to specify it in every request.

In Llamabot's AGENTS.md, I've also documented the specific test configuration. Here's what it says:

Testing

  • Framework: pytest with coverage reporting
  • Config: Tests run with pytest -v --cov --cov-report term-missing -m 'not llm_eval' --durations=10
  • Exclusions: Tests marked with llm_eval are excluded from default runs
  • Structure: Tests mirror the source structure in the tests/ directory

This level of detail ensures the agent understands not just the style, but also the specific workflow for running tests in that project.

Stop writing throwaway test scripts

Here's a pattern I noticed with Cursor: when the agent wants to test something, it loves to write little throwaway scripts. You know the type: test_random_thing.py or quick_check.py that do some ad hoc verification and then just sit there cluttering your project.

The problem is these scripts aren't real tests, yet they're also tests. They don't run with your test suite. They don't provide ongoing regression protection. They're just there.

I taught my agent to write proper tests instead. Now when the agent needs to verify something works, it writes an actual test that becomes part of the project. These tests continue to provide value by catching regressions, documenting expected behavior, and running in CI.

The shift is subtle but powerful: instead of creating technical debt in the form of random scripts, you're building up a proper test suite. In Llamabot's AGENTS.md, I've made this explicit. Here's what it says:

Code Style

  • Testing: Always add tests when making code changes (tests mirror source structure in tests/ directory)

This instruction ensures the agent builds proper test coverage rather than creating one-off verification scripts.

Teach your agent about new tooling

I recently adopted Pixi as my main package manager. The problem? Most LLMs aren't familiar with Pixi commands yet. They kept trying to run python directly when I only have Python available through Pixi.

The solution was to teach the agent through AGENTS.md. In my Llamabot project, I've documented this explicitly. Here's the exact section from the AGENTS.md file:

CRITICAL FOR LLM AGENTS: All commands must be run with the pixi run prefix to ensure they execute within the pixi environment. Never run commands directly without this prefix. This is essential for proper dependency management and environment isolation.

Examples: - ✅ pixi run test (correct) - ❌ pytest (incorrect - will fail) - ✅ pixi run pytest tests/specific_test.py (correct) - ❌ python -m pytest tests/specific_test.py (incorrect - will fail)

This works for any new tooling. If you've adopted pixi or uv or any other modern Python tools that aren't well-represented in LLM training data, you can explicitly teach your agent how to use them through AGENTS.md.

The same principle applies to any domain-specific tools or workflows unique to your project. For example, in Llamabot, all notebooks are Marimo notebooks, which have a relatively strict syntax. Here's what the AGENTS.md file says:

Notebooks: All notebooks in this repository are Marimo notebooks. When agents create or edit notebooks, they must run uvx marimo check <path/to/notebook.py> to validate the notebook and fix any issues raised by the check command. Always run uvx marimo check on notebooks before considering them complete - this catches critical errors like duplicate variable definitions and other Marimo-specific issues. CRITICAL: Fix ALL issues found by marimo check, including warnings. Do not leave any warnings unfixed.

This ensures notebooks are written correctly the first time and prevents syntax errors from propagating.

Why this matters

The traditional approach to working with coding agents involves repeating yourself constantly. "Remember to use this format." "Don't forget to run this command." "We prefer this style here."

AGENTS.md flips this model. Instead of being a human repeating instructions to a forgetful assistant, you're building up institutional knowledge that persists. You're training your agent to work the way you work.

As one developer observed, it's all about simple human psychology: you get immediate feedback and results. You write it once, and your AI assistant immediately becomes more useful. The feedback loop is much longer with READMEs.

This is the key insight. When you write a README, you're creating documentation for a future human reader who may or may not show up. When you write AGENTS.md, you get instant gratification. Your next conversation with the agent immediately reflects what you just taught it. The AI won't judge you for weird conventions or hacky workarounds. It just learns and applies what you've documented.

Each time you discover a preference, a gotcha, or a best practice for your project, you can capture it in AGENTS.md. The next time your agent encounters a similar situation, it already knows what to do.

This is especially powerful in larger projects or monorepos. You can have AGENTS.md files in subdirectories, and agents will use the nearest file to the code being edited, similar to how .gitignore or ESLint configs work. This lets you provide context-specific instructions for different parts of your codebase.

Secondary benefits: onboarding and knowledge transfer

There's a powerful secondary benefit to having a well-curated AGENTS.md that I didn't fully appreciate until I saw it in action. I had a colleague who wasn't necessarily well-versed in programming, but he was learning Python and getting things done with a coding agent. One day, I saw code he had written in his repository. It was beautiful: fluent functional style classes with method chaining. I was impressed. "Dude, how did you do that?" I asked. "That code looks beautiful. How did you know to write it that way?"

He freely told me: "Oh, actually it was AI that did it. And it turns out those instructions were in AGENTS.md. It's all because of you."

I was surprised. What? Oh, okay. Yeah.

Here's what happened: by having a well-curated AGENTS.md file that specified my preferred coding style, the AI agent was teaching my colleague that style as he worked. He wasn doing more than getting code written; he was learning how to write code the way I prefer it. The agent became a silent mentor, consistently applying the patterns and conventions I had documented.

This is a powerful point. If you're opinionated about how code should look, and that's okay -- everyone should have opinions -- you can help influence and onboard less experienced colleagues onto that style simply by having a well-curated AGENTS.md file. You're not just training an agent; you're creating a knowledge transfer mechanism that scales. When someone uses an AI coding assistant in your repository, they're not just getting help, but rather are adopting learning your conventions, your preferences, and your style. The agent teaches them as they work.

This is especially valuable for teams. Instead of having to manually review every pull request and explain style preferences over and over, your AGENTS.md file does the teaching automatically. New team members learn your conventions by working with an agent that already knows them. It's like having a pair programming partner who never forgets the style guide.

What a real AGENTS.md looks like

Let me show you what this looks like in practice. In my Llamabot project, the AGENTS.md file has grown to include specific instructions about package management, testing workflows, code style preferences, and project-specific conventions.

For code style, here's what the file says:

Code Style

  • Functional over OOP: Prefer functional programming except for Bot classes (PyTorch-like parameterized callables)
  • Docstrings: Use Sphinx-style arguments (:param arg: description)
  • Testing: Always add tests when making code changes (tests mirror source structure in tests/ directory)
  • Linting: Automatic linting tools handle formatting (don't worry about linting errors during development)
  • File Editing: When possible, only edit the requested file; avoid unnecessary changes to other files
  • No "Private" Functions: Do not create functions prefixed with underscores (e.g., _helper_function). Python doesn't need this convention - if a function is only used internally, it can simply be a regular function without the underscore prefix.

These aren't abstract guidelines; they're concrete instructions that the agent follows automatically. This level of detail might seem excessive at first, but remember: you're not writing this for humans to read. You're writing it for an agent that needs explicit, unambiguous instructions. The more specific you are, the better your agent will perform.

Getting started

If you already have agent instruction files like .cursorrules, CLAUDE.md, or .github/copilot-instructions.md, you can simply rename them to AGENTS.md. Most modern coding agents now support this standard.

Start simple. Create an AGENTS.md in your project root and add one or two critical preferences. Then, as you work with your agent, whenever you find yourself giving the same instruction twice, add it to AGENTS.md instead.

The key insight is this: every time you teach your agent something, make it permanent by updating AGENTS.md. That's how you build an agent that truly understands your project.

See it in action

If you want to see what a well-curated AGENTS.md file looks like in practice, take a look at the Llamabot repository's AGENTS.md. It demonstrates how these principles work together in a real project, with specific instructions for package management, testing, code style, and project-specific conventions.