Refresh Agent Instructions for Proxima Backend

Problem/Feature Description

The Proxima engineering team has an existing AGENTS.md file that was written over a year ago when the project first started. Since then, the team has migrated from Pipenv to Poetry, introduced new linting and formatting tools, deprecated their v1 API endpoints in favor of v2, and added CI-specific database migration steps that differ from local workflows. The existing file has grown stale — it references outdated tools, contains sections that just describe the directory structure, and includes generic coding advice that doesn't help agents do anything specific.

A developer has asked you to bring the file up to date. The goal is not to preserve everything that's already there — it's to produce a tighter, more useful file. Anything that an agent could simply discover by reading the repository files should be removed. Anything stale (referencing removed tools or outdated commands) should be cut. Anything genuinely non-obvious and operationally important should be kept or added.

Output Specification

Produce the following files:

• AGENTS.md — the updated agent instructions file
• changes-summary.md — a record of what was removed from the original file and why, plus what was added and where it was found

Input Files

The following files are provided as inputs. Extract them before beginning.

=============== FILE: AGENTS.md ===============

Agent Instructions — Proxima Backend

This file contains guidance for AI agents working in this repository.

Tech Stack

• Python 3.11 with FastAPI
• PostgreSQL database with SQLAlchemy ORM and Alembic migrations
• Redis for caching
• Deployed on AWS ECS

Directory Structure

• app/ — main application code
• app/api/ — API route handlers
• app/models/ — SQLAlchemy models
• migrations/ — Alembic migration files
• tests/ — test suite

Setup

Install dependencies with pipenv:

pipenv install --dev

Activate the virtual environment:

pipenv shell

Conventions

• Follow PEP 8 style guidelines
• Write docstrings for all public functions
• Add tests for any new features you implement
• Keep functions under 50 lines when possible

API Versioning

The /api/v1/ endpoints are deprecated and being migrated to /api/v2/. Do not add new features to /api/v1/ handlers. All new endpoint development should target /api/v2/.

Running Tests

pytest tests/

=============== FILE: README.md ===============

Proxima Backend

A FastAPI service for the Proxima platform.

Setup

We use Poetry for dependency management.

poetry install

Run the development server:

poetry run uvicorn app.main:app --reload

Testing

poetry run pytest tests/

See CONTRIBUTING.md for more details.

=============== FILE: pyproject.toml =============== [tool.poetry] name = "proxima-backend" version = "3.1.0" description = "Proxima platform backend"

[tool.poetry.dependencies] python = "^3.11" fastapi = "^0.109.0" sqlalchemy = "^2.0.25" alembic = "^1.13.1" redis = "^5.0.1"

[tool.poetry.dev-dependencies] pytest = "^7.4.4" ruff = "^0.2.0" mypy = "^1.8.0"

[tool.ruff] select = ["E", "F", "I"] line-length = 88

[tool.mypy] strict = true

=============== FILE: .pre-commit-config.yaml =============== repos:

• repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.2.0 hooks:
  • id: ruff
  • id: ruff-format
• repo: https://github.com/pre-commit/mirrors-mypy rev: v1.8.0 hooks:
  • id: mypy

=============== FILE: .github/workflows/ci.yml =============== name: CI

on: [push, pull_request]

jobs: test: runs-on: ubuntu-latest env: DATABASE_URL: postgresql://postgres:postgres@localhost:5432/proxima_test REDIS_URL: redis://localhost:6379 services: postgres: image: postgres:16 env: POSTGRES_PASSWORD: postgres ports: - 5432:5432 redis: image: redis:7 ports: - 6379:6379 steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: '3.11' - run: pip install poetry && poetry install - run: poetry run alembic upgrade head --no-ansi - run: poetry run pytest tests/ --tb=short

=============== FILE: app/api/v1/users.py ===============

DEPRECATED: This module is part of the v1 API being phased out.

New user management endpoints are in app/api/v2/users.py

from fastapi import APIRouter router = APIRouter()

=============== FILE: app/api/v2/users.py =============== from fastapi import APIRouter router = APIRouter()

=============== FILE: CHANGELOG.md ===============

v3.1.0 (2025-11-15)

• Migrated from Pipenv to Poetry for dependency management
• Removed pipenv-related CI steps
• Upgraded to Python 3.11

v3.0.0 (2025-08-01)

• Introduced /api/v2/ endpoint family
• Deprecated /api/v1/ — removal planned for v4.0