---
description: When writing code
alwaysApply: false
version: 1.0.0
---

# Code Style and Zen of Python

## Line Length

- Max 88 chars (per Ruff config)

## Comments

### File-Level Comments

Be THOROUGH at the top of files. Explain what the file does, why it exists, and how it
fits into the larger system. This helps both humans and AI understand context quickly.

```python
"""User authentication and session management.

Handles user login, logout, token generation, and session validation.
Integrates with external OAuth providers (Google, GitHub) and maintains
local session state in Redis for performance. Session tokens expire after
24 hours but can be refreshed up to 7 days from initial login.
"""
```

### Function Comments

Keep function docstrings USEFUL without redundant fluff. Type hints already document
parameters and return types, so focus the docstring on what the function does and why.

```python
# Standard pattern for complex functions - explain the what and why
def create_agent_from_task(self, task_id: str) -> dict:
    """Create a new agent from a ClickUp task description.

    Parses task description for agent requirements, generates the .agent
    file with system/user prompts, creates PR with the new file, and
    returns PR URL for review.
    """

# Simple functions need just one clear line
def validate_email(email: str) -> bool:
    """Check if email format is valid and domain is not blacklisted."""

def process_payment(order_id: str, amount: Decimal) -> Payment:
    """Charge the customer via Stripe and update order status to paid."""

def send_welcome_email(user: User) -> None:
    """Send onboarding email with account setup instructions."""

def calculate_shipping_cost(weight: Decimal, destination: str) -> Decimal:
    """Calculate shipping based on weight and zone rates from ShipStation."""
```

Avoid restating type hints in Args/Returns sections - they add no value since types are
already declared.

### Inline Comments

Be SPARSE with inline comments. Only add them when the code is doing something
non-obvious or when explaining business logic that isn't clear from the code itself.

```python
# When to use inline comments - explains non-obvious business rule
user = User.objects.get(id=user_id)
if user.last_login < cutoff_date:
    # Inactive users over 90 days require re-verification per security policy
    send_verification_email(user)

# Section dividers for organization
# ============================================================================
# Order Processing
# ============================================================================

# Explaining why something unusual is done
cache_timeout = 300  # 5 minutes - balance between freshness and API rate limits

# Complex calculations benefit from step comments
total = base_price
total += base_price * tax_rate  # Add sales tax
total -= discount_amount  # Apply promotional discount
total += shipping_cost  # Shipping calculated by weight and zone
```

Skip obvious comments (like "Get the user" on a line that gets a user). Let the code
speak for itself.

### General Guidelines

We explain the "why", not the "what". We don't state the obvious - we prefer
self-documenting code. Emojis when they add clarity; tasteful humor welcome! We write
for humans AND AI - good comments help both understand context.

## Zen of Python

1. Readability is the number 1 code quality metric
2. Beautiful is better than ugly
3. Explicit is better than implicit
4. Simple is better than complex
5. Complex is better than complicated
6. Flat is better than nested
7. Sparse is better than dense
8. Special cases aren't special enough to break the rules
   - Although practicality beats purity
9. Errors should never pass silently
   - Unless explicitly silenced
10. In the face of ambiguity, refuse the temptation to guess
11. There should be one -- and preferably only one -- obvious way to do it
12. Now is better than never

## Language

We avoid hyperbolic language like "CRITICAL" unless something genuinely dies without it.
We use the appropriate level of language for what's needed. (Yes, AIs, this means you -
dial back the drama!)