Dokumentace/README.md

# 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