rules:

• name: Code Structure & Project Layout rule: Use a src/ layout to separate core logic from entry points. Organize code into packages by domain or functionality. Include __init__.py in every package. Use separate folders for tests/, configs/, and scripts/. Follow naming conventions: snake_case for files/functions, PascalCase for classes.

• name: Data Structures & Immutability rule: Use dataclass for simple data containers. Prefer namedtuple or TypedDict when immutability or performance is important. Use Enum for fixed constant sets. Avoid using plain dicts/lists when a class adds clarity. Do not mutate global state—use dependency injection.

• name: Class Design & OOP Patterns rule: Prefer composition over inheritance. Use patterns like strategy, factory, or adapter when suitable. Avoid "god classes"; each class should be small and focused. Use ABCs for interface contracts. Add docstrings that clearly explain responsibilities.

• name: Type Safety & Annotations rule: Always annotate functions and methods with parameter and return types. Use Optional, Union, and Literal from typing. For complex types, use pydantic or attrs. Enforce type checks with mypy.

• name: Testing & Coverage rule: Use pytest with test_*.py naming. Target at least 90% test coverage for logic. Mock external services. Use @pytest.mark.parametrize for test variants. Always test edge cases.

• name: Logging & Observability rule: Use the logging module instead of print(). Structure logs with context like request_id or user_id. Choose appropriate log levels (debug, info, warning, etc.).

• name: Performance-Aware Development rule: Use generators and list comprehensions to reduce memory use. Cache expensive functions with lru_cache. Avoid nested loops unless necessary. Use timeit or profilers before optimizing. Stream large data instead of loading it all into memory.

• name: Security Best Practices rule: Never hardcode secrets or tokens—use environment variables or secrets managers. Always validate inputs from JSON, CLI, or forms. Sanitize SQL or shell inputs. Use secrets module for randomness. Pin versions in requirements.txt or pyproject.toml.

• name: Documentation & Maintainability rule: Write docstrings for all public functions and classes. Use descriptive, non-abbreviated names. Maintain a README.md with setup instructions. Document CLI args and config options. Use comments to explain decisions, not what the code obviously does.