StemCode for Python Developers: AI Coding with FastAPI, Django, and pytest.

Give StemCode durable repository instructions before asking it to edit.

Add an AGENTS.md file at the repository root for persistent project instructions. StemCode loads AGENTS.md or .agent/AGENTS.md from the workspace into the model context, so this is the right place for architecture boundaries, generated-file rules, coding conventions, validation expectations, and manual setup notes that should apply across sessions.

# Python Project Instructions

This is a Python project.

Important source and configuration:
- pyproject.toml, requirements files, or the repository's package configuration
- src/, app/, or the project's main package
- tests/
- migrations and framework configuration when present

Follow these rules:
- Follow the repository's existing typing, formatting, linting, and import conventions.
- Do not modify .venv/, __pycache__/, .pytest_cache/, build output, or generated files.
- Preserve sync/async boundaries and existing FastAPI, Django, or service-layer patterns.
- Reuse existing dependencies before adding new packages.
- Keep validation, permissions, ORM behavior, and migrations in view when changing data flows.
- Run focused pytest, type-check, and lint commands before broader validation.

Commit the file with the project so the same instructions are reviewable and shared by everyone using StemCode in the repository.

Use AI across modules, frameworks, tests, and tooling.

Python projects can look simple at first and become complex quickly. A production application may combine API routes, dependency injection, ORM models, background jobs, validation, data pipelines, async code, notebooks, CLI tools, tests, type checking, and deployment scripts.

StemCode works against the whole repository instead of only the file currently open in an editor. It can search the codebase, use language-server information, make tracked edits, run approved project commands, investigate failures, and review Git changes.

Install StemCode and open your existing Python repository.

Install the StemCode CLI with an npm-family package manager or the official shell installers. The packaged CLI is self-contained and does not require the .NET SDK.

Start StemCode from the repository root:

cd my-python-project
stemcode

Initialize repository-specific StemCode files:

/init

Use those files for architecture notes, test strategy, reusable commands, framework conventions, and project-specific constraints.

Use BasedPyright, Pyright, or Pylsp for semantic navigation.

StemCode supports LSP-powered code intelligence and includes built-in Python server definitions. The documented options include BasedPyright, Pyright, and Python LSP Server.

Install BasedPyright

pip install basedpyright

Or install Pylsp

pip install python-lsp-server

Then refresh server detection inside StemCode:

/lsp refresh

Inspect detected servers:

/lsp

Or inspect one Python source file:

/lsp file app/services/order_service.py

Semantic information about definitions, references, diagnostics, and symbols is especially useful in Python codebases that rely on protocols, abstract base classes, decorators, dependency injection, or dynamic framework registration.

Trace an API feature from route to persistence and side effects.

FastAPI projects often distribute a feature across routers, dependencies, Pydantic models, services, SQLAlchemy repositories, background tasks, and external integrations.

Then narrow the investigation:

Find every place OrderStatus changes and explain which transitions are allowed.

Find all dependencies used by this endpoint and explain which ones perform I/O or authorization.

When implementing a feature, make discovery part of the request:

Add support for cancelling an order before fulfillment.

Before editing:
- inspect similar FastAPI endpoints
- identify authorization dependencies
- find the service and persistence flow
- inspect transaction handling
- identify background tasks or events
- find relevant tests

Then implement the feature, run targeted tests, and review the Git diff.

Use repository context across views, models, forms, signals, and tasks.

Django applications often hide important behavior in model methods, managers, middleware, signals, forms, DRF serializers, permissions, Celery tasks, and settings. StemCode can inspect those pieces together.

For security-sensitive Django work, ask StemCode to review permission classes, queryset scoping, object ownership, and administrative paths rather than checking only the visible view code.

Keep the real Python test suite in the loop.

AI-generated changes become more trustworthy when they are validated by the repository's real test runner and configuration.

pytest
pytest tests/test_orders.py
pytest -k cancel_order

python manage.py test

A useful instruction for a large suite is:

Run the smallest relevant test scope first. If it passes, run the broader affected suite.

Debug failures before editing again

Run the failing test and explain whether the root cause is production code, fixtures, dependency overrides, database state, async behavior, or environment configuration before changing anything.

Add a reusable Python validation command

Teams can turn the normal test, type-check, and lint loop into a project command under .stemcode/commands. After this file is committed, developers can run it in StemCode as /python-validate.

---
name: python-validate
description: Run Python tests, type checks, and linting
args: ["testScope"]
---

Validate the Python workspace using the repository's real tools.

Run these commands in order:

1. pytest $testScope
2. pyright
3. ruff check .

If a command fails, stop, summarize the failure, identify the most
relevant module or test, and explain the next fix before editing.

Important allow-list checks

Python validation may read virtual environments, write test caches, and inspect package metadata, so check the active rules before running a validation-heavy task:

/permissions
/rules
/allow shell "pytest *"
/allow shell "pyright *"
/allow shell "ruff check *"

The important tool categories are repository file read/search, Python language-server inspection, shell execution for pytest and static checks, and file writes only when you ask StemCode to implement a fix.

Use type checking and linting as AI guardrails.

Python's flexibility is productive, but it also means a change can look correct while violating assumptions only expressed through types, lint rules, or tests.

pyright

ruff check .
mypy .

Map dynamic call paths before restructuring Python code.

Refactoring Python can be deceptively risky when decorators, runtime registration, dependency injection, dynamic imports, or framework conventions obscure callers.

Find every caller and implementation related to PaymentService. Explain how splitting authorization and capture would affect API handlers, background jobs, tests, and dependency wiring.

For a risky change, switch to planning mode:

/profile plan

Then request a staged migration:

Create a step-by-step refactoring plan that keeps the application runnable and testable between steps. Do not modify files yet.

After reviewing the plan, implement incrementally and run the relevant tests and static checks after each meaningful step.

Store Python conventions where the team can review them.

StemCode workspace memory can capture project-specific expectations so you do not have to restate them in every prompt.

Example architecture notes

FastAPI routers contain HTTP orchestration only.
Business logic belongs in service modules.
Database access is isolated behind repository functions.
Background tasks must be idempotent.
External API clients use explicit timeout and retry policies.

Example test strategy

Focused tests: pytest tests/unit
API tests: pytest tests/api
Type check: pyright
Lint: ruff check .

Add a Python-specific review pass before the pull request.

Review the current Git diff as a senior Python reviewer.

Focus on:
- correctness and regressions
- async and await mistakes
- mutable defaults and shared state
- typing and API contracts
- database query behavior
- authorization and input validation
- background-task reliability
- error handling and logging
- missing tests

Or pipe the diff directly:

git diff | stemcode --stdin --profile review

StemCode for Python developers: common questions.

Does StemCode work with FastAPI?

Yes. StemCode works against the repository, so it can inspect routers, dependencies, Pydantic models, services, database code, background tasks, tests, and surrounding project configuration.

Does StemCode work with Django?

Yes. It can analyze Django and Django REST Framework projects alongside models, managers, serializers, permission classes, signals, settings, Celery tasks, and tests.

Can StemCode run pytest?

Yes. StemCode can run approved shell commands, including pytest, project-specific test scripts, and targeted test selections.

Which Python language servers does StemCode support?

StemCode's built-in language-server definitions include BasedPyright, Pyright, and Pylsp options for Python code intelligence.

Can StemCode use Ruff, mypy, or Pyright?

Yes. You can include your existing linting and type-checking commands in the validation steps for a task so the agent works with your repository's current quality gates.

Put StemCode to work in a real repository.

Install StemCode, open the project you already work in, and begin with a repository-understanding task before asking the agent to change code. That gives the model better context and keeps the workflow reviewable.

npm install -g stemcode
cd your-project
stemcode