106 lines
5.4 KiB
Markdown
106 lines
5.4 KiB
Markdown
# 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`
|