Tagger/AGENTS.md

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

  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:

  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