Dokumentace/Claude/AGENTS.md

AI Agents - Project Rules

Document Version: v6 (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, 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
• Never commit shared documentation (AGENTS.md, DESIGN_DOCUMENT*.md) — it comes from the documentation repository, not from the project
• README.md, PROJECT.md and CHANGELOG.md are committed — they are project-specific

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