Preskoči na sadržaj

.arch/ baseline + drift gate

TL;DR

Per-subsystem graph.json + arch-state.json + opcioni diagram.md baseline u .arch/<sub>/. Generiše ih bin/design. Stop-hook (bin/check_arch_reminder.py) detektuje drift i pita za regeneraciju. Source-of-truth je kod, baseline je generisan artifact — commit-uj generisani, ne kodiraj ručno.

Struktura

.arch/
├── <subsystem>/
│   ├── graph.json       # ulazni graf (ko zavisi od koga)
│   ├── arch-state.json  # baseline fingerprint + drift status
│   └── diagram.md       # opcioni Mermaid diagram (committable)

15 subsystems: aws, coolify, docker, expo, flagsmith, git, github, infisical, json, lint, make, registry, sentry, slack, verbs.

Zašto baseline + drift

Bez baseline-a: promijeniš ci/coolify/CLAUDE.md, niko ne zna da li je neki drugi fajl (npr. ci/verbs/deploy.py) trebao da se ažurira u skladu s tim.

Sa baseline-om:

  • bin/design generate generiše graph.json sa svim vezama.
  • Mtime tracking: ako ci/<vendor>/ mtime > .arch/<sub>/graph.json mtime → drift.
  • Stop-hook pita da se regeneriše.

Kada regen

Situacija Akcija
Promijenio ci/<vendor>/** bin/design generate za <vendor> subsystem
Dodao novi vendor bin/design generate za ci/ cross-reference
Dodao novi call site u ci/ bin/design generate za verb/cross-section
Samo typo fix u komentaru NE treba regen (nema structural change)

Kada NE regen

  • Čisti comment/docstring edit (nema import/call promjene).
  • Promjena u tests/ (test nema production dependency).
  • Promjena u .arch/ samoj (regen je circular).

Mtime clear (bez regen)

Ako SI generisao baseline, ali stop-hook i dalje pita:

# Per-subsystem (bez structural change):
touch .arch/<sub>/graph.json

# NE: bin/design generate (pollutira sa worktree path-ovima)

touch graph.json je za verified case-(a) — znaš da je baseline istinit, samo ga osvježi mtime. Za case-(b) (stvarno structural change) — bin/design generate.

Hook ponašanje u worktree

bin/check_arch_reminder.py preskače worktree sesije (cwd pod .claude/worktrees/). Neće ometati tvoj rad u worktree-u.

Ako se ikad aktivira u worktree-u, regresija je u skip-detection logici.

Dijagrami (Mermaid)

bin/design mermaid generiše Mermaid flowchart u .arch/<sub>/diagram.md. Koristan za PR opis ili ruke za brainstorming.

Mermaid mora biti byte-faithful sa kod control flow-om. Ako dijagram laže o kodu, codex stop-hook će uhvatiti. Fiksiranje dijagrama = dio PR-a, ne "kasnije".

Vidi i