# AI Agents - Project Rules

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

Language-agnostic rules for AI assistants (Claude Code, Cursor, Copilot, etc.).

Everything language-specific — package manager, formatter, linter, test framework,
logging library, line length, project layout — lives in the matching design document:

| Project type       | Design document              |
|--------------------|------------------------------|
| Python application | `DESIGN_DOCUMENT.md`         |
| Python library     | `DESIGN_DOCUMENT_MODULE.md`  |
| Rust application   | `DESIGN_DOCUMENT.md`         |
| Rust library       | `DESIGN_DOCUMENT_LIB.md`     |
| Godot              | `DESIGN_DOCUMENT_GODOT.md`   |

Where this file and a design document disagree, **the design document wins**.

## 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 add and remove dependencies through the package manager CLI** — **never edit the manifest** (`pyproject.toml`, `Cargo.toml`, …) by hand
- The exact commands are in the design document for the given language

## Project Structure

- Source code, tests and detailed documentation each have their own directory — the concrete layout is in the design document
- Detailed documentation belongs in `docs/`, never in the project root
- The project root holds only the core documents: `README.md`, `CLAUDE.md`, `AGENTS.md`, `DESIGN_DOCUMENT*.md`, `PROJECT.md`, `CHANGELOG.md`
- Entry points follow the language convention; a project may have several
- The dependency/build directory (`.venv/`, `target/`, …) is tool-managed — do not copy it, do not generate it by hand

## Code

- **Always use static typing** — annotate every parameter and return value
- Format and lint with the tools named in the design document
- **Nothing is committed without a clean formatter, linter and test run**

## Testing

- Use the test framework named in the design document — never a second framework alongside it
- Arrange-Act-Assert pattern
- Test naming: `test_<action>_<context>`

## Logging

- Use the logging library named in the design document — **never `print()` (or its language equivalent) for debugging**
- Never log secrets, passwords, tokens, or API keys

## Environment and Secrets

- Applications store secrets in `.env` and load them at runtime — **never commit `.env`**
- Debug mode is driven by an `ENV_DEBUG=true/false` flag
- Libraries do not read `.env` — configuration is passed in by the caller

## Git

- `.gitignore` must cover at least: the dependency/build directory, tool caches, and `.env`
- **Commit the lock file for applications, do not commit it for libraries**
- **Every core document is committed**, including the shared ones (`CLAUDE.md`, `AGENTS.md`, `DESIGN_DOCUMENT*.md`). A checkout then carries the rules that applied to that code, and a fresh clone works standalone.
- **Never edit a shared document inside a project** — it is a copy. Changes belong in the documentation repository and are copied outward; project-specific deviations go in `PROJECT.md`.
- Synchronising the copies is its own commit (`docs: sync guidelines to AGENTS v7 / DESIGN_DOCUMENT v10`) and is **not** recorded in the project `CHANGELOG.md` — it is not a change to the product

### Commit messages

- **Never sign commits with AI authorship** — no `Co-Authored-By: Claude` (or any other assistant), no "Generated with …" line, no tool name or emoji footer. The same applies to pull request descriptions and issue comments.
- The commit author is the human running the tool; the message describes the change, nothing else
- Single-line verbal style — "Add X", "Fix Y", "Refactor Z" — never a filename-style message
- Written in English

## Versioning

- Follow semantic versioning (MAJOR.MINOR.PATCH)
- **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` **before** the version bump
- The version source of truth is the project manifest (`pyproject.toml`, `Cargo.toml`, `project.godot`)

## Task Management

Tasks are **single-line comments in the code**, written with Todo Tree tags:

| Tag      | Meaning                                          |
|----------|--------------------------------------------------|
| `TODO:`  | work still to be done                            |
| `FIXME:` | something broken that must be repaired           |
| `BUG:`   | a known defect, not fixed yet                    |
| `HACK:`  | temporary workaround, needs rewriting            |
| `NOTE:`  | important context for whoever reads this next    |

- **No checkboxes and no numbered task lists in documentation** — the code is the task list
- `PROJECT.md` carries only cross-cutting tasks that have no single place in the code
- If a tag already exists at a location in code, do not repeat it in `PROJECT.md`
- **Update documentation** — when completing changes, update the relevant sections of `PROJECT.md` and `CHANGELOG.md`