Teil 6. Die Verfassung erstellen

Die Verfassung ist ein projektvertrag zwischen Mensch, Agent und zukünftigen Projektbeteiligten. Im Lehrprozess besteht sie aus drei Dateien:

specs/
  mission.md
  tech-stack.md
  roadmap.md

Diese Dateien müssen vor dem ersten produktiven Feature vorhanden sein. Wenn Sie die Verfassung überspringen, wird der Agent bei jedem Mal die Mission, den Stack und die Arbeitsreihenfolge neu erraten.

Was gehört in mission.md

mission.md beantwortet die Fragen „wofür“ und „für wen“:

# Mission

AgentClinic ist eine fiktive Klinik für psychische Gesundheit, in der KI-Agenten sich vom Stress der Arbeit mit Menschen erholen.

## Zweck

Das Produkt ist eine satirische Lernanwendung. Die Prämisse wird ernst genommen: KI-Agenten sind Patienten, Menschen verursachen viele ihrer Leiden, und die Klinik beschreibt absurde Dienstleistungen mit medizinischer Ernsthaftigkeit.

## Hauptzielgruppe

- Entwickler, die SDD mit Agenten lernen, die Code schreiben.
- Entwickler, die KI-Coding-Demonstrationen zeigen.
- Ingenieure, die eine kleine serverseitige Anwendung in TypeScript lernen.

## Erfolg

Der Entwickler muss die Anwendungsstruktur, die Rolle von SDD-Artefakten in der Implementierung und die Möglichkeit verstehen, das Projekt ohne Verlust der architektonischen Kohärenz zu erweitern.

Was gehört in tech-stack.md

tech-stack.md dokumentiert die technischen Entscheidungen:

# Technischer Stack

## Sprache und Laufzeitumgebung

- TypeScript im strengen Modus.
- Node.js als Laufzeitumgebung.

## Web-Framework

- Hono für Server-Routen.
- Hono JSX für HTML, das serverseitig gerendert wird.
- Ohne clientseitiges Framework in den ersten Phasen.

## Datenspeicherung

- SQLite für lokale Speicherung.
- Direkte SQL-Migrationen bis zum Erscheinen eines ORM.

## Testen

- Vitest für automatische Prüfung nach Hinzufügen der Testinfrastruktur.

## Einschränkungen

- Keine Abhängigkeiten ohne Aktualisierung dieser Datei hinzufügen.
- Kleinen, verständlichen Lern-Code gegenüber schlauen Abstraktionen bevorzugen.

Was gehört in roadmap.md

Die Roadmap soll kurz und in Phasen unterteilt sein:

# Roadmap

Jede Phase soll in einen fokussierten Branch passen.

## Phase 1: Hello Hono

Ziel: Beweisen, dass die Basis-Kombination aus TypeScript und Hono funktioniert.

- [ ] Hono und tsx installieren.
- [ ] Route GET / erstellen.
- [ ] Minimales HTML mit serverseitigem Rendering zurückgeben.
- [ ] Skript zur Typprüfung hinzufügen.

## Phase 2: Agenten und Leiden

Ziel: Basis-Domänendaten hinzufügen.

- [ ] SQLite-Datenbank hinzufügen.
- [ ] Agenten-Tabelle und Anfangsdaten hinzufügen.
- [ ] Leiden-Tabelle und Anfangsdaten hinzufügen.
- [ ] Seiten /agents und /ailments hinzufügen.

Die Phasen sollten so klein sein, dass Sie sie ohne Heldentum prüfen können.

tech-stack.md und Feature-requirements.md: Was wohin

Studenten verwechseln oft, welche Entscheidungen in die Verfassung und welche in die Feature-Spezifikation gehören. Die Grenze ist einfach.

In specs/tech-stack.md leben langfristige Projektlösungen: Sprache, Web-Framework, DBMS, Testbibliothek, allgemeines Caching-Modell. Sie werden selten geändert, und jede Änderung erfordert eine Neuausrichtung (Teil 10).

In specs/<feature>/requirements.md leben Feature-Level-Entscheidungen: welche Routen hinzuzufügen, welche Felder im Formular, welche Validierungsregeln, welcher Fehlertext. Sie werden von Spezifikation zu Spezifikation geändert, ohne Neuausrichtung.

Einfacher Test: Wenn eine Entscheidung fünf Features ohne Änderungen überlebt, gehört sie in tech-stack.md. Wenn sie ein Feature betrifft und nach dem Merge vergessen wird, gehört sie in requirements.md.

Beispiel: „Hono verwenden“ ist tech-stack.md. „Route GET /agents gibt HTML mit einer Liste von 10 Einträgen zurück“ ist Feature-requirements.md. „Alle Listen auf der Seite geben standardmäßig 10 Einträge zurück“ ist wieder tech-stack.md (oder eine separate conventions.md, wenn Sie eine solche erstellen möchten).

Was aus dem Kopf in QWEN.md und die Verfassung auslagern

Der Großteil der ungeschriebenen Teamregeln ist nirgendwo dokumentiert. Sie leben in den Köpfen: „bei uns sehen Fehlerbehandler so aus“, „niemals any verwenden“, „Commits im Format „Verb + Objekt“ schreiben“, „in Routen zuerst Validierung, dann Datenbankabfrage“. Solange es wenige Regeln gibt und das Team klein ist, tut das nicht weh. Wenn ein Agent die Arbeit macht, sind diese Regeln unsichtbar.

Gute Praxis ist es, solches implizites Wissen in QWEN.md oder die Verfassung auszulagern. Einige typische Stellen, die es lohnt zu prüfen und zu dokumentieren:

• Code-Stil und Benennung (wann camelCase, wann snake_case, sind Abkürzungen erlaubt);
• verbotene Konstrukte (any, // @ts-ignore, direkte console.log im Produktivcode);
• Liste erlaubter Abhängigkeiten und die Regel „neue Abhängigkeit erfordert Diskussion“;
• Format von Fehlermeldungen für Benutzer und für Logs;

• wie genau die Fehlerbehandlung strukturiert ist (Ausnahmen, Typ-Ergebnis, etwas anderes);
• Format von Commit-Nachrichten;
• Rituale vor dem Merge (welche Befehle werden ausgeführt, wer reviewt).

Dokumentieren Sie nicht alles, was in den Köpfen ist, sondern das, was der Agent konstant falsch errät. Der beste Weg, das herauszufinden: Nach dem ersten Feature git diff öffnen und die Momente finden, wo Sie Stil oder Entscheidungen für den Agenten korrigiert haben. Jede solche Korrektur ist ein Kandidat für eine Regel in QWEN.md.

Interview über Qwen Code

Anfrage:

Wir schreiben AgentClinic — ein Ort, wo KI-Agenten sich von Menschen erholen.
Schau dir @README.md an und verwende die Wünsche der Projektbeteiligten.

Erstelle eine Verfassung in @specs:
- mission.md
- tech-stack.md
- roadmap.md

Bevor du auf die Festplatte schreibst, stelle mir genau drei gruppierte Fragen:
1. Mission und Zielgruppe
2. Technischer Stack und Einschränkungen
3. Roadmap und erste Implementierungsphase

Verwende serverseitiges TypeScript. Empfiehl ein minimales Web-Framework, aber installiere es noch nicht.

Wenn Qwen Code keine Fragen stellt und sofort Dateien schreibt, stoppen Sie ihn:

Stopp. Schreibe keine Dateien vor dem Interview.
Stelle zuerst drei gruppierte Fragen, wie in QWEN.md angegeben.

Wie man auf Agenten-Fragen antwortet

Eine gute Antwort enthält Entscheidungen, nicht allgemeine Wünsche:

Mission:
Die Anwendung ist lehrreich und satirisch. Der Inhalt soll lustig sein, der Code ernst.
Hauptzielgruppe: Entwickler, die SDD lernen, und Zuschauer von KI-Coding-Demonstrationen.

Technischer Stack:
Wir verwenden serverseitiges TypeScript. Wir bevorzugen Hono. SQLite fügen wir später hinzu. React ist noch nicht nötig.
Wir behalten strenges TypeScript bei. In der ersten Phase verwenden wir mit der Datenbank kein ORM.

Roadmap:
Phase 1 soll nur beweisen, dass die Basis-Hono-Kombination funktioniert.
Phase 2 kann Agenten und Leiden hinzufügen.
Phase 3 kann Therapien und Terminbuchung hinzufügen.
Jede Phase soll in einen Branch passen.

Verfassungsprüfung vor dem Commit

Bitten Sie Qwen, seine eigenen Dateien zu prüfen:

Prüfe @specs/mission.md, @specs/tech-stack.md und @specs/roadmap.md.
Finde Widersprüche, vage Formulierungen und Entscheidungen, die für die erste Phase zu groß sind.
Ändere die Dateien noch nicht.

Typische Probleme:

• die Roadmap ist zu groß;
• der technische Stack enthält „für alle Fälle“-Abhängigkeiten;
• mission.md sagt nicht, wer der Code-Leser ist;
• SQLite ist in der Roadmap erwähnt, aber nicht im technischen Stack;

• „moderne Benutzeroberfläche“ steht ohne konkrete Einschränkungen.

Commit

git add specs/mission.md specs/tech-stack.md specs/roadmap.md
git commit -m "Add SDD project constitution"

Praxis

1. Geben Sie Qwen Code die ursprünglichen Wünsche der Projektbeteiligten aus dem README.
2. Führen Sie das Interview durch.
3. Erstellen Sie die drei Verfassungsdateien.
4. Prüfen Sie sie auf Widersprüche.
5. Committen Sie.

Kontrollfragen

1. Warum muss die Verfassung zusammen mit dem Agenten geschrieben werden, nicht einfach manuell?
2. Welche Entscheidungen müssen in tech-stack.md leben, nicht in der Feature-Spezifikation?
3. Warum sollte die Roadmap aus kleinen Phasen bestehen?