Skip to main content

How to write AGENTS.md file

Connect docs via MCP

AGENTS.md is an open, README-style Markdown file that tells AI coding agents how to work in your repository. The spec lives at agents.md and has no required sections. The most effective files include exact setup commands, code-style rules, testing instructions, and explicit boundaries, kept under roughly 300 lines.

If your project integrates with the Atlan MCP server, point agents at the metadata, lineage, and glossary context they need to query before generating data code.

note

AGENTS.md isn't the same as Atlan context agents. AGENTS.md is an external community standard for coding agents, the tools that write code in your IDE. Atlan's context agents in Context Agents Studio are a separate product capability for metadata enrichment. The currently available agents are Description, README, and SQL Intelligence. Link Terms is coming soon.

Prerequisites​

  • A code repository where AI coding agents (Codex, Cursor, Copilot, Aider, Jules, Windsurf, Zed, or similar) operate.
  • A text editor.
  • Optional: access to an Atlan tenant if you want agents to query Atlan context. Remote MCP is enabled for all Atlan tenants.

Create your AGENTS.md file​

The spec requires no template. The patterns below come from analysis of public AGENTS.md files and from the canonical examples on agents.md.

  1. Create a file named AGENTS.md at the root of your repository.
  2. Write a one-line project description as the opening paragraph.
  3. Add a ## Setup commands section with exact install, dev, and test commands an agent can copy-paste.
  4. Add a ## Code style section with executable rules: formatter, line length, import order, language version.
  5. Add a ## Testing section naming the test framework and the command to run it.
  6. Add a ## Boundaries section using the three-tier pattern: Always, Ask first, Never.
  7. Commit the file. Agents read it the next time they operate on the repo.
note

Keep AGENTS.md under roughly 300 lines. Practitioner consensus keeps files between 60 and 300 lines. Files longer than that consume token budget without improving outcomes.

Minimal example​

The shape below mirrors the canonical example on agents.md:

# Sample project

This is a Node.js library that exposes a CLI for converting CSV to JSON.

## Setup commands
- Install deps: `npm install`
- Start dev: `npm run dev`
- Run tests: `npm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible

## Testing
- Framework: Vitest
- Run a single test: `npm test -- <file>`
- Add tests for every new function

## Boundaries
- Always: run `npm test` before declaring work complete
- Ask first: changes to `package.json` dependencies
- Never: commit secrets, edit `.github/workflows/` without review

For a real-world non-code example, the Atlan marketing team's repository ships an AGENTS.md under 200 lines, scoped to Markdown content and light Python automations. It shows the under-300-line guideline applied outside a pure software codebase.

Work with nested AGENTS.md files in monorepos​

In a monorepo, agents read the closest AGENTS.md, walking from the working directory up to the repo root. Subprojects can override repo-wide rules without restating them.

  1. Keep a root AGENTS.md with conventions that apply everywhere.
  2. Add a subproject-level AGENTS.md only when its rules differ from the root.
  3. State the override explicitly. For example: "This subproject uses Python 3.11, not Node.js."
tip

The "nearest file wins" rule is the precedence model. There is no merge, no inheritance, and no override syntax. Local files replace the root for that directory tree.

Reference Atlan context from AGENTS.md​

If your repository contains code that queries data assets, such as analytics pipelines, dbt models, BI dashboards, or agent harnesses, your AGENTS.md can point coding agents at the Atlan MCP server before they generate SQL or transformations. Atlan MCP gives AI tools access to governed metadata so they can search and discover assets, explore lineage, and update metadata using real-time context from Atlan.

Example block to drop into AGENTS.md:

## Data context
- Before writing SQL, query the Atlan MCP server for asset metadata,
  column-level lineage, and business glossary terms.
- Prefer governed asset names from the glossary over names inferred
  from raw column headers.
- MCP setup: see the team runbook for the canonical endpoint list.

For setup instructions per coding tool, see Atlan MCP, Set up Claude Desktop with Remote MCP, Set up ChatGPT with Remote MCP, or Set up Cursor with Remote MCP.

Common pitfalls​

  • Autogenerating from /init commands. Research shows autogenerated AGENTS.md files often perform worse than no file at all.
  • Including discoverable information. Don't restate what package.json, pyproject.toml, or the README already says. Agents can read those files directly.
  • Writing past 300 lines. Token budget is finite. Cut anything an agent couldn't act on.
  • Conflicting tool-specific files. If CLAUDE.md says one thing and AGENTS.md says another, agents that read both produce inconsistent output. Pick one source of truth.
  • Vague boundaries. "Be careful with the database" isn't useful. "Never run migrations on production without explicit user confirmation" is.

See also​