listen/AGENTS.md

AGENTS.md — Guidance for AI coding agents

Purpose: short, actionable guidance for coding agents working in this repository.

Quick facts

• Python: >= 3.13 (see pyproject.toml).
• Run app: uvicorn app.main:app --reload (see app/main.py).
• Docker: docker-compose up -d (see docker-compose.yml).
• Migrations: alembic upgrade head (see alembic.ini and alembic/).
• Tests: pytest (configuration in pyproject.toml; tests under app/tests).

What agents should know (concise)

• Use the project's README for onboarding steps and environment setup: README.md.
• Dependencies are declared in pyproject.toml; dev extras include pytest, pytest-asyncio, pytest-xdist, and ruff.
• Tests create temporary databases (see app/tests/conftest.py) and rely on docker-compose for a PostgreSQL service when needed.
• The app entrypoint is app.main:app; routers are in app/api.
• Alembic is configured for async SQLAlchemy—use the repository's alembic folder for migrations.

Agent behavior recommendations

• Prefer linking to existing docs instead of copying long sections; follow "link, don't embed".
• When suggesting code edits, reference the exact file(s) and include minimal, focused patches.
• Run tests locally with pytest -q and use -k to target changed areas during iteration.
• Respect the project's Python version and typing/mypy strictness.

Next customizations to consider

• Add a small .github/copilot-instructions.md if repository owners want per-repo agent role presets.
• Create a /.vscode or devcontainer quickstart note for reproducible developer environments.

Relevant files

• README.md
• pyproject.toml
• app/main.py
• alembic.ini
• app/tests/conftest.py