AntwortenVeröffentlicht14 Quellen
Ein klares Repo braucht mehr als neue Ordner
Tests sollten grundsätzlich zentral liegen; bei Go können White Box Tests jedoch im getesteten Paket sinnvoll oder nötig sein. Spezifikationen halten den aktuell geltenden Vertrag fest, ADRs dokumentieren wichtige Entscheidungen und Tests prüfen Verhalten.
Veröffentlicht vonBilder erstellt mit GPT Image 2
Forschungsantwort
Wichtige Erkenntnisse
- Tests sollten grundsätzlich zentral liegen; bei Go können White Box Tests jedoch im getesteten Paket sinnvoll oder nötig sein.
- Spezifikationen halten den aktuell geltenden Vertrag fest, ADRs dokumentieren wichtige Entscheidungen und Tests prüfen Verhalten.
- Ein eingefrorener Plan ist nicht abgeschlossen: Er bleibt als unvollständig gekennzeichnet und braucht für die Wiederaufnahme eine erneute Prüfung.
- Temporäre Dateien lassen sich aufräumen – aber nicht, wenn dadurch der einzige Beleg für eine weiterhin genutzte Schlussfolgerung verschwindet.
![[GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W](https://d15bya8fi85z1v.cloudfront.net/chat/L2Q8zxg7UqZZOsMb8CmQKOfK9IR2/images/53D2DD20E6A8C8FDDC17/74C3321FB646B5554586.png)
KI-Prompt
openai.comCreate a landscape editorial hero image for this Studio Global article: [GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W. Article summary: <tool call {"name":"attempt completion","arguments":{"result":"这套布局可以作为收敛方向，但需要纠正三个等同关系：所有测试不能无条件迁出业务包，规范不是全部 ADR 的摘要，冻结也不是完成归档。以下是六项建议的明确边界；涉及的新路径均为候选，尚未创建或迁移。\n\n 1.. Topic tags: general web, openai, automation, workflow, code. Style: premium digital editorial illustration, source-backed research mood, clean composition, high detail, modern web publication hero. Use reference image context only for broad subject, composition, and topical grounding; do not copy the exact image. Avoid: logos, brand marks, copyrighted characters, real person likenesses, fake screenshots, UI text, readable text, watermarks, charts with fake numbers, clickbait thumbnails, icons, a
Eine übersichtliche Repository-Struktur hilft nur dann, wenn sie den Status von Arbeit und Wissen korrekt abbildet. Drei Gleichsetzungen führen dabei leicht in die Irre: Nicht jeder Test muss aus dem Quellcodeverzeichnis verschwinden, Spezifikationen sind keine Zusammenfassung sämtlicher ADRs, und ein eingefrorener Plan ist nicht abgeschlossen.
Die folgenden sechs Leitlinien verbinden eine klare Ablage mit den nötigen Ausnahmen. Neue Pfade sind als Vorschläge zu verstehen; sie wurden nicht automatisch angelegt oder migriert.
1. Tests zentral ablegen – mit begründeten Ausnahmen
Ein zentrales Testverzeichnis sollte der Standard sein, aber keine starre Regel für jedes Projekt. Bei Python bietet sich tests/ an. Vor einer Migration müssen jedoch Importe, Test-Erkennung, Fixtures und CI geprüft werden. Die CI-Konfiguration dieses Repositories verwendet bereits einen zentralen Testpfad.
Bei Go ist die Paketgrenze entscheidend: White-Box-Tests, die nicht exportierte Paketmitglieder prüfen müssen, können im Verzeichnis des getesteten Pakets bleiben. Black-Box-, komponentenübergreifende und End-to-End-Tests lassen sich dagegen bevorzugt zentral organisieren. Go baut Tests paketweise und unterstützt sowohl Tests im selben Paket als auch externe Testpakete.14
16
Zwei Regeln sollte man dabei nicht verwechseln: Die Importbeschränkung für internal-Pakete richtet sich nach der Verzeichnisstruktur oberhalb des internal-Ordners. Der Zugriff auf nicht exportierte Mitglieder ist eine eigene Paketgrenze.10
16 Deshalb sollte nicht pauschal verlangt werden, alle Go-Tests aus den Paketverzeichnissen zu verlagern – jedenfalls nicht, wenn dadurch White-Box-Abdeckung verloren ginge oder interne Zustände nur für Tests exportiert werden müssten.
Sinnvoll ist, dauerhaft benötigte Regressionstests mit dem Projekt zu versionieren. Einmalige Prüfskripte oder kurzlebige Experimente gehören dagegen in einen temporären Bereich. Ziel ist weniger unnötige Zersplitterung, nicht möglichst wenige Testdateien um jeden Preis.
2. Projektregeln, Spezifikationen und ADRs auseinanderhalten
specs/ sollte nicht als Sammelstelle für verallgemeinerte Inhalte sämtlicher ADRs verstanden werden. Die drei Ebenen erfüllen unterschiedliche Aufgaben:
| Ebene | Leitfrage | Typischer Inhalt |
|---|---|---|
| Globale Methodik | Wie wird analysiert, geprüft und geliefert? | Projektübergreifende Arbeitsweise |
Projekteinstieg AGENTS.md |
Wie wird in diesem Repository gearbeitet? | Bestätigte Projektregeln und wichtige Einstiege |
Projektspezifikationen specs/ |
Welches Verhalten und welche Verträge gelten jetzt? | Anforderungen, akzeptierte Entscheidungen und genehmigte Änderungen |
Entscheidungsprotokolle docs/adr/ |
Warum wurde eine bestimmte Lösung gewählt? | Architekturentscheidungen, Abwägungen und Alternativen |
Cline dokumentiert ein dauerhaftes Regelsystem für Anweisungen, die über einzelne Sitzungen hinweg gelten sollen.4 Daraus folgt aber nicht, dass Cline Dateien in einem bestimmten Spezifikationsverzeichnis automatisch anlegt oder aktualisiert. Eine solche Ablage wäre eine eigene Projektkonvention, keine hier belegte eingebaute Funktion.
Projektwissen muss weder vollständig manuell entstehen noch erst nach einem Problem mit der aktuellen Umsetzung festgehalten werden. Ein praktikabler Ablauf ist:
- Bei der Einrichtung können auf Grundlage von Anforderungen und Repository-Belegen erste Spezifikationen vorgeschlagen werden. Unbekanntes bleibt ausdrücklich offen.
- Vor einer Aufgabe werden die relevanten Spezifikationen und Entscheidungen gelesen; daraus entstehen Abnahmekriterien und passende Prüfungen.
- Ein neues ADR ist sinnvoll, wenn tatsächlich eine wichtige Abwägung ansteht. Gilt bereits eine dokumentierte Entscheidung, wird sie referenziert, statt für jeden Plan ein neues ADR anzulegen.
- Prüfergebnisse können zeigen, dass eine Umsetzung den Vertrag erfüllt – oder dass der Vertrag überarbeitet werden muss. Sie bestimmen nicht automatisch, welche Anforderungen gelten.
- Nach einer genehmigten Entscheidung wird die aktuell geltende Vorgabe in der passenden Spezifikation festgehalten. Das ADR liefert den Entscheidungsgrund, nicht eine vollständige Kopie der Historie.
Kurz gesagt: Spezifikationen halten den aktuellen Vertrag fest, ADRs begründen wichtige Entscheidungen und Tests prüfen Verhalten. Sie hängen zusammen, ersetzen einander aber nicht. Eine projektspezifische Erkenntnis sollte außerdem nicht ungeprüft zur globalen Regel werden.
3. ADRs an einem Ort sammeln, ohne die Entscheidungshistorie zu glätten
Für neue Architekturentscheidungen ist docs/adr/ ein klarer Standardpfad. Das ist eine sinnvolle Projektkonvention, muss aber nicht als einzig gültige Branchenlösung ausgegeben werden.
Ein nachvollziehbarer Entscheidungsprozess bewahrt nicht nur akzeptierte ADRs. Auch Vorschläge, abgelehnte Optionen und später ersetzte Entscheidungen können wichtig sein. Neue Aufgaben sollten einschlägige, weiterhin gültige ADRs wiederverwenden. Wird eine Entscheidung abgelöst, wird die Beziehung dokumentiert, statt die ursprüngliche Begründung nachträglich umzuschreiben.
Ein bestandener Test ist für sich genommen keine Genehmigung, ein ADR als akzeptiert zu markieren. Bei einer Migration müssen außerdem Verweise, Routings und Berechtigungsregeln angepasst werden – das bloße Verschieben von Dateien reicht nicht.
4. Pläne flach ablegen und „eingefroren“ von „abgeschlossen“ unterscheiden
Für eine überschaubare Zahl von Plänen kann ein flaches Verzeichnis wie plans/ genügen. Eine mögliche Benennung wäre:
| Zweck | Möglicher Dateiname | Bedeutung |
|---|---|---|
| Aktiver Plan | pending_implementation_plan.md |
Standard-Einstieg für die aktuell laufende Planung |
| Abgeschlossener Plan | plan-20261022-example-id.md |
Fertiggestellt und zur Ablage freigegeben |
| Eingefrorener Plan | plan-20261022-example-id-frozen.md |
Nicht abgeschlossen; vorerst nicht aktiv, offene Punkte bleiben dokumentiert |
Ein eigener Ordner oder ein zusätzlicher Status muss nicht sofort eingeführt werden. Der vorhandene Validator unterstützt bereits einen Pausenstatus; er kann zunächst auch für eingefrorene Pläne verwendet werden. Im Plan sollten dann Grund der Pause, offene Punkte und Bedingungen für eine Wiederaufnahme stehen.
Dabei gilt:
- Abgeschlossen und archiviert: Alle nötigen Abnahmekriterien sind erfüllt und die Ablage ist freigegeben.
- Eingefroren: Der Plan ist nicht mehr der aktive Einstieg, aber weiterhin unvollständig. Ungeprüfte Vorschläge werden dadurch nicht zu Tatsachen.
- Verworfen: Es wird ausdrücklich festgehalten, dass die Arbeit nicht umgesetzt wird und welche Folgen das hat. Das ist nicht dasselbe wie eine vorübergehende Pause. Ein eigener formaler Endstatus wäre eine separate Vertragsänderung.
Als Standard sollte nur der aktive Einstieg gelesen werden, nicht automatisch jedes historische Dokument im Verzeichnis. Eine Wiederaufnahme erfolgt gezielt auf Aufforderung: mit einem neuen, auf die Quelle verweisenden Ausführungsplan und erneuter Prüfung. Ein früherer grüner Status gilt nicht automatisch weiter. Das entspricht den geltenden Lebenszyklusregeln.
Auch das Umbenennen einer Datei belegt keine Abnahme. Vor dem Speichern müssen Überschreibungen verhindert, offene Punkte erhalten und Verweise berücksichtigt werden. Ein leeres Plan-Template nur deshalb anzulegen, damit ein fixer Einstieg existiert, ist nicht nötig.
5. Tests über Module und Verträge zuordnen – nicht Datei für Datei
Eine starre Eins-zu-eins-Zuordnung zwischen Quellcode und Testdatei ist selten hilfreich. Ein Test kann mehrere Komponenten abdecken; umgekehrt kann ein Modul Unit-, Property- und Integrationstests benötigen.
Als Ausgangspunkt bieten sich diese Regeln an:
tests/wird nach Modulen oder Zuständigkeiten gegliedert.- Die zugehörige Spezifikation hält wichtige Invarianten, relevante Test-Einstiege und begrenzte Prüfkommandos fest.
- Nur wenn die Zuordnung sonst schwer auffindbar ist, kommt eine zusätzliche Datei wie
tests/test-map.yamlinfrage.
Eine solche Karte sollte nur die nötigen Beziehungen enthalten: Modul- oder Vertragskennung, betroffene Quellcodebereiche, Testbereiche und Prüf-Einstieg. Sie sollte weder den gesamten Verzeichnisbaum kopieren noch Testergebnisse doppelt festhalten.
Als Pflegekriterium genügt zunächst, dass Pfade und Kommandos gültig bleiben. Eine vorhandene Zuordnung belegt weder ausreichende Abdeckung noch einen erfolgreichen Testlauf. So wird Übersicht geschaffen, ohne eine zweite, leicht veraltende Bestandsliste aufzubauen.
6. Temporäres aufräumen, ohne die Beweiskette zu zerstören
Ein Verzeichnis wie .scratch/ eignet sich für einmalige Entwürfe, kurzlebige Skripte und explorative Berichte. Daraus folgt aber weder, dass alles darin bloß zweitrangig ist, noch dass der gesamte Inhalt jederzeit gefahrlos gelöscht werden kann.
Eine Zusammenfassung aus einer Recherche ist beispielsweise eine Sekundärdarstellung und wird nicht allein dadurch zum Beleg. Umgekehrt kann ein echter Testlauf oder ein Diagnoseprotokoll auch in einem temporären Verzeichnis eine Primärquelle sein. Entscheidend sind Herkunft, Umgebung, Zeitpunkt und Vollständigkeit.
Wird ein temporäres Artefakt noch von einem Plan, einer Entscheidung oder einer Abnahme als einzigem Beleg herangezogen, sollte es nicht einfach gelöscht werden. Vor einer Bereinigung muss entweder das nötige Original erhalten bleiben oder die davon abhängige Schlussfolgerung ausdrücklich zurückgenommen werden. Verdichtete Erkenntnisse sollten außerdem ihre Belegstelle, ihren Geltungsbereich und offene Fragen behalten – eine knappe Zusammenfassung darf eine Annahme nicht als Tatsache ausgeben.
Auch alte Berichte und Architekturdiagramme in docs/ sollten nicht allein wegen ihres Alters pauschal als wertlos gelten. Hilfreich ist eine Unterscheidung zwischen aktuell gepflegten Dokumenten, ausdrücklich historischen Unterlagen und noch zu prüfendem Material:
- Aktuelle Dokumente nennen ihren Geltungsbereich und werden bei Änderungen am zugehörigen Vertrag überprüft.
- Überholte Diagramme und verworfene Entwürfe werden als historisch, überholt oder ersetzt markiert und gelten nicht standardmäßig als aktuelle Grundlage.
- Prozessmaterial ohne dauerhaften Nutzen und ohne offene Verweise kann nach Freigabe in den temporären Bereich verschoben oder gelöscht werden.
Aufbewahren und standardmäßig laden sind zwei verschiedene Dinge. Nötige Historie kann erhalten bleiben, ohne bei jeder Aufgabe gelesen zu werden. Gegen überladenen Kontext helfen gezieltes Lesen und klare Gültigkeitsmarkierungen – nicht das pauschale Löschen von Belegen.
Fazit: Ordnung braucht klare Statusregeln
Die vorgeschlagene Struktur ist ein guter Ausgangspunkt, wenn vier Grenzen ausdrücklich gelten: Tests werden zentral organisiert, soweit die jeweilige Sprache und Paketgrenze es zulassen; Spezifikationen halten den aktuellen Vertrag fest und fassen nicht alle ADRs zusammen; eingefrorene Pläne bleiben als unvollständig erkennbar; und beim Aufräumen werden keine weiterhin nötigen Belege vernichtet.
Die Standardpfade und erlaubten Pfade im Validator sowie der Bearbeitungsbereich für den Analysemodus sind derzeit noch an die bisherige Struktur gebunden. Eine spätere Migration muss Regeln, Vorlagen, Verweise, Validierung und die Anpassung an die jeweilige Laufzeit gemeinsam berücksichtigen. Ein Verzeichnis umzubenennen, reicht nicht aus, um eine neue Regel wirksam zu machen.
Die hier beschriebenen Punkte sind eine Analyse für eine mögliche Umstellung. In diesem Schritt wurden keine Projektdateien geschrieben, verschoben, eingefroren oder bereinigt.
Studio Global AI
Setzen Sie Ihre Recherche fort
Diese Seite enthält eine quellengestützte Antwort, die Sie in Studio Global fortsetzen können.
Die Leute fragen auch
Wie lautet die kurze Antwort auf „Ein klares Repo braucht mehr als neue Ordner“?
Tests sollten grundsätzlich zentral liegen; bei Go können White Box Tests jedoch im getesteten Paket sinnvoll oder nötig sein.
Was sind die wichtigsten Punkte, die zuerst validiert werden müssen?
Tests sollten grundsätzlich zentral liegen; bei Go können White Box Tests jedoch im getesteten Paket sinnvoll oder nötig sein. Spezifikationen halten den aktuell geltenden Vertrag fest, ADRs dokumentieren wichtige Entscheidungen und Tests prüfen Verhalten.
Was soll ich als nächstes in der Praxis tun?
Ein eingefrorener Plan ist nicht abgeschlossen: Er bleibt als unvollständig gekennzeichnet und braucht für die Wiederaufnahme eine erneute Prüfung.