Was macht TO-BE?
Finde die Ebenen, die eine Änderung berührt, stelle AS-IS und TO-BE für jede Ebene nebeneinander und verbinde die Ebenen mit durch Belege gestützten Pfeilen: "Dieses Feld fällt weg, also ändert sich diese Antwort, also verschwindet dies von (oder erscheint auf) diesem Bildschirm." Wenn sich der Code ändert, die Benutzeransicht aber gleich bleibt, ist dies die Schlussfolgerung. Erfinde keine Änderungen.
<skill> in den untenstehenden Befehlen ist das Basisverzeichnis dieses Skills: der Ordner, der diese SKILL.md enthält (~/.claude/skills/asis-tobe für eine benutzerweite Installation, <project>/.claude/skills/asis-tobe für eine projektweite). Ersetze es vor der Ausführung eines Befehls mit dem tatsächlichen Pfad.
Prinzipien
- Nebeneinander. AS-IS links, TO-BE rechts. Niemals vertikal gestapelt.
- Reale Artefakte vergleichen. Payloads gemäß 「실물 고르는 순서」 unten, Bildschirme aus echten Screenshots, Schemata aus echten Migrations- und Modelldiffs. Ohne das echte Artefakt: 「실물 없음: <이유>» ("kein reales Artefakt: "). Handgemachte Beispiele: 「예시(손으로 만듦)» ("Beispiel (handgefertigt)").
- Nur geänderte Ebenen zeichnen. Eine unveränderte Ebene erhält 「변경 없음» ("keine Änderung") plus eine Zeile Beleg. Keine leeren Tabellen.
- Jeder Pfeil hat einen Beleg. Ein
file:lineoder ein Commit pro Glied der Auswirkungskette. Ohne Beleg, markiere es als 「추정:» ("Schätzung:"). - Sage, wer noch die alte Spezifikation verwendet. Was nach der Auslieferung dieser Änderung noch alten Code ausführt: bereits im Store befindliche App-Builds, noch geöffnete Browser-Tabs auf der alten Seite, andere Dienste, andere Aufrufstellen wie ein Admin-Tool oder ein Bot. Dies bestimmt die Reihenfolge von Merge und Rollout.
- Zusammenfassung zuerst. Die Zusammenfassungsbox oben allein muss die Entscheidung stützen: ein einleitiger Schlusssatz in den Worten des Benutzers (keine Feldnamen oder Statuscodes), was sich für den Benutzer ändert, wie es ausgeliefert wird, ob es zurückgerollt werden kann; 3 Einträge oder weniger pro Gruppe. Direkt darunter beantworten drei Karten, was jeder Leser als Nächstes fragt, benannt nach der Frage und nicht nach einer Rolle: 「정해야 할 것» (was die Änderung im Namen von jemandem entschieden hat), 「먼저 볼 곳» (Umfang, die zuerst zu öffnenden Dateien, vom Code angenommene Prämissen), 「직접 확인하는 법» (Prüfpunkte, dann wie man es ausführt) — Regeln in references/document.md ("Frage-Karten"). Die beiden Dinge, von denen eine Entscheidung abhängt, das Abzeichen und das Rollback, sind die sichtbarsten Dinge auf dem ersten Bildschirm. Sage jede Tatsache einmal: Ein Satz, der bereits in der Schlussfolgerung oder der Warnung steht, wird nicht in der Einleitung, den Frage-Karten oder einem Szenario wiederholt. Alles darunter ist Belegmaterial. Falte lange Payloads und erschöpfende Tabellen in
<details>; lösche sie nicht. Keine Einleitung, Fortschrittserzählung oder Schlussbemerkungen. - Layout ist Inhalt. Bei 420px Breite darf die Seite nicht horizontal scrollen (nur Tabellen dürfen). Körperbreite auf 880px begrenzt; nur Tabellen und nebeneinanderliegende Vergleiche nutzen die volle Breite.
codeinnerhalb von Tabellen nur für Bezeichner; nur Dateipfade und Bezeichner sind in nichtproportionaler Schrift, koreanische Beschreibungen nie. Sätze um 70 Zeichen, Modifikatoren gestrichen. Zwei Farbschemata, umschaltbar durch einen Kippschalter über dem Titel: Standard Dusk, beige (AS-IS) und schieferblau (TO-BE); Bloom, pink (AS-IS) und mint (TO-BE). Folge nicht der systemweiten Dunkelmodus-Einstellung. Gestrichelte und durchgehende Linien begleiten immer die Farbe. Inline-Code-Hervorhebungen verwenden die hellen--a-mark,--b-mark, nicht die dunklen Chip-Farben. Einmal in jedem Schema und einmal bei 420px rendern. - Fachbegriffe, einmal erklärt. Verwende Wörter, die Entwickler, QA und Planer sofort verstehen. Im koreanischen Dokument verwende 레이어, 필드, API 스펙, 호출처, deprecated, breaking change, mock 응답, mit einer einfachen Erklärung in Klammern nur bei erster Verwendung (z.B. codegen(서버 스펙으로 자동 생성한 타입 파일) — "Typdateien, die automatisch aus der Serverspezifikation generiert werden"). Für internen Jargon (「AC」, erfundene Bildschirm-Spitznamen), gib bei erster Verwendung an, was es ist. Glossar: references/terms.md. Wenn ein Begriff dich blockiert, lies dort nach; überspringe diesen Schritt nicht.
Ebenen
| Ebene | Was vergleichen | Woher das reale Artefakt kommt |
|---|---|---|
| Daten (데이터) | Tabellen, Felder, Typen, Enums, Constraints, Indizes. Ein Entity-Diagramm nur der geänderten Entitäten und der Modellcode | Migrationen, ORM-Schema (prisma usw.), DDL-Diff |
| API-Spezifikation (API 스펙) | Request- und Response-Payloads, Events, Codegen-Typen. Hinzufügungen, Entfernungen, Typänderungen, semantische Änderungen pro Feld | OpenAPI-Diff, Response-DTOs, Test-Fixtures |
| Verhalten (동작) | Das Ergebnis, das Server und Client für dieselbe Eingabe erzeugen | Test-Assertion-Diff, Zustandsübergangscode |
| Bildschirm (화면) | Zwei Aufnahmen des Bildschirms im selben Zustand | Das Screenshot-Tool des Projekts (references/adapters.md, 「프로젝트 어댑터» ) |
| Benutzerauswirkung (사용자 영향) | Was Benutzer jetzt tun können oder nicht mehr tun können, Zahlen, die sich ändern. Enthält Zwischenzustände, die durch die Rollout-Reihenfolge verursacht werden | Issue-AC, die Summe der obigen Ebenen, Kompatibilitätstabelle |
Checklisten pro Ebene und häufige Fallstricke: references/layers.md.
Das reale Artefakt auswählen (실물 고르는 순서, API-Spezifikation)
Server-Test-Fixture > OpenAPI-Beispiel > aufgezeichneter echter Aufruf > Client-Mock-Antwort. Nimm das erste, das vollständig existiert. Wenn eine höhere Quelle nur teilweise ist (ein Fixture, das aus Variablen erstellt wurde, oder Tests, die die Anfrage inline aufbauen und Feld für Feld prüfen) und du einen echten Aufruf aufgezeichnet hast, zeige die höhere Quelle im Panel und den aufgezeichneten Aufruf als vollständigen Text, jeweils mit seiner Quelle beschriftet. Ein aufgezeichneter Aufruf enthält Werte, die bei jeder Ausführung variieren (IDs, Zeitstempel); vergleiche solche Payloads mit code_diff.py --mask id,time und gib dies in der Quellenzeile an, damit eine neue ID nicht als geändertes Feld gewertet wird. Ein Client-Mock (z.B. eine gefälschte Antwort für Screenshots) ist nicht das echte Artefakt des Servers. Schreibe den Pfad der gewählten Quelle unter die Payload. Wenn das Fixture aus Variablen ohne vollständiges JSON erstellt wurde, transkribiere es aus den erwarteten Werten des Tests, beschrifte es als 「예시(테스트 기대값에서 옮김)» ("Beispiel (aus Testerwartungen transkribiert)") und verwende … wo gekürzt. Fülle keine Felder aus, die in den erwarteten Werten fehlen; lasse sie als …. Wenn du einen Wert von woanders übernommen hast (eine Mock-Antwort usw.), notiere die Quelle neben diesem Feld.
Vorgehen
1. Den Umfang festlegen
- PR-Eingabe: Den Diff nach PR-Nummer abrufen (
gh pr diff <n> -R <repo>). Ein Pfad oder Branch allein ergibt einen gestapelten PR als Basis und mischt Änderungen anderer Personen ein. - Issue-Eingabe: Die PRs in jedem Repo finden (
gh pr list -R <repo> --search <key> --state all). Zwei oder mehr Repos gehen in ein Dokument. - Kein PR:
git diff <base>...HEADim Arbeitsbaum, mit<base>als dem Verzweigungspunkt, berechnet vom Repo-Root (lokalesmainist veraltet und mischt hunderte von Dateien ein):
Wenn der Diff Dateien enthält, die nichts mit dem Issue zu tun haben, ist die Basis falsch. Neu berechnen, bevor in Ebenen aufgeteilt wird.git fetch origin main git merge-base origin/main HEAD - Kein Remote: Das Fetch überspringen und die vom Benutzer genannte Basis nehmen, andernfalls den Commit, von dem aus die Arbeit begonnen wurde (
git merge-base main HEAD, oderHEADselbst für nicht-committete Arbeit). - Nicht-committeter Arbeitsbaum: AS-IS ist
HEAD, TO-BE ist der Arbeitsbaum.git diff HEADübersieht neue Dateien, also lies auchgit ls-files --others --exclude-standard. Wo immer ein Head-SHA abgefragt wird, schreibe 「커밋 전» ("nicht committet"). Mache keinen Commit, Stash oder Checkout, um den Vergleich durchzuführen. - Kein PR oder Issue: Das Ziel wird danach benannt, was es ist (「 작업 트리 변경» , 「 브랜치» ). Die Rollout-Tabelle erhält eine Zeile pro Einheit, die ausgeliefert wird (ein Branch, 「작업 트리 커밋» ) wobei die PR-Zelle dies benennt; der Issue-Key wird weggelassen, nicht erfunden.
- Pro Repo, schreibe eine Zeile
<repo> <kurzer Basis-SHA> → <kurzer Branch-SHA>. Verwende es wörtlich im Bericht. Im Dokument kommen PRs und SHAs einmal in der Rollout-Reihenfolge-Tabelle der Zusammenfassungskarte und der Basistabelle (references/document.md) vor, nicht in der Kopfzeile.
2. Geänderte Dateien Ebenen zuordnen
Jede Datei geht zu einer oder mehreren Ebenen; wenn unklar, öffne sie. Testdateien werden nicht zugeordnet; sie sind Belege für die Verhaltensebene (동작). Diese Tabelle entscheidet, welche Ebenenabschnitte das Dokument erhält; sie ist Arbeitsmaterial und wird nicht im Dokument gedruckt.
3. Zuerst entscheiden, ob sich der Bildschirm tatsächlich ändert
Selbst wenn sich Bildschirm-Code geändert hat, frage vor der Aufnahme: Ist der geänderte Branch mit den aktuellen Daten erreichbar? Wähle einen Wert, von dem der Branch abhängt, und finde heraus, ob der Server ihn tatsächlich produziert.
# Beispiel: Entfernt den Branch, in dem die App ein 「품절» ("ausverkauft")-Abzeichen anzeigte, wenn stockState === 'SOLD_OUT'
git -C <server repo> grep -n "SOLD_OUT" -- <source files> # setzt der Server diesen Wert irgendwo in eine Antwort?
git -C <app repo> grep -n "stockState" -- <generated types> # Werte, die der generierte Typ erlaubt
Kein Server-Code, der den Wert setzt (nur Typ- oder Enum-Definitionen), bedeutet unerreichbar, selbst wenn der generierte Typ ihn erlaubt. Notiere die file:line als Beleg für 「변경 없음» .
Wenn sich nur der Ort bewegt, der einen Wert berechnet (z.B. der Server-Fehler ERROR wird nun von der App als lastError berechnet), stelle beide Formeln mit ihrer file:line nebeneinander. Gleicher Wert für gleiche Eingabe: gleicher Bildschirm. Unterschiedlich: finde eine Eingabe, die einen anderen Wert ergibt und halte diesen Zustand fest.
- Erreichbar: in Schritt 4 erfassen.
- Unerreichbar: Die Bildschirmebene erhält 「현재 데이터로는 변경 없음: <이유와 근거>» ("keine Änderung mit aktuellen Daten: "). Notiere den verschwundenen Zustand unter 「실물 없음» und zeige sein altes Erscheinungsbild über die Teststrings, deren Assertions diesen Zustand überprüft haben. Wenn Bestätigung erforderlich ist, erfasse ein repräsentatives Szenario und zeige die Gleichheit mit md5.
- Unsicher: erfassen.
4. Reale Artefakte pro Ebene sammeln
- Daten: drei Teile, in dieser Reihenfolge.
- Entity-Diagramm, offen. Nur die geänderten Entitäten und die direkt daran hängenden, 6 oder weniger pro Seite. Schreibe sie als JSON und lasse das Skript beide Seiten als Inline-SVG zeichnen:
python3 -I <skill>/scripts/erd.py <spec.json>(das Spezifikationsformat steht im Kopf des Skripts). Zeichne das SVG niemals von Hand und lade keine Diagrammbibliothek; die Seite ist eigenständig. Das Skript markiert hinzugefügte, entfernte und geänderte Felder und Entitäten selbst durch den Vergleich der beiden Seiten, also schreibe jede Seite so, wie sie in diesem Commit wirklich ist. - Modellcode, gefaltet (
<details>): das Modell, wie es der Code hält (Struct, Klasse, ORM-Schema) in der Basis und jetzt. Ein Einzeilen-Diff pro Modell vonpython3 -I <skill>/scripts/code_diff.py <ASIS.txt> <TOBE.txt> --label "<name (path)>" --start-a <line> --start-b <line>; ein neues oder entferntes Modell verwendet/dev/nullfür die fehlende Seite. Das Skript berechnet die geänderten Zeilen und zeigt beide Ansichten (나란히 nebeneinander, 합쳐서 vereinheitlicht), damit der Leser wechseln kann; markiere Zeilen niemals von Hand. - Feldtabelle, gefaltet: was das Diagramm auslässt (Defaults, Constraints, Indizes, Behandlung vorhandener Zeilen).
Ein einzelnes geändertes Feld ohne Beziehung braucht kein Diagramm: eine Zeile in der Feldtabelle, offen angezeigt. Wenn AS-IS kein gespeichertes Schema hatte (im Speicher, eine Datei), gib dem Skript nur
tobemitasis_note, das sagt, wo die Daten lebten (file:line); der Modellcode ist dann der AS-IS-Beleg, also lasse dieses<details>offen. Die Migration, die die ersten Tabellen erstellt, ist TO-BE. Wenn dies nach einer bereits ausgelieferten Migration aufräumt, ist 「이미 반영()» ("bereits angewendet ()") das erste Glied der Auswirkungskette.
- Entity-Diagramm, offen. Nur die geänderten Entitäten und die direkt daran hängenden, 6 oder weniger pro Seite. Schreibe sie als JSON und lasse das Skript beide Seiten als Inline-SVG zeichnen:
- API-Spezifikation: die Payload vorher und nachher als Zeilendiff von
scripts/code_diff.py(dasselbe Skript wie für den Modellcode; ein Aufruf pro Payload,--context 3für lange,--mask id,timefür aufgezeichnete Aufrufe). Darunter필드 | AS-IS | TO-BE | 시맨틱 변경(Feld | AS-IS | TO-BE | semantische Änderung). Eine reine Namens- oder Typänderung fasst beide Zellen in einer Zeile zusammen:<code class="old">start_time</code> → <code class="new">starts_at</code>. Aufrufstellen:git grep <field>in jedem Repo, vom Repo-Root aus (ein Unterverzeichnis macht Pfade relativ und liefert 0 Treffer).- Auch in der veröffentlichten Version:
git grep -n <field> <sha>. Dessen Ergebnis entscheidet über Merge- und Rollout-Reihenfolge und das Abzeichen. Lies references/adapters.md ("Die veröffentlichte Version finden") bevor du dies tust. Muss: Nur ein SHA aus der Build-Liste ist bestätigt, andere sind 「추정:» ; wenn Quellen widersprüchlich sind, jeden SHA grep durchführen und jeden Treffer als 「배포된 앱이 읽는다» ("die veröffentlichte App liest es") zählen; niemals allein nach Tag-Namen wählen (Tags können zu einer anderen bereitstellbaren Einheit im selben Repo gehören). Leichter Rückfall, wenn die Build-Liste fehlschlägt (z.B. kein Login zum Build-Dienst): SHAs aus dem Issue oder den Release-Notes, sonst eine untere 「추정:» -Schranke. - Codegen-Ausgabe ist keine Aufrufstelle; sie wird aus der Serverspezifikation neu generiert. Notiere separat 「다시 뽑으면 무엇이 바뀌나» ("was sich ändert, wenn neu generiert").
- Grep auch das entfernte Feld in den Mock-Antworten und Test-Fixtures des Clients. Wenn es dort bleibt, kann die Typüberprüfung brechen, sobald das Codegen nach Auslieferung des Servers neu generiert wird. Liste diese Dateien als letzten Rollout-Schritt auf (「codegen 재생성과 fixture 정리» , "Codegen neu generieren und Fixtures bereinigen").
- Verhalten:
입력·상태 | AS-IS | TO-BE | 근거(테스트 이름)(Eingabe/Zustand | AS-IS | TO-BE | Beleg (Testname)). - Bildschirm: Lies references/screens.md ("Erfassen") vor dem Erfassen. Gleiches Szenario, Daten, eine Sprache und Größe auf beiden Seiten, in einem temporären Arbeitsbaum (Basis für AS-IS, Branch für TO-BE) oder, bei nicht-committeter Arbeit oder einem Repo, das du nicht anfassen darfst, in zwei Kopien außerhalb des Repos; Installation und Erfassung im Hintergrund, md5-Vergleich, dann, sobald Schritt 10 nachgemessen hat, was benötigt wird, die Server stoppen und den temporären Arbeitsbaum oder die Kopien entfernen (behalte sie, wenn der Benutzer die Reproduzierbarkeit des Laufs wünscht); committe sie niemals. Ohne Mock-Erfassungswerkzeug, führe die echte Version jedes Servers auf seinem eigenen Port aus und erfasse diese. Erfassungsbefehle pro Projekt: references/adapters.md. Überspringe die Erfassung nur, wenn die Plattform nicht erfasst werden kann (z.B. nativ) oder Schritt 3 den Branch als unerreichbar befunden hat; dann 「실물 없음: <이유>」 plus Test-Assertion-Strings. Wenn unsicher, erfasse.
4b. Die Szenario-Leiste füllen
Lies references/scenario-rail.md vor dem Füllen von 「시나리오별 전후」 . Zellennamen für andere Domänen: references/domains.md.
| Gerüst | Web/App ...