Manueldav2/begin

Was macht begin?

Orientieren Sie sich in einer Codebase in einem Durchgang, basierend auf Beweisen, ohne zu streifen.

Der Fehler, den dies verhindern soll: Ein Agent öffnet ein Repo, grept nach einem plausibel klingenden Wort, liest drei Dateien, die zufällig passen, und berichtet eine selbstbewusste Architekturzusammenfassung, die 4 % des Systems beschreibt. begin ersetzt das Raten darüber, wo der wichtige Code ist, durch Messen, wo er ist, und liest dann nur das, worauf die Messung hingewiesen hat.

Der Vertrag

1. Nichts wird erinnert. Alles wird abgeleitet. Wichtigkeit stammt von einem PageRank über den realen Importgraphen; Komplexität von gezählten Entscheidungspunkten; Fokus von Git und dem PR-Logbuch. Wenn Sie nicht auf eine Datei:Zeile oder einen Commit zeigen können, sagen Sie es nicht.
2. Jede Behauptung ist verankert. Jede Aussage in BEGIN.md zitiert Pfad:Zeile, einen Commit oder eine PR-Nummer. Ein unverankerter Satz ist eine Vermutung, und Vermutungen sind das, was dieser Skill zu beseitigen versucht.
3. Zwei Schichten, eine davon lebendig. .begin/ ist Maschinenausgabe, neu generiert und ignoriert sich selbst. BEGIN.md ist Prosa, die Sie geschrieben, committet und mit dem Commit gestempelt haben, von dem sie abgeleitet wurde. Ein Post-Commit-Hook leitet die Maschinenschicht neu ab und berichtet, welche Prosaabschnitte der Code überholt hat. Nichts in diesem Skill bearbeitet jemals eine verfolgte Datei – .begin/ bringt seine eigene .gitignore mit, sodass die des Repos unberührt bleibt.
4. Proxys werden als Proxys benannt. complexityProxy ist eine Anzahl von Entscheidungspunkten, keine Parse-Ausgabe. Verschachtelungstiefe wird aus der Einrückung gemessen. Sagen Sie das; waschen Sie keinen Proxy in eine Tatsache ein.
5. Eine verschlechterte Messung wird angekündigt, niemals stillschweigend verwendet. Der Scan gibt einen [!WARNING]-Block für einen flachen Klon, ein totes Churn-Fenster, verworfene Dateien, eine Sprache aus, die er überhaupt nicht parsen kann, oder eine Auflösung, die für eine, die er kann, fehlschlägt. Lesen Sie diesen Block vor der Tabelle und wiederholen Sie, was er sagt, in BEGIN.md. Ein Ranking, das auf einem defekten Graphen aufbaut, sieht genauso aus wie ein gutes – das ist die ganze Gefahr.

Führen Sie es aus

S=~/.claude/skills/begin/scripts

bash  $S/recon.sh      # wer/was/wann: PRs, Ihre Commits, Live-Bearbeitungen, Doks
node  $S/scan.mjs      # Struktur: Importgraph, Hotspots, Oberfläche->Engine

Beide schreiben in .begin/ und geben eine Zusammenfassung aus. Führen Sie sie von überall im Repo aus – der Scan verankert sich selbst im Repo-Root. recon.sh degradiert sauber ohne gh, ohne Netzwerk und ohne Remote, aber es benötigt node (Redaktion ist obligatorisch). Gemessene Warm-Cache-Zeiten: 259 Dateien 0,24 s · 3.384 Dateien 1,9 s · 2.809 Dateien 1,9 s · 1.819 Dateien 2,5 s · 1.397 Dateien 3,5 s. Die Dateianzahl sagt die Zeit nicht voraus; der Inhalt tut es.

Flags, die es wert sind, gekannt zu werden:

• --since "vor 90 Tagen" – Churn-Fenster (beide Skripte standardmäßig 90).
• --top 40 – wie viele Hotspots ausgedruckt werden sollen (Standard 25).
• --author "..." – ein regulärer Ausdruck. Sie brauchen es selten: Es standardisiert auf den user.name des Repos, und recon.sh greift auf den aktivsten Autor des Repos zurück und sagt dies, wenn Sie dort keine Commits haben. Das ist der normale Fall in einem Repo, das Sie gerade geklont haben.
• --exclude 'examples/**,site/**' – hält vendored Bäume und Dokumentationsseiten aus der Oberflächenzählung heraus. Muster sind an beiden Enden verankert, und die Anzahl der entfernten Dateien wird ausgegeben, da ein stiller Ausschluss später als fehlende Kante erscheint.
• --root VERZ – durchsucht ein anderes Repo.

Die Reihenfolge der Operationen – befolgen Sie sie genau

Diese in der falschen Reihenfolge zu tun, ist der Grund, warum ein Agent die falschen Dateien liest.

1. Aufklärung vor Struktur

Führen Sie recon.sh zuerst aus. Es beantwortet "Was hat diese Person gemacht?" – uncommittete Bearbeitungen, Branch-vs-Main-Commits, die letzten ~20 gemergten PRs mit ihren Bodies, und was jeder davon geändert hat. Das ist der Fokus-Priorität. Lesen Sie .begin/recon.md vollständig; es ist kurz.

Das uncommittete Diff ist normalerweise das informativste Ding im Repo – es ist die Frage, die der Benutzer gerade gedanklich hält. Recon kennzeichnet drei Dinge daran: Wenn der Baum sauber ist, sagt es das explizit (anstatt den Abschnitt wegzulassen und Sie suchen zu lassen); wenn das Diff nur aus Sperrdateien und Build-Ausgabe besteht, sagt es Ihnen, Ihre erste Lektüre nicht dort zu verbringen; und wenn Ihr Checkout hinter origin zurück ist, sagt es um wie viele Commits und nennt die Dateien aus aktuellen PRs, die nicht in Ihrem Baum sind.

Das Letzte ist eine Vorbedingung, kein Hinweis. Wenn recon meldet, dass Sie zurück sind, ist Schritt 3.2 unten unsicher: Die PR-Dateilisten beschreiben Code, den Sie nicht haben. Entweder git pull zuerst, oder überspringen Sie den PR-Leseschritt und sagen Sie in BEGIN.md, dass Sie das getan haben.

2. Struktur als Zweites

Führen Sie scan.mjs aus und lesen Sie .begin/scan.md, beginnend mit einem [!WARNING]-Block. Sie haben dann, gemessen statt angenommen:

• Oberflächen – jeder Ort, an dem ein Mensch oder Aufrufer das System tatsächlich berührt, gruppiert nach Art (web-page, ui-component, http-route, cli-command, mcp-tool, worker, public-api, migration, plus example, config und test, die Oberflächen sind, aber kein Produkt). Dies ist das UI-Ende der Karte.
• Hotspots – bewertet, mit einer why-Spalte, die den Begriff nennt, der jede Datei dorthin gebracht hat: depended-on, churn, complex oder recent. Eine Datei an der Spitze für churn ist ein anderes Tier als eine an der Spitze für depended-on; die Spalte sagt Ihnen, welches Gespräch zu führen ist.
• Oberfläche → Engine-Pfade – die buchstäbliche Importkette von einem Endpunkt oder einem Button bis zum schwierigen Teil, berechnet durch BFS. Ein Pfad, der eine faule await import()-Kante kreuzt, wird als solcher gekennzeichnet, da er zur Aufrufzeit und nicht zur Ladezeit aufgelöst wird.
• Importzyklusgruppen – stark verbundene Mengen über statische Wert- Kanten, mit einem echten gerichteten Zyklus, der ausgeschritten wurde. Nur-Typ- und faule (await import(...))-Kanten sind ausgeschlossen, da keines einen echten Initialisierungszyklus bildet.
• Nicht erreichbare Dateien – toter Code oder eine Oberfläche, die die Heuristiken übersehen haben. Entscheiden Sie was, und sagen Sie was.

2.5. Lesen Sie die Karte, die das Repo bereits für Sie geschrieben hat

Bevor Sie einen Hotspot öffnen, prüfen Sie auf AGENTS.md, CLAUDE.md, ARCHITECTURE.md oder pro-Verzeichnis READMEs – recon.md listet sie auf. Ein Repo, das eine Subsystem-Karte ausliefert, gibt Ihnen in dreißig Zeilen, was der Scan in zwei Sekunden ableitet und Prosa eine Stunde braucht, um zu rekonstruieren. Lesen Sie diese zuerst, dann verwenden Sie den Scan, um sie zu überprüfen: Dokumentation wird alt, der Graph nicht.

3. Lesen Sie nur, worauf die Messung hingewiesen hat

Lesen Sie in dieser Reihenfolge und hören Sie auf:

1. Das uncommittete Diff und die Commits des aktuellen Branches (was sie gerade tun).
2. Die Dateien, die von den 3–5 neuesten gemergten PRs geändert wurden (was sie gerade entschieden haben).
3. Die Top 8–15 Hotspots aus scan.md.
4. Gehen Sie für jeden der Top 3 seinen reachedVia-Oberflächen-Pfad nach innen, sodass Sie den vollständigen Pfad von der Benutzeraktion zur Engine angeben können.
5. README, die agentenorientierte Dokumentation aus 2.5 und jede Dokumentation, deren Überschrift mit einem Hotspot übereinstimmt.

Öffnen Sie keine Dateien außerhalb dieser Menge beim ersten Durchgang. Wenn etwas zu fehlen scheint, ist das ein Befund zum Melden, keine Lizenz zum Stöbern.

4. Überprüfen Sie, bevor Sie schreiben

Die Tabelle ist eine Menge von Hinweisen, keine Schlussfolgerung. Bevor jede Behauptung in BEGIN.md kommt:

• Öffnen Sie die Datei und bestätigen Sie, dass die Zeile, die Sie zitieren werden, das sagt, was Sie denken.
• Bestätigen Sie für einen Oberfläche → Engine-Pfad, dass der Import tatsächlich im Quelltext existiert.
• Bevorzugen Sie für alles Verhaltensbezogene einen Test, der es demonstriert, gegenüber einer Funktion, die so aussieht.
• grep Sie die heißen Pfade nach verschluckten Fehlern – catch {}, .catch(() => {}), as any, as never, verworfene Rückgaben. Fehler leben dort, wo Fehler weggeworfen werden, und diese sind der höchstwertige Befund, den Sie am ersten Tag zurückgeben können.
• Verbringen Sie mindestens einen Durchlauf damit, zu versuchen, Ihre Hauptbehauptung zu falsifizieren, nicht sie zu bestätigen. Die wertvollsten Sätze in einem guten BEGIN.md sind die, die dem Scan widersprechen.

Wenn der Scan in etwas falsch liegt, sagen Sie das in BEGIN.md und korrigieren Sie es. Eine Datei, die der Graph tot nennt, die aber tatsächlich über HTTP oder eine Warteschlange erreicht wird, ist das einzelne nützlichste Ding, das Sie aufzeichnen können, weil niemand sonst sie wieder finden wird. Deklarieren Sie solche Einstiegspunkte in .begin/surfaces.txt (ein Pfad pro Zeile, optional Pfad<TAB>Art) und der nächste Lauf wird sie als Oberflächen behandeln.

5. Schreiben Sie BEGIN.md

Verwenden Sie references/BEGIN-template.md und lesen Sie zuerst references/EXAMPLE-BEGIN.md, um sich zu kalibrieren – es ist ein echtes, kein Mock-up. Struktur, in der Reihenfolge:

1. Was dieses System in einem Absatz tut – in den Worten des Benutzers, nicht des Codes.
2. Der grundlegende Mechanismus – erste Prinzipien. Was ist die Kernumwandlung? Was ist die eine Idee, die den Rest offensichtlich macht? Was bricht ohne sie?
3. Oberflächen → Engine – eine Tabelle aus den Pfaden von scan.md, jede Zeile überprüft. Wenn keine Zeile eine Prozess- oder Netzwerkgrenze überschreitet, sagen Sie das explizit: In einem sprachübergreifenden Repo ist die eigentliche Naht normalerweise ein HTTP- oder Queue-Aufruf, den kein Importgraph sehen kann.
4. Die komplexen Teile, bewertet – Befund zuerst, Messung zuletzt. Jeder Eintrag benötigt eine Falle, die eine Datei:Zeile zitiert, die nicht bereits in seiner Messlinie ist. Ein Eintrag, dem Sie das nicht geben können, ist einer, den Sie nicht wirklich gelesen haben: löschen Sie ihn.
5. Entscheidungen und warum – jede verknüpft mit ihrem PR oder Commit, mit der Begründung aus dem PR-Body. Das ist es, was das Dokument zu einem Wissensgraphen macht, nicht zu einer Code-Tour.
6. Wo Sie aufgehört haben – oder, in einem Repo, das Sie nicht besitzen, wem es gehört und wo es wächst: die aktiven Autoren, was die neuesten offenen PRs hinzufügen, welche zuerst zu lesen.
7. Was die Maschinenschicht hier nicht sehen konnte – und offene Fragen, einschließlich der einzelnen Annahme, die die meiste tragende Arbeit leistet. Lassen Sie dies niemals aus.

Zeichnen Sie auch auf, wie man es ausführt und überprüft (die Skripte, die recon.md aus package.json extrahiert hat) und ein Glossar für jedes Wort, das dieses Repo überlädt. Beides ist, was ein Neuling zuerst braucht und was jede Code-Tour vergisst.

Verknüpfen Sie mit [[wiki-style]]-Ankern. Stempeln Sie jeden Abschnitt:

<!-- begin:section id="aufnahme" sha="0055f01" files="src/adapter.ts,src/identity.ts" -->

sha = git rev-parse --short HEAD in dem Moment, in dem Sie den Abschnitt abgeleitet haben (nicht der Commit, der später BEGIN.md hinzufügt). files = die Dateien, auf denen die Behauptungen des Abschnitts ruhen; Globs wie src/engine/** funktionieren. Ein Abschnitt mit keinem files= oder einem files=, der einen Pfad nennt, der nicht existiert, kann nie veralten und wird als nicht überprüfbar gemeldet – was der Fehler ist, den dieser Skill zu verhindern versucht, also machen Sie die Pfade richtig.

6. Machen Sie es lebendig

bash $S/install-hook.sh          # post-commit; --pre-push für den anderen Auslöser

Der Hook führt den Scan erneut aus und druckt eine einzeilige Notiz, die angibt, wie viele Abschnitte veraltet sind, mit Details in .begin/stale.md. Er respektiert core.hooksPath (husky) und git Worktrees, hängt an einen bestehenden Hook an, ohne ihn zu beschädigen, weigert sich, an einen Nicht-Shell-Hook anzuhängen, und berührt niemals eine verfolgte Datei. Entfernen Sie ihn mit --uninstall, der nur seinen eigenen Block entfernt.

/begin update

Wenn der Benutzer zu einem Repo zurückkehrt, das bereits eine BEGIN.md hat:

node $S/refresh.mjs && cat .begin/stale.md

Überschreiben Sie nur die veralteten Abschnitte, führen Sie recon.sh erneut aus, um Abschnitt 6 zu aktualisieren, und stempeln Sie jeden neu geschriebenen Abschnitt mit dem neuen HEAD-sha. Lassen Sie aktuelle Abschnitte byte-identisch – ein Update, das alles neu schreibt, zerstört sowohl das Gefühl des Lesers, was sich geändert hat, als auch die Nützlichkeit der Git-Historie.

Wenn es noch keine BEGIN.md gibt, ist /begin update einfach /begin: schreiben Sie eine.

Rückmeldung geben

Ein kurzer Absatz: der grundlegende Mechanismus, die eine oder zwei Dateien, die am meisten zählen, und warum, wo der Benutzer aufgehört hat, und die einzige Sache, die Sie nicht überprüfen konnten. Details leben in BEGIN.md, nicht in der Antwort.

Schließen Sie mit dem, was Sie nicht überprüft haben. Ein begin-Durchgang, der vollständige Abdeckung beansprucht, lügt.

Bekannte Grenzen – geben Sie diese an, übertünchen Sie sie nicht

• Der Importgraph ist statisch. Ein wörtliches import('./x') wird aufgelöst (und markiert als faul); ein berechnetes import(ausdruck), ein DI-Container oder ein Registry-Schlüssel, der durch eine Zeichenkette indiziert wird, erzeugt keine Kante, sodass eine solche Datei unerreichbar aussehen kann, obwohl sie lasttragend ist. In einem sprachübergreifenden Repo ist die Frontend↔Backend-Naht ein HTTP- oder WebSocket-Aufruf und ist konstruktionsbedingt unsichtbar. Der Scan kennzeichnet unerreichbare Dateien genau, damit ein Mensch urteilen kann.
• Vollständige JS/TS- und Python-Auflösung – tsconfig paths (jede Konfiguration im Baum, nicht nur die Wurzel), extends, Projekt references, NodeNext ./x.js → x.ts, und Python absolute, relative und Submodul-Importe gegen abgeleitete Wurzeln (gemessen bei ~98 % Rückruf und Präzision gegen einen CPython ast-Grundwahrheit). Go, Rust, Ruby, Java, Kotlin, Swift, PHP, C# und C/C++ tragen überhaupt keine Kanten bei. In einem solchen Repo zeigt jede Datei Wichtigkeit auf dem Boden an und erscheint "unerreichbar"; der Scan warnt, und Sie müssen diese Warnung wiederholen, anstatt einen leeren Graphen als Befund zu melden.
• complexityProxy zählt Entscheidungspunkte pro Sprache, in Code mit entfernten Kommentaren und einzeiligen Zeichenketten. Markup- und Schema-Dateien erreichen 0, konstruktionsbedingt; vendored, minified und generierte Dateien werden erkannt und separat bewertet. Mehrzeilige Template- Literale werden immer noch gezählt, sodass eine template-lastige Datei etwas heiß gelesen wird.
• Churn ist durch --since begrenzt, und ein flacher oder frischer Klon hat keinen – der Scan sagt das laut. Eine Datei, die vor zwei Jahren einmal neu geschrieben wurde, erzielt immer noch fast null Punkte und kann dennoch die wichtigste Datei im Repo sein.

Tests

node $S/test-scan.mjs                   # Graph, Zyklen, Oberflächen, Erreichbarkeit, Python
node $S/test-scan.mjs --mutate pyDotDot # ...und beweisen, dass die Assertionen rot werden können
bash  $S/test-living.sh                 # Veralterung, Hooks, Baum-Sauberkeit
node  $S/redact.mjs --self-test         # Geheimnisse gefangen UND sauberer Text unbeschädigt

Jede Assertion existiert, weil dieser Fehler echt war und einmal ausgeliefert wurde. Mutationen: alias, jsToTs, valueCycle, typeCycle, pyAbsolute, pyDotDot – jede muss ihre Assertion rot machen, und CI schlägt fehl, wenn eine es nicht tut.