Multi-Surface-Harness-Konventionen

Kanonische normative Referenz für nachgelagerte Mitwirkende. Dieses Dokument spiegelt die Abschnitte der Projektspezifikation zu den Multi-Surface-Harness-Konventionen (Spezifikation §0.6 + §2.8 + §4.7); es ist die eigenständige Referenz, die mit dem veröffentlichten Repository ausgeliefert wird. Die architektonische Begründung ist in ADR-0003 festgehalten.

1. Warum PluralCopy Anchor Link

Eine moderne Engineering-Oberfläche wird von mehreren Harnesses berührt — Chat-Konsolen, Vervollständigungs-Engines in der IDE, Pair-Programming-Begleitern und Pull-Request-Reviewern. Jeder liest seine eigene kanonische Konfigurationsdatei. Liefert das Projekt nur eine solche Datei aus, improvisieren die übrigen Laufzeiten stillschweigend gegen unausgesprochene Konventionen; das fehlende Gedächtnis im Repository sickert sofort durch.

Die Kosten einer fehlenden Oberfläche sind stille Drift in maschinell generiertem Code — die schlimmste Klasse von Defekten, weil sie sich unsichtbar anhäuft. Jedes maschinell generierte Artefakt verstärkt die Divergenz; bis ein menschlicher Reviewer den Widerspruch bemerkt, trägt die Codebasis bereits Wochen inkonsistenter Konventionen in sich.

Die Konfiguration der Harness-Laufzeiten ist durch die Realität der Bereitstellung plural. Das veröffentlichte Ökosystem MUSS die drei verpflichtenden Oberflächen aus §3 ausliefern: AGENTS.md, eine Verhaltensgedächtnis-Datei für die Chat-Konsolen-Laufzeit (CLAUDE.md) und eine repo-bezogene Anweisungsdatei für die Vervollständigungs-Laufzeit in der IDE. Die Oberflächen MÜSSEN wechselseitig kohärent sein — kein Widerspruch, keine Drift — und MÜSSEN gemeinsam dieselben Disziplinen kodieren.

2. Der KohärenzvertragCopy Anchor Link

Jede Konventionsoberfläche im Geltungsbereich (§3) ist ein Kanal, der die eine Konventionsspezifikation des Projekts ausdrückt. Die Spezifikation gliedert sich in:

• Gemeinsame Abschnitte — Plan-Disziplin, strukturierte Rückfrage (oder ein oberflächenäquivalentes Mittel), Autorschafts-Header, Benennung, Antimuster, modale Hierarchie. Diese MÜSSEN in jeder erforderlichen Oberfläche erscheinen und MÜSSEN über die Oberflächen hinweg semantisch äquivalent sein.
• Oberflächenspezifische Abschnitte — Fähigkeits-Rahmungen, Muster für Tool-Aufrufe, Unterschiede zwischen Codegenerierung und Chat. Diese DÜRFEN sich zwischen den Oberflächen unterscheiden, DÜRFEN aber den gemeinsamen Abschnitten NICHT widersprechen.

Der Validator multi-surface-coherence (§7) läuft bei jedem CI-Lauf und im Pre-Commit und prüft den Vertrag.

Die Oberflächen sind verschiedene Kanäle, die eine Spezifikation ausdrücken. Gemeinsame Abschnitte MÜSSEN über die Oberflächen hinweg übereinstimmen — semantisch und, wo möglich, lexikalisch. Oberflächenspezifische Abschnitte DÜRFEN den gemeinsamen Abschnitten NICHT widersprechen.

3. Oberflächen im GeltungsbereichCopy Anchor Link

Für dieses Repository sind die Opt-in-Oberflächen diejenigen, die die Fixture der Aussagenliste (tests/fixtures/multi-surface-claims.yaml) unter optional-in aufführt. Nicht genutzte anbieterspezifische Wurzelkonfigurationen fehlen absichtlich; eine toolspezifische Konfigurationsdatei wird nur hinzugefügt, wenn dieses Tool eine aktive Bearbeitungsoberfläche für dieses Repository ist.

4. Abschnittsliste für die Anweisungsdatei in der IDECopy Anchor Link

Die repo-bezogene Anweisungsdatei unter .github/ MUSS in dieser Reihenfolge die folgenden Abschnitte enthalten (jeweils mit dem exakten Überschriftentext unten; die Abschnittsinhalte werden verfasst, nicht aus einer Vorlage gestempelt, aber jeder MUSS die aufgeführten Aussagen abdecken):

1. Project Context — ein Absatz: was dieses Repository ist, wer es nutzt, seine Gestalt auf oberster Ebene. Konkret; kein Marketing.
2. Coding Conventions — Benennung, modale Hierarchie, Frontmatter, Markdown-Stil, sprachspezifische Stilpunkte, wo sie von den Standardvorgaben abweichen.

3. File Headers — jede Datei, die die Laufzeit generiert, MUSS mit der kanonischen einzelnen Zeile SPDX-License-Identifier: MIT gemäß site/content/docs/reference/authorship-header.mdx beginnen, in der Kommentarvariante, die zum Dateityp passt. Verweis auf scripts/inject-header.* und site/content/docs/reference/authorship-header.mdx.

4. Plans Discipline — die Laufzeit DARF KEINEN Code und keine Skripte generieren, die in ein Harness-Konfigurationsverzeichnis (zum Beispiel ~/.claude/plans/ oder ~/.codex/.plans/) oder an einen anderen globalen Plan-Ablageort schreiben. Planungsartefakte gehören gemäß site/content/docs/reference/plans-discipline.mdx nach <project-root>/.apothem/plans/ (ein veralteter <project-root>/.plans/-Baum wird via apothem migrate-workspace hochgestuft).
5. Structured Inquiry Behavior — wenn die Laufzeit unsicher ist, DARF sie NICHT stillschweigend etwas erfinden. Stattdessen fügt sie einen klar gekennzeichneten Klärungsblock ein (z. B. einen Kommentar # TODO(clarify): <question>) und bringt die Frage im Chat vor, wo die Oberfläche dies zulässt. Keine erfundenen APIs, keine erfundenen Modellnamen, keine erfundenen Dateipfade.
6. Forbidden Patterns — ausdrückliche Verbote: keine Marketing-Adjektive, keine ausweichenden Füllwörter, keine console.log-Debug-Überreste, keine fest codierten absoluten Pfade zum Home-Verzeichnis des Benutzers, kein Committen von Geheimnissen, kein Committen von Dateien unter .apothem/plans/ (oder dem veralteten .plans/), kein Widerspruch zur kanonischen Projektanweisungsdatei.
7. Output Format — generierter Code und generierte Prosa entsprechen den vereinheitlichten Konventionen für Gesprächsausgaben: Bestimmtheit, einheitliche Gliederung, Dichte, Zusammenfassungsdisziplin, Quellenangaben. Für Code: dokumentierte öffentliche Oberfläche, typisiert, wo die Sprache Typen unterstützt, getestet, wo ein Testgerüst existiert.
8. Review Checklist — was ein Reviewer (Mensch oder Laufzeit im Pull-Request-Review-Modus) vor der Freigabe verifizieren MUSS: Header vorhanden, Benennung konform, keine Schreibvorgänge in .apothem/plans/, keine Widersprüche zur kanonischen Projektanweisungsdatei, Validatoren lokal grün.
9. Pointers — Links zu AGENTS.md, CLAUDE.md, site/content/docs/reference/plans-discipline.mdx, site/content/docs/reference/authorship-header.mdx, diesem Konventionsdokument, src/apothem/schemas/ und CONTRIBUTING.md.

Die Datei beginnt mit der SPDX-Zeile des kanonischen Autorschafts-Headers (Markdown-Variante) gemäß site/content/docs/reference/authorship-header.mdx §2 — sichtbar oder unsichtbar gemäß der vom Projekt gewählten Richtlinie zur Header-Sichtbarkeit.

Die Anweisungsdatei in der IDE ist keine wörtliche Kopie von AGENTS.md oder CLAUDE.md. AGENTS.md ist die kanonische Oberfläche für Projektanweisungen, CLAUDE.md spiegelt sie für Claude Code, und die Anweisungsdatei in der IDE ist für eine Code-Vervollständigungs-Laufzeit im Editor formuliert, die Vorschläge ausgibt, die ein Entwickler annimmt oder ablehnt. Die Information (Disziplinen, Konventionen, Antimuster) ist identisch; die Rahmung unterscheidet sich.

5. Referenz zur AussagenlisteCopy Anchor Link

Die Fixture unter tests/fixtures/multi-surface-claims.yaml zählt jede gemeinsame Aussage auf. Beispieleinträge:

- id: plans.location
  claim: "Planning artifacts live at <project-root>/.apothem/plans/, never inside a harness configuration directory."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
  optional-in: [site/content/docs/architecture/agents.mdx, .cursorrules]
- id: header.canonical
  claim: "Every applicable new file begins with the canonical SPDX-License-Identifier: MIT header line, in the comment family matching the filetype."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
- id: ambiguity.resolution
  claim: "Ambiguity is surfaced via the structured-inquiry channel or a clearly-marked TODO(clarify); never silently invented."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
# ... (one entry per shared claim)

Der Validator parst jede Oberfläche, versucht für jede Aussage deren Vorkommen auf der Oberfläche zu finden (über die Überschriftenhierarchie + Schlüsselwortextraktion aus dem Fließtext) und schlägt bei jedem Fehlen und jedem Widerspruch fehl.

6. AbgleichsregelCopy Anchor Link

Wird erkannt, dass sich zwei Oberflächen bei einer gemeinsamen Aussage widersprechen, gilt standardmäßig folgender Abgleich:

AGENTS.md ist die kanonische Stimme des Projekts. Jede widersprechende Oberfläche wird so umgeschrieben, dass sie die Semantik von AGENTS.md in einer der Oberfläche angemessenen Rahmung spiegelt.

Eine oberflächenspezifische Überschreibung ist nur mit einer expliziten Markierung <!-- coherence-override: <claim-id> --> in der Datei zulässig, die auf einen ADR verweist, der die bewusste Abweichung erklärt. Die Überschreibungsmarkierung ist selbst in der Erlaubnisliste des Validators aufgeführt und erscheint im CI-Bericht.

Für dieses Repository ist die ratifizierte Abgleichsstrategie agents-md-wins: AGENTS.md ist kanonisch, und jeder aktive Harness-Spiegel bleibt semantisch äquivalent.

7. ValidatorenCopy Anchor Link

Drei Validatoren implementieren den Kohärenzvertrag gemeinsam:

- in-IDE-instructions-presence    (src/apothem/conformity/copilot_instructions_presence_grep.py)
- multi-surface-coherence         (src/apothem/conformity/multi_surface_coherence_grep.py)
- license-author-consistency      (src/apothem/conformity/license_author_consistency_grep.py)

• Der erste prüft, dass die Anweisungsdatei in der IDE existiert, sich parsen lässt, jeden in §4 aufgezählten kanonischen Abschnitt enthält und mit der kanonischen Zeile SPDX-License-Identifier: MIT (Markdown-Variante) beginnt.
• Der zweite parst die kanonischen Abschnitte jeder Oberfläche und prüft, dass die gemeinsamen Abschnitte unter einem normalisierenden Vergleich wechselseitig konsistent sind (ohne Beachtung der Groß-/Kleinschreibung, tolerant gegenüber Leerraum, lexikalische Paraphrasen erlaubt, aber semantische Äquivalenz für die in der Fixture definierte Aussagenliste verlangt).
• Der dritte prüft ausschließlich, dass die LICENSE in der Wurzel eine parsbare Zeile Copyright (c) <name> trägt. Er liest keine Header pro Datei; diese tragen keinen Autorennamen.

8. Lebenszyklus einer OberflächeCopy Anchor Link

• Eine Oberfläche hinzufügen. Der Operator entscheidet sich über den Kanal der strukturierten Rückfrage dafür. Der Generator verfasst die Oberfläche anhand der Aussagenliste, führt den Validator aus und legt einen ADR an, falls eine oberflächenspezifische Überschreibung nötig ist.
• Eine Oberfläche entfernen. Eine strukturierte Rückfrage bestätigt die Entfernung, ein ADR hält die Begründung fest, und die required-in-Liste des Validators wird angepasst.
• Drift-Erkennung. Jeder Commit, der von der Aussagenliste abweicht, wird von Pre-Commit / CI abgelehnt; der Autor des Commits schreibt die Oberfläche um, um die Kohärenz wiederherzustellen.

Siehe auchCopy Anchor Link

• ADR-0003 — architektonische Begründung, erwogene Alternativen.
• tests/fixtures/multi-surface-claims.yaml — die kanonische Fixture der Aussagenliste.
• AGENTS.md — die kanonische Stimme des Projekts.
• CLAUDE.md — der Spiegel für Claude Code.
• site/content/docs/reference/plans-discipline.mdx — die kanonische Referenz der gemeinsamen Aussage zur Plan-Disziplin.
• site/content/docs/reference/authorship-header.mdx — die kanonische Referenz der gemeinsamen Aussage zum Autorschafts-Header.
• Projektspezifikation §0.6 + §2.8 + §4.7 — der vollständige kanonische Text, der hier gespiegelt wird.