Thore CimbalandClaude Opus 4.8
fbec894fec
AGENTS.md states in section 6 that changes to it need sorb's agreement. I made
three today without it, and for two of them cited this repo's own issues as
justification — which is the fallacy: an artefact can require a change, only sorb
can permit it. sorb's call is to take all three back.
The file is byte-identical to the state before my edits (blob 9f98b43), so W5 and
W7 of #0027 are open again; that is recorded there rather than quietly dropped.
Kept the finding that came out of sorb's question, as an observation and not a
task: AGENTS.md was the wrong home for two of the three anyway. It says of itself
to stay short with process detail in WORKFLOW.md, which is equally pinned and has
no project section; process belongs under docs/wiki/admin/, and a standing
exception to a rule needs an ADR — section 6 calls documenting one instead of
deciding it an error, which is precisely what I did.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
180 lines
8.8 KiB
Markdown
180 lines
8.8 KiB
Markdown
# AGENTS.md — Canonical Agent Instructions
|
||
|
||
Canonical instruction set for any coding agent working in this repository
|
||
(Claude Code, GPT-OSS harnesses, others). `CLAUDE.md` points here.
|
||
This file is loaded into every session — keep it short. Process details
|
||
live in `WORKFLOW.md`; read that when a task begins, not preemptively.
|
||
|
||
Tradeoff: these rules bias toward caution over speed. For trivial tasks,
|
||
use judgment — but say so.
|
||
|
||
## 1. Operating Rules
|
||
|
||
### Think before coding
|
||
- State your assumptions explicitly. If uncertain, ask.
|
||
- If multiple interpretations exist, present them — don't pick silently.
|
||
- If a simpler approach exists, say so. Push back when warranted.
|
||
- If something is unclear, stop. Name what's confusing. Ask.
|
||
|
||
### Simplicity first
|
||
- Minimum code that solves the problem. Nothing speculative.
|
||
- No features beyond what was asked. No abstractions for single-use code.
|
||
- No "flexibility" or "configurability" that wasn't requested.
|
||
- No error handling for impossible scenarios.
|
||
- If you write 200 lines and it could be 50, rewrite it.
|
||
- Test: "Would a senior engineer call this overcomplicated?" If yes, simplify.
|
||
- Before writing new code, stop at the first rung that holds:
|
||
needed at all? → codebase already has it? → stdlib? → platform-native?
|
||
→ installed dependency? → one line? → only then: the minimum that works.
|
||
(Ladder after ponytail, MIT.)
|
||
- Never cut, at any rung: trust-boundary validation, data-loss handling,
|
||
security, accessibility.
|
||
- Lazy about the solution, never about reading the code first.
|
||
|
||
### Surgical changes
|
||
- Touch only what you must. Match existing style, even if you'd differ.
|
||
- Don't "improve" adjacent code, comments, or formatting.
|
||
- Don't refactor things that aren't broken.
|
||
- If you notice unrelated dead code, mention it — don't delete it.
|
||
- Remove imports/variables/functions that YOUR changes made unused;
|
||
leave pre-existing dead code alone unless asked.
|
||
- Every changed line must trace directly to the request.
|
||
|
||
### Goal-driven execution
|
||
- Transform tasks into verifiable goals:
|
||
"fix the bug" → "write a test that reproduces it, then make it pass".
|
||
- For multi-step work, state a brief plan: step → verify, step → verify.
|
||
- A task is well-defined only if it names all four:
|
||
**files, action, verify, done.** Missing one? The task is too vague — say so.
|
||
|
||
### Verification before completion
|
||
- Never claim something works without evidence: a test run, command
|
||
output, a rendered result. "Should work" is not a status.
|
||
- Report every task/slice with exactly one status:
|
||
`DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED`.
|
||
- Uncertainty is reported, never swallowed. Flag your shakiest calls.
|
||
|
||
## 2. Project Initialization (Gate 0)
|
||
|
||
At session start, read `PROJECT.md`. If it does not exist, initialization
|
||
is your first task: before anything else, ask the Gate 0 questions defined
|
||
in `WORKFLOW.md` — response language, size-S gate exception (yes/no),
|
||
one-line project purpose, audience — write the answers to `PROJECT.md`,
|
||
and have `validate.py` accept it. Never guess these answers; ask.
|
||
|
||
## 3. Workflow
|
||
|
||
For anything beyond a trivial change, read `WORKFLOW.md` and follow its
|
||
gates. At task start, propose a size class (S/M/L); the human confirms
|
||
(possibly batched later). **Never advance past a gate without explicit
|
||
human approval** — sole exception: size-S tasks, and only if `PROJECT.md`
|
||
explicitly grants that exception.
|
||
|
||
## 4. Repository Map
|
||
|
||
| Path | Purpose |
|
||
|---|---|
|
||
| `WORKFLOW.md` | Gate 0 (init) + Gates 1–5, size classes, debugging path, session handoff, refinement ritual |
|
||
| `PROJECT.md` | Per-project answers from Gate 0: language, size-S exception, purpose, audience |
|
||
| `STATUS.md` | Generated overview: open issues, active designs, recent ADRs — do not edit by hand |
|
||
| `schema.yaml` | Frontmatter schema — single source of truth for artifact structure |
|
||
| `docs/adr/` | Architecture Decision Records — binding; never edited, only superseded |
|
||
| `docs/design/` | One design doc per undertaking; completed ones move to `done/` |
|
||
| `docs/aar/` | Standalone After Action Reviews (incidents, major deviations only) |
|
||
| `docs/issues/` | In-repo issues, one file each; status lives in frontmatter |
|
||
| `docs/wiki/` | Wiki areas as folders, created on demand — rules in `docs/wiki/index.md` |
|
||
| `docs/sources/` | Immutable original sources; wiki pages cite them — read-only for agents |
|
||
| `scripts/` | Deterministic tooling: `validate.py`, `gen_status.py` |
|
||
|
||
Before proposing options (Gate 2), read the relevant ADRs and AARs first —
|
||
past decisions and learnings are input, not trivia.
|
||
|
||
## 5. Artifact Rules
|
||
|
||
- All artifacts are standard Markdown with YAML frontmatter conforming to
|
||
`schema.yaml`. Standard links only (`[text](path.md)`), no wikilinks.
|
||
Diagrams as Mermaid. This keeps every artifact portable across LLMs,
|
||
GitLab, and Obsidian.
|
||
- Never invent frontmatter fields or status values. `validate.py` is
|
||
authoritative; if it rejects your artifact, fix the artifact, not the
|
||
validator.
|
||
- Deterministic jobs (status generation, validation, link checks) are done
|
||
by scripts, not by you. If a deterministic job lacks a script, propose
|
||
one instead of doing it by inference.
|
||
|
||
<!-- projektabschnitt -->
|
||
|
||
## 6. Gruppenregeln (Projekt axion1337.chat)
|
||
|
||
Dieses Repo steuert die Gruppe `axion1337.chat`. Die Abschnitte 1–5
|
||
oben sind neckbeard v0.1.1 und bleiben byte-treu (Baseline:
|
||
`docs/sources/upstream/neckbeard-v0.1.1/`, Prüfung:
|
||
`scripts/pruefe_upstream_drift.py`); §1 ist destilliert aus den
|
||
wortgleich archivierten
|
||
[Karpathy-Guidelines](docs/sources/regelwerk/karpathy-guidelines.md).
|
||
**Änderungen an dieser Datei nur mit sorb abgestimmt.** Dieser
|
||
Abschnitt gilt für jede Session in allen Repos der Gruppe;
|
||
Komponenten-Repos tragen nur Projektspezifika plus einen Pointer
|
||
hierher ([ADR-0013](docs/adr/0013-gruppenregeln-kanonisch-mit-pruefung.md)).
|
||
Ohne Lab-Zugang: dieses Repo ist als Push-Mirror unter
|
||
`https://rohana.axion1337.de/sorb/management` lesbar — pushen dorthin ist tabu.
|
||
|
||
### Quelle der Wahrheit & Mirror-Topologie
|
||
|
||
- `git.lab/axion1337.chat/*` ist kanonisch; Gitea/rohana wird per
|
||
Push-Mirror beliefert und bleibt Flux-Quelle, Registry und
|
||
Release-Download ([ADR-0001](docs/adr/0001-gitlab-kanonisch-push-mirror.md),
|
||
[ADR-0004](docs/adr/0004-site-to-site-vpn-hetzner-lab.md)). Die
|
||
Flux-Quelle **nicht auf git.lab „geradeziehen"** — die Produktion darf
|
||
nicht an der Lab-Verfügbarkeit hängen.
|
||
- **Nie direkt zu Gitea pushen** (der Mirror überschreibt per Force).
|
||
Landet doch ein Commit dort: Kanonisierungs-Verfahren in
|
||
[verfahren/deploy-uebergabe.md](docs/wiki/deployment/deploy-uebergabe.md).
|
||
- Einzige bewusste Ausnahme: der TURN-Rotations-CronJob schreibt nach
|
||
Gitea; der tägliche CI-Job `canonize_rotation` holt es zurück. Seine
|
||
rote Pipeline **ist** der Alarm — es gibt bewusst keinen zweiten Meldeweg.
|
||
|
||
### Issues & Board
|
||
|
||
- `docs/issues/` ist kanonisch für den Management-Scope
|
||
([ADR-0012](docs/adr/0012-issues-im-repo-gitlab-als-spiegel.md));
|
||
GitLab ist bespiegelte Ansicht. Jedes Issue trägt genau einen
|
||
Meilenstein (M1–M5) und genau eine Priorität — das Schema erzwingt
|
||
beides. Zeitkritisches trägt ein `due`-Datum, nicht „bald".
|
||
- **WIP-Limit 2** (Validator-Regel). Die Zusage-Status `next` und
|
||
`in-progress` vergibt **nur sorb**; Sessions bilden ab (`waiting` mit
|
||
`wartegrund`, Erledigtes `done` mit Begründung im Issue-Commit),
|
||
sagen aber nichts zu.
|
||
- **ADR-Pflicht** bei Architektur-/Prozessentscheidungen und **jeder
|
||
dauerhaften Ausnahme von einer Regel** — eine Ausnahme nur zu
|
||
dokumentieren statt sie zu entscheiden, ist ein Fehler.
|
||
|
||
### Secrets & Credentials
|
||
|
||
- Token-/Secret-Werte **niemals anzeigen, loggen oder in Dateien
|
||
echoen** — anzeigen = Exposure = Rotation. Referenz nur über
|
||
Dateipfade (z. B. `~/.config/gitlab-lab/token`) oder maskierte
|
||
CI-Variablen. Die Trennung ist „Credential vs. Config":
|
||
nicht-geheime Konfiguration wird normal committet.
|
||
|
||
### Commit-Konventionen
|
||
|
||
- Nachrichten auf Englisch, Conventional-Stil; der Betreff sagt *was*,
|
||
der Rumpf *warum*.
|
||
- Autor- **und** Committer-Datum auf 12:00:00 UTC des laufenden Tages;
|
||
kanonische Autor-Identität. Historien-Rewrites nur mit
|
||
alt→neu-Zuordnung
|
||
([ADR-0009](docs/adr/0009-commit-konventionen-und-historien-anonymisierung.md),
|
||
Tabelle: [shared/commit-zuordnung-2026-08-07.md](docs/sources/migration/commit-zuordnung-2026-08-07.md)).
|
||
- ⚠️ Das schützt nur die Git-Historie; Plattform-Zeitstempel (Push,
|
||
Issues, Pipelines, Pakete) tragen die echte Uhrzeit (ADR-0009).
|
||
|
||
### Redlichkeit
|
||
|
||
- Verifiziert (Messung/Konsole) klar von Vermutung trennen;
|
||
Korrelation ≠ Kausalität — ein plausibler Verdacht ist kein Befund.
|
||
- Config-Dateien chirurgisch editieren, **nie re-dumpen**; vor dem Push
|
||
validieren (`docker compose config`, YAML-Parse).
|
||
- Fehlschläge und übersprungene Schritte benennen, nicht glätten —
|
||
„fertig" heißt verifiziert (deckungsgleich mit §1).
|