84 lines
3.1 KiB
Markdown
84 lines
3.1 KiB
Markdown
|
# 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
|