Cursor Rules Template for Medical Billing with Cursor AI | Suhas Bhairav

Overview

The Cursor rules configuration is a copyable, stack-aware guide for building medical billing validation tools with Cursor AI. This Cursor rules template targets a Python FastAPI + SQLAlchemy + PostgreSQL stack, emphasizing HIPAA-conscious data handling, auditability, and deterministic code generation. Paste the included .cursorrules block into your project root to steer Cursor AI in constructing secure, testable endpoints and domain models for claim review teams.

When to Use These Cursor Rules

When implementing modular claim validation services backed by PostgreSQL via SQLAlchemy.
When enforcing a policy-driven adjudication workflow for claim reviews.
When standardizing API surface area for PHI-protected billing data using FastAPI.
When embedding tests, linting, and CI hooks around the Cursor-generated code to preserve auditability.
When you want a reusable seed for HIPAA-aware, cursor-assisted development.

Copyable .cursorrules Configuration

# .cursorrules configuration for a Python FastAPI + SQLAlchemy + PostgreSQL stack
cursorrules_version: 1
stack: "Python FastAPI + SQLAlchemy + PostgreSQL"
framework: "FastAPI"
language: "Python 3.11+"
role_context: "You are Cursor AI, guiding engineers to build medical billing validation tools with careful handling of PHI, strict typing, and auditable paths. Provide solutions that are testable and secure."
codeStyle: "Black, isort, mypy"
architecture:
  rootDir: "app"
  modules:
    billing: "billing logic and validation rules"
    claims: "claims processing and workflow"
    validation: "rule sets and policy checks"
authSecurity:
  method: "OAuth2 with JWT"
  tokenLifetime: "15m"
  audience: "billing_claims_api"
dbOrm: "SQLAlchemy"
database: "PostgreSQL"
migrations: "Alembic"
testing:
  unit: "pytest"
  integration: "pytest + httpx"
linting:
  tools: ["black", "ruff", "isort", "mypy"]
prohibitedActions:
  - "Do not bypass ORM for data access or generate raw SQL strings via string concatenation"
  - "Do not log PHI in application logs; redact on all outputs"
antiPatterns:
  - "Inline SQL or string interpolation in repository code"
  - "Storing secrets in code or environment defaults"
notes: "Cursor AI adheres to HIPAA-like privacy constraints; avoid PHI leakage and ensure deterministic, testable code paths."

Recommended Project Structure

medical-billing-cursor-rules-template/
├── app/
│   ├── api/
│   │   └── v1/
│   │       └── claims.py
│   ├── core/
│   │   ├── config.py
│   │   └── security.py
│   ├── models/
│   │   └── claim.py
│   ├── schemas/
│   │   └── claim_schemas.py
│   └── main.py
├── tests/
│   ├── unit/
│   │   ├── test_claim_model.py
│   │   └── test_validation.py
│   └── integration/
│       └── test_api.py
├── alembic/
├── migrations/
└── .env

Core Engineering Principles

Correctness and data integrity with strict typing and validated models.
Security and privacy first: PHI minimization, encryption at rest, and access controls.
Observability: structured logs, tracing, and clear audit trails for all claim reviews.
Modularity: small, testable components with well-defined interfaces for billing, validation, and claims.
Testability: design for unit, integration, and end-to-end tests; seed data for reproducible tests.
Documentation and reproducibility: clear contracts and CI-friendly configurations.
Deterministic Cursor AI outputs: avoid non-deterministic prompts and randomization in code generation.
Scalability and maintainability: clean architecture and gradual refactors safely.
Compliance posture: explicit handling of medical data privacy during development.

Code Construction Rules

Use async FastAPI endpoints where appropriate and keep business logic in services under app/.
All data models should be SQLAlchemy ORM classes with explicit relationships and migrations via Alembic.
Define Pydantic models for request/response shapes and rely on query validation to prevent invalid data.
Do not embed raw SQL in app code. Use parameterized queries via SQLAlchemy Core when necessary and avoid string concatenation.
Follow Black formatting, isort for imports, and mypy for typing checks; CI should enforce linting.
Organize code by domain (billing, claims, validation) and keep a clear separation of concerns between API, domain, and persistence layers.
Document endpoints and data contracts in code comments and docstrings for clarity and auditability.
Do not rely on non-secure storage for secrets; use environment variables and a secrets vault in production.
Prefer dependency injection for security, config, and services to enable testability and isolation.

Security and Production Rules

Enforce TLS, use secure cookies, and rotate JWT signing keys; implement short-lived access tokens with refresh tokens.
Redact PHI in logs and avoid echoing raw data from requests; use auditing hooks for reviews without exposing sensitive fields.
Store secrets in a dedicated vault or environment-based config; do not commit secrets to code repositories.
Implement strict CORS, rate limiting, and input validation to prevent injection and abuse vectors.
Use database roles and least-privilege access for each service account; enable row-level security if needed.

Testing Checklist

Unit tests for models and validators; mock database interactions with fixtures.
Integration tests for claim validation endpoints using a PostgreSQL test container.
End-to-end tests simulating real-world claim review scenarios with sample data.
Static analysis and type checks (mypy) in CI; ensure lint passes on every PR.
Security tests for token handling, access control, and data leakage prevention.

Common Mistakes to Avoid

Using raw SQL or string building in repositories; prefer ORM abstractions with migrations.
Logging PHI inadvertently; always redact sensitive fields in logs and traces.
Coupling business logic to API layers; maintain a clean service layer for testability.
Neglecting audit trails and versioning of rules; ensure every change is recorded.
Overengineering authentication flows; keep JWT scope and audience clearly defined.

FAQ

What is this Cursor Rules Template for medical billing validation?

This Cursor Rules Template provides a ready-to-paste .cursorrules configuration and a stack-specific project blueprint for building medical billing validation tools. It targets a Python FastAPI + SQLAlchemy + PostgreSQL stack and emphasizes HIPAA-conscious practices, testability, and auditable development with Cursor AI.

Which stack does this template cover?

The template is tailored for a Python FastAPI backend using SQLAlchemy as the ORM and PostgreSQL as the database, with Alembic for migrations and Pytest-based testing. It includes security and data handling patterns suitable for medical claim reviews.

How does Cursor AI enforce HIPAA-like privacy in this template?

Cursor AI guidance focuses on minimizing exposure of PHI, redacting sensitive fields in logs, and ensuring data handling paths are auditable. The configuration emphasizes strict authentication, access controls, and secure data flows from API to persistence.

How do I extend the rules for other payers or additional validation checks?

Extend the domain modules under app/ by adding new validation services and extend the .cursorrules with new rule sets. Ensure migrations reflect DB changes and add corresponding tests to validate new logic and coverage for edge cases.

What should I run to verify correctness and security before deployment?

Run unit tests for models and validators, integration tests for API endpoints, and security checks for token handling. Use CI to enforce linting, type checks, and end-to-end tests; review audit logs for any PHI exposure during test runs.

Where can I find the canonical page and related templates?

See the Cursor Rules Templates collection at https://suhasbhairav.com/ai-skills/cursor-rules-templates/cursor-rules-templates and this page at https://suhasbhairav.com/ai-skills/cursor-rules-templates/medical-billing-cursor-rules-template for the exact configuration and structure described here.

Cursor Rules Template: Medical Billing Validation for Claim Review Teams

Target User

Use Cases