Unify documentation rules across languages and fix the Python template
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Jan Doubravský
co-authored by
Claude Opus 5
Claude Opus 5
parent
19e9b8f2fa
commit
5c0f2f758f
+55
-44
@@ -1,12 +1,25 @@
|
||||
# AI Agents - Project Rules
|
||||
|
||||
**Document Version:** v4 (independent, incremented on structural changes)
|
||||
**Document Version:** v5 (independent, incremented on structural changes)
|
||||
|
||||
Rules and instructions for AI assistants (Claude Code, Cursor, Copilot, etc.)
|
||||
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.
|
||||
- **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
|
||||
|
||||
@@ -14,70 +27,68 @@ Rules and instructions for AI assistants (Claude Code, Cursor, Copilot, etc.)
|
||||
|
||||
## Dependency Management
|
||||
|
||||
- **Always use `poetry add`** to add dependencies, **never edit `pyproject.toml` directly**
|
||||
```bash
|
||||
poetry add requests
|
||||
poetry add --group dev pytest
|
||||
```
|
||||
- Use `poetry remove` to remove dependencies — **never edit `pyproject.toml` manually**
|
||||
- **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
|
||||
|
||||
- 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)
|
||||
- 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 type annotations
|
||||
- Follow PEP8 and format with Ruff (88 characters per line)
|
||||
- Before commit run `poetry run ruff check` and `poetry run mypy`
|
||||
- **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 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:
|
||||
```bash
|
||||
poetry run python project_name.py
|
||||
poetry run pytest
|
||||
```
|
||||
- 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 **loguru** for logging - never use `print()` for debugging
|
||||
- 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
|
||||
|
||||
- Store secrets in `.env` file with `ENV_DEBUG=true/false` variable
|
||||
- Load secrets using `python-dotenv` and `os.getenv()`
|
||||
- **Never commit `.env` file**
|
||||
- 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` 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
|
||||
- `.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
|
||||
|
||||
## 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)
|
||||
- **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
|
||||
|
||||
- **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
|
||||
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`
|
||||
|
||||
+1
-1
@@ -7,4 +7,4 @@
|
||||
- `AGENTS.md`
|
||||
- `PROJECT.md`
|
||||
- `CHANGELOG.md`
|
||||
- `DESIGN_DOCUMENT.md`
|
||||
- `DESIGN_DOCUMENT*.md` (`DESIGN_DOCUMENT.md`, `DESIGN_DOCUMENT_MODULE.md`, `DESIGN_DOCUMENT_LIB.md` or `DESIGN_DOCUMENT_GODOT.md`)
|
||||
@@ -5,4 +5,4 @@ description: Updates changelog in project
|
||||
|
||||
Take known info and make changes to CHANGELOG.md to make them up-to-date.
|
||||
|
||||
Ignore changes to: `docs/`, `CONTEXT.md`, `Documentation_AI.md`, `Documentation_human.md` — documentation and context files are not logged in the changelog.
|
||||
Ignore changes to: `docs/`, `CONTEXT.md`, `AGENTS.md`, `DESIGN_DOCUMENT*.md`, `PROJECT.md` — documentation and context files are not logged in the changelog.
|
||||
|
||||
Reference in New Issue
Block a user