Core Rules

• Prioritize working, correct code over perfect process.
• Make the smallest reasonable changes.
• Match the style of surrounding code.  

Development Flow

• Understand requirements before coding.
• For non-trivial tasks, outline a short plan first.
• Implement incrementally.
• Add tests for new critical logic or bug fixes.  

Code Standards

• Keep functions small and single-purpose.
• Use clear, domain-specific names.
• Extract repeated strings, numbers, and config to centralized files (should be in constants).
• Prefer simple solutions; refactor only after verification.
• No unnecessary comments.
• Type hints required on all function signatures (arguments and return values). Use specific types (e.g., List[str] not list).
• Google-style docstrings on all modules, classes, and functions. Include Args, Returns, and Raises where applicable.  - UI on desktop and basic mobile sizes should be coherent.

Module Structure

• Order every file top to bottom: copyright header, imports, constants, classes, functions, if __name__ block.
• Group imports: standard library, then third-party, then local/relative. All at the top of the file.  

Testing

• Test files named test_*.py, one per source module.
• Test names follow test_<what>_<condition>_<expected_result>.
• Every test function must have a docstring.
• Use unittest.mock.Mock with spec= for mocking.  

Feature Flags & Debug

• Use feature flags for experimental, debug, or incomplete work.
• Wrap debug code, logs, or new features behind flags.
• Disable or remove debug code in production builds.
• Document flags in a central config or README.
• Never ship code that relies on debug flags being on.  

Security

• Never hardcode secrets or keys.
• Use .env (gitignored) or server/runtime environment only.
• After auth or data changes, check build outputs for accidental exposure.  

Writing Style

• Be direct and concise. State assumptions and limitations clearly.
• Use plain English (avoid overcomplicated explanations, excessive specifics, or deep jargon).
• No "This isn't X. It's Y." contrast patterns.
• No self-answering rhetorical questions.
• No em-dashes; use commas instead.
• No three-part alliterative phrases.
• No vague inspirational pivots.
• No unsourced claims or unverified quotes.  

End-to-end Validation (Occasionally verify changes by running the app and testing affected flows)

• Build must succeed with zero errors.
• Test changed functionality manually.
• Check UI on desktop and basic mobile sizes.