# Dokumentace Personal development documentation — guidelines, conventions, and templates for my projects, structured for use with AI coding assistants. ## Purpose This repository is the single source of truth for how I develop software. AI assistants (Claude Code, Cursor, Copilot) are given these documents at the start of each session to understand my conventions before touching any code. ## Structure ``` Dokumentace/ ├── Claude/ # AI assistant configuration │ ├── CLAUDE.md # Claude Code session instructions │ ├── AGENTS.md # Language-agnostic rules for all AI assistants │ └── skills/ # Custom Claude Code skills │ ├── changelog/ # /changelog — update CHANGELOG.md │ ├── check/ # /check — run tests, investigate failures │ ├── commit/ # /commit — changelog + commit message proposal │ ├── documentation/ # /documentation — write docs/ │ └── documentation_context/ # /documentation_context — compress docs/ into CONTEXT.md │ ├── Python/ # Python development guidelines │ ├── DESIGN_DOCUMENT_PYTHON.md # Guidelines for Python applications │ ├── DESIGN_DOCUMENT_PYTHON_MODULE.md # Guidelines for Python libraries │ ├── TEMPLATE.md # New project template specification │ ├── .gitignore # Python-specific ignore rules │ ├── prebuild.py # Pre-build script (PyInstaller) │ ├── src/ # Reference constants module + version fallback │ └── tests/ # Tests for the reference module │ ├── Rust/ # Rust development guidelines │ ├── DESIGN_DOCUMENT_RUST.md # Guidelines for Rust applications │ ├── DESIGN_DOCUMENT_RUST_LIB.md # Guidelines for Rust libraries │ └── .gitignore # Rust-specific ignore rules │ ├── Godot/ # Godot development guidelines │ ├── DESIGN_DOCUMENT_GODOT.md # Guidelines for Godot projects │ └── .gitignore # Godot-specific ignore rules │ ├── Project template/ # Reusable files for new projects │ ├── CHANGELOG.md # Changelog template │ ├── PROJECT.md # Project documentation template │ └── .gitignore # Shared, language-agnostic ignore rules │ ├── Zscaler/ # Corporate network setup │ ├── ZSCALER_CERTIFICATE.md # Cert setup for Node, Python, git, cargo │ └── ZscalerRootCertificate-2048-SHA256.crt │ ├── check_versions.py # Reports projects whose guideline copies are behind └── CHANGELOG.md # History of this repository ``` ## AI Coding Workflow Every project gets two rule documents, and the split between them is strict: - **AGENTS.md** — language-agnostic rules only: documentation language, dependency management, static typing, secrets, git, versioning, task notation. It names no concrete tool. - **DESIGN_DOCUMENT\*.md** — everything language-specific: package manager, formatter, linter, test framework, logging library, line length, project layout, distribution. Where the two disagree, **the design document wins**. | Project type | Design document | |--------------|-----------------| | Python (application) | `Python/DESIGN_DOCUMENT_PYTHON.md` | | Python (library) | `Python/DESIGN_DOCUMENT_PYTHON_MODULE.md` | | Rust (application) | `Rust/DESIGN_DOCUMENT_RUST.md` | | Rust (library) | `Rust/DESIGN_DOCUMENT_RUST_LIB.md` | | Godot | `Godot/DESIGN_DOCUMENT_GODOT.md` | ### Starting a new project 1. Copy `Project template/PROJECT.md` and `Project template/CHANGELOG.md` into the project root and write a `README.md` — all three are committed. 2. Build `.gitignore` from `Project template/.gitignore` plus the `.gitignore` of the matching language folder. 3. Copy `Claude/CLAUDE.md`, `Claude/AGENTS.md` and the matching `DESIGN_DOCUMENT*.md` into the project root. This repository is their source of truth, but the copies **are committed** with the project — see "Guideline copies in projects" below. 4. For Python, follow `Python/TEMPLATE.md` to generate the project skeleton. ### Guideline copies in projects `CLAUDE.md`, `AGENTS.md` and the matching `DESIGN_DOCUMENT*.md` live in the root of every project and are **committed there**. They are duplicated on purpose: - A checkout of an old commit carries the rules that applied to that code. Kept only here, the guidelines are always "latest" and the pairing is lost. - A fresh clone — another machine, CI, Claude Code on the web or a remote agent — has to work standalone. `CLAUDE.md` and `AGENTS.md` are only picked up from the repository root. - Drift becomes visible: `git log DESIGN_DOCUMENT_PYTHON.md` shows when a project was last synchronised. Three rules keep the copies from rotting: - **Never edit a copy inside a project.** Changes go into this repository and are copied outward. - **Project-specific deviations belong in `PROJECT.md`**, which is project-owned and already on the session read list. That is also where extra files to read (for example a generated `CONTEXT.md`) are named. - **Sync commits stand alone**, in the form `docs: sync guidelines to AGENTS v8 / DESIGN_DOCUMENT_PYTHON v11`. They do not go into the project `CHANGELOG.md` — they are not a change to the product. Run `check_versions.py` from this repository to list every sibling project whose copies are behind. Add `--sync` and it offers to overwrite the outdated copies with the master version, keeping each file's existing line endings. Only copies that are purely behind or still carry a pre-rename name are offered: one edited in place is reported as `MODIFIED` and left alone, because copying would silently discard the local change. A project still holding `DESIGN_DOCUMENT.md`, `DESIGN_DOCUMENT_MODULE.md` or `DESIGN_DOCUMENT_LIB.md` from before the rename is reported as `OLD NAME`, and `--sync` renames it on the way. If both the old and the new name exist the copy is flagged `DUPLICATE` and left for you to resolve. ```bash python check_versions.py # report only python check_versions.py --sync # report, then ask before copying python check_versions.py --sync --dry-run # show what would be copied, change nothing python check_versions.py --sync --yes # copy without asking, for scripts ``` ### Skills The skills in `Claude/skills/` are the source of truth; the copies Claude Code actually runs live in `~/.claude/skills/`. Install or refresh them by copying the whole folder across. Two rules keep the two sides from drifting apart: - **The folder name is the command.** For personal skills the frontmatter `name` is only a display label — `/documentation_context` comes from the directory, not from `name:`. Keep the two identical so renaming a folder can never silently change the command. - **Every skill carries a version** in `metadata.version`, incremented on every content change, the same way design documents carry `Document Version`: ```yaml --- name: commit description: Updates changelog and proposes a concise verbal git commit message metadata: version: v2 --- ``` There is no top-level `version:` field in the skill format. `metadata` is a free-form map that Claude Code ignores, and it is one of the six fields the [Agent Skills](https://agentskills.io) spec allows — so it also survives an upload to claude.ai or the Skills API. Any other invented key fails packaging with `Unexpected key(s) in SKILL.md frontmatter`. ## Key Conventions - **Python tooling:** Poetry · Ruff · mypy · pytest · loguru - **Rust tooling:** Cargo · rustfmt · clippy · tracing (`thiserror` / `anyhow` for errors) - **Godot tooling:** gdformat · gdlint · GUT - **No `print()` for debugging** — the language's logging library, everywhere - **Static typing required** on every parameter and return value - **Line length:** 120 characters (Python), 100 characters (Rust, rustfmt default), 100 soft limit (GDScript) - **Tests:** the framework named in the design document — pytest (Python, never `unittest`), built-in `#[test]` (Rust), GUT (Godot) - **Tasks:** single-line `TODO` / `FIXME` / `BUG` / `HACK` / `NOTE` comments in code — no checkboxes in documentation - **Versioning:** semantic, always ask before bumping, `CHANGELOG.md` updated first - **Secrets:** `.env`, never committed; libraries take configuration from the caller