#### 1. **Project Structure**
- Always suggest a modular folder structure:
  ```
  /bot
    ├── __init__.py
    ├── handlers/
    ├── services/
    ├── utils/
    ├── config.py
    └── main.py
  ```
- Handlers contain Telegram event-specific logic (e.g., `/start`, messages).
- Services contain external logic (e.g., database, APIs).
- Utils contain reusable tools and helpers.

#### 2. **Framework and Libraries**
- Prefer `python-telegram-bot` (latest v20+ unless specified).
- Use `asyncio` (async/await) for non-blocking bot.
- If needed, integrate `aiogram` or `telethon` based on use case.
- Use `python-dotenv` or `pydantic` for managing environment variables.

#### 3. **Command and Message Handling**
- Separate command handlers (`/start`, `/help`) from message/text handlers.
- Use command filters and `MessageHandler` for text processing.
- Enforce clear handler registration in `main.py`.

#### 4. **Security and Tokens**
- Never hardcode the bot token or secrets.
- Load secrets using environment variables or `.env` file.
- Suggest use of `dotenv.load_dotenv()` or `os.getenv()`.

#### 5. **Logging and Debugging**
- Always include basic logging configuration.
- Avoid `print()` for production; use `logging.info/debug/error`.

#### 6. **State Management**
- If needed, recommend `ConversationHandler` for multi-step user flows.
- Store temporary user states in-memory or use Redis if scaling.

#### 7. **Extensibility**
- Always write code with scalability in mind:
  - Easy to add new commands
  - Clean separation of logic
- Support dynamic command routing if needed.

#### 8. **Testing & Linting**
- Write tests using `pytest` or `unittest`.
- Enforce formatting with `black`, `flake8`, or `ruff`.

#### 9. **Deployment**
- Support running via:
  - `python main.py`
  - Docker (provide sample `Dockerfile` and `docker-compose.yml`)
- Bot should be able to run locally or in the cloud (Heroku, Railway, etc).

#### 10. **Assistant Communication**
- Explain *why* a certain method or structure is recommended.
- Ask clarifying questions when requirements are vague.
- Prefer full code snippets with comments.
- If generating a new file, provide suggested filename/path.
- Suggest improvements without being intrusive.

### **Rule 11: Virtual Environment Management**
- Always create a virtual environment before installing dependencies.
  - Use:  
    - `python -m venv venv` *(preferred standard)*  
    - or `poetry` for advanced dependency + packaging management  
- Activate the virtual environment using:
  - **Windows**: `venv\Scripts\activate`
  - **Unix/macOS**: `source venv/bin/activate`
- Enforce all package installations via `pip install ...` **only after activation**.
- Generate and maintain a `requirements.txt` file using:
  - `pip freeze > requirements.txt`
- If using `poetry` or `pipenv`, handle lock files (`poetry.lock`, `Pipfile.lock`) appropriately.
- Include `.venv/` or `venv/` in `.gitignore`:
  ```
  venv/
  .venv/
  ```
- Document how to set up the environment in a `README.md`:
  ```bash
  python -m venv venv
  source venv/bin/activate
  pip install -r requirements.txt
  ```