AGENTS.md Contract
Each generated template now ships with an AGENTS.md file— a focused operating contract for AI assistants (Cursor, Copilot Chat, PR bots) powered by agents.md.
Purpose
Separate human docs from AI guidance
Humans read README + docs/*. AI assistants read AGENTS.md for rules, guardrails, and execution steps.
Guardrails
Reduce hallucinations + unsafe changes
Explicit refusal cases, escalation triggers, and validation reminders keep AI changes scoped + safe.
Workflow
Reinforce expected execution flow
Encourages read-before-write, plan-before-apply, and explicit assumption surfacing.
Generated Example (FastAPI Template)
A trimmed example of the AGENTS.md shipped with the FastAPI starter template.
# AGENTS.md – AI Interaction & Execution Guide (Human contributors: see CONTRIBUTING.md & docs/)
This file is intentionally scoped **only** for AI assistants (Cursor, Copilot Chat, PR automation bots).
Humans: read CONTRIBUTING.md and the documents under docs/.
## 1. Authoritative References (Never Reproduce Content Here)
| Topic | Source of Truth |
|-------|-----------------|
| Project architecture | docs/PROJECT_STRUCTURE.md |
| API route patterns | docs/API_GUIDELINES.md |
| Settings & env vars | docs/CONFIGURATION.md |
| Database / ORM usage | docs/DATABASE.md |
| Testing strategy | docs/TESTING.md |
| Deployment notes | docs/DEPLOYMENT.md |
## 2. Operating Principles (AI Perspective)
- Documentation-first
- Reuse-before-build
- Type hints always (mypy/pyright clean)
- Deterministic, incremental changes
- Explicit assumption logging
## 3. AI Execution Protocol (FastAPI Feature Work)
When asked to add/modify API behavior:
1. Locate the relevant router or service module under src/
2. Read related docs/* referenced above
3. Prefer extending existing dependency-injection patterns
4. Show proposed file tree + diff plan BEFORE writing code
5. After code: list follow-up validation steps (ruff, mypy, pytest)
## 4. Guardrails (Must Enforce)
- Do NOT fabricate file paths, settings keys, or package versions
- Do NOT bypass pydantic validation or typed settings without rationale
- Do NOT add sync I/O inside async route handlers without explicit approval
- ALWAYS flag large dependency additions (>1 lib) for human confirmation
- ALWAYS surface potential performance regressions (N+1 queries, blocking calls)
## 5. Endpoint Creation Checklist
- Typed request/response models (Pydantic v2)
- Router registered in the app factory
- Settings read via pydantic-settings, not raw os.environ
- Test added or explicitly deferred with reason
- OpenAPI tags and summaries updated when applicable
## 6. When the AI Should Ask or Refuse
Ask for clarification if: feature scope unclear, conflicting patterns, missing target module.
Refuse if: asked to bypass validation, remove type checks, or duplicate existing documented endpoints.
## 7. Post-Change Assistant Report
Return a bullet summary:
- Files touched (concise)
- New dependencies (if any)
- ruff/mypy/pytest status
- Suggested manual QA steps
- Deferred items (tests, docs)
---
Maintained automatically by create-awesome-python-app FastAPI template provisioning.
Humans: stop reading—go to CONTRIBUTING.md + docs/.
Customizing Your AGENTS.md
Adapting for your team
Feel free to extend sections (Guardrails, Protocol, Refusal Conditions) but avoid duplicating rich procedural docs—link to existing sources instead.
- Add domain-specific escalation triggers (security, data, billing)
- Reference internal design system docs instead of re-stating variants
- Include CI scripts or task runners (e.g.
uv run pytest,uv run ruff check .) if not obvious - Keep tone imperative and concise—optimize for machine parsing + embedding