Start Cursor Agent with cursor-agent in the root of a Flask project and it reads AGENTS.md or .cursor/rules before acting. For Flask work, that turns an otherwise generic coding agent into one that respects your application factory, blueprint layout, Jinja conventions and pytest workflow. This guide covers the setup and working loop that make the agent most useful on Flask codebases.
Why Cursor Agent suits Flask work
Flask projects vary a lot in structure, so an agent that assumes a flat app.py layout is dangerous. Cursor Agent is useful because it works in the project directory, can inspect the actual create_app() return value, read url_map output, render templates with the test client and run pytest with your existing fixtures. It is closer to pair programming with a team member who has the whole repo in front of them than to asking an editor for a generic snippet.
The agent also fits Flask’s repetitive changes well: adding a route to an existing blueprint, changing a view to use a SQLAlchemy query, adding a missing test, or fixing a Jinja template error. Because it can run the failing test and the template render in one loop, it can close the gap between a traceback and a working view. This matters more in Flask than in a monolithic framework, because Flask delegates so many decisions to the project structure and the developer’s own conventions.
Setting up a Flask project for Cursor Agent
Cursor Agent does not know your Flask conventions unless you write them down. Put project-specific commands and structural rules in AGENTS.md at the repository root, or in a rules file under .cursor/rules. Include the exact command line for tests, linting, formatting, type checking and the Flask CLI entrypoint. State that the app uses create_app(), where blueprints and templates live, and which SQLAlchemy session pattern you use. Keep the file short enough to be read every turn; verbose rules are ignored in practice. If a rule applies only to a subset of files, put it in a scoped .cursor/rules file; keep the root AGENTS.md for global commands and Flask conventions.
A realistic AGENTS.md for a Flask project looks like this:
# AGENTS.md
## Commands
- Install: python3 -m venv .venv && source .venv/bin/activate && pip install -e '.[dev]'
- Run tests: pytest
- Focused test: pytest -k '<test_name>'
- Lint: ruff check .
- Format check: ruff format --check .
- Flask CLI: flask --app 'app:create_app()' routes
## Flask conventions
- Use the create_app() factory in app/__init__.py.
- Blueprints live in app/blueprints/<name>.py and are registered in create_app().
- Templates live in app/templates/<blueprint>/<name>.html.
- Models live in app/models.py or app/models/.
- Use SQLAlchemy 2.x session patterns; no db.session calls at import time.
- Access current_app and request only inside a request or app context.
## Rules for agent changes
- Run the full test suite before and after a change.
- Keep changes small; do not rewrite an entire module unless asked.
- Do not create a new blueprint without confirming route prefix and template folder.
- When touching models, include a migration or note that one is required.That file is enough for most Flask projects. If you use Flask-Migrate, add the migration command to the list; if you use a different linter, replace ruff with your tool. The goal is not to document the entire architecture, but to stop the agent from guessing wrong about the app factory, import boundaries and test command.
A working loop with example prompts
Use a plan-first loop: describe the observable outcome, ask for a small diff, run pytest, review the diff, then ask for the next step. For changes that touch blueprints, SQLAlchemy or Jinja, ask for a failing test or a regression test before the implementation. These prompts all specify a concrete, testable result:
- In the auth blueprint, add a before_request hook that redirects anonymous users to auth.login unless the endpoint belongs to auth or static. Add a regression test with the test client for a protected route and an unprotected route.
- Add a SQLAlchemy Role model with a many-to-many relationship to User, then write a pytest fixture that creates a user with the admin role and asserts that user.has_role(‘admin’) is true.
- Create a dashboard blueprint in app/blueprints/dashboard.py, register it in create_app() at /dashboard, and render a Jinja template that lists the current user’s projects from the database. Include a basic route test.
- Find the N+1 query in the project list view and add a joinedload or selectinload to the SQLAlchemy query. Add a test that asserts the query count does not grow when more projects are added.
- Refactor app.py to call create_app() without changing the Flask CLI command flask —app ‘app:create_app()’ run.
A prompt like ‘improve the Flask app’ is too vague; it leads to unnecessary refactors. A prompt like the ones above gives the agent a small surface and a clear acceptance check. After the agent returns, review the diff in the context of request and application context, not just in isolation. When the agent reports that tests pass, run the same command yourself before moving on. That catches cases where the agent only ran a subset, relied on an existing dev database, or edited a test to match broken behavior.
What Cursor Agent handles well in Flask and where to watch closely
Cursor Agent handles small, well-bounded Flask changes reliably: routes in blueprints, Jinja changes when tied to a failing test or expected HTML, SQLAlchemy 2.x query conversions, pytest fixtures for the test client, and import fixes caused by app factory circular imports. It is less reliable when asked to redesign the factory pattern, introduce a new extension globally, or guess the Flask request lifecycle.
| Area | Watch closely in the diff |
| App factory and imports | The agent may import the app module directly or create circular imports between models, extensions and blueprints. |
| SQLAlchemy | It may use db.session outside an app context, forget a commit, or leak a session between tests. |
| Blueprints and templates | It may register a blueprint with the wrong prefix or put templates at app/templates/ instead of app/templates/<blueprint>/. |
| Testing | It may write tests that pass against a shared development database or fail to isolate the app fixture. |
The most common Flask-specific failures are SQLAlchemy queries at import time, current_app called outside a request context, and hard-coded URLs instead of url_for. Review those lines before accepting a change. A quick check of the app factory and the blueprint registration diff catches most issues before they become test failures. For larger changes, split the work by Flask layer: blueprint, model, template, test. That mirrors how Flask developers naturally break down a feature and keeps each agent turn reviewable.
Testing and verification
Make testing part of the prompt from the start, not a final step. In Flask, the test client is the fastest way to verify a route, redirect, status code or template context without starting a server. Ask Cursor Agent to run pytest after each change and to show the diff only if the suite is green. For database tests, require an isolated fixture that creates and drops tables per test or uses transactions/rollbacks. Use pytest -k ‘<test_name>’ while iterating, then a full run before accepting.
If the agent changes Jinja, ask it to add a test that renders the template with a context dictionary and checks the important text, not just that the response is 200. Use flask shell for manual sanity checks, but do not accept a change that only worked interactively and has no test. A useful pattern is to ask the agent to write the test first, show it failing, then implement the fix and show the green run. A review step like How to vibe code safely: a practical workflow prevents a quick Flask fix from turning into an untested refactor.
Running several agents on one Flask project with AgentVera
On a Flask project, parallel agents can work on separate blueprints, tests, and templates in their own git worktrees, so they don’t overwrite each other’s files. AgentVera runs the real command line tools side by side in one window and adds automatic code review when an agent’s turn ends; findings link to file:line, which helps catch Flask mistakes such as SQLAlchemy session use outside a request context or incorrect blueprint registration. Checkpoints make it practical to undo a bad refactor of the app factory, and token budgets stop an agent from rewriting the entire project. See Best tools to run AI coding agents in parallel for a broader view.
Wrap-up
Cursor Agent earns its place on Flask projects when you feed it the project’s real commands and Flask-specific conventions, then keep changes small and testable. Start with AGENTS.md, use the plan-test-diff loop, and keep an eye on app context, SQLAlchemy and blueprint boundaries. Once that loop works, parallel agents can extend the same discipline across a larger Flask codebase.