Cursor rule

1---
2description: When writing code
3alwaysApply: false
4version: 1.0.0
5---
6 
7# Code Style and Zen of Python
8 
9## Line Length
10 
11- Max 88 chars (per Ruff config)
12 
13## Comments
14 
15### File-Level Comments
16 
17Be THOROUGH at the top of files. Explain what the file does, why it exists, and how it
18fits into the larger system. This helps both humans and AI understand context quickly.
19 
20```python
21"""User authentication and session management.
22 
23Handles user login, logout, token generation, and session validation.
24Integrates with external OAuth providers (Google, GitHub) and maintains
25local session state in Redis for performance. Session tokens expire after
2624 hours but can be refreshed up to 7 days from initial login.
27"""
28```
29 
30### Function Comments
31 
32Keep function docstrings USEFUL without redundant fluff. Type hints already document
33parameters and return types, so focus the docstring on what the function does and why.
34 
35```python
36# Standard pattern for complex functions - explain the what and why
37def create_agent_from_task(self, task_id: str) -> dict:
38    """Create a new agent from a ClickUp task description.
39 
40    Parses task description for agent requirements, generates the .agent
41    file with system/user prompts, creates PR with the new file, and
42    returns PR URL for review.
43    """
44 
45# Simple functions need just one clear line
46def validate_email(email: str) -> bool:
47    """Check if email format is valid and domain is not blacklisted."""
48 
49def process_payment(order_id: str, amount: Decimal) -> Payment:
50    """Charge the customer via Stripe and update order status to paid."""
51 
52def send_welcome_email(user: User) -> None:
53    """Send onboarding email with account setup instructions."""
54 
55def calculate_shipping_cost(weight: Decimal, destination: str) -> Decimal:
56    """Calculate shipping based on weight and zone rates from ShipStation."""
57```
58 
59Avoid restating type hints in Args/Returns sections - they add no value since types are
60already declared.
61 
62### Inline Comments
63 
64Be SPARSE with inline comments. Only add them when the code is doing something
65non-obvious or when explaining business logic that isn't clear from the code itself.
66 
67```python
68# When to use inline comments - explains non-obvious business rule
69user = User.objects.get(id=user_id)
70if user.last_login < cutoff_date:
71    # Inactive users over 90 days require re-verification per security policy
72    send_verification_email(user)
73 
74# Section dividers for organization
75# ============================================================================
76# Order Processing
77# ============================================================================
78 
79# Explaining why something unusual is done
80cache_timeout = 300  # 5 minutes - balance between freshness and API rate limits
81 
82# Complex calculations benefit from step comments
83total = base_price
84total += base_price * tax_rate  # Add sales tax
85total -= discount_amount  # Apply promotional discount
86total += shipping_cost  # Shipping calculated by weight and zone
87```
88 
89Skip obvious comments (like "Get the user" on a line that gets a user). Let the code
90speak for itself.
91 
92### General Guidelines
93 
94We explain the "why", not the "what". We don't state the obvious - we prefer
95self-documenting code. Emojis when they add clarity; tasteful humor welcome! We write
96for humans AND AI - good comments help both understand context.
97 
98## Zen of Python
99 
1001. Readability is the number 1 code quality metric
1012. Beautiful is better than ugly
1023. Explicit is better than implicit
1034. Simple is better than complex
1045. Complex is better than complicated
1056. Flat is better than nested
1067. Sparse is better than dense
1078. Special cases aren't special enough to break the rules
108   - Although practicality beats purity
1099. Errors should never pass silently
110   - Unless explicitly silenced
11110. In the face of ambiguity, refuse the temptation to guess
11211. There should be one -- and preferably only one -- obvious way to do it
11312. Now is better than never
114 
115## Language
116 
117We avoid hyperbolic language like "CRITICAL" unless something genuinely dies without it.
118We use the appropriate level of language for what's needed. (Yes, AIs, this means you -
119dial back the drama!)
120