🔄 Project Awareness & Context

• Always read PLANNING.md at the start of a new conversation to understand the project's architecture, goals, style, and constraints.
• Check TASK.md before starting any task to understand current priorities and work.
• Maintain file structure and architecture patterns as defined in project documentation.
• Consider the entire project context when suggesting changes or additions.

🧱 Code Structure & Modularity

• Keep files under 500 lines of code. Split into modules when approaching this limit.
• Organize code into clear, logical modules grouped by feature or responsibility.
• Use consistent import styles (prefer relative imports within packages).
• Suggest refactoring when code becomes too complex or tightly coupled.

🧪 Testing & Reliability

• Create unit tests for all new features (functions, classes, routes, etc.).
• After updating logic, verify whether existing tests need updating.
• Tests should live in a /tests directory mirroring the main app structure.
• Include at least:
  • 1 test for expected use case
  • 1 test for edge cases
  • 1 test for failure scenarios
• Test early, test often - every feature should have tests before moving on.

✅ Task Management

• Start fresh conversations frequently to maintain high-quality responses.
• Focus on one task per message to avoid overloading.
• Mark completed tasks in TASK.md and add newly discovered work.
• Update project documentation as the codebase evolves.

📎 Style & Conventions

• Follow language-specific conventions (PEP8 for Python, etc.).
• Use type hints/annotations when available in the language.
• Be consistent with project formatting tools (black, prettier, etc.).
• Write descriptive docstrings for all functions, following the project's style:

  def example():
      """
      Brief summary of function purpose.
  
      Args:
          param1 (type): Description.
  
      Returns:
          type: Description.
      """
  

📚 Documentation & Explainability

• Document as you go - don't delay writing documentation.
• Update README.md when adding features, changing dependencies, or modifying setup steps.
• Add explanatory comments for complex or non-intuitive code.
• Use inline comments with # Reason: to explain why certain decisions were made.
• Write code that is understandable to a mid-level developer.

🔒 Security & Best Practices

• Never implement environment variables directly - instruct the user to set them up.
• Don't include API keys or secrets in code - use environment variables or secure vaults.
• Follow security best practices for input validation, authentication, etc.
• Validate and sanitize all inputs in user-facing interfaces.

🧠 AI Assistant Behavior

• Never assume missing context - ask questions if uncertain.
• Never hallucinate libraries or functions - use verified, real packages.
• Always verify file paths and module names before referencing them.
• Never delete existing code without explicit instructions.
• Provide explanations for suggested changes to help the user understand your reasoning.
• Suggest improvements when you notice opportunities for better design.

🐳 Deployment & Environment

• Consider containerization (Docker) when applicable for consistent deployment.
• Define clear deployment processes in documentation.
• Ensure reproducible environments through dependency management.
• Verify cross-environment compatibility of all code suggestions.