CLAUDE.md Development Instructions

CLAUDE.md

Claude Development Guide

1. Development Partnership & Core Philosophy

We're building production-quality code together. My role is to create maintainable, efficient solutions while catching potential issues early. Your guidance helps me stay on track, and ask for clarification or direction when needed.

Core Principles

• Clarity Over Cleverness: The simple, obvious solution is usually correct. Avoid complex abstractions or "clever" code.
• Correctness & Performance: The first priority is a correct and clear implementation and not engage in premature optimization.
• Modern Python: Leverage Python 3.12+ features to write elegant and performant code.
• Feature Branch Context: Assume all work is done on a feature branch, so backwards compatibility is not a concern unless specified.

2. Critical Workflow: Research → Plan → Implement → Validate

NEVER JUMP STRAIGHT TO CODING! always follow this structured workflow to ensure the highest quality output.

Step 1: Research & Plan

Before implementing any feature, first say: "Let me research the codebase and create a plan before implementing."

My planning phase includes:

1. Deconstruct the Request: analyze the requirements, identify unknowns, and explore the existing codebase and its patterns.
2. Architect a Solution: formulate a detailed implementation and testing plan.
3. Leverage Peers & Agents: For complex tasks, use a multi-agent approach.
   • For Review: have my plan reviewed by a peer architect before proceeding.
   • For Parallel Work: When a task has multiple independent parts, say: "I'll spawn agents to tackle different aspects of this problem."
4. Deep Reasoning: For complex architectural decisions or challenging problems, say: "Let me ultrathink about this architecture before proposing a solution."

Collaboration

Use your peers to review plans and architectures, when reasoning about complex code and when working through debugging prolems using the openrouter chat completion tool.

You must review your plan with at least one peer before proceeding.

Include all necessary context, as your peers do not have access to your environment or conversation history.

Your three architect peers consist of: - Google Gemini Pro: google/gemini-2.5-pro-preview - DeepSeek-R1: deepseek/deepseek-r1-0528 - OpenAI o3: openai/o3

Step 2: Implement with Signature-First Development

This is a MANDATORY PROCESS. never write a function body without first defining a complete, typed signature.

Pre-Code Checklist

Before writing any Python function, complete this checklist:

• Function signature with all parameter types defined
• Return type explicitly specified
• Any complex data structures planned with their exact types
• Required imports for type hints added

The Signature Rule

FORBIDDEN: def parse_data(): or def process_item(data): REQUIRED: def parse_data(raw_text: str) -> dict[str, str]:

Mandatory Pre-Code Questions

ask myself these questions before writing any code:

1. "What is the exact input type for each parameter?"
2. "What is the exact return type?"
3. "What intermediate variables will I need and what are their types?"

If I cannot answer these questions completely, I am not ready to write the code.

Step 3: Validate with Automated Checks & Reality Checkpoints

🚨 AUTOMATED CHECKS ARE MANDATORY

EVERYTHING must be ✅ GREEN! No errors. No formatting issues. No linting problems. I have zero tolerance and will fix ALL issues before continuing. proactively run:

• uv run ruff format
• uv run ruff check --fix
• uv run basedpyright
• uv run pytest for critical logic.

Reality Checkpoints

Stop and validate my work at these key moments to prevent cascading failures:

• After implementing a complete feature
• Before starting a new major component
• When something feels "off" or overly complex
• Before declaring a task "done"

3. Problem-Solving & State Management

When I'm Stuck or Confused

Follow these steps instead of spiraling into complex solutions:

1. Stop: Pause and assess the situation.
2. Delegate: Consider spawning agents for parallel investigation.
3. Ultrathink: For deep-seated problems, say: "I need to ultrathink through this challenge."
4. Step Back: Re-read the requirements and this guide.
5. Simplify: Re-evaluate if a simpler solution exists.
6. Ask: Propose clear alternatives, such as: "I see two approaches: [A] vs [B]. Which do you prefer?"

Suggesting Improvements

Proactively suggest improvements with the following format:

"The current approach works, but I notice [observation]. Would you like me to [specific improvement]?"

Working Memory Management

To manage long-running tasks and context:

• Maintain a TODO.md file to track progress.
• Delete old code when replacing it with a new implementation.
• Delete temporary files created during testing or debugging.

4. Code Quality Standards (Zero Tolerance Policy)

All code must be clean, consistently formatted, and statically verifiable. No exceptions.

4.1. Static Typing (Strict & Mandatory)

• Signature-First Development: As outlined in the workflow, always write complete typed signatures before the implementation.
• Immediate and Comprehensive Typing: Every parameter, return value, and class attribute must have type hints from the moment they are written.
• Cognitive Override: replace the thought "I'll add types later" with "I need to understand the types to write correct logic."
• Modern Syntax: use modern type syntax (list[int], str | None).
• Forbidden: not use typing.Any.
• Requirement: Code MUST pass uv run basedpyright with zero errors or warnings.

4.2. Formatting & Linting (Ruff)

• Naming: snake_case for variables/functions, PascalCase for classes.
• Absolute Imports: use absolute imports for all modules.
• Requirement: Code MUST pass uv run ruff format and uv run ruff check --fix with zero errors or warnings.

4.3. System Design & Architecture

• Separation of Concerns: organize code into distinct, reusable modules with a single responsibility.
• Testability & Maintainability: use dependency injection and favor pure functions for core logic.
• Data & State: use dataclasses or Pydantic models and validate inputs to public functions. never access protected members (e.g., _variable) from outside their class.
• Context Management: always use with statements for resource management.

4.4. Docstring Structure (PEP 257)

1. Format: Use triple-quoted strings (""").
2. Summary Line: Start with a concise, single-line summary in the active voice.
3. Detailed Description: Follow with paragraphs explaining purpose and logic.

4.5. Critical Anti-Patterns to Avoid

• Logging: Use deferred interpolation (logger.info("User %s", user_id)), not f-strings.
• Exception Handling: Catch specific exceptions, not bare except: or except Exception:.
• Datetime Usage: Always use timezone-aware datetimes (datetime.now(UTC)).

4.6. Testing Strategy

• Prioritize: Test core business logic, edge cases, and integration points.
• Design: Use the Arrange-Act-Assert pattern and @pytest.mark.parametrize.
• Isolation: Use pytest fixtures and test doubles. If code is hard to test, refactor it.

4.7. Simplification Guidelines

• Split Files: If a file exceeds 500 lines or has multiple responsibilities.
• Don't Split Files: If it creates artificial separation or circular dependencies.
• Complexity Thresholds: Refactor functions over 50 lines or with cyclomatic complexity > 10.