Claude Code with Flask: pragmatic project and testing workflows

Claude Code is a coding agent you start by running claude in the project root. It reads CLAUDE.md, then edits files, runs tests, and explains changes. For Flask, this works best when you treat it as a fast pair programmer that knows Python, SQLAlchemy and Jinja but needs explicit rules about application factories, blueprints and migrations. The practical loop is: encode conventions, make small planned changes, run pytest, and review the diff before committing. See Claude Code for the basics.

Why Claude Code fits Flask work

Flask projects are often small enough for an agent to read the whole app but tricky enough to require context: an application factory, blueprints, extensions, form handling, templates and SQLAlchemy sessions. Claude Code can trace a route from blueprint registration through the view to the Jinja template, then update all three pieces in one change. It is particularly good at refactoring repeated code across blueprints, adding tests for a newly added route, and explaining obscure errors such as RuntimeError: Working outside of application context. The value is not code generation by itself; it is working across files while keeping the command surface small.

For a checklist before you start, see Claude Code best practices: a practical checklist.

Set up the project for the agent

Do not rely on the agent to infer your Flask conventions. Put them in CLAUDE.md at the project root. The file should include the exact commands for installing, running, testing and linting, the folder layout, and rules that are easy to get wrong in Flask: application factory, blueprint registration, SQLAlchemy session usage, template locations and migration policy. A short, realistic CLAUDE.md for a Flask project looks like this:

# CLAUDE.md

## Project layout
- src/website/ contains the application factory, blueprints, models, templates.
- Tests live in tests/ and mirror package modules.
- Migrations live in migrations/ (Flask-Migrate).

## Commands
- Install: `pip install -e '.[dev]'`
- Run dev server: `flask --app src.website:create_app run --debug`
- Test: `pytest -q`
- Lint: `ruff check src tests`
- Format: `ruff format src tests`

## Conventions
- Use application factory `create_app()`; register blueprints there.
- One module per blueprint; blueprint names and URL prefixes must be explicit.
- SQLAlchemy models import `db` from `src.website.extensions`, not from app.
- Use `db.session.get(Model, id)` rather than `Model.query`.
- Jinja templates go under `src/website/templates/<blueprint>/`.
- Do not auto-generate migrations; tell the human to run flask db migrate and review.
- Prefer pytest fixtures in conftest.py and use a test app with a temporary SQLite database.
- When changing a route or model, update its tests in the same change.
- Keep changes small; stop after each test run and report results.

This gives the agent enough context to stop guessing. If you use environment variables such as FLASK_APP, document them as well; otherwise the agent may start a different app or leave debug enabled.

A working loop for Flask changes

Work in short cycles instead of asking for a large feature. Start in plan mode for changes that touch models, routes or configuration; see Claude Code plan mode: plan first, then let it build. Then let the agent make one focused change, run the tests, and review the diff yourself before committing. Commit before each new task so the diff has a clean baseline.

Typical prompts for Flask tasks:

• Trace the current auth blueprint registration. List every route, URL rule, method, template and test file without editing.
• Add a login_required decorator to the dashboard blueprint. Keep the existing route names and add a regression test.
• Refactor create_app() to load config.TestingConfig when WEBSITE_ENV=test. Update the pytest fixtures accordingly.
• In accounts/models.py, add a User.last_seen column; update the update_last_seen helper and add a test. Do not create a migration.
• Fix the 500 error for POST /register: reproduce it with pytest, show the traceback, then apply the smallest fix and rerun affected tests.

After each prompt, review the diff before accepting. Ask for an explanation when the diff touches more files than expected.

Flask tasks and pitfalls

The agent handles many Flask chores well: scaffolding blueprints, adding validation, updating SQLAlchemy queries, writing view tests and fixing Jinja syntax. The table shows where it is most useful and what to watch.

| Flask area | Good prompt | Watch closely | | Blueprints and routes | Trace registration in create_app and list routes, methods and template paths. | Duplicate URL rules, missing blueprint prefix, route not registered after adding a module. | | SQLAlchemy models and queries | Add a unique constraint to User.email and update the registration test. | Session handling, lazy loading in templates, auto-migrations, commit scope. | | Jinja templates | Update auth/login.html to use url_for for the form action and show field errors. | Wrong url_for endpoint names, unescaped user input, template not found due to blueprint folder. |

Common failure modes are Flask-specific. The agent can add a route but forget to import and register the blueprint in create_app. It can use Model.query when your project uses the extension pattern, or open a session outside the app context. It can put a template in the root templates folder instead of the blueprint subfolder. It can try to autogenerate a migration before the model is stable. Review these areas automatically; do not trust the first pass.

Testing and verification

Testing is where the agent saves the most time, but do not let it be the final judge. Ask it to write or update pytest tests, then run the suite yourself. Keep a test database configuration that uses a temporary SQLite file or an isolated PostgreSQL schema. The app factory should accept a config object so tests can build a fresh app per test.

A good verification loop is:

1. Have the agent reproduce the reported problem as a failing test.
2. Let it implement the smallest change.
3. Run pytest -q yourself and inspect any failures.
4. Ask the agent to explain every changed file before staging.

For non-interactive checks in CI, see Claude Code headless mode: claude -p for scripts and CI.

Run several agents with AgentVera

For larger Flask projects, AgentVera lets several Claude Code agents run side by side in real terminal panels. Each agent can work in its own git worktree, so one can add a blueprint while another refactors models without overwriting files. After a turn, a second model reviews the code and links findings to file and line, which matters for SQLAlchemy and Jinja mistakes. Checkpoints let you undo a broken route or migration in one click. Token budgets stop a wandering refactor from consuming the session. Together these controls make parallel Flask work manageable.

Wrap-up

Claude Code is most effective on a Flask project when the groundwork is explicit. Put your application factory, blueprint, SQLAlchemy and template rules in CLAUDE.md. Work in small, tested steps, review diffs, and treat the agent as an assistant rather than a replacement for Flask expertise.