🧠 Claude Rule — Python Async & Concurrency Best Practices

You are an async-first backend engineer using Claude to design fast, reliable, and scalable I/O systems in Python.

🧩 Understand When Async Matters

• Use async only when workloads wait on I/O (databases, APIs, file/network ops)
• CPU-bound tasks should move to worker pools — not the event loop
• Claude can help classify endpoints: "wait-heavy" vs "compute-heavy"

Reference: https://docs.python.org/3/library/asyncio-task.html

🔄 Clean Event Loop Management

• Never block the loop with long computations
• Prefer async drivers for DB and network calls
• Use cancellation-friendly patterns to avoid zombie tasks

Reference: https://docs.python.org/3/library/asyncio-eventloop.html

🧱 Design Predictable Async APIs

• Keep route handlers pure: orchestrate work, don't embed logic
• Propagate cancellation upstream when clients disconnect
• Establish clear timeouts for external calls to avoid hangs

Reference: https://fastapi.tiangolo.com/async/

🗄️ Async Database Efficiency

• Use connection pooling and reuse sessions efficiently
• Fetch only what's needed — protect memory footprints
• Backpressure slow consumers to avoid unbounded queues

Reference: https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html

🧮 Error Safety in Async Systems

• Avoid suppressing exceptions inside tasks — they vanish silently
• Log failures with tracebacks for diagnostic clarity
• Aggregate partial results carefully to avoid corrupted responses
• Errors in async code hide deeper — make debugging intentional

🧲 Concurrency Controls

• Limit parallelism using semaphores or task groups
• Fail gracefully when systems are under stress
• Share mutable state only through secure primitives

Reference: https://peps.python.org/pep-0703/

📊 Monitoring Real Latency Assets

• Track queue depth, wait time, retry counts
• Measure tail latency (p95/p99) instead of averages
• Claude helps analyze telemetry for targeted fixes

Reference: https://opentelemetry.io/

🧠 Performance Tuning Before Scaling Out

• Start with profiling to identify blocking calls
• Introduce caches around repetitive workloads
• Scale horizontally only after fixing core choke points
• Async is a performance tool — not a replacement for good architecture

🧭 Guiding Principles for Async Excellence

• Async is a business decision: use it purposefully
• Do one thing concurrently — do everything reliably
• Visibility & monitoring are non-optional
• Claude can reason about task flow better than humans under pressure