Beitragen zu Semantic Anchors

Vielen Dank für Ihr Interesse, zum Semantic Anchors Katalog beizutragen! Dieser Leitfaden erklärt, wie Sie neue semantische Anker vorschlagen und was einen guten semantischen Anker ausmacht.

Was sind Semantic Anchors?

Semantic Anchors (semantische Anker) sind klar definierte Begriffe, Methodologien und Frameworks, die als Referenzpunkte bei der Kommunikation mit Large Language Models (LLMs) dienen. Sie fungieren als gemeinsames Vokabular, das spezifische, kontextreiche Wissensbereiche im Trainingsdatensatz eines LLMs aktiviert.

Beispiel: Wenn Sie einem LLM "TDD, London School" erwähnen, aktiviert es Wissen über Mock-intensive Tests, Outside-in-Entwicklung und die Arbeit von Steve Freeman und Nat Pryce - viel reichhaltiger als einfach zu sagen "verwende Mocks beim Testen."

Artefakttypen: Anchor, Contract, Skill

Der Katalog kennt drei Artefakttypen. Welchen Sie vorschlagen, entscheidet, wohin Ihr Beitrag gehört. Die vollständige Begründung steht in ADR-007; die Arbeitsdefinitionen stehen hier.

Typ Funktion Sprachform Laden

Anchor

„Was weiß ich?" — fokussiert vorhandenes Wissen

Nomen / benanntes Konzept („Cockburn Use Cases")

Passiv (Aktivierungssignal)

Contract

„Was darf ich?" — pinnt anwendbare Anchors + Invarianten

Deklarativ („folgt / NIE / MUSS")

Always-on

Skill

„Wie tue ich es?" — liefert Prozedur

Verb / Imperativ („Erstellen / Verifizieren / Schreiben")

On-demand

  • Anchor — ein benanntes Aktivierungssignal für einen Wissenscluster, der in den Trainingsdaten eines LLMs bereits dicht vorhanden ist. Er fokussiert; er lehrt nicht. Muss die vier Qualitätskriterien unten bestehen.

  • Contract — knappes, always-on geltendes gemeinsames Vokabular (in CLAUDE.md / AGENTS.md), das pinnt, welche Anchors gelten, und Invarianten festlegt. Sobald er beschreibt, wie etwas Schritt für Schritt zu tun ist, gehört dieser Teil in einen Skill.

  • Skill — on-demand geladene prozedurale Maschinerie (references/, Prompts, ein Workflow) für ein Wie, das das Modell nicht allein aus einem Namen ausführen kann.

Unterscheidungstest:

  1. Wissen schon dicht im LLM, braucht nur Fokus → Anchor

  2. Pinnen nötig, welche Anchors gelten und was erlaubt/verboten ist → Contract

  3. Beschreiben nötig, wie etwas konkret getan wird → Skill

Die Thin-Prior-Regel. Ist ein Name in den Trainingsdaten nicht dicht, ist er kein Anchor — ihn zu benennen verändert die Ausgabestruktur nicht zuverlässig gegenüber einem generischen Prompt. Was ihn repariert, hängt davon ab, was fehlt: fehlt die Bedeutung/Rahmung → ein Contract (er liefert seine eigene Bedeutung; eine URL repariert keinen Prior); fehlt die Prozedur → ein Skill. Ein dünner Name wird nie zum Anchor gezwungen.

Qualitätskriterien

Bevor Sie einen neuen semantischen Anker vorschlagen, stellen Sie sicher, dass er diese vier Kriterien erfüllt:

Details

=== ✓ Präzise Der Anker referenziert einen spezifischen, etablierten Wissensbereich mit klaren Grenzen.

Gut: "SOLID Principles" - fünf spezifische Design-Prinzipien (SRP, OCP, LSP, ISP, DIP)

Schlecht: "Gutes Design" - vage und subjektiv

=== ✓ Reichhaltig Der Anker aktiviert mehrere miteinander verbundene Konzepte, nicht nur eine einzelne Anweisung.

Gut: "Domain-Driven Design" - aktiviert Bounded Contexts, Ubiquitous Language, Aggregates, Value Objects, Entities, Repositories, etc.

Schlecht: "Verwende aussagekräftige Namen" - einzelne Anweisung ohne konzeptionelle Tiefe

=== ✓ Konsistent Verschiedene Benutzer, die den Anker verwenden, sollten ähnliche konzeptionelle Aktivierung vom LLM erhalten.

Gut: "Test-Driven Development" - weithin dokumentierte Methodologie mit konsistentem Verständnis

Schlecht: "Modernes Testen" - unterschiedliche Interpretationen durch verschiedene Personen

=== ✓ Zuordenbar Der Anker kann zu Schlüsselvertretern, Publikationen oder dokumentierten Standards zurückverfolgt werden.

Gut: "Hexagonal Architecture" (Alistair Cockburn, 2005)

Schlecht: "Best Practices" - keine spezifische Quelle oder Autorität

Testen Ihres semantischen Ankers

Bevor Sie einen Vorschlag machen, testen Sie den Anker mit diesem Prompt in einem LLM:

Welche Konzepte verbindest du mit '<Name Ihres semantischen Ankers>'?
Die Vorlagsvorlage enthält ein Pflichtfeld LLM Activation Test Result. Fügen Sie dort Ihre Testausgabe ein — es liefert Reviewern vorab das Precise/Rich/Consistent-Signal.

Bewerten Sie die Antwort:

  • Erkennung: Erkennt das LLM den Begriff?

  • Genauigkeit: Ist die Erklärung korrekt?

  • Tiefe: Deckt es mehrere verwandte Konzepte ab?

  • Spezifität: Ist der Umfang gut definiert?

Viability-Test (Liefert der Anker?)

Erkennung ist nicht Aktivierung. Ein Modell kann flüssig über einen Begriff reden, während sein Benennen an der Ausgabe nichts ändert — oder schlimmer: still ein älteres Konzept substituiert oder ein plausibel klingendes, aber erfundenes konfabuliert. Der training-data-vs-practice-Artikel dokumentiert diese Failure-Modes über Modellfamilien hinweg. Der Aktivierungstest oben fängt die Erkennung; der Viability-Test unten fängt die Lieferung.

  1. Before/After-Test. Dem Modell eine Aufgabe ohne den Anker-Term geben, dann dieselbe Aufgabe mit ihm. Ändert sich die Ausgabestruktur? Wenn nicht, ist der Term dekorativ, nicht funktional.

  2. Substitutions-Check. "Was ist [Term]?" auf einem schwächeren Modell (Haiku-Klasse) fragen. Hedgt es, substituiert still oder konfabuliert es, ist der Prior zu dünn für einen Anchor — er gehört in einen Contract (der seine eigene Bedeutung mitliefert), gemäß der Thin-Prior-Regel unter Artefakttypen.

  3. Cross-Model-Check. Hält der Before/After-Unterschied auf mindestens einem schwachen und einem starken Modell? Wenn nur auf Frontier-Modellen, als ★★ (needs qualification) notieren.

Ein Term, der die vier Qualitätskriterien besteht, aber den Viability-Test nicht, ist ein Contract, kein Anchor.

Dieses Gate ist themenneutral. Kein Themengebiet ist bevorzugt oder verboten — Persönlichkeits- und Assessment-Modelle (MBTI, DISC, Big Five, HEXACO) werden weder wegen ihres Themas ausgeschlossen noch wegen ihrer Bekanntheit aufgenommen. Sie müssen denselben Viability-Test bestehen wie jeder andere Kandidat und — angesichts ihrer umstrittenen empirischen Absicherung — einen == Criticism / == Current Status-Abschnitt tragen. Die Begründung steht in ADR-008.

Wie man einen neuen Anker vorschlägt

Wir verwenden einen automatisierten Workflow mit GitHub Copilot zur Validierung und Anreicherung von Vorschlägen:

Schritt 1: Issue erstellen

Klicken Sie auf die btn:[Neuen Anker vorschlagen] Schaltfläche auf der Website oder erstellen Sie ein Issue mit unserer Vorlagsvorlage.

Alles, was Sie angeben müssen:

  • Der Begriff oder Konzeptname

  • Ein LLM-Aktivierungstestergebnis (Pflichtfeld)

  • (Optional) Warum Sie denken, dass es wertvoll wäre

Schritt 2: Copilot-Validierung

GitHub Copilot führt automatisch folgendes aus:

  1. Testet den Anker gegen die vier Qualitätskriterien

  2. Akzeptiert oder lehnt den Vorschlag ab

  3. Bei Ablehnung: Erklärt, warum die Kriterien nicht erfüllt werden

  4. Bei Akzeptierung: Reichert das Issue mit detaillierten Informationen an

Schritt 3: Copilot erstellt den Anker

Sobald akzeptiert und angereichert, wird Copilot beauftragt:

  1. Die AsciiDoc-Datei in docs/anchors/ zu erstellen

  2. Alle erforderlichen Metadaten hinzuzufügen (Kategorien, Rollen, Vertreter, Tags)

  3. Einen Pull Request einzureichen

  4. Maintainer überprüfen und mergen

Schritt 4: Veröffentlicht

Nach dem Merge erscheint der neue Anker innerhalb von Minuten durch automatisches Deployment auf der Website!

Format der Anker-Datei

Jeder Anker wird als AsciiDoc-Datei mit Metadaten-Attributen gespeichert:

= TDD, London School
:categories: testing-quality
:roles: software-developer, qa-engineer, software-architect
:related: tdd-chicago-school, hexagonal-architecture
:proponents: Steve Freeman, Nat Pryce
:tags: testing, tdd, mocking, outside-in
:tier: 2

[%collapsible]
====
*Vollständiger Name*: Test-Driven Development, London School

*Auch bekannt als*: Mockist TDD, Outside-In TDD

*Kernkonzepte*:
* Mock-intensive Tests
* Outside-in-Entwicklung
* Interaktionsbasiertes Testen

*Schlüsselvertreter*: Steve Freeman, Nat Pryce ("Growing Object-Oriented Software, Guided by Tests")

*Wann zu verwenden*:
* Komplexe Systeme mit vielen zusammenarbeitenden Objekten
* Beim Entwerfen von APIs und Schnittstellen
* Verteilte Systeme, wo Integration kostspielig ist
====

Erforderliche Metadaten:

  • :categories: - Eine oder mehrere Kategorie-IDs (siehe Website für Liste)

  • :roles: - Eine oder mehrere berufliche Rollen, die diesen Anker verwenden

  • :proponents: - Schlüsselpersonen, Publikationen oder Standards

  • :tags: - Schlüsselwörter für die Suche (optional, aber empfohlen)

  • :related: - Verwandte Anker-IDs (optional)

  • :tier: - Aktivierungsstufe: 1 (nur Frontier-Modelle), 2 (braucht Qualifizierung), 3 (breit erkannt)

  • :advisory: - Kurzes Hinweis-Label (optional). Nur für Counter-Consensus-Framing: Der Anker aktiviert zuverlässig, aber sein Framing widerspricht dem dokumentierten Konsens seines eigenen Fachgebiets. Wird als sichtbares Badge in Karte/Modal gerendert; Detail und zitierte Quelle bleiben im == Criticism / == Current Status-Abschnitt (Single Source of Truth). Siehe eisenhower-matrix.adoc.

Gegenbeispiele

Dies sind KEINE semantischen Anker:

"TLDR"

Unterspezifizierte Anweisung, keine definierte Struktur
"ELI5"

Vages Zielniveau, kein pädagogisches Framework
"Halte es kurz"

Reine Anweisung, keine konzeptionelle Tiefe
"Best Practices"

Kein spezifischer Wissensbereich, nicht zuordenbar
"Moderner Ansatz"

Zu vage, nicht konsistent über Benutzer hinweg

Kategorien

Anker sind in 12 MECE (Mutually Exclusive, Collectively Exhaustive) Kategorien organisiert:

  1. Kommunikation & Präsentation

  2. Design-Prinzipien & Muster

  3. Entwicklungs-Workflow

  4. Dialog & Interaktionsmuster

  5. Dokumentationspraktiken

  6. Meta (Repository- und Katalogkonzepte)

  7. Problemlösungsmethoden

  8. Requirements Engineering

  9. Software-Architektur

  10. Statistische Methoden & Prozessüberwachung

  11. Strategische Planung & Entscheidungsfindung

  12. Testing & Qualitätssicherung

Siehe die Website für vollständige Kategorienbeschreibungen.

Berufliche Rollen

Anker sind mit beruflichen Rollen getaggt, um relevante Inhalte zu filtern. Verwenden Sie die Rollen-ID (kebab-case) im :roles: Metadaten-Attribut.

Siehe docs/roles/ für ausführliche Rollenbeschreibungen (EN + DE).

Operative Fachliche Rollen

ID Anzeigename

software-developer

Softwareentwickler/in

software-architect

Softwarearchitekt/in

qa-engineer

QA-Ingenieur/in / Tester/in

devops-engineer

DevOps-Ingenieur/in

product-owner

Product Owner / Produktmanager/in

business-analyst

Business Analyst / Anforderungsmanager/in

technical-writer

Technische/r Redakteur/in

ux-designer

UX-Designer/in / Researcher/in

data-scientist

Data Scientist / Statistiker/in

consultant

Berater/in / Coach

team-lead

Teamleiter/in / Engineering Manager/in

educator

Trainer/in / Dozent/in

Organisatorische Governance-Rollen

ID Anzeigename

data-protection-officer

Datenschutzbeauftragte/r

ethics-officer

Ethikbeauftragte/r

legal-compliance

Recht & Compliance

Entwicklungsumgebung

Voraussetzungen

  • Git

  • Python 3.12+ (für pre-commit Hooks)

  • Node.js 20+ (für Website-Entwicklung, optional)

Pre-Commit Hooks installieren

Pflicht für alle Beitragenden!

Installationsskript ausführen:

./pre-commit-install.sh

Dies installiert:

  • AsciiDoc Linter - validiert Anker-Dateisyntax automatisch

  • pre-commit Framework - führt Checks vor jedem Commit aus

  • Standard-Hooks - Trailing Whitespace, YAML/JSON-Validierung

Manuelle Hook-Ausführung

Alle Hooks auf allen Dateien ausführen:

pre-commit run --all-files

Spezifischen Hook ausführen:

pre-commit run asciidoc-linter --all-files
Lokale Build-Artefakte (z.B. website/dist/, generierte Dateien in website/public/docs/) dürfen nicht committed werden. Diese werden durch die CI/CD-Pipeline erzeugt.

Criticism und Current Status (Recherche erforderlich, aufnehmen wenn gefunden)

Der Katalog ist ein Lexikon, keine Empfehlungsliste — Aufnahme bedeutet, dass der Term als präziser Pointer funktioniert, nicht dass wir die Praxis empfehlen. Für jeden neuen Anchor recherchieren, ob dokumentierte Kritik oder Drift existiert, und das Ergebnis als Section aufnehmen:

  • == Criticism — die Methode selbst ist umstritten. Nur benannte, zitierbare Kritik (Kritiker + verlinkte Quelle), niemals Bauchgefühl wie „das nutzt doch keiner mehr". Die Section berichtet den Diskurs; sie urteilt nicht. Wo der Diskurs Alternativen benennt, diese ebenfalls benennen.

  • == Current Status — die Methode besteht, aber der Training-Data-Prior und die Gegenwart sind auseinandergedriftet: eine neuere Edition existiert (die Edition benennen, auf die der Prior wahrscheinlich zeigt), ein Successor ist entstanden, oder die Adoption hat nachgelassen.

Jede verlinkte Quelle vor dem Commit tatsächlich fetchen und verifizieren. Falls die Recherche nichts Zitierbares findet, beide Sections weglassen — eine leere Section ist Noise. Siehe #603 für die Full-Catalog-Triage hinter dieser Konvention.

PR-Review-Richtlinie

Review-Anforderungen

Alle Pull Requests auf main erfordern mindestens ein genehmigendes Review vor dem Merge.

Stichproben-Review (~20%)

In aktiven Phasen mit vielen Beiträgen wenden Maintainer ein 20% Stichproben-Review an:

  • Mindestens 1 von 5 PRs erhält ein gründliches, zeilenweises Review

  • Alle anderen PRs erhalten ein High-Level-Review (Struktur, Qualitätskriterien, CI-Status)

  • KI-generierte PRs (GitHub Copilot) erhalten immer ein menschliches Review

Automatisierte Checks (müssen bestehen)

Jeder PR muss vor dem Merge alle folgenden Checks bestehen:

  • E2E Tests — alle 28+ Playwright-Tests grün

  • Lint & Format Check — ESLint + Prettier (keine Fehler)

  • Dependency Audit — npm audit --audit-level=high sauber

  • CodeQL — keine high/critical Security-Findings

  • AsciiDoc Linter — Anker-Dateien entsprechen dem Format (pre-commit Hook)

Was Reviewer prüfen

Für neue semantische Anker:

  1. Qualitätskriterien erfüllt (Präzise, Reichhaltig, Konsistent, Zuordenbar)

  2. Alle erforderlichen Metadaten-Attribute vorhanden (:categories:, :roles:, :proponents:, :tier:)

  3. AsciiDoc-Format korrekt ([%collapsible]-Block, korrekte Attribut-Syntax)

  4. Anker mit LLM-Prompt getestet (siehe Testen Ihres semantischen Ankers)

  5. Dokumentierte Kritik / Editions-Drift recherchiert — und in einem Criticism- oder Current Status-Abschnitt mit benannten, fetch-verifizierten Quellen festgehalten, sofern vorhanden

Für Code-Änderungen:

  1. Keine Regressionen in bestehenden Tests

  2. Keine neuen high/critical Sicherheitslücken

  3. Folgt ESLint/Prettier Code-Style

  4. Keine Build-Artefakte im Commit (z.B. website/dist/, generierte Dateien)

KI-unterstützte Reviews

Dieses Projekt verwendet CodeRabbit für automatisiertes KI-Code-Review auf allen PRs. CodeRabbit-Reviews sind beratend — menschliche Maintainer-Genehmigung ist weiterhin erforderlich.

Issue-Titel-Konvention

Alle Issues sollten einem konsistenten [Typ]: <Name> Titelformat folgen. Dies macht Filtern, Suchen und Triagieren wesentlich einfacher.

Anerkannte Prefixe

Prefix Verwendet für Quelle

[Anchor Proposal]:

Vorschläge für neue semantische Anker

Issue-Template

[Contract Proposal]:

Vorschläge für neue semantische Contracts

Issue-Template

[Improve]:

Verbesserungen an bestehenden Ankern

Issue-Template

[Bug]:

Fehlermeldungen

Issue-Template

[Process Proposal]:

Änderungen an Projektprozessen

Issue-Template

[Feature]:

Feature-Anfragen

Frei formuliert

EPIC:

Tracking-Issues für größere Initiativen

Frei formuliert

Richtlinien

  • Verwenden Sie das Issue-Template, wann immer eines existiert — das Prefix wird automatisch gesetzt.

  • Frei formulierte Issues (kein passendes Template) sollten manuell eines der anerkannten Prefixe verwenden.

  • Nur zukünftig anwenden — geschlossene Issues nicht rückwirkend umbenennen.

  • EPICs verwenden das bloße EPIC: Prefix ohne Klammern als anerkannte Ausnahme.

Verhaltenskodex

Unser Versprechen

Wir verpflichten uns, die Teilnahme an diesem Projekt zu einer belästigungsfreien Erfahrung für alle zu machen, unabhängig von Alter, Körpergröße, Behinderung, Ethnizität, Geschlechtsidentität und -ausdruck, Erfahrungsniveau, Nationalität, persönlichem Erscheinungsbild, Rasse, Religion oder sexueller Identität und Orientierung.

Unsere Standards

Positives Verhalten:

  • Verwendung von einladender und inklusiver Sprache

  • Respektvoller Umgang mit unterschiedlichen Standpunkten

  • Konstruktive Kritik anmutig akzeptieren

  • Fokus auf das, was für die Community am besten ist

  • Empathie gegenüber anderen Community-Mitgliedern zeigen

Inakzeptables Verhalten:

  • Trolling, beleidigende/abwertende Kommentare und persönliche Angriffe

  • Öffentliche oder private Belästigung

  • Veröffentlichung privater Informationen anderer ohne Erlaubnis

  • Anderes Verhalten, das vernünftigerweise als unangemessen betrachtet werden könnte

Durchsetzung

Fälle von missbräuchlichem, belästigendem oder anderweitig inakzeptablem Verhalten können den Projekt-Maintainern gemeldet werden. Alle Beschwerden werden geprüft und untersucht und führen zu einer Reaktion, die als notwendig und angemessen erachtet wird.

Fragen?

  • Durchsuchen Sie existierende Anker auf der Website

  • Prüfen Sie die README für eine Projektübersicht

  • Öffnen Sie ein GitHub Issue für Fragen

Lizenz

Durch Beiträge stimmen Sie zu, dass Ihre Beiträge unter derselben Lizenz wie dieses Projekt lizenziert werden (siehe LICENSE-Datei).

Bereit vorzuschlagen? Klicken Sie hier: Neuen semantischen Anker vorschlagen