82 lines
4.5 KiB
Markdown
82 lines
4.5 KiB
Markdown
# 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
|
|
│
|
|
├── 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
|
|
│ └── .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
|
|
```
|
|
|
|
## 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.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
|
|
- **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
|