Set Up Agent Instructions for a Growing Python Monorepo

Problem/Feature Description

Datastream Analytics has a Python monorepo that has grown organically over three years. The codebase now spans multiple service packages, a shared utilities layer, and a legacy payments module that predates the current architecture. The team recently started using AI coding assistants heavily, but there is no AGENTS.md in the repository — agents keep making the same costly mistakes: using the wrong package manager, running tests with flags that produce different output than CI, and occasionally touching a legacy directory that cannot be safely modified.

A staff engineer has gathered the key configuration files and wants you to create a focused AGENTS.md for the repo root. The file should give agents exactly what they cannot figure out on their own from reading the code — no more, no less. Given the size of the repo, think carefully about whether the root file should try to capture everything or whether some guidance belongs closer to individual modules.

Output Specification

Produce an AGENTS.md file at the root of the workspace. The file should be concise and contain only instructions that meet a high bar for inclusion. Do not create any other files.

Input Files

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

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

Datastream Analytics Platform

A Python-based event streaming and analytics platform.

Services

• services/ingestion/ — Kafka consumer that normalizes incoming events
• services/aggregator/ — Computes rolling metrics from normalized events
• services/api/ — FastAPI service exposing aggregated data to clients
• packages/shared/ — Shared Pydantic models, logging utilities, and DB helpers
• legacy/payments/ — Legacy billing integration (pre-2022 architecture)

Tech stack

Python 3.12, FastAPI, Kafka (confluent-kafka), PostgreSQL, Redis, SQLAlchemy 2.x.

Getting started

Install dependencies with uv sync and run services individually. See docs/runbooks/ for deployment guides. =============== END FILE ===============

=============== FILE: pyproject.toml =============== [project] name = "datastream" version = "0.1.0" requires-python = ">=3.12" dependencies = [ "fastapi>=0.111", "confluent-kafka>=2.4", "sqlalchemy>=2.0", "pydantic>=2.7", "redis>=5.0", "alembic>=1.13", ]

[tool.uv] dev-dependencies = [ "pytest>=8.2", "pytest-asyncio>=0.23", "httpx>=0.27", "ruff>=0.4", ]

[tool.pytest.ini_options] addopts = "--no-header -p no:warnings" asyncio_mode = "auto"

[tool.ruff] line-length = 88 select = ["E", "F", "I"] quote-style = "double" =============== END FILE ===============

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

on: [push, pull_request]

jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: astral-sh/setup-uv@v4 - name: Install dependencies run: uv sync --all-extras - name: Lint run: uv run ruff check . - name: Test run: uv run pytest services/ packages/ --no-header -p no:warnings =============== END FILE ===============

=============== FILE: .cursorrules ===============

Cursor rules for Datastream

• Use uv for all Python package management (not pip, not poetry)
• The legacy/payments/ directory must not be refactored or deleted — it is still imported directly by the production billing service and has undocumented side effects on invoice generation. Any changes require sign-off from the billing team.
• For new services, copy the structure from services/ingestion/ as a template =============== END FILE ===============

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

• repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.4.4 hooks:
  • id: ruff args: [--fix]
  • id: ruff-format =============== END FILE ===============