# AI Agents - Project Rules

**Document Version:** v4 (independent, incremented on structural changes)

Rules and instructions for AI assistants (Claude Code, Cursor, Copilot, etc.)

## First-time setup

- **On first read of this file, immediately read all other `.md` files in the project root** (e.g. `PROJECT.md`, `CHANGELOG.md`, `DESIGN_DOCUMENT.md`) to get full project context before starting any task.

## Language

- **Always write all documentation in English**

## Dependency Management

- **Always use `poetry add`** to add dependencies, **never edit `pyproject.toml` directly**
  ```bash
  poetry add requests
  poetry add --group dev pytest
  ```
- Use `poetry remove` to remove dependencies — **never edit `pyproject.toml` manually**

## Project Structure

- Entry points are in the project root (named after project or by purpose: `project_name.py`, `cli.py`, `gui.py`, `server.py`)
- A project can have multiple entry points
- All modules belong in the `src/` folder
- Tests belong in the `tests/` folder
- Virtual environment is in `.venv/` (do not copy, do not generate)

## Code

- Always use type annotations
- Follow PEP8 and format with Ruff (88 characters per line)
- Before commit run `poetry run ruff check` and `poetry run mypy`

## Testing

- **Use pytest exclusively** - never use the `unittest` module
- No `unittest.TestCase` classes, no `self.assert*` methods
- Use plain `assert` statements and pytest fixtures

## Running

- Use `poetry run` to run scripts:
  ```bash
  poetry run python project_name.py
  poetry run pytest
  ```

## Logging

- Use **loguru** for logging - never use `print()` for debugging
- Never log secrets, passwords, tokens, or API keys

## Environment and Secrets

- Store secrets in `.env` file with `ENV_DEBUG=true/false` variable
- Load secrets using `python-dotenv` and `os.getenv()`
- **Never commit `.env` file**

## Git

- `.gitignore` should contain: `.venv/`, `__pycache__/`, `*.pyc`, `.mypy_cache/`, `.env`
- Do not commit `poetry.lock` only if it's a library (for applications, commit it)
- **Never commit this documentation** (`DESIGN_DOCUMENT.md`, `AGENTS.md`, `.claudeignore`)
- `PROJECT.md` **should be committed** - it's project-specific

## Versioning

- **Always ask user before bumping version** - never increase version automatically
- **Keep `CHANGELOG.md` updated** - document all significant changes as they are made
- Update `CHANGELOG.md` with changes before version bump
- Version is defined in `pyproject.toml` under `[project]` section
- Follow semantic versioning (MAJOR.MINOR.PATCH)

## Task Management

- **When completing tasks, mark them as done** - if you finish any task with a checkbox anywhere in project documentation, check it off as completed `[ ]` → `[x]`
- **Track all work** - this applies to tasks in `PROJECT.md` (TODO section, Development Roadmap, any checklists) and other documentation
- **Update documentation** - when completing changes, update relevant sections in `PROJECT.md`, `CHANGELOG.md`, and architecture diagrams
- **Keep task lists current** - completed items with `[x]` stay visible to show progress history