Write the house rules file every agent loads

Vibe codingMedium25 minAnthropic and OpenAI style

Your task

Your team of 25 engineers works on one large Python service, and everyone uses a coding agent. Each agent starts every task knowing nothing about the repo, so reviews keep catching the same mistakes. Agents use requests instead of the team's HTTP client, write raw SQL strings and put tests in the wrong place. You are writing the shared AGENTS.md that every agent loads at the start of every task.

Write the file.

What you know:

  • Python 3.12, FastAPI, SQLAlchemy 2.0 and pytest; make check runs lint, type checks and tests
  • app/orders/ is the team's model feature: data access in app/repos/order_repo.py, tests in tests/orders/, and tests always mirror the path in app/
  • outbound HTTP goes through client from app/clients/http.py, which adds retries, timeouts and tracing
  • settings load once, as settings in app/config.py
  • database access goes through repository classes in app/repos/
  • app/payments/ belongs to another team, and merged Alembic migrations in migrations/versions/ are never edited
  • CI already enforces formatting with ruff format

Then, in a few sentences: what should stay out of the file, and how do files like this usually fail?