Build An AGENTS.MD File Step By Step

An AGENTS.md file is a single Markdown file in your repo root. It tells AI coding agents how to work. It covers build steps, tests, and rules.

Follow these steps to build one for a Python FastAPI project.

  1. Define the stack Start with one sentence. Tell the agent the language, framework, and database. Example: A URL shortener API in Python using FastAPI, SQLite, and pytest.

  2. Provide setup commands Give the agent real commands to run. Do not use placeholders.

  • Setup: python -m venv .venv && source .venv/bin/activate
  • Run: uvicorn app.main:app --reload
  1. Set the testing bar This is vital. The agent uses tests to check its own work.
  • Run pytest
  • Run ruff check
  • Run mypy
  1. Map the structure List your folders so the agent does not have to search every file.
  • app/main.py: route handlers
  • app/db.py: SQLite access
  • migrations/: generated SQL (do not edit)
  1. Define conventions Be specific. Vague rules are useless.
  • Use Pydantic for all input validation.
  • Raise HTTPException for client errors.
  • Type everything to keep mypy clean.
  1. List the "Don'ts" Prevent mistakes by setting hard boundaries.
  • Do not hand-edit migrations.
  • Do not commit directly to main.
  • Never run seed scripts on non-local databases.

Why this works When you give an AI agent a task like "Add a DELETE endpoint," it reads this file first.

With an AGENTS.md file, the agent:

  • Knows exactly where to add code.
  • Uses your specific testing tools.
  • Follows your style without asking questions.
  • Opens a branch instead of breaking your main code.

Without this file, the agent guesses. It might use the wrong test runner or edit files it should not touch.

Treat this file like code. If your workflow changes, update the file immediately. A stale file leads to errors.

Source: https://dev.to/wolfejam/agentsmd-hands-on-build-one-step-by-step-and-watch-an-agent-use-it-3g27

Optional learning community: https://t.me/GyaanSetuAi