flowCreate.solutions

AGENTS.md Creation Guide

This guide explains how to write a high-signal AGENTS.md file that reliably steers AI agents and automated contributors.

Required placement

  • AGENTS.md must live at the repository root.

Required structure

AGENTS.md should follow this structure:

  1. What this repo is
  2. How the repo is organized (top-level folder map + notes)
  3. Where the main docs live (must be docs/ at repo root)
  4. Hard rules for agents
  5. How to work in this repo (workflow + verification)
  6. Escalation policy
  7. What “done” looks like

Hard rules section (minimum set)

Include the rules you care about most. Common examples:

  • Migrations: who owns migrations; when agents must not create/modify revisions.
  • Security: sanitization, authz boundaries, rate limiting, input validation rules.
  • Scope: what directories are allowed to change without explicit approval.
  • No secrets: never add secrets or private URLs to docs, code, or trackers.

Workflow guidance (keep it short and enforceable)

Use clear imperatives:

  • Read the relevant standards doc first.
  • Verify claims against source code before documenting them.
  • If behavior is ambiguous, ask the project lead.
  • Prefer safe-by-default changes; avoid bypasses.

Keep it maintainable

  • Use bullet lists and short sections.
  • Prefer links to internal docs over duplicating long explanations.
  • Prefer linking to shared workflow playbooks instead of restating them. For Git/GitHub workflow, link to: docs/playbooks/git/workflow.md.
  • Update it when new modules, workflows, or constraints are introduced.

Required docs reference (must-have line)

Every AGENTS.md must explicitly state:

  • The main documentation lives in the root docs/ folder, and
  • The recommended starting point (for example docs/readme.md or docs/index.md, whichever the repo uses).

Required folder map (must-have list)

Every AGENTS.md must include a short “module map” of the repo root, for example:

  • docs/ — main documentation entrypoint + deeper guides
  • src/ or app/ — primary application code
  • tests/ — automated tests mirroring module boundaries
  • trackers/ — tracking docs (trackers/files/), only when explicitly requested

Keep it concise: 6–12 bullets is usually enough.