Prefixer

Prefixer: Scope first, widen on miss, log the delta

Ein Agent, der das gesamte Repository durchsucht, bezahlt für jeden irrelevanten Treffer in Tokens. Eine Namespace-Map – ein Dutzend Zeilen, die sagen, was wo lebt – erlaubt es, von Anfang an im richtigen Bereich zu suchen. Diese Fertigkeit baut diese Map auf, hält sie aktuell und zwingt den Agenten zuerst zum scoped Searching. Sie hat eine Aufgabe: günstigere, bessere Code-Durchsuchung.

Size Gate. Bei weniger als etwa einhundert Dateien oder wenn die Struktur des Repos auf einen Blick offensichtlich ist, überspringe die Map und scope Suchen nach Verzeichnisnamen; die Map zahlt sich erst danach aus.

Arbeitsweise

1. Einmal orientieren. Prüfe auf .prefixer/namespaces.md. Existiert keine und die Aufgabe wird mehr als zwei Suchen erfordern, kartiere den Abschnitt, in dem du arbeitest (§1 bis §3), und suche dann darin. Wenn eine Map existiert, lies sie und starte gescoped.
2. Gescoped suchen, bei Fehlschlag erweitern. Die erste Suche geht in den engsten plausiblen Namespace, nicht zur Repository-Wurzel (§4 bis §6).
3. Protokollieren. Beende die Aufgabe mit einer Zeile in .prefixer/metrics.jsonl, und einem Delta, wenn eine Baseline existiert (§7 bis §8). Erforderliche Ausgabe, nicht optional.

Wo es sich auszahlt

• Erste Session in einem großen oder unbekannten Repo. Lies zwölf Zeilen Map, anstatt den Baum zu scannen; die erste Suche ist bereits gescoped.
• Monorepos. Ein Namespace pro Package: Suchen ziehen nicht mehr das Rauschen von Geschwister-Packages in den Kontext.
• Viele Codebestände. Eine Map auf Organisationsebene wählt den Codebestand aus, die Repo-Map wählt den Namespace darin. Zwei Ebenen, nie eine Union-Suche.
• Wiederholte Erkundung. „Wo lebt X“, Refactorings, unbekannte Feature-Bereiche; die Trefferquote beim ersten Versuch ist der Punkt, an dem sich die Map auszahlt.
• Repos, die du wiedersehen wirst. Die Map überdauert Sessions; jeder zukünftige Agent startet orientiert, anstatt erneut zu scannen.

A. Die Namespace-Map

1. Kartiere den Abschnitt, nicht die Welt

Regel: Wenn ein Repo keine .prefixer/namespaces.md hat und die Arbeit mehr als zwei Suchen benötigt, kartiere den Teil des Repos, den diese Aufgabe berührt: drei bis fünf Namespaces, nicht den gesamten Baum. Eine Teil-Map, die die heutigen Suchen scoped, ist besser als eine vollständige Map, die eine Stunde gebraucht hat. Erweitere sie, wenn eine echte Suche außerhalb landet, niemals vorsorglich. Führe bash scripts/init_namespaces.sh (im Verzeichnis dieser Fertigkeit) für ein Gerüst aus, korrigiere dann seine Schätzungen: benenne, wofür jeder Namespace ist.

Warum: Adoption ist von Natur aus inkrementell. Die Map ist eine Arbeitsdatei, keine Volkszählung; sie verdient eine Zeile, wenn eine Suche diese Zeile braucht.

Entwürfe sind keine Maps. Jede Zeile, deren Präfix oder contains noch TODO sagt, ist unvollständig; beende sie oder entferne sie, bevor du dich auf die Map verlässt. Das Gerüst meldet, wie viele Entwurfszeilen übrig sind.

Vorhandene Doks zuerst. Wenn AGENTS.md, CLAUDE.md oder die README die Struktur bereits beschreiben, bestücke contains daraus (das Gerüst tut dies) und behandele namespaces.md als maßgeblich für den Such-Scope; pflege nicht zwei auseinanderdriftende Inhaltsverzeichnisse.

Session-Start ist besser als Merken. Das einmalige Lesen der Map pro Session ist der Schritt, der am ehesten übersprungen wird. Wenn die Umgebungskontrolle Dateien zu Session-Beginn einfügen kann, lasse sie namespaces.md ausgeben: Dann startet jede Suche bereits gescoped, ohne dass Disziplin erforderlich ist. Ausgelieferte Verkabelung: scripts/install_hook.sh schreibt den Hook für dich (scripts/session_start.sh gibt die Map plus einen Gesundheitsstatus aus); Handschnipsel leben in integrations/. Rezept und Begründung: references/namespaces.md.

2. Halte sie klein und glob-gestützt

Regel: 5 bis 12 Namespaces. Jede Zeile besteht aus einem kurzen Präfix, einem Pfad-Glob und einer einzeiligen Beschreibung zur Unterscheidung. Wenn zwei Zeilen gleich häufig von derselben Suche getroffen würden, fasse sie zusammen. Wenn eine Zeile nie eine echte Suche scoped, entferne sie.

Format:

# namespaces
repo: acme-payments

| prefix | scope              | contains                    |
|--------|--------------------|-----------------------------|
| api:   | src/api/**         | REST-Handler, Routen        |
| auth:  | src/auth/**        | Login, Sessions, Token      |
|   sso: | src/auth/sso/**    | SSO-Subteam-Bereich         |
| test:  | tests/**, **/*.test.* | Suiten, Fixtures          |

Der repo:-Header ist der eindeutige Qualifizierer dieses Codebestands (aus dem git-Remote); er macht jedes Präfix global eindeutig, wenn eine Organisation viele Codebestände betreibt: acme-payments:auth: kann niemals mit checkout-service:auth: kollidieren.

Zeilen verschachteln: Eine eingerückte Zeile gehört zum Namespace darüber, für Subteams innerhalb eines Moduls oder Packages innerhalb eines Dienstes. Das Tag setzt sich zusammen, auth:sso:, sodass derselbe Name unter zwei Eltern eindeutig bleibt (orders:checkout: vs payments:checkout:).

Namen werden abgeleitet, nicht deklariert. Präfixe und contains-Text stammen aus dem eigenen Vokabular des Codebestands: Verzeichnisnamen, die dominierenden Begriffe in den Dateien, die eine Zeile scoped, niemals aus selbst erfundenen Kategorien. Abgeleitete Namen folgen dem Repo, während es sich entwickelt; erfundene driften ab. Das Gerüst macht das für dich: Korrigiere, was es falsch macht, behalte, was es richtig macht.

Formatdetails und Maps für andere Repo-Formen: references/namespaces.md.

3. Aktualisieren, niemals neu generieren

Regel: Wenn die Map veraltet ist, bearbeite die veralteten Zeilen. Überschreibe die Datei nicht. Eine vollständige Neugenerierung verliert die angesammelten Details, die sie nützlich gemacht haben. Entferne tote Zeilen, füge fehlende hinzu, behalte den Rest byte-identisch; eine neu geschriebene Map bricht auch den Prompt-Cache-Präfix jeder Session, die sie geladen hat. Nach der Kuratierung führe bash scripts/check_namespaces.sh aus: Eine Zeile, deren Globs ins Leere auflösen, ist eine Lüge, die die Map jeder zukünftigen Session erzählt. Wenn die Map sich veraltet anfühlt oder das Log gewachsen ist, führe bash scripts/suggest_map.sh aus: Es liest metrics.jsonl und den Baum und schlägt die Zeilen vor, die echte Suchen bereits angefragt haben.

Viele Codebestände: Derselbe Trick stapelt sich. Eine Map auf Organisationsebene wählt den Codebestand aus (pay: services/payments/**), die Repo-Map wählt den Namespace darin. Jede Maps repo:-Header hält Präfixe codebestandübergreifend eindeutig; vierzig Dienste können alle ein auth/ haben, weil ein qualifiziertes Tag payments:auth: genau einen benennt. Vereinige niemals jedes Repo in eine Suche – das ist der Root-Grep-Fehler auf Organisationsebene. Siehe references/namespaces.md.

B. Such-Scoping

4. Zuerst der engste

Regel: Jede Suche beginnt im engsten Namespace, der die Antwort enthalten könnte. grep "expire" src/auth/ schlägt grep "expire" .. Ein Fehlschlag kostet einen Aufruf; eine breite Suche kostet die gesamte Trefferliste in Tokens.

Lass das Skript die Regel tragen: bash scripts/search.sh auth "expire" löst das Tag zu seinen Globs auf, sucht darin, erweitert bei Fehlschlag eine Ebene und protokolliert die Metrikzeile; §4 bis §8 laufen von selbst. --scope <ns> gibt die Glob-Liste aus, --paths <ns> die aufgelösten Dateien, --list jedes Tag; die Map als Index, den andere Befehle abfragen können.

Achte auf: Suchen der Repo-Wurzel „nur für den Fall“, Glob-Muster wie **/* ohne Pfadeinschränkung, find verwendet, wo ein Namespace-Glob ausreichen würde.

5. Bei Fehlschlag eine Ebene erweitern

Regel: Innerhalb eines Namespace nichts gefunden? Erweitere eine Ebene: Namespace, dann seinen Elternbereich, dann das Repo, dann vendor- und generierte Verzeichnisse. Springe nicht von einem Fehlschlag direkt zu einem gesamten Repo-Scan und durchsuche nicht node_modules, vendor, dist, build oder Lock-Dateien, es sei denn, die Aufgabe betrifft sie.

6. Antwort in Namespace-Tags

Regel: Melde Funde als prefix:path:line (auth:src/auth/session.ts:42). Die nächste Suche – deine oder die einer zukünftigen Session – startet dann bereits gescoped. Wenn eine Datei sich jedem Namespace widersetzt, ist das ein Signal, dass die Map eine Lücke hat; erwähne es, anstatt ein Tag zu erfinden.

C. Tracking

7. Baseline vor Behauptungen

Regel: Bevor du Änderungen an der Suche empfiehlst, zähle das aktuelle Verhalten: Suchen pro Aufgabe, Tool-Aufrufe pro Aufgabe, Trefferquote beim ersten Versuch. Ohne Baseline gibt es kein Delta, nur eine Geschichte. Nimm eine auf, indem du eine feste Sonde ausführst: bash scripts/measure_search.sh --baseline orientation -- grep -rn "TODO" . bei der Repo-Wurzel oder indem du die ersten Aufgaben zählst, bevor die Map existiert. Siehe references/metrics.md für das, was aufgezeichnet werden soll und wie es bewertet wird.

8. Jede Aufgabe protokollieren

Regel: Füge am Ende jeder Aufgabe eine JSON-Zeile zu .prefixer/metrics.jsonl hinzu:

{"ts":"2026-10-26T14:03:11Z","task":"find-session-expiry","searches":3,"tool_calls":4,"first_try_hit":true,"est_tokens":1400}

est_tokens ist Zeichen/4, eine Schätzung; behalte das Feld auch, wenn du nicht genau messen kannst. Am Session-Ende berichte das Delta zur Baseline. scripts/measure_search.sh kapselt eine Suche und protokolliert eine Zeile pro Suche auf der Repo-Wurzel (hits, scope; --baseline markiert die Sonde, --hit|--miss zeichnet first_try_hit auf). Handgeschriebene Aufgabenzeilen fügen tool_calls und first_try_hit hinzu. Ein Schema, optionale Felder; references/metrics.md listet sie auf. scripts/report_metrics.sh liest das Log zurück: Trefferquote, Ausgaben pro Scope, das gescopte-vs-Baseline-Delta.

Git-Handhabung. Committe namespaces.md: Es ist der gemeinsame Präfix, von dem jede zukünftige Session profitiert. metrics.jsonl ist lokale Telemetrie; das Gerüst schreibt ein .prefixer/.gitignore dafür. Committe es nur, wenn das Team Trenddaten haben möchte.

Warnsignale

Diese Gedanken bedeuten Stopp. Du rationalisierst.

Gedanke	Realität
„Ein breites grep schadet nicht“	Das breite grep ist die Kosten, die diese Fertigkeit entfernen soll. Scope es.
„Ich weiß, wo es wahrscheinlich ist“	Überprüfe im Namespace. Eine falsche Vermutung kostet mehr als ein gescopter Check.
„Kartiere zuerst das ganze Repo“	Kartiere den Abschnitt, in dem du bist. Der Rest verdient Zeilen, wenn Suchen sie brauchen.
„Die Map ist übertrieben für diese Aufgabe“	Eine Teil-Map zahlt sich bereits bei der dritten Suche aus.
„Überspringe die Baseline, wende es einfach an“	Keine Baseline bedeutet keine Beweise. Miss zuerst.
„Ich generiere die ganze Map neu, das ist schneller“	Neugenerierung verwirft kuratierte Details und zerbricht den Cache. Bearbeite die veralteten Zeilen.
„Eine mit Gerüst erstellte Map zählt“	Eine Map voller TODO-Zeilen ist ein Entwurf, keine Map. Beende sie oder entferne sie.
„Durchsuche vendor-Verzeichnisse, um gründlich zu sein“	Generierter Code ist der Ort, an dem Tokens sterben. Suche darin nur, wenn es das Thema ist.

Wann nicht zu prefixen

• Einzeldatei-Skripte und Wegwerf-Repos: Es gibt nichts zu scopn.
• Aufgaben mit einer offensichtlichen Datei: Öffne sie, baue keine Infrastruktur dafür.
• Wenn der Pfad es bereits sagt: Eine Suche in src/auth/ braucht keine auth:-Zeremonie.
• Vorgemerkte oder generierte Code, es sei denn, es ist das Thema der Aufgabe.
• Repos mit ~100 Dateien, deren Struktur offensichtlich ist: Scope nach Verzeichnisnamen und überspringe die Map.

Referenzen

• references/namespaces.md: Map-Format, Repo-Formen, Multi-Repo-Stapelung
• references/metrics.md: Metrikdefinitionen, JSONL-Schema, Delta-Berichterstattung
• scripts/init_namespaces.sh: Erstelle ein Namespace-Map-Gerüst für das aktuelle Repo
• scripts/check_namespaces.sh: Überprüfe eine Map: tote Scopes, doppelte Tags, Entwürfe
• scripts/search.sh: Gescopte Suche als Befehl: auflösen, suchen, erweitern, protokollieren
• scripts/suggest_map.sh: Lese das Log + den Baum, schlage Map-Bearbeitungen vor
• scripts/measure_search.sh: Führe eine Suche aus und protokolliere sie in einem Schritt
• scripts/report_metrics.sh: Lese das Log zurück: Trefferquote, Scope-Ausgaben, Delta
• scripts/session_start.sh: Gib die Map (+ Gesundheitsstatus) für Session-Start-Hooks aus
• scripts/install_hook.sh: Verkabeln des SessionStart-Hooks für devin/claude
• scripts/doctor.sh: Gesundheitscheck des Setups eines Repos: Map, Lint, Hook, Installationsstempel
• scripts/eval_scope.sh: Messe das Token-Delta einer gescopten Suche vs. Wurzel
• scripts/eval_repo.sh: Lint + Bewerte jeden Namespace in einer Map, mittlere %-Ersparnis
• scripts/visualize.py: Rendere die Map auf dem Dateibaum + die gemessenen Ersparnisse als HTML-Bericht
• SPEC.md: Der Formatvertrag für namespaces.md, für Werkzeuge, die Maps lesen oder schreiben
• integrations/: Session-Start-Hook-Schnipsel + ein PR-Lint-Workflow für Verbraucher-Repos

Angrenzende Playbooks, die für Pipeline- und Prompt-Autoren aufbewahrt werden (außerhalb des Kernjobs dieser Fertigkeit): references/index-prefixes.md, references/prefix-library.md, references/cache-ordering.md.