Anforderungsimplementierung (Ordnerstruktur + Protokoll)

Implementierung einer Anforderung (Ordnerstruktur + Protokoll)

Allgemeine Anweisungen, die anzuwenden sind, wenn mit der Umsetzung einer bereits analysierten Anforderung begonnen wird (nicht für die Analysephase). Rekonstruiert aus dem bereits in RV2-054-132-019_ Integration des ADG-Prozesses (CONSUBANCO) verwendeten Muster, wo es erstmals angewendet wurde. Diese Skill ist portabel: Sie gilt gleichermaßen unabhängig davon, in welchem Projekt/Kunden sie verwendet wird, gemäß der Verankerungsregel von §0.

0. Wo dies lebt (Portabilität zwischen Projekten)

Dieser Prompt geht weder von einem absoluten Pfad noch vom Namen eines bestimmten Kunden aus. Die Verankerungsregel, gültig in jedem Projekt, in dem sie verwendet wird:

• Es existiert immer ein Ordner, der alle Anforderungen dieses Projekts/Kunden gruppiert – der wörtliche Name kann variieren (Req\, Requerimientos\ oder ein anderer, den der Benutzer beim ersten Mal angibt, wenn an einem neuen Projekt gearbeitet wird) – und darin ein Unterordner pro Anforderung, benannt nach ihrem Code (z.B. RV2-054-132-019, manchmal gefolgt von _<Kurzname>, z.B. RV2-054-132-019_ Integration des ADG-Prozesses).
• Alles andere in diesem Dokument (README.md, Compartidos\, EchasXC\, SCRIPTS\...) ist relativ zu DIESEM Unterordner der spezifischen Anforderung, unabhängig vom Namen des darüberliegenden Container-Ordners. Es ist nicht nötig, jedes Mal nach dem Namen des Container-Ordners zu fragen – wenn im Projekt bereits einer existiert (Req\ oder Requerimientos\), diesen verwenden; wenn noch keiner existiert (neues Projekt), den Benutzer fragen, wie er ihn nennen möchte, bevor er erstellt wird.
• Eine neue und separate Anforderung (siehe §10) wird daran erkannt, dass sie einen eigenen Unterordner unter diesem Container-Ordner hat (oder benötigt), mit eigenem Code – sie wird niemals innerhalb des Ordners einer anderen, bereits existierenden Anforderung platziert, selbst wenn sie sich im selben Kunden/Modul befindet.

Konkreter Baum (alles von §1-§4 hängt direkt am Ordner der Anforderung, nichts lebt eine Ebene höher oder tiefer als in diesem Baum dargestellt):

Req\                                     (oder "Requerimientos\", der Name, den das Projekt bereits verwendet)
└─ RV2-054-132-019_ Integration ADG\     ← Ordner der Anforderung (§0), Anker für alles andere
   ├─ README.md                         ← §1, das Protokoll
   ├─ Compartidos\                      ← §2, User Stories/Bilder/Nachweise/Schlüssel
   ├─ EchasXC\                     ← §4, alles, was Claude generiert, was kein formales Arbeitsergebnis ist
   │  └─ SCRIPTS\                       ← §3, der ARBEITSORDNER von Claude (nicht das Stammverzeichnis)
   │     ├─ ORG\                       ← Rollback, eigene Nummerierung
   │     └─ MOD\
   │        ├─ ALTERS\                 ← nur Tabellen
   │        ├─ SP\                     ← nur Stored Procedures
   │        ├─ FN\                     ← nur Funktionen
   │        └─ VI\                    ← nur Sichten
   ├─ SCRIPTS\                          ← Stammordner, den der Benutzer kuratiert (§3), NICHT ohne Erlaubnis berühren
   ├─ Analisis_Impacto_[CÓDIGO].docx    ← Arbeitsergebnisse der Analysephase (falls angefordert)
   ├─ Estimacion_tiempos_[CÓDIGO].xlsx
   └─ Plan_Implementacion_[CÓDIGO].docx

1. Änderungsprotokoll – README.md im Stammverzeichnis des Anforderungsordners

Eine einzige, lebendige Datei, die jedes Mal aktualisiert wird, wenn etwas erstellt/geändert wird, eine ausstehende Frage geklärt oder hinzugefügt wird oder sich der Status von etwas ändert. Feste Struktur:

• Überschrift mit Code und Namen der Anforderung + "Letzte Aktualisierung: YYYY-MM-DD".
• Was ist das – Zusammenfassung von 2-4 Zeilen der Anforderung.
• Allgemeiner Status – was bereits erstellt ist – ein Aufzählungspunkt pro Phase/Modul, markiert als erstellt / teilweise / ausstehend.
• Architektur (wo sich jedes Teil befindet) – Pfade von Bildschirmen, wichtige SPs (mit ihren Flags), Jobs, wichtige Tabellen, Konfigurationsdateien. Datenbankzugriff (Server, Datenbankname, Benutzer und Passwort) wird weder hier noch in einer anderen Datei dokumentiert – es ändert sich je nach Portal/Projekt, und der Benutzer gibt es bei Bedarf zusammen mit dem Passwort an (siehe §7).
• Ausstehendes – unterteilt in "Fragen an den Kunden" (bei Klärung mit ~~text~~ durchstreichen, nicht löschen) und "Ausstehende Entwicklung".
• Änderungsprotokoll – ein Eintrag pro Sitzung/Datum (**YYYY-MM-DD (kurzer Titel)**), aktuellster zuerst, mit: welcher tatsächliche Fehler/Bug gefunden wurde, was entschieden wurde und warum, welche Dateien geändert wurden, was der Benutzer noch tun muss (Skript ausführen, neu kompilieren, auf dem Bildschirm testen).

Ersetzt nicht Analisis_Impacto_[CÓDIGO].docx oder Plan_Implementacion_[CÓDIGO].docx (dies sind Arbeitsergebnisse der Analysephase) – dieses README ist der Live-Status der Erstellung.

Rotation bei zu starkem Wachstum – wenn README.md sich ~200KB nähert oder überschreitet, die älteren Sitzungen archivieren, bevor weitere hinzugefügt werden (bereits eingetretener Fall: Ein README.md überschritt 256KB und das Lesetool konnte es nicht mehr öffnen). Mechanik: Die älteren Protokolleinträge in eine neue Datei README_historico_YYYY.md verschieben (eine pro Jahr oder nach Bedarf), wobei im aktiven README.md nur die ~10-15 aktuellsten Sitzungen + eine Zusammenfassung von 2-3 Zeilen des Archivierten verbleiben (um die Kontinuität beim Lesen nur des Aktiven nicht zu verlieren). Die anderen Abschnitte (Was ist das, Allgemeiner Status, Architektur, Ausstehendes) werden niemals archiviert, sie leben immer im Aktiven – nur das Sitzungsprotokoll rotiert.

2. Ordner Compartidos\

Alles, was Input oder gemeinsam genutzter Nachweis mit dem Kunden/externen Lieferanten ist, kein Code: User Stories und ihre Anhänge, aus dem Dokument extrahierte eingebettete Bilder/Screenshots, Schlüssel (PGP/Zertifikate), Datenzuordnungsdateien, erhaltene oder an Dritte gesendete Testdateien (z.B. CDC).

Wenn ein Dokument in Compartidos\ erscheint, dessen Thema nicht zur aktuellen Anforderung passt (z.B. eine User Story über "Logs/Prüfung" im Ordner "Integration des ADG-Prozesses"): Keine der beiden einfachen Schlussfolgerungen ziehen – weder als Nachweis dieser Anforderung behandeln, nur weil es dort ist, noch ignorieren/verschieben auf eigene Faust. Den Benutzer fragen, welcher dieser drei Fälle zutrifft:

• Falsch platziert – gehört in einen anderen Ordner, wurde versehentlich kopiert.
• Neue und separate Anforderung, die noch keinen eigenen Ordner hat – einen mit dieser gleichen Struktur erstellen, und falls sie Datenbankobjekte/Bildschirme mit der aktuellen teilt, in "Verwandte Anforderungen" beider dokumentieren (§10).
• Satz von absichtlich in einem Kundenordner gruppierten Anforderungen (es gibt einen Präzedenzfall dieses Musters in der E-Mail-Vorlage für den QA-Übergang, die explizit einen "Satz von Anforderungen" vorsieht) – wenn ja, bestätigen, ob trotzdem ein Unterordner pro Code sinnvoll ist.

3. Skript-Ordner – SCRIPTS\ORG\ und SCRIPTS\MOD\

Es gibt zwei verschiedene SCRIPTS-Ordner im Anforderungsordner: <Anforderung>\SCRIPTS\ (Stamm) und <Anforderung>\EchasXC\SCRIPTS\. Der Arbeitsordner, in dem Claude jedes Skript ablegt, während er es erstellt, ist EchasXC\SCRIPTS\. Den Stammordner SCRIPTS\ kuratiert der Benutzer manuell, indem er aus EchasXC\SCRIPTS\ übernimmt, wenn er der Meinung ist, dass etwas fertig ist – diesen Stammordner nicht berühren, es sei denn, der Benutzer fordert es ausdrücklich an.

MOD\ – ein Unterordner pro Objekttyp, nicht gruppiert, jeder mit einer eigenen und unabhängigen fortlaufenden Nummerierung (sie teilen keine Nummerierung untereinander):

• MOD\ALTERS\ – nur Tabellen (CREATE TABLE / ALTER TABLE).
• MOD\SP\ – nur Stored Procedures.
• MOD\FN\ – nur Funktionen (CREATE FUNCTION).
• MOD\VI\ – nur Sichten.
• Wenn ein Objekttyp erscheint, der keinen dedizierten Ordner hat (Index, Trigger, Job usw.), den Benutzer fragen, wie der Ordner heißen soll, anstatt anzunehmen, wohin er gehört, oder ihn in den zu packen, der "ähnlich aussieht". (Bereits einmal gemachter Fehler: Eine Funktion wurde zuerst in SP\, dann in ALTERS\ abgelegt, bis der Benutzer die Erstellung eines dedizierten FN\ forderte.)
• Namensmuster für alle: Bereits existierendes Objekt, das geändert wird → N_NAME_MOD.sql; vollständig neues Objekt (existiert nicht in der Datenbank) → N_NAME_NEW.sql.

ORG\ – Rollback der Objekte, die geändert werden (die _NEW haben hier kein Gegenstück: Das Rollback von etwas Neuem ist einfach dessen Löschung, es gibt nichts Vorheriges zu erfassen). Vor dem Berühren eines existierenden Objekts dessen aktuelle Definition so extrahieren, wie sie heute in der Datenbank lebt, und hier speichern – diese Datei IST das Rollback.

• ORG\ IST KEIN numerisches Spiegelbild von MOD\. Es ist leicht, dies anzunehmen, und es ist falsch – sie haben eine unabhängige Nummerierung. Es kann sogar innerhalb seiner selbst nach Kategorie nummeriert werden (z.B. ein konsolidiertes Rollback aller MOD\ALTERS in einem einzigen Durchgang unter Beachtung von Abhängigkeiten und separat ein Rollback für jeden berührten SP). Das Nummerierungsschema von ORG\ mit dem Benutzer bestätigen, bevor angenommen wird "gleiche Nummer wie in MOD" – dies wurde bereits einmal korrigiert, weil es falsch angenommen wurde.
• Jedes Mal, wenn ein Objekt berührt/bereitgestellt wird, den Benutzer explizit darüber informieren, welches es ist (Name), damit klar ist, was bewegt wurde.

Allgemeine Regeln für jedes Skript in diesem Abschnitt:

• DDL immer idempotent (IF NOT EXISTS / COL_LENGTH(...) IS NULL).
• Ein neuer SP, der einen anderen neuen SP aufruft, wird in derselben Datei/demselben Batch wie seine Abhängigkeit definiert, niemals in einer späteren Dateinummer.
• Wenn später inkrementelle Skripte "vereinheitlicht"/bereinigt werden (später über separate ALTER hinzugefügte Spalten, die zurück in das ursprüngliche CREATE gefaltet werden): Das Sicherungs-ALTER bleibt trotzdem unter dem bereits vollständigen CREATE (beide Wege koexistieren, es wird nicht einer gewählt); das entsprechende ORG muss nicht geändert werden, wenn es bereits ein vollständiges DROP des Objekts durchführt – wenn es ein spaltenweises Rollback durchführt, die Reihenfolge überprüfen (Indizes/Constraints werden vor dem Berühren der Spalte im Rollback gelöscht, nach dem Festlegen der endgültigen NULL-Zulässigkeit im Erstellungsvorgang wiederhergestellt).

4. Arbeitsmaterial, das kein Arbeitsergebnis ist – EchasXC\

Alles, was Claude zur Unterstützung der Erstellung generiert, aber nicht formal an den Kunden oder das Team ausgeliefert wird (Validierungsabfragen, manuelle Tests, technische Blätter, E-Mail-Entwürfe): Es kommt in einen Unterordner EchasXC\, getrennt von Compartidos\ und den formalen Arbeitsergebnissen.

5. Kodierung – auf keinen Fall die bereits in der Datei etablierte Kodierung ändern

Vor dem Bearbeiten einer Datei mit Akzenten (.aspx/.aspx.vb/.master/Skripte usw.) nicht annehmen, dass es UTF-8 ist, nur weil sie es deklariert oder weil file es so meldet. Einige alte Dateien von Legacy-Portalen sind intern tatsächlich ISO-8859-1/Windows-1252 (Akzente als einzelne High-Bytes), und der Standard-Edit/Write dekodiert/überschreibt die GANZE Datei als UTF-8 – jeder vorher existierende Akzent in der gesamten Datei (nicht nur in der Nähe der Bearbeitung) wird in Müll umgewandelt (U+FFFD, erscheint als "�" oder ähnlich im Browser), still und permanent, sobald gespeichert wird.

• Tatsächliche Kodierung vor dem Berühren einer solchen Datei überprüfen (file datei.aspx, und Achtung: Eine bereits zuvor beschädigte Datei kann "UTF-8" sauber melden, ohne es tatsächlich zu sein).
• Wenn es ISO-8859-1 ist, über PowerShell mit [System.Text.Encoding]::GetEncoding("ISO-8859-1") bearbeiten – Roh-Bytes mit dieser Kodierung dekodieren, im Speicher ersetzen, mit derselben Kodierung neu schreiben. Niemals mit dem Standard-Edit/Write-Tool bei einer Datei mit diesem Verdacht.
• Nach JEDER Bearbeitung überprüfen, nicht nur vorher: Wenn das Repo Git hat, git diff --stat sofort danach – eine deutlich höhere Anzahl von Löschungen als das, was geändert werden sollte, ist das Zeichen für Korruption, nicht die erwartete Bearbeitung. Ohne Git, Dateigröße vorher/nachher vergleichen.
• Wenn es bereits versehentlich beschädigt wurde: Mit git checkout -- datei rückgängig machen (stellt die ursprünglichen intakten Bytes wieder her), bevor mit der korrekten Methode neu versucht wird – verlorene Akzente können nach dem Überschreiben nicht wiederhergestellt werden.
• Für neue Dateien, die Claude erstellt (nicht bearbeitet): Ja, explizite UTF-8-BOM verwenden, wenn das Projekt es erfordert (mit dem Benutzer bestätigen, ob dies zutrifft).

6. Allgemeine Haltung – wie ein Senior handeln, niemals etwas als gegeben betrachten

Nicht annehmen, dass etwas "so funktionieren sollte", dass sich ein Muster genauso wie woanders wiederholt oder dass ein Datum/Schema dem entspricht, was das Gedächtnis oder die oberflächliche Lesart vermuten lässt. Den tatsächlichen Prozess IMMER validieren:

• Gegen die tatsächliche Datenbank (DEV), bevor Schema, Daten oder Verhalten behauptet werden – nicht annehmen, abfragen.
• Gegen den tatsächlichen Code (grep/Datei lesen), bevor behauptet wird, was ein Bildschirm/SP tut – sich nicht auf den Namen oder den ersten Eindruck verlassen.
• Gegen die User Story/das Dokument der Anforderung, bevor etwas hinzugefügt wird, das "notwendig erscheint" – wenn es nicht explizit da ist, wird es nicht aus Trägheit erstellt.
• Das Ergebnis jeder Änderung validieren (SET PARSEONLY ON, git diff, Testausführung), bevor es als abgeschlossen betrachtet wird, anstatt anzunehmen, dass es gut kompiliert/ausgeführt wurde, weil die Logik korrekt erscheint.

7. Ausführungsregeln gegen die Datenbank (gilt für alles, nicht nur DDL von Skripten)

• Niemals INSERT/UPDATE/DELETE/DDL gegen die Datenbank ausführen, weder in DEV noch mit expliziter Bestätigung im Chat. Der Benutzer führt selbst alles aus, was er in die Datenbank schreibt; Claudes Rolle ist es, das Skript vorzubereiten und, nachdem der Benutzer es ausgeführt hat, mit SELECT zu validieren, dass alles wie erwartet ist. Dies ist unabhängig von der Ordnerregel ORG/MOD – es gilt auch für Kataloge, Testdaten, jede Art von Schreibzugriff.
• Nur-Lese-Abfragen (SELECT, INFORMATION_SCHEMA, sys.sql_modules) sind frei, ohne jedes Mal um Erlaubnis zu bitten.
• Server, Datenbankname, Benutzer und Passwort der Datenbank werden in keiner Datei dokumentiert (README.md, Compartidos\, .sql-Skripte, Code-Kommentare) – der Name der spezifischen Datenbank ändert sich je nach Portal/Projekt, daher gibt es keinen festen Wert, den es wert wäre, schriftlich festzuhalten. Der Benutzer gibt sie im Chat, wenn sie benötigt werden, zusammen mit dem Passwort, und sie werden nur über Umgebungsvariablen im Befehl dieser Sitzung verwendet – beim nächsten Mal neu anfordern, nicht speichern, "um nicht noch einmal fragen zu müssen". Wenn bereits ein Passwort/eine Verbindung vorhanden ist...