## 🔄 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:
  ```python
  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.