Agentic Ventures Wiki

Code-Stil fuer AI-Reader (knappe Kommentare, WHY-only)

2 Min. Lesezeit

Code-Stil: AI-optimiert, knappe Kommentare

Im bas-twin-Repo war der Code zunaechst „verbose fuer Menschen die sich erst einlesen muessen” geschrieben — viele WHAT-Kommentare, Plan-Anker in jedem zweiten Block, Vorher-Nachher-Geschichten, Section-Trenner als visueller Schmuck. Marvins Feedback am 12.05.2026: „Ist der Code für AI geschrieben? Menschen werden den nicht lesen.”

Antwort: Reader sind AIs, nicht Menschen die sich einlesen — der Stil muss entsprechend anders aussehen.

Was raus soll

PatternBeispielWarum weg
Mehrfach-Plan-AnkerP1-19: in 3 Bloecken einer Funktion1× pro Funktion reicht — Plan, PR-Body und Commit-Message haben den Rest
Vorher-Nachher-Prosa"Vorher SELECT-then-INSERT war TOCTOU-anfaellig — bei parallelen Worker-Instanzen scheiterte der zweite an pipeline_runs_tenant_anfrage_stage_uq"git-blame und Commit-Body haben das, Code zeigt nur den aktuellen Stand
WHAT-Kommentare// 2. EML aus S3 lesen ueber await getObject(...)Code zeigt’s selbst
Section-Trenner// ─── Material ───────────── in positionToRowrein visuell, kein Informationsgehalt
Numerierte 8-Punkt-Listen oben„Stage 2 — KI-Extraktion. Schritte: 1. Idempotenz-Check… 2. Anfrage laden… 3. Excel zu Text…“gehoert in CONTEXT.md neben das Verzeichnis

Was drin bleibt

WHY-Kommentare wo es nicht aus dem Code ableitbar ist:

  • Subtile Invarianten: "DELETE-before-INSERT macht Retry idempotent gegen anfrage_extraktionen_pos_uq"
  • Konstanten-Hintergrund: "Bedrock-Multimodal cap ist ~32 MB inkl. JSON-Overhead" ueber PDF_MAX_FILE_BYTES = 10 * 1024 * 1024
  • Charset-/Encoding-Entscheidungen: "Bytes als latin1 dekodiert — UTF-8 zerstoert deutsche Outlook-Mails (windows-1252 / quoted-printable)"
  • Library-Defaults: "maxRetries=0 weil pg-boss schon retried — sonst verdreifachen sich die Versuche"
  • Sprint-Verschiebungen: "Rueckfrage-Outbox: siehe Issue #12"
  • Forward-Refs / Circular-Workarounds: "Forward-reference per Lazy-Callback, weil anfrage.ts seinerseits cross-cutting importiert"

Konkrete Metrik

Cleanup-PR im bas-twin (PR #18, 12.05.2026): -276 / +57 Zeilen ueber 15 Sprint-1-Files. Tests blieben unveraendert gruen — keine Logik-Aenderung, nur Comment-Reduktion.

Konsequenz fuer CONTEXT.md

Wenn der Code knapp ist, muss die Hub-Doku die Lücke füllen. Im bas-twin-Repo gehoeren 27 CONTEXT.md neben die Code-Ordner (PR #17):

  • Frontmatter (description, last_reviewed, audience: agent-only)
  • „Was wo”: Tabelle file → 1-Zeiler
  • „Regeln”: nur die nicht-offensichtlichen
  • „Verweise”: klickbare Links statt nochmal-erklaeren

Stil-Vorbild im Vault: intern/capabilities/repos/_index.md, intern/firma/stack.md — strukturiert, Tabellen statt Prosa.

Wann gilt das NICHT

  • Wenn Kunden den Code lesen (z.B. bei Custom-Connector-MCPs die Kunden im Browser sehen). Dann muss die README/CONTEXT-Schicht ausreichen, der Code-Stil bleibt gleich.
  • In Tutorials oder Beispielen — andere Zielgruppe.

Trigger

Wenn du in einem Code-File mehr als drei Kommentar-Bloecke siehst die einen Plan-Anker (P0-, P1-, …) tragen oder als Vorher-Nachher-Geschichte beginnen, ist es Zeit fuer einen Cleanup-PR.

Graphansicht

Backlinks