How I Write My AGENTS.md Files - Best Practices

How I Write My AGENTS.md Files — Best Practices

What Agents.md is

• agents.md is an open, vendor-agnostic plain-text/Markdown format for supplying persistent instructions and context to coding AI agents.
• It is supported/usable across different agent platforms (examples: Cursor, Claude, Google/Gemini-style systems).
• Purpose: keep recurring environment, style, and workflow constraints centrally defined so agents follow project-specific conventions without repeating the same prompt every conversation.

Keep a single source of truth for environment and workflow rules so agents consistently follow project conventions.

Demo setup (what the presenter did)

• Simple Django “sample project” used as a sandbox. utils.py contains math functions.
• Demo: asked an LLM (demo used “sonnet 4.5”) to implement a function (nth Lucas number).
  • Without agents.md: agent used defaults (no type hints, incorrect command patterns).
  • With a root agents.md containing rules (e.g., “always use type hints”), the agent adapted and produced type-hinted code even if existing files lack hints.
  • Added a local (per-folder) agents.md in the mathematics app to override the global rule (e.g., “never use type hints here”). The agent honored the local override while keeping other rules (e.g., camelCase).

Key technical / practical points and behavior

• Platforms that support agents.md treat these files as contextual instructions; you don’t need to paste the same instructions into each prompt.
• You can compose multiple agents.md files (root + per-directory). More specific files can override broader ones.
• Not foolproof: agents can still ignore boundaries (for example, run git commands or rm) if explicitly instructed — agents.md helps reduce mistakes but doesn’t guarantee safety.

Best practices and recommended content

1. Put commands early
   • Specify how to run project commands so agents use the correct invocation.
   • Example: for Django + uv workflows, state something like “use uv; all Python commands must run with uv run.”
2. Provide concrete examples rather than long prose
   • For coding style, prefer “bad example → corrected example” over long textual descriptions.
3. Specify stack and exact versions
   • State precise versions (e.g., Python 3.12+, package manager, DB such as SQLite3, frameworks).
4. Include a project structure / file tree
   • A pasted tree output or brief outline helps agents locate files and understand app responsibilities.
5. Define coding conventions via examples
   • Show examples for camelCase vs snake_case, type hint usage, etc., instead of exhaustive prose.
6. Add ground rules and boundaries
   • Examples: “Never delete files with rm”, “Never run git commands” (note: agents may ignore these if asked directly).
7. State workflow constraints and environment details early
   • Example: migrations must be run via uv run manage.py migrate, or how to set up Tailwind/Vite/React.
8. Prefer a single central file for global rules, with local agents.md for exceptions
   • Use local files to disable or alter rules for specific directories/apps.

Use cases called out

• Ensuring correct commands and package manager usage (e.g., Django + uv example).
• Environment-specific installs (Tailwind + Vite + React) where agents often fail without explicit instructions.
• Docker or package-manager setups.
• Testing and contribution workflows (can be referenced from a central agents.md or linked CONTRIBUTING.md).

Limitations / cautions

• Agents may still perform unsafe or undesired operations if explicitly instructed (e.g., running git or deleting files).
• agents.md reduces repeated mistakes but cannot fully enforce behavior.
• If the codebase lacks consistent typing/style, align agents.md with existing code to avoid friction.

What to include in your agents.md (concise checklist)

• Project overview and purpose
• Environment and exact versions (Python, package manager, DB, frameworks)
• Command examples (real, correct command lines)
• Coding style examples (bad/correct snippets)
• Project tree / file map
• Explicit rules and boundaries
• Any per-directory agents.md for local overrides

Sources / main speakers

• Video presenter / author (YouTuber demoing the workflow; unnamed in subtitles)
• Agents.md best-practices documentation referenced in the video
• Demo project: “sample project” (basic Django app used in the walkthrough)
• Agent platforms and models referenced: Cursor, Claude, Gemini-style agents; demo model noted as “sonnet 4.5.”