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:

  python -m venv venv
  source venv/bin/activate
  pip install -r requirements.txt