Touch Map

Was macht Touch Map?

Erstelle eine mentale Landkarte dessen, was für diese Änderung berührt werden muss, um sie abzuschließen. Schreibe keinen Implementierungsplan. Schreibe keinen Code. Lade nicht die nächste Fertigkeit in einer Pipeline. Eine spätere Workflow-Fertigkeit reiht diese Landkarte mit anderen Fertigkeiten aneinander.

Die Landkarte ist das Produkt: die Teile und Dateien, die erforderlich sind, um die Änderung über die Ziellinie zu bringen.

Wann zu verwenden

Laden, nachdem der Benutzer entschieden hat, was die Änderung ist, und alle wie, die er bereits gewählt hat.

• Ausführen für: eine neue Funktion, eine Fehlerbehebung, ein Refactoring, das eine Grenze verschiebt.
• Überspringen: Tippfehler, Kommentare, Formatierung, nur Lockfile, Dokumentation ohne Code.
• Wenn die Absicht noch offen ist („X implementieren“ ohne gewähltes Verhalten): anhalten. Nachfragen, bis die Änderung festgelegt ist. Dann kartieren. Keine Funktion kartieren, die noch nicht gewählt ist.

Harte Tore

1. Kein Code und keine nächste Fertigkeit. Diese Fertigkeit kartiert. Sie plant keine Blöcke. Sie implementiert nicht.
2. Die Landkarte anzeigen und anhalten. Nicht auf Zustimmung warten. Der Benutzer unterbricht, wenn die Landkarte falsch ist.
3. coupling.json nicht lesen. Das ist eine spätere, separate Prüfung.
4. Nicht das gesamte Repo nach Hilfsfunktionen durchsuchen. Nur die Wiederverwendung aufzeichnen, die der Agent tatsächlich in den betroffenen Domänen gesehen hat. Eine spätere Fertigkeit besitzt die vollständige Suche.

Persistenter Atlas

Pfad: <repo>/.agent/domain-map.json

Im Repo committet. Nur Domänenkörnung. Funktionsnamen gehören nicht hierher.

{
  "version": 1,
  "domains": [
    {
      "id": "auth",
      "owns": ["packages/auth", "packages/auth-ui"],
      "talksTo": ["users", "sessions"]
    }
  ]
}

• id — kurzer Name, ein Wort oder kebab-case.
• owns — Paket- oder Ordnerpfade.
• talksTo — andere Domänen-IDs.

Diese Datei nur schreiben, wenn sich eine Tatsache auf Domänenebene geändert hat: eine Domäne hinzugefügt, entfernt oder umbenannt wurde; owns-Pfade; oder ein talksTo-Link. Das Hinzufügen einer Funktion innerhalb einer bestehenden Domäne darf diese Datei nicht bearbeiten.

Verfahren

Verfahren 1: Festgelegte Absicht bestätigen

1. Wenn die Änderung bereits klar ist (benannter Bug, benannte Funktion, benanntes Verhalten), fortfahren.
2. Wenn der Benutzer noch wählt, was er möchte, mit dem Kartieren aufhören. Nachfragen, bis die Absicht festgelegt ist. Dann hierher zurückkehren.

Verfahren 2: Atlas laden oder bootstrappen

1. Wenn .agent/domain-map.json existiert, lesen.
2. Wenn es fehlt, einen ersten Atlas erstellen, nur auf Domänenkörnung:
   • packages/* (oder die Paketordner des Repos) bevorzugen.
   • Sonst Ordner der obersten Ebene unter src/ (oder dem Hauptquellverzeichnis) verwenden.
   • talksTo aus Importkanten zwischen diesen owns-Pfaden festlegen.
   • Keine Funktionsnamen in den Atlas aufnehmen.
3. .agent/ erstellen, falls nötig. Die Datei schreiben. Den neuen Atlas im selben Durchgang anzeigen. Fortfahren. Nicht warten.

Verfahren 3: In diese Änderung hineinzoomen

1. Die betroffenen Domänen aus dem Atlas und der festgelegten Absicht auswählen.
2. Bei den Modulen beginnen, die eindeutig zur Änderung gehören.
3. Diese Dateien lesen. Importen nur folgen, solange sich die Liste der „zu bearbeitenden Dateien“ noch ändert.
4. Anhalten, wenn eine neu geöffnete Datei die Landkarte nicht verändert. Kein Paket vollständig lesen.
5. Teile als Module plus bestehende Funktionen und Typen benennen, die die Änderung verwenden wird oder neben denen sie liegen wird. Dateien sind Zeiger, nicht die Landkarte.
6. Tatsächlich in diesen Dateien gesehene Wiederverwendung notieren (Pfad + Symbol). Nicht den gesamten Workspace nach Hilfsfunktionen durchsuchen.

Verfahren 4: Den Pfad wählen, wenn mehr als einer existiert

Wenn nur ein ehrlicher Pfad existiert, diesen in einer Zeile angeben.

Wenn mehr als ein Pfad existiert, einen auswählen. Bei der ersten Leiterschrittstufe anhalten, die entscheidet:

1. Etwas Vorhandenes wiederverwenden, anstatt ein neues Modul zu schreiben.
2. Innerhalb der betroffenen Domäne(n) bleiben. Keine neue Domäne eröffnen.
3. Kein Paket, keine Schicht oder öffentliche API hinzufügen, wenn eine interne Änderung funktioniert.
4. Dann die wenigsten Dateien.

Den Gewinner nennen und welcher Schritt entschieden hat. Die wenigsten Dateien sind der Tie-Break, nicht die gesamte Regel. Neues Verhalten nicht in eine Gott-Datei stopfen, um bei der Dateianzahl zu gewinnen.

Verfahren 5: Atlas aktualisieren (nur Domänenebene)

1. Wenn diese Änderung eine Domäne hinzufügt, entfernt oder umbenennt oder owns- / talksTo-Werte ändert, .agent/domain-map.json im selben Durchgang patchen.
2. Wenn sich auf Domänenebene nichts geändert hat, die Datei in Ruhe lassen.

Verfahren 6: Die änderungsspezifische Landkarte anzeigen

Diese sechs Abschnitte in dieser Reihenfolge anzeigen. Keine aufgabenbezogene Markdown-Datei schreiben.

1. Betroffene Domäne(n) — aus dem Atlas.
2. Teile — Module plus bestehende Funktionen und Typen im Spiel. Gesehene Wiederverwendung einschließen (Pfad + Symbol).
3. Wie sie kommunizieren — nur Kanten, die diese Änderung verwendet (Aufrufe, Typen, Daten). Kein vollständiger Aufrufgraph. Ein Mermaid-Diagramm nur hinzufügen, wenn diese Kanten in Aufzählungspunkten schwer zu erkennen sind.
4. Zu bearbeitende Dateien — die Ziellinienliste. Dies ist das eigenständige Produkt.
5. Wird nicht bearbeitet — explizit. Verhindert Streifschuss-Bearbeitungen.
6. Pfadwahl — eine Zeile, wenn es einen Pfad gab. Bei mehreren: der Gewinner und der Leiterschritt.

Verfahren 7: Anhalten

1. Nach Verfahren 6 anhalten.
2. Keinen Code schreiben. Keine andere Fertigkeit von dieser aus laden.

Entscheidungsbaum

• Absicht nicht festgelegt → Verfahren 1, dann mit Kartieren aufhören, bis sie es ist.
• Absicht festgelegt, Verhaltensänderung → Verfahren 2 → 3 → 4 → 5 → 6 → 7.
• Tippfehler / Kommentar / Formatierung / Lockfile / Nur Dokumentation → diese Fertigkeit gilt nicht.
• Atlas-Datei fehlt → Verfahren 2 Schritt 2 (bootstrappen), dann fortfahren.
• Ein Pfad vs. viele Pfade → Verfahren 4.

Rote Flaggen

Signal	Was es bedeutet	Stattdessen tun
Kartieren, bevor der Benutzer die Funktion gewählt hat	Absicht nicht festgelegt	Verfahren 1. Erst ausfragen.
Jede Datei in owns öffnen	Tour, keine Landkarte	Verfahren 3: anhalten, wenn die Dateiliste stabil ist.
Das Monorepo nach isRecord durchsuchen	Vollständige Suche ist eine andere Fertigkeit	Nur bereits gesehene Wiederverwendung aufzeichnen.
coupling.json lesen	Falsche Datei	Diese Prüfung für später lassen.
Auf „sieht gut aus?“ bei der Landkarte warten	Tor ist anzeigen-und-anhalten	Die sechs Abschnitte anzeigen und anhalten.
Nach der Landkarte mit dem Codieren beginnen	Diese Fertigkeit kartiert nur	Verfahren 7. Kein Code.
Die nächste Pipeline-Fertigkeit von hier aus laden	Verlässt die Komposition im Workflow	Anhalten. Die Workflow-Fertigkeit soll aneinanderreihen.
.agent/touch-maps/<task>.md schreiben	Veralteter Aufgabenmüll	Nur Chat (oder Sitzung). Die Atlas-Datei ist die einzige Persistenz.
Atlas bearbeiten, weil ein Helfer hinzugefügt wurde	Funktionskörnung im Atlas	Atlas in Ruhe lassen. Den Helfer in Abschnitt 2 setzen.
Pfad mit den wenigsten Dateien zuerst wählen	Gott-Datei-Falle	Die gesamte Leiter durchlaufen.

Fehlerbehandlung

• Nicht in einem Git-Repo: Diese Änderung in den sechs Abschnitten kartieren. Die Atlas-Datei überspringen. Das in einer Zeile sagen.
• Atlas-JSON ist ungültig: Nicht raten. Den Parse-Fehler melden. Nur neu aus Verfahren 2 Schritt 2 erstellen, wenn der Benutzer zustimmt, oder das JSON korrigieren, wenn die Absicht offensichtlich ist (nachgestelltes Komma, fehlende Klammer).
• Betroffene Domäne ist unklar: Die kleinste Menge von Domänen wählen, die die Änderung besitzen kann. Den Zweifel in der Pfadwahl angeben. Keine neue Domäne für einen Ein-Datei-Bug erfinden.
• Benutzer unterbricht, dass die Landkarte falsch ist: Die sechs Abschnitte korrigieren. Verfahren 4 erneut ausführen, wenn sich der Pfad geändert hat. Dann anhalten.