Skip to content

project rulesBackend and APIspythonflask

Flask Rules

Project rules for Flask apps: application factory, blueprints, environment-based config, explicit extensions, JSON error handlers and pytest fixtures.

npx workspacetemplates add flask-rules --tool claude-code

Writes 1 file to your project root

CLAUDE.mdadd to your file24 lines · 1.3 KBFile
# Project rules: Flask

## Structure
- Use an application factory: `create_app(config_name)` in `app/__init__.py`. No module-level `app` object.
- One blueprint per feature under `app/<feature>/` with `routes.py`, `schemas.py` and `services.py`. Register blueprints inside the factory.
- Create extensions (`db`, `migrate`) unbound in `app/extensions.py` and call `init_app` in the factory. Import them from there, never from `app`.

## Config
- Config classes in `config.py`; select by environment variable. Secrets come from the environment only.
- Read settings through `current_app.config`, not through globals.

## Routes
- Handlers stay short: validate with marshmallow or pydantic, call a service, return `jsonify` with an explicit status code.
- Do not touch the database from a route function directly; go through a service.
- Register `errorhandler` functions that return one JSON shape: `{"error": {"code": ..., "message": ...}}`. Log the traceback; do not send it to the client.

## Data
- SQLAlchemy sessions come from the extension. Manage schema with Flask-Migrate and commit the generated revision after reviewing it.

## Tests
- pytest with an `app` fixture built from the factory using a testing config, plus a `client` fixture. Use a throwaway database per test run.

## Before finishing
Run `ruff check .`, `flask db check` and `pytest -q`.

What it does

Flask is small enough that every project invents its own structure. These rules fix one structure so new routes, extensions and tests land where a teammate would look first.

They lean on the application factory pattern, which removes most of the import cycles and test setup headaches that Flask projects collect over time.

Example

you › Add a route to archive a project

agent › The agent adds the route to the projects blueprint, calls an archive service, returns 404 through the shared error handler for unknown ids, and adds a client fixture test.

Questions

Why ban a module-level app?
A global app forces imports in a fixed order and makes it hard to build a clean instance per test. The factory removes both problems.
Is it written for Flask-RESTful?
No, it assumes plain blueprints. The structure still fits if you add a resource library, but the route rules would need adjusting.
  • ASP.NET Core Web API Rules

    Project rulesdotnet

    Free
  • Django Rules

    Project rulespython

    Free
  • Go Service Rules

    Project rulesgo

    Free
  • GraphQL API Rules

    Project rulesgraphql

    Free