Summary of "How I Write My AGENTS.md Files - Best Practices"

How I Write My AGENTS.md Files — Best Practices

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.

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).

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.

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.”
Provide concrete examples rather than long prose
- For coding style, prefer “bad example → corrected example” over long textual descriptions.
Specify stack and exact versions
- State precise versions (e.g., Python 3.12+, package manager, DB such as SQLite3, frameworks).
Include a project structure / file tree
- A pasted tree output or brief outline helps agents locate files and understand app responsibilities.
Define coding conventions via examples
- Show examples for camelCase vs snake_case, type hint usage, etc., instead of exhaustive prose.
Add ground rules and boundaries
- Examples: “Never delete files with rm”, “Never run git commands” (note: agents may ignore these if asked directly).
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.
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.

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).

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.

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.”