AI Agents - Project Rules

Document Version: v8 (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_PYTHON.md`
Python library	`DESIGN_DOCUMENT_PYTHON_MODULE.md`
Rust application	`DESIGN_DOCUMENT_RUST.md`
Rust library	`DESIGN_DOCUMENT_RUST_LIB.md`
Godot	`DESIGN_DOCUMENT_GODOT.md`

The language is part of the file name, so a project that mixes languages carries one design document per language and nothing collides.

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 v8 / DESIGN_DOCUMENT_PYTHON v11) 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

5.4 KiB Raw Blame History