From 7cf235db83c27388d51f6563d0ca735c305c5b52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Doubravsk=C3=BD?= Date: Tue, 18 Aug 2026 13:28:01 +0200 Subject: [PATCH] Documentation updated --- AGENTS.md | 26 +++++++++++-------- CLAUDE.md | 4 +-- ...ULE.md => DESIGN_DOCUMENT_PYTHON_MODULE.md | 4 +-- 3 files changed, 19 insertions(+), 15 deletions(-) rename DESIGN_DOCUMENT_MODULE.md => DESIGN_DOCUMENT_PYTHON_MODULE.md (98%) diff --git a/AGENTS.md b/AGENTS.md index 053c8a8..933fa33 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,19 +1,22 @@ # AI Agents - Project Rules -**Document Version:** v6 (independent, incremented on structural changes) +**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.md` | -| Python library | `DESIGN_DOCUMENT_MODULE.md` | -| Rust application | `DESIGN_DOCUMENT.md` | -| Rust library | `DESIGN_DOCUMENT_LIB.md` | -| Godot | `DESIGN_DOCUMENT_GODOT.md` | +| 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**. @@ -34,7 +37,7 @@ Where this file and a design document disagree, **the design document wins**. - 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` +- 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 @@ -65,8 +68,9 @@ Where this file and a design document disagree, **the design document wins**. - `.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 +- **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 diff --git a/CLAUDE.md b/CLAUDE.md index c4aa103..303fe6a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,6 @@ # CLAUDE.md -**Document Version:** v2 (independent, incremented on structural changes) +**Document Version:** v3 (independent, incremented on structural changes) ## First-time setup @@ -11,4 +11,4 @@ - `AGENTS.md` - `PROJECT.md` - `CHANGELOG.md` -- `DESIGN_DOCUMENT*.md` (`DESIGN_DOCUMENT.md`, `DESIGN_DOCUMENT_MODULE.md`, `DESIGN_DOCUMENT_LIB.md` or `DESIGN_DOCUMENT_GODOT.md`) +- `DESIGN_DOCUMENT*.md` — one per language used in the project (`DESIGN_DOCUMENT_PYTHON.md`, `DESIGN_DOCUMENT_PYTHON_MODULE.md`, `DESIGN_DOCUMENT_RUST.md`, `DESIGN_DOCUMENT_RUST_LIB.md`, `DESIGN_DOCUMENT_GODOT.md`) diff --git a/DESIGN_DOCUMENT_MODULE.md b/DESIGN_DOCUMENT_PYTHON_MODULE.md similarity index 98% rename from DESIGN_DOCUMENT_MODULE.md rename to DESIGN_DOCUMENT_PYTHON_MODULE.md index 4fcfa84..590a799 100644 --- a/DESIGN_DOCUMENT_MODULE.md +++ b/DESIGN_DOCUMENT_PYTHON_MODULE.md @@ -1,6 +1,6 @@ # Python Library Development Guidelines -**Document Version:** v2 +**Document Version:** v4 > **Note on Versioning:** > - This document version is independent — reused across projects @@ -18,7 +18,7 @@ All detailed documentation of features and systems belongs in the `docs/` folder, not in the project root. -The root directory contains only the core documents: `README.md`, `AGENTS.md`, `DESIGN_DOCUMENT_MODULE.md`, `PROJECT.md`, `CHANGELOG.md`. +The root directory contains only the core documents: `README.md`, `CLAUDE.md`, `AGENTS.md`, `DESIGN_DOCUMENT_PYTHON_MODULE.md`, `PROJECT.md`, `CHANGELOG.md`. ---