Put the language in design document names and add a sync mode
This commit is contained in:
Jan Doubravský
@@ -10,45 +10,45 @@ 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 # 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
|
||||
├── 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.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
|
||||
├── 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.md # Guidelines for Rust applications
|
||||
│ ├── DESIGN_DOCUMENT_LIB.md # Guidelines for Rust libraries
|
||||
│ └── .gitignore # Rust-specific ignore rules
|
||||
├── 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
|
||||
├── 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
|
||||
├── 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
|
||||
├── 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
|
||||
├── check_versions.py # Reports projects whose guideline copies are behind
|
||||
└── CHANGELOG.md # History of this repository
|
||||
```
|
||||
|
||||
## AI Coding Workflow
|
||||
@@ -62,10 +62,10 @@ 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` |
|
||||
| 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
|
||||
@@ -84,7 +84,7 @@ are **committed there**. They are duplicated on purpose:
|
||||
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.md` shows when a project was last synchronised.
|
||||
- Drift becomes visible: `git log DESIGN_DOCUMENT_PYTHON.md` shows when a project was last synchronised.
|
||||
|
||||
Three rules keep the copies from rotting:
|
||||
|
||||
@@ -93,10 +93,25 @@ Three rules keep the copies from rotting:
|
||||
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 v6 / DESIGN_DOCUMENT v9`. They do not go into the project
|
||||
`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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user