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

Explore More

Back to Docs View Templates

# 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/.