Honza/Dokumentace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Unify documentation rules across languages and fix the Python template

Browse Source 
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Jan Doubravský
2026-08-18 10:33:00 +02:00
co-authored by Claude Opus 5
parent 19e9b8f2fa
commit 5c0f2f758f
19 changed files with 502 additions and 244 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+49 -29
View File
@@ -10,52 +10,72 @@ This repository is the single source of truth for how I develop software. AI ass
```
Dokumentace/
├── Claude/ # AI assistant configuration
│ ├── CLAUDE.md # Claude Code session instructions
│ ├── AGENTS.md # Rules for all AI assistants
│ └── skills/ # Custom Claude Code skills
├── Claude/ # AI assistant configuration
│ ├── CLAUDE.md # Claude Code session instructions
│ ├── AGENTS.md # Language-agnostic rules for all AI assistants
│ └── skills/ # Custom Claude Code skills
│
├── Python/ # Python development guidelines
│ ├── DESIGN_DOCUMENT.md # Guidelines for Python applications
│ ├── DESIGN_DOCUMENT_MODULE.md # Guidelines for Python libraries
│ ├── TEMPLATE.md # New project template specification
│ └── prebuild.py # Pre-build script (PyInstaller)
├── Python/ # Python development guidelines
│ ├── DESIGN_DOCUMENT.md # Guidelines for Python applications
│ ├── DESIGN_DOCUMENT_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.md # Guidelines for Rust applications
│ └── DESIGN_DOCUMENT_LIB.md # Guidelines for Rust libraries
├── Rust/ # Rust development guidelines
│ ├── DESIGN_DOCUMENT.md # Guidelines for Rust applications
│ ├── DESIGN_DOCUMENT_LIB.md # Guidelines for Rust libraries
│ └── .gitignore # Rust-specific ignore rules
│
├── Project template/ # Reusable files for new projects
│ ├── CHANGELOG.md # Changelog template
│ └── PROJECT.md # Project documentation template
├── Godot/ # Godot development guidelines
│ ├── DESIGN_DOCUMENT_GODOT.md # Guidelines for Godot projects
│ └── .gitignore # Godot-specific ignore rules
│
└── Zscaler/ # Corporate network setup
├── NODE_EXTRA_CA_CERTS.md # Instructions for Zscaler cert
├── 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
```
## AI Coding Workflow
Each project references these documents so AI assistants operate within consistent rules:
Every project gets two rule documents, and the split between them is strict:
- **AGENTS.md** — language-agnostic rules: dependency management, testing, logging, git, versioning
- **DESIGN_DOCUMENT.md** — Python-specific: code style, tooling (Ruff, mypy, pytest, Poetry), project structure, logging with loguru, distribution via PyInstaller
- **DESIGN_DOCUMENT_MODULE.md** — same as above, adapted for Python libraries (no sinks, no `.env`, PyPI distribution)
- **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.
## Languages Covered
Where the two disagree, **the design document wins**.
| Language | Guidelines |
|----------|-----------|
| Project type | Design document |
|--------------|-----------------|
| Python (application) | `Python/DESIGN_DOCUMENT.md` |
| Python (library) | `Python/DESIGN_DOCUMENT_MODULE.md` |
| Rust (application) | `Rust/DESIGN_DOCUMENT.md` |
| Rust (library) | `Rust/DESIGN_DOCUMENT_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 — both are committed.
2. Build `.gitignore` from `Project template/.gitignore` plus the `.gitignore` of the matching language folder.
3. Copy `Claude/AGENTS.md` and the matching `DESIGN_DOCUMENT*.md` into the project root — these are **not** committed, they come from here.
4. For Python, follow `Python/TEMPLATE.md` to generate the project skeleton.
## Key Conventions
- **Python tooling:** Poetry · Ruff · mypy · pytest · loguru
- **No print() for debugging** — loguru everywhere
- **Type hints required** on all functions
- **Tests:** pytest only, no unittest, no mocks of the database
- **Versioning:** semantic, always ask before bumping
- **Secrets:** `.env` + `python-dotenv`, never committed
- **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 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