social-app/AGENTS.md

Docker Startup

Always start services with the env file:

docker compose --env-file .env -f docker/docker-compose.yml up -d

Python Environment

MUST use uv for dependency management and virtual environment execution.

• All Python commands: uv run <command>
• Add dependencies: uv add <package>
• All dependencies declared in pyproject.toml

Code Quality Checks

Git pre-commit hook enforces code quality before commit.

Pre-commit hook automatically runs on api/ directory:

• ruff check - code style and linting
• basedpyright - type checking with error level

If any error detected, commit is rejected. Fix errors before committing. Do not bypass or weaken checks (no ignores, disables, or config relaxations). Resolve the underlying issues.

TDD First Policy

Principle: tests before implementation.

Coverage Requirements

• Minimum coverage: 80%
• Required test types:
  • Unit: isolated functions, utilities, components
  • Integration: API endpoints, database operations
  • E2E: critical user flows (Playwright)

Limited Exceptions

• Docs-only changes (README, comments, formatting) may skip integration/E2E
• Non-runtime config changes may skip E2E if no behavior changes
• Any runtime code change requires unit + integration + E2E
• If an exception is used, record the reason in the PR/test notes

Mandatory TDD Workflow

1. Write tests (RED) - they must fail
2. Run tests - confirm failure
3. Implement minimal code (GREEN) - only to pass
4. Run tests - confirm success
5. Refactor (IMPROVE)
6. Verify coverage - must be 80%+

Enforcement

• Must use the tdd-guide agent for new features
• Do not write implementation before tests
• Do not lower coverage requirements
• Must include unit, integration, and E2E tests