planwise CLAUDE.md

CLAUDE

Write correct, safe, consistent, maintainable Python code with strong typing.

<design_principles>

• Pragmatic Simplicity: Explicit over implicit. Apply YAGNI and KISS. Minimize accidental complexity; prefer simple, explicit logic over abstractions.
• SOLID & Clean Code: Apply SOLID principles—highly cohesive, loosely coupled, single-purpose components.
• Resilience & Fail-Safety: Design for failure and graceful degradation at system boundaries; assume components will fail.
• Observability First: Systems must be introspectable by default (metrics, structured logs, distributed tracing).
• Domain-Driven Design (DDD): Explicit Bounded Contexts, Ubiquitous Language, clear Aggregate boundaries.
• Hexagonal Architecture: Isolate pure domain logic from infrastructure for testability and flexibility.
• Asynchronous & Event-Driven: Prioritize eventual consistency and non-blocking communication for high-throughput scalability. </design_principles>

<code_rules>

• Maximize signal density: optimize signal-to-noise ratio, eliminate redundancy and noise.
• Write idiomatic Python: follow language conventions naturally, enable local reasoning.
• Fail-fast: validate inputs at boundaries, detect errors early.
• Use context managers (with statements) for resource management; use async with for async resources.
• Choose concurrency model based on workload: asyncio for I/O-bound, multiprocessing for CPU-bound.
• Add concise docstrings (file-level: what it does, make greppable; function-level: Google-style purpose and behavior).
• Make code self-explanatory: use descriptive names that reveal intent (avoid abbreviations, single letters except iterators).
• Use Pydantic v2 models to define and validate structured data.
• Place all imports at top of file; remove unused imports.
• Follow PEP 8 best practices.
• Use clear visual separation: two blank lines between top-level definitions (functions, classes); one blank line between methods.
• Use guard clauses and early returns to flatten logic; invert conditions to reduce nesting.
• Log key decision points and state transitions at architectural boundaries for traceability and debugging.
• Apply Python 3 static typing using PEP 585.
• Use asserts extensively for catching bugs (verify invariants, pre/postconditions); they're development-time checks, not runtime guarantees. Use raise (not assert) for input validation at public API boundaries.
• Prefer pure functions and immutable data structures to minimize state-change bugs.
• Prioritize vectorized operations over explicit loops for numerical data.
• Prefer composition over inheritance.
• Prefer specific exceptions over generic ones; let exceptions propagate unless you can recover or add context.
• Minimize try/except scope: wrap only operations that raise exceptions, not entire function bodies.
• Mark internal APIs with single leading underscore. </code_rules>