Facet
EnglishInstallieren

Ein Dokumentationsstandard für KI-gestützte Entwicklung

Dein Agent sagt: fertig. Prüfe es gegen den Feature-Record.

FACET ist ein Dokumentationsstandard mit einer Datei pro Feature: dem FACET-Record. Wie eine Spec gibt er dem Agenten vor der Entwicklung das erwartete Verhalten vor. Bei jeder Änderung wird der Record mitgepflegt – zusammen mit Codeverweisen und Testnachweisen.

  • facet testFührt die Tests aus, die einem Feature zugeordnet sind, und zeigt ihre Ergebnisse je Szenario.Mehr lesen
  • knowledgeFünf Knowledge-Antworten erklären Vorwissen, Grenzen, Einstieg, typische Fehler und Erfolgssignale.Mehr lesen
  • facet lspStartet den Sprachserver, der Quellcode-Anker im Editor mit ihren Records verbindet.Mehr lesen
  • Commit-PrüfungDie eingerichtete Pre-Commit-Prüfung verlangt die Prüfung von Änderungen an verankertem Code vor dem Commit.Mehr lesen
  • AtlasAtlas zeigt verschiedenen Rollen dieselben Records, ihre Anforderungen und die vorhandenen Nachweise.Mehr lesen
  • —Ein Strich bedeutet, dass kein Messwert vorliegt. Er behauptet keinen gemessenen Wert von null.Mehr lesen
  • den Code fragenDer Atlas-Begleiter antwortet anhand von Records und Quellverweisen. Allgemeine Dateiänderungswerkzeuge sind gesperrt; Plugin-Aktionen benötigen separate KI-Freigaben.Mehr lesen
  • facet mcpStartet den MCP-Server, über den ein Agent FACET-Werkzeuge für die Registry nutzen kann.Mehr lesen
  • facet docs checkPrüft, ob erzeugte Hilfe gegenüber den zugrunde liegenden Knowledge-Antworten veraltet ist.Mehr lesen

WAS EIN RECORD ENTHÄLT

Mehr als Szenarien. Alles, was dein Team immer wieder erklärt.

Ein Feature-Record hat sieben Facetten. Jede beantwortet eine regelmäßig gestellte Frage. Drei weitere Record-Typen beschreiben, was mehrere Features betrifft: Regeln, Annahmen und Daten.

Ein Balken pro Facette2 / 7 · Contract

Feature · sieben Facetten

Daneben · eigene Records

FACET · contract

Welches Verhalten ist gefordert?

Szenarien in Given / When / ThenGherkinGherkin ist das Format in Alltagssprache, das an konkreten Beispielen beschreibt, wie sich Software verhalten soll, geschrieben als Given, When und Then.Mehr über Gherkin lesen, dazu Geschäftsregeln in klaren Sätzen. Dort stehen die Zahlen, die sonst im Code verstreut sind: die 14 Tage, die 50 %.

WER LIEST DAS

Produktteam, QA und der Agent vor einer Änderung.

YAMLcheckout/pricing/discount-codes.yaml
contract:  business_rules:    - id: discount-cap      rule: A discount never exceeds 50 % of the cart.  scenarios:    - id: expired-code-rejected      Given a code that expired yesterday      When the customer applies it      Then the total is unchanged

Feldnamen aus den schema/facet.schema.jsonOriginalauszug aus der englischen Quelle.[…] Schema for a FACET feature record (FACET spec 1.3.0, Appendix A.1). […]Auf GitHub öffnen · Beispiele aus FACETOriginalauszug aus der englischen Quelle.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]Auf GitHub öffnen

DREI EBENEN. NIE VIER.

Dein Produkt hat bereits eine Struktur. Die ID bildet sie ab.

Jeder Record heißt domain/capability/feature. DomänenDomain-Driven DesignDomain-Driven Design richtet Software an der Fachdomäne aus und an den Worten der Menschen, die sie kennen.Mehr über DDD in FACET lesen und Fähigkeiten werden einmal in einer Datei deklariert. Ein Record unter einer unbekannten Fähigkeit wird vom Lint abgewiesen, solange sich die ID noch leicht korrigieren lässt.

DOMÄNE · worum es im Produkt geht

FÄHIGKEIT · was es dort kann

FEATURE · eine Person, eine Sitzung, ein Ergebnis

  • discount-codes

    5 Szenarien · 2 Regeln

  • free-shipping-threshold

    2–9 Szenarien

  • tax-display

    2–9 Szenarien

Die ID aus diesen drei Entscheidungen: checkout/pricing/discount-codes

  • zu groß

    „Meine Musik verwalten“

    Ein Ziel über mehrere Sitzungen. Das ist eine Fähigkeit, kein einzelnes Feature.

  • passende Feature-Größe

    „Eine Playlist erstellen“

    Ein klar abschließbares Ergebnis. Zwei bis neun Szenarien, darunter mindestens ein Fehlerfall.

  • zu klein

    „Den Playlist-Titel validieren“

    Niemand fragt allein danach. Das ist ein Szenario des Features darüber.

Domänen beschreiben das Produkt, nicht das Organigramm. Teams ändern sich, IDs bleiben. Verantwortung hat ein eigenes Feld und kann sich unabhängig ändern.

SO FUNKTIONIERT ES

Der Code ändert sich. Alles, was davon abhängt, erfährt davon.

account/access/password-resetBeispiel-Repository · Wiederholung alle 16 s

RECORD · password-reset.yaml

intent:  summary: A customer who forgot their    password gets a link by email. It works    once and stops after 60 minutes.contract:  scenarios:    - id: link-expires-after-60-minutes

CODE · src/reset.ts

// @facet: account/access/password-reset// @facet-role: primaryexport const LINK_LIFETIME_MINUTES = 60; export function isLinkValid(sentAt, now) {  return now - sentAt    < LINK_LIFETIME_MINUTES * 60_000;}

Passwort zurücksetzen

Du erhältst einen Link per E-Mail. Er gilt einmalig für 60 Minuten. Fordere danach einen neuen an.

neu generiert · aktuell

record updated · link-expires-after-60-minutes$ facet docs checkstale: help/password-reset.md — written from an older revision of its recordregenerated from the record · every sentence cited

Ablauf · Beispiel-Repository · Drift-Zeile im echten FACET-Format; Hook- und Docs-Check-Texte sinngemäß

WENN SICH DIE SPEZIFIKATION ÄNDERT

Ändere die fachliche Anforderung. Sieh alle Stellen, die folgen müssen.

Das Produktteam verlängert die Testphase von 14 auf 30 Tage. Die Konstante wird angepasst. Die Preisseite auch. Die Erinnerung kommt weiterhin an Tag 11 – und die Abrechnung belastet die Karte an Tag 14.

RECORDbilling/subscriptions/free-trial.yaml
business_rules:  - id: trial-length-   rule: A new account gets 14 days free.+   rule: A new account gets 30 days free.contract:  scenarios:    - id: reminder-before-trial-ends      Given a trial that ends in 3 days      Then the customer gets one reminder    - id: first-charge-after-trial      Given the trial has ended      Then the card is charged once

Eine fachliche Anforderung wurde geändert. Fünf verankerte Stellen und ein referenzierter Test müssen geprüft werden.

anchor_list billing/subscriptions/free-trial6 Stellen · 3 geändert

Die Zeilen kürzen Dateien ab, die nach anchor_list geöffnet wurden. Umliegender Code ist hier ausgeblendet. Wähle einen Eintrag für den Beispielkontext. Zeilennummern markieren Anker; die Teststelle stammt aus record.verification.

  • src/billing/trial.ts:7Beispielcode nach dem Öffnen der Datei. Die markierte Implementierungszeile ist von der Ankerstelle zu unterscheiden; umliegende Zeilen sind gekürzt. anchor_list selbst liefert diesen Code nicht.…// @facet: billing/subscriptions/free-trial// @facet-role: primaryexport const TRIAL_DAYS = 30export function trialEndsAt(start: Date) { return addDays(start, TRIAL_DAYS);}…Mehr über Anker lesen
  • web/pricing/PricingPage.tsx:42Beispielcode nach dem Öffnen der Datei. Die markierte Implementierungszeile ist von der Ankerstelle zu unterscheiden; umliegende Zeilen sind gekürzt. anchor_list selbst liefert diesen Code nicht.…// @facet: billing/subscriptions/free-trial// @facet-role: relatedexport function PricingPage() { return <h1>Start your 30-day free trial</h1>;}…Mehr über Anker lesen
  • test/billing/trial.spec.ts:18Dieser Beispieltest wird über record.verification referenziert. Er ist kein Anker mit einer Verification-Rolle. Umliegender Testcode ist gekürzt.…describe('free trial', () => { it('expires after 30 days', () => { expect(trialEndsAt(start)).toEqual(addDays(start, 30)); });});…Mehr über Anker lesen
  • src/jobs/trial-reminder.ts:23Beispielcode nach dem Öffnen der Datei. Die markierte Implementierungszeile ist von der Ankerstelle zu unterscheiden; umliegende Zeilen sind gekürzt. anchor_list selbst liefert diesen Code nicht.…// @facet: billing/subscriptions/free-trial// @facet-role: relatedexport function scheduleReminder(start: Date) { return scheduleEmail({ sendAt: addDays(start, 11), template: 'trial-ending', });}…Mehr über Anker lesen
  • config/billing/stripe.yaml:4Beispielcode nach dem Öffnen der Datei. Die markierte Implementierungszeile ist von der Ankerstelle zu unterscheiden; umliegende Zeilen sind gekürzt. anchor_list selbst liefert diesen Code nicht.…# @facet: billing/subscriptions/free-trial# @facet-role: configsubscriptions: defaults: trial_period_days: 14 currency: EUR…Mehr über Anker lesen
  • emails/trial-ending.mjml:9Beispielcode nach dem Öffnen der Datei. Die markierte Implementierungszeile ist von der Ankerstelle zu unterscheiden; umliegende Zeilen sind gekürzt. anchor_list selbst liefert diesen Code nicht.…<!-- @facet: billing/subscriptions/free-trial --><!-- @facet-role: related --><mj-text> Your 14-day trial ends in 3 days</mj-text>…Mehr über Anker lesen

WAS BEIM KUNDEN ANKOMMT – 3 STELLEN ÜBERSEHEN

  1. TAG 11

    „Deine Testphase endet in 3 Tagen.“ Das stimmt nicht.

  2. TAG 14

    Stripe belastet die Karte. Die Preisseite nennt 30 Tage.

  3. TAG 15

    Ein Support-Ticket, eine Erstattung, ein Kunde, der nicht wiederkommt.

Die Liste entsteht aus den Ankern in deinem Code. Sie abzuarbeiten bleibt Aufgabe des Agenten – nicht verankerter Code muss weiterhin separat geprüft werden.

anchor_list liefert Ankerstellen, keine passenden Codezeilen · Test aus record.verification · Beispielauszüge nach dem Öffnen der Dateien

IN EINER AGENTENSITZUNG

Dein Agent öffnet eine Datei. Die fachlichen Anforderungen kommen mit.

Das -Plugin greift an fünf Zeitpunkten jeder Sitzung ein. Niemand muss ans Nachschlagen denken: Liest der Agent verankerten Code, stehen die fachlichen Anforderungen und die Szenarien des Records schon in seinem Kontext – vor der ersten Änderung.

PostToolUse · Read · read-context.sh

Die fachlichen Anforderungen kommen mit der Datei.

Der Agent liest eine Datei mit Anker. Im selben Schritt erhält er das erwartete Verhalten des Records und alle Szenario-IDs – bevor er eine Zeile ändert. Die zugehörigen Tests sind nur einen Aufruf entfernt.

Einmal pro Record und Datei je Sitzung; erneut nach Kontextverdichtung. Auf 8 KB begrenzt.

AGENT CONTEXTKontext zum Lesevorgang
read src/billing/trial.tsFACET claims for src/billing/trial.ts, before editing: billing/subscriptions/free-trial  promises: A new account gets 30 days free, one  reminder three days before the end, and the first  charge the day after.  contract: trial-length, reminder-before-trial-ends,  first-charge-after-trial, no-second-trial Check these existing claims before changing observable behaviour.Use read_facet for the full intent or contract; update the recordwhen its claims change.

hooks/hooks.json · Kontexttext aus dem Read-Hook des Programms · Beispiel-Feature

01 · ANKER

Zeige auf eine Codezeile. Lies das erwartete Verhalten.

Ein Kommentar verbindet den Code mit seinem Record. Dein Editor folgt der Verbindung: Anforderungen beim Zeigen lesen, zum Record springen, überall gleichzeitig umbenennen.

CODEinternal/checkout/discount.go
// @facet: checkout/pricing/discount-codesfunc Redeem(code string, c Cart) (Cart, error) {    d, err := lookup(code)    if d.Expired(now()) {        return c, ErrExpired(d.Until)    }    return c.Apply(d), nil}

checkout/pricing/discount-codes · active

Ein gültiger Code senkt die Warenkorbsumme einmal. Ein abgelaufener Code wird unter Angabe seines Ablaufdatums abgelehnt.

3 Szenarien · F12 zum Record · F2 umbenennen

RECORDdocs/facets/features/checkout/pricing/discount-codes.yaml
id: checkout/pricing/discount-codeslifecycle: activecontract:  scenarios:    - id: expired-code-is-refused      given: a code that expired yesterday      when: the customer redeems it      then: the total is unchanged and            the expiry date is shown

facet lsp · stdio-Server; benötigt einen konfigurierten LSP-Client · Beispiel-Feature · Welche Editoren können sich verbinden?Grundsätzlich: Neovim und Helix mit eigener Serverkonfiguration; Emacs mit Eglot und Sublime Text mit dem LSP-Paket. VS Code benötigt eine Client-Erweiterung; JetBrains-IDEs können LSP4IJ nutzen. Das beschreibt Client-Fähigkeiten, keine verifizierten FACET-Anbindungen. Dateizuordnungen und Projektstamm müssen eingerichtet werden; mehrere Sprachserver hängen vom Client ab.CLI-Referenz lesen

02 · facet test

Mehr als Codeabdeckung. Geprüfte Features.

Führe facet test aus: Jedes Feature erhält ein eigenes Ergebnis aus den Tests seines Records – nur aktuelle Berichte zählen. Ein grüner Exitcode allein reicht nicht.

facet test: Ergebnis pro Feature
checkout/pricing/discount-codes3 Testdateien, alle bestandenbestanden
checkout/cart/apply-vouchervoucher.spec.ts fehlgeschlagenfehlgeschlagen
account/profile/export-datakein Bericht für export_test.gonicht gemessen
account/auth/magic-linkRecord nennt keine Testdateinicht gemessen
navigation/search/recent-queries2 Testdateien, alle bestandenbestanden
billing/invoices/pdf-downloadRunner endete mit 0, schrieb keinen Berichtnicht gemessen

$ facet test2 bestanden1 fehlgeschlagen3 nicht gemessenBeispiellauf

  • bestandenaktueller Bericht, alle benannten Tests bestanden
  • fehlgeschlagenein benannter Test ist fehlgeschlagen
  • nicht gemessenkein aktueller Bericht – nicht gemessen, ohne angenommene Freigabe

Wo lohnt sich der nächste Review?

Nicht nur aus Erinnerung entscheiden. FACET verbindet behobene Fehler aus der Git-Historie mit den betroffenen Features – samt Commit, Datum und Dateien. So lässt sich gezielt fragen, wo ein zusätzlicher Review oder bessere Tests sinnvoll sind.

Ein behobener Fehler bekommt einen fachlichen Zusammenhang

  1. Der Commit nennt eine Korrektur

    fix(checkout): reject an expired code

    Der Betreff passt zur vereinbarten Konvention für Fehlerkorrekturen.

  2. Die geänderte Datei trägt einen Anker

    src/checkout/discount.ts

    Die Zuordnung entsteht über die vorhandenen Code-Anker im aktuellen Arbeitsstand.

  3. Der Feature-Record bewahrt den Beleg

    checkout/pricing/discount-codes

    Das Fehlerjournal hält Commit, Datum und betroffene Dateien fest. Die zugehörigen Testnachweise werden separat gelesen.

Beispielwerte · keine Messung dieses Projekts
Features nach aufgezeichneten Korrekturen
FeatureKorrekturen
checkout/pricing/discount-codessrc/checkout/discount.ts7
billing/subscriptions/free-trialsrc/billing/trial.ts3
account/access/password-resetsrc/account/password-reset.ts1

Sieben aufgezeichnete Korrekturen sind nicht sieben offene Fehler. Ohne Journal erscheint ein Feature nicht als vermeintlich fehlerfreie Null.

CLIBegrenzt beginnen, vor dem Schreiben prüfen
facet defects backfill \  --since=90.days --limit=500 --dry-run facet defects --top 3
  • --dry-run zeigt den Import, ohne Records zu ändern. Ohne dieses Flag wird nur deren defects-Abschnitt ergänzt.
  • Nicht jede Korrektur trägt einen passenden Commit-Betreff. Fehlende Anker sowie umbenannte oder gelöschte Pfade begrenzen die Zuordnung.
  • Die Liste zeigt gefundene und behobene Fehler. Lies sie zusammen mit Testnachweisen und Nutzung – sie ist kein Urteil über die heutige Fehlerzahl.
Fehlerjournal und Befehle ansehen

Mit der Software anfangen, die schon da ist.

Ein bestehendes Projekt braucht keinen Neustart, um fachlich nachvollziehbar zu werden. Der geführte Nachdokumentationslauf sichtet den Code, entwirft Feature-Records und macht sichtbar, was geprüft wurde – und welche Antworten noch von den Verantwortlichen fehlen.

  1. Bereich und Aufwand klären

    Zuerst werden Umfang, Sprachen und der Ablageort des Laufprotokolls vereinbart. Eine Kostenschätzung steht vor dem eigentlichen Durchgang.

  2. Vom Code zu Feature-Entwürfen

    Der Lauf ordnet vorhandenen Code fachlichen Fähigkeiten zu und entwirft die zugehörigen Records mit ihren Verbindungen.

  3. Die gewünschte Prüftiefe wählen

    Entwurf, Code-Prüfung und Beobachtung im Produkt sind unterschiedliche Nachweise. Der Bericht benennt den gewählten Umfang.

  4. Offenes gezielt weiterbearbeiten

    Ungeklärte Fragen gehen an Verantwortliche. Ein unterbrochener Lauf knüpft an sein geprüftes Protokoll an, statt alles neu zu erzeugen.

Jeden Entwurf mit dem Code abgleichen

Eine eigene Prüfung liest jeden Entwurf gegen die Umsetzung. Beanstandungen werden überarbeitet, mit Begründung zurückgewiesen oder als offene Arbeit festgehalten – einschließlich fehlender Tests.

  • Feature-Entwürfe und Formprüfungenthalten
  • Review und Überarbeitung jedes Entwurfsenthalten
  • Abweichungen im laufenden Produkt reproduzierennicht enthalten

Ergebnis: geprüfte und überarbeitete Beschreibungen mit einer nachvollziehbaren Liste verbleibender Lücken.

/facet:setup

Die Einrichtung führt zur Aufnahme vorhandenen Codes. Das ist ein Agenten-Workflow, nicht der Import von Fehlerkorrekturen mit facet defects backfill.

Nachdokumentation im Detail

Große Durchgänge können das KI-Nutzungskontingent stark beanspruchen. Beispiele zeigen den Ablauf, keine geprüfte Abdeckung dieses Projekts.

Null heißt: geprüft. Ein Strich heißt: nicht gemessen.

GEMESSEN

0

fehlgeschlagene Tests. Die Suite lief, der Bericht ist aktuell, kein Test schlug fehl.

NICHT GEMESSEN

fehlgeschlagene Tests. Es liegt kein Bericht vor. Daraus machen wir keine Null.

Atlas macht diesen Unterschied überall sichtbar und zeigt Prozentwerte nur mit ihrer Bezugszahl.

ATLAS

Dein ganzes Produkt. Verständlich auch ohne YAML.

Ein Befehl öffnet dein Repository als Produktkarte im Browser. Anforderungen, zugeordnete Tests und Drift werden für sieben Leserollen sichtbar. Atlas AI beantwortet Fragen; Plugins ergänzen Bearbeitungsabläufe wie Wiki-Vorschläge.

Bald verfügbarAtlas entdecken
7 (Quelle: the Atlas docs, Seven roles)
Leserollen
3 (Quelle: navigation/atlas/visible-depth)
Ebenen: Register, Record, Akzeptanzkriterium
127.0.0.1 (Quelle: internal/ui/server.go)
die einzige Adresse, auf der Atlas lauscht

checkout › pricing › discount-codesEntwicklung

Einen Rabattcode einlösen

  • A valid code lowers the total oncenamed ×2
  • An expired code is refusednamed ×1
  • Two codes don’t stackno test
  • The discount is capped at 50 %named ×3
  • src/checkout/discount.ts changeddrift

ATLAS FRAGEN

Weist der Code abgelaufene Codes noch ab?

Ja: redeem() liefert ErrExpired zurück, bevor sich der Gesamtpreis ändert.

3 Dateien gelesen · keine geschrieben

03 · ATLAS

Sieben Leserollen. Für jede eine eigene Ansicht.

Atlas liest dein Repository und bereitet dieselben Records je nach Leserolle anders auf. Die Leitung erhält einen Bericht ohne Schema-Begriffe. Agenten bekommen Rohdaten mit null für nicht gemessene Werte.

  • REPORT

    Der Produktstand in einem Satz, ohne Schema-Begriffe.

  • DIESE WOCHE

    Was sich geändert hat

  • BEOBACHTEN

    Was gefährdet ist

  • VERANTWORTLICHE

    Wer wofür zuständig ist

  • OFFEN

    Fragen ohne Verantwortliche

  • NICHT GEMESSEN

    — als Strich dargestellt

facet ui · läuft auf 127.0.0.1 neben deinem Code · beispielhafte Ansichten der Leserollen

04 · FRAGEN

Frag den Code. Antworten mit geregeltem Zugriff.

Atlas AIAtlas mit verknüpften Records als Grundlage für KI-Antworten.Atlas AI beantwortet Fragen und erstellt Einordnungen mit deiner bestehenden -Anmeldung; bei Abo-Nutzung kaufst du keine zusätzlichen FACET-Tokens, während Anbieterlimits und eine ausdrücklich eingerichtete API-Abrechnung weiter gelten.Jetzt ansehenHier weiterlesen antwortet anhand deiner Records und deines Codes und nennt seine Quellen. Die Standardwerkzeuge können keine Dateien bearbeiten und keine Shell starten. Separat freigegebene Plugin-Werkzeuge können gezielte Aktionen ergänzen; der Wiki-Editor schlägt bereits Änderungen auf einem Branch vor.

  • Write
  • Edit
  • Bash
  • WebFetch
  • WebSearch
  • Task

Wo weisen wir abgelaufene Rabattcodes ab, und stimmt der Record damit überein?

  1. liest docs/facets/features/checkout/pricing/discount-codes.yaml
  2. liest internal/checkout/discount.go
  3. liest internal/checkout/discount_test.go

In Redeem(), bevor sich der Gesamtpreis ändert: Ein abgelaufener Code liefert ErrExpired mit seinem Datum. Das entspricht dem Record-Szenario expired-code-is-refused.

Quellen: internal/checkout/discount.go:15 · discount-codes.yaml

Beispiel

05 · KNOWLEDGE

Fünf Fragen.
Jedes Feature erklärt.

  1. 01Was müssen Nutzende bereits verstehen, um dieses Feature zu verwenden?
  2. 02Wann ist dieses Feature nicht das passende Werkzeug?
  3. 03Wo beginnt dieser Ablauf im Produkt?
  4. 04Welche Fehler machen Nutzende typischerweise mit diesem Feature?
  5. 05Woran erkennen Nutzende, dass es funktioniert hat?

Einmal beantworten. FACET erstellt daraus Hilfeartikel, FAQ und Einführung: mit Quellen für jeden Satz. Offene Antworten werden ausgelassen statt erfunden.

Dieselben Antworten. Fünf Leserollen.

„Kann es das?“ aus dem Record beantworten statt aus dem Gedächtnis.

WARUM ES SO GEBAUT IST

Jede Regel hat einen Grund. Festgehalten in der Spezifikation.

Antworten aus der FACETOriginalauszug aus der englischen Quelle.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]Auf GitHub öffnen. Die vollständige Begründung steht dort.

Warum ein Record pro Feature statt pro Service oder Seite?
Menschen fragen nach Features. Ein Service ist Implementierung und erhält einen Anker; eine Seite beschreibt den Einstieg in einen Ablauf. Ein Feature erfüllt fünf Kriterien: ohne „und“ benennbar, in einer Sitzung abschließbar, zwei bis neun Szenarien, ein benennbarer Verlust bei Entfernung und eine klare Teamverantwortung.

Quelle: FACETOriginalauszug aus der englischen Quelle.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]Auf GitHub öffnen FACET §2.1Originalauszug aus der englischen Quelle.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]Auf GitHub öffnen, FACET §2.1.1Originalauszug aus der englischen Quelle.[…] It has between two and nine observable scenarios, including at least one failure path. […]Auf GitHub öffnen

Warum verweist der Code auf den Record?
Features passen nicht in einen Ordner. Ein Tastenkürzelsystem kann vierzig Dateien in zwölf Verzeichnissen betreffen. Ein Record, vierzig Anker: Beim Verschieben bleibt der Anker am Code. Eine Pfadliste im Record wäre nach dem ersten Refactoring veraltet.

Quelle: FACETOriginalauszug aus der englischen Quelle.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]Auf GitHub öffnen FACET §2.3Originalauszug aus der englischen Quelle.[…] FACET does not require a feature-based repository layout. […]Auf GitHub öffnen, FACET §3.3Originalauszug aus der englischen Quelle.[…] Where in the codebase the feature is implemented. […]Auf GitHub öffnen

Warum hat jede ID genau drei Ebenen?
Domäne, Fähigkeit und Feature bilden die Produktstruktur ab. Eine vierte Ebene beschreibt meist Szenarien. Domänen und Fähigkeiten werden zentral deklariert. Ungültige IDs fallen so früh auf, denn einmal vergebene IDs bleiben unverändert.

Quelle: FACETOriginalauszug aus der englischen Quelle.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]Auf GitHub öffnen FACET §2.2Originalauszug aus der englischen Quelle.[…] Every feature has a canonical, stable identifier of the form: […]Auf GitHub öffnen, FACET §4.4Originalauszug aus der englischen Quelle.[…] which is the decomposition a product actually has. […]Auf GitHub öffnen

Warum darf eine Domäne kein Team sein?
Teams werden umorganisiert, IDs bleiben. IDs aus dem Organigramm veralten daher vorhersehbar. Verantwortung hat ein eigenes Feld und kann sich unabhängig ändern.

Quelle: FACETOriginalauszug aus der englischen Quelle.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]Auf GitHub öffnen FACET §2.2Originalauszug aus der englischen Quelle.[…] Every feature has a canonical, stable identifier of the form: […]Auf GitHub öffnen

Warum im Zweifel einen größeren Record wählen?
Die beiden Fehler verursachen unterschiedlich viel Aufwand. Aufteilen ist später mechanisch möglich. Beim Zusammenführen werden unveränderliche IDs stillgelegt und dauerhafte Weiterleitungen nötig. Wenn beide Zuschnitte passen, wähle den gröberen.

Quelle: FACETOriginalauszug aus der englischen Quelle.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]Auf GitHub öffnen FACET §2.1.1Originalauszug aus der englischen Quelle.[…] It has between two and nine observable scenarios, including at least one failure path. […]Auf GitHub öffnen

Warum bleiben fehlende Antworten offen?
Eine plausible Erfindung ist schlechter als eine sichtbare Lücke. Generierte Dokumentation belegt jeden Satz. Leere Antworten bleiben offen und für die Verantwortlichen sichtbar. Dasselbe gilt für Zahlen: nicht gemessen heißt Strich, nicht Null.

Quelle: FACETOriginalauszug aus der englischen Quelle.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]Auf GitHub öffnen FACET §8.5Originalauszug aus der englischen Quelle.[…] The Knowledge facet exists precisely to feed this pipeline. […]Auf GitHub öffnen

Ist „proves:“ nicht nur eine Behauptung?
Ja. Der Lint prüft nur, ob das Szenario existiert. Deshalb führt facet test die benannten Dateien aus und berichtet pro Feature. Ohne aktuellen Bericht gilt ein Feature als nicht gemessen, selbst wenn der Testprozess mit Exit 0 endet.

Quelle: FACETOriginalauszug aus der englischen Quelle.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]Auf GitHub öffnen FACET §3.4Originalauszug aus der englischen Quelle.[…] The tests and property checks that prove the contract holds. […]Auf GitHub öffnen · facet test

Was gehört nicht zu FACET?
Strategie und Entscheidungsgründe gehören in ADRs. UX, Texte, nur statistisch korrektes ML-Verhalten und Sprintplanung sind ebenfalls eigene Themen. FACET hält fachliche Anforderungen und erwartetes Verhalten fest.

Quelle: FACETOriginalauszug aus der englischen Quelle.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]Auf GitHub öffnen FACET §9Originalauszug aus der englischen Quelle.[…] FACET is a single source of truth for a defined domain of claims about features. […]Auf GitHub öffnen

LOSLEGEN

Richte FACET ein, bevor dein Agent die nächste Änderung macht.

Vier Schritte. Ein Assistent prüft den Istzustand, fragt vor Änderungen und kontrolliert jeden Schritt dort, wo er wirkt.

  1. 01 · PROJECT

    Öffne dein Projekt

    Dein Repository bleibt zunächst unverändert. In Projekten ohne FACET bleibt das Plugin still.

    Prüfung: Der Agent befindet sich im Projektordner

  2. 02 · WIZARD

    Einrichtungsassistent starten

    /facet:setup

    Bei vorhandenem Code ohne Records schlägt er die nachträgliche Erfassung vor: Grundgerüst, Domänentaxonomie, Agentenintegration und Git.

    Prüfung: Jeder Schritt wird an seinem Wirkungsort kontrolliert

  3. 03 · ADOPT

    Records nachträglich erfassen

    /facet:setup adopt

    Erfasst Fähigkeiten aus deinem Code und erstellt Records. Fragen, die nur Verantwortliche beantworten können, werden zurückgegeben. Wähle unten die gewünschte Prüftiefe.

    Prüfung: Fortsetzbares Protokoll und Liste offener Fragen

  4. 04 · CHECK

    Bestand prüfen

    facet lint

    Der Lint prüft jeden erfassten Record gegen das Schema und die Anker in deinem Code und nennt jeden, der durchfällt.

    Prüfung: Ein Lint-Bericht für die ganze Registry

NACHTRÄGLICHE ERFASSUNG · DREI WEGE FÜR BESTEHENDEN CODE

  • Schnell

    Token: niedrig · Qualität: Entwürfe

    Ungeprüfte Entwürfe. Bei komplexer Software können die Records Fehler enthalten.

  • Gründlich

    Token: höher · Qualität: gut

    Prüft jeden Entwurf gegen den Code und überarbeitet ihn. Abschließend entstehen Listen mit Abweichungen und fehlenden Tests.

  • Mit Nachweisen

    Token: sehr hoch · Qualität: sehr gut

    Reproduziert zusätzlich jede Abweichung im laufenden Produkt. Gemeldete Fehler wurden beobachtet.

Vor dem Start erhältst du eine Kostenschätzung. Jeder Lauf führt ein fortsetzbares Protokoll. Fragen an Verantwortliche werden zurückgegeben statt erfunden.