metis: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to any coding agent working on this repository.

Standards

This is a production-grade codebase. All contributions must meet the following bar:

• Code quality: Clean, readable, well-structured code. No shortcuts, no hacks, no "good enough" solutions. Every function should be purposeful and every abstraction justified.
• Performance: Optimized by default. Async where it matters, efficient data structures, minimal allocations, no N+1 queries, no unnecessary re-renders.
• Security: Zero tolerance for vulnerabilities. Input validation at boundaries, parameterized queries, proper auth checks, no secrets in code, OWASP top 10 awareness at all times.
• Error handling: Graceful degradation, meaningful error messages, proper logging. No silent failures, no bare excepts, no swallowed errors.
• Type safety: Full type hints (Python) and strict TypeScript. No Any unless absolutely unavoidable. Types are documentation.
• Testing mindset: Write code that is testable. Dependency injection, clear interfaces, no hidden side effects.
• Consistency: Follow existing patterns in the codebase. Match naming conventions, file organization, and architectural patterns already established.

Project Overview

Metis is an AI-powered GitHub code reviewer that provides intelligent, context-aware feedback on pull requests. The system uses a GitHub App to receive webhook events, analyze code changes, and post automated reviews.

Architecture: Monorepo with separate backend (Python/FastAPI) and frontend (React/TypeScript/Vite).

Commands

Backend (Python/FastAPI)

Navigate to backend/ for all backend commands:

cd backend

# Development
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Celery worker (async task processing)
celery -A app.core.celery_app worker --loglevel=info
celery -A app.core.celery_app flower --port=5555  # Monitoring UI

# Install dependencies (using uv)
uv sync

# Database
docker-compose -f docker-compose.dev.yml up -d  # Start PostgreSQL + Redis + pgAdmin + Redis Insight
alembic upgrade head                             # Run migrations
alembic revision --autogenerate -m "description" # Create migration
alembic downgrade -1                             # Rollback one migration
alembic history                                  # View migration history

# Code quality
ruff check .              # Lint
ruff format .             # Format
mypy app/                 # Type check
pytest                    # Run all tests
pytest tests/unit         # Run unit tests only
pytest tests/integration  # Run integration tests only
pytest -v -k test_name    # Run specific test

# Pre-commit hooks
pre-commit install
pre-commit run --all-files

# Services
docker-compose -f docker-compose.dev.yml up -d     # Start all services
docker-compose -f docker-compose.dev.yml logs -f   # View logs
docker-compose -f docker-compose.dev.yml down      # Stop all services