Doku: Modulare Architektur-Dokumentation für Coding-Agenten #34

New Issue

2026-04-25T08:27:41+02:00

marcus commented

2026-04-25 08:27:41 +02:00

Ziel

CLAUDE.md schlank halten und stattdessen auf modulare Architektur-Dokumente verweisen. Ein Coding-Agent, der z.B. nur an der GUI arbeitet, soll nur das Relevante einlesen – nicht die gesamte Codebasis kennen müssen.

Aktuelles Problem

CLAUDE.md wächst und enthält zunehmend Detail-Wissen über Klassen und Pakete. Das macht sie unübersichtlich und zwingt Agenten, alles zu lesen, auch wenn sie nur in einem Teilbereich arbeiten.

Lösung: Modulare Doku-Struktur

Datei	Inhalt
`CLAUDE.md`	Architekturprinzipien, Konventionen, Modulübersicht, Verweise auf Detail-Docs
`docs/architecture/gui-overview.md`	GUI-Pakete, Schlüsselklassen, Interaktionsmuster
`docs/architecture/domain-overview.md`	Domain-Modell, Ports, Use Cases
`docs/architecture/adapter-overview.md`	Adapter-out, CLI, Bootstrap

Nutzung durch Agenten

Ein Agent, der an der GUI arbeitet, bekommt im Prompt gezielt mitgegeben:

„Lies CLAUDE.md und docs/architecture/gui-overview.md"

Er muss nicht die Domain- oder Adapter-Klassen kennen.

Akzeptanzkriterien

CLAUDE.md verweist auf die modularen Doku-Dateien statt Details selbst zu enthalten
Mindestens gui-overview.md, domain-overview.md und adapter-overview.md sind angelegt
Jede Übersicht enthält: relevante Pakete, Schlüsselklassen, typische Einstiegspunkte
Ein neuer Coding-Agent kann anhand der Doku ohne weitere Erklärung im jeweiligen Bereich arbeiten

## Ziel CLAUDE.md schlank halten und stattdessen auf modulare Architektur-Dokumente verweisen. Ein Coding-Agent, der z.B. nur an der GUI arbeitet, soll nur das Relevante einlesen – nicht die gesamte Codebasis kennen müssen. ## Aktuelles Problem CLAUDE.md wächst und enthält zunehmend Detail-Wissen über Klassen und Pakete. Das macht sie unübersichtlich und zwingt Agenten, alles zu lesen, auch wenn sie nur in einem Teilbereich arbeiten. ## Lösung: Modulare Doku-Struktur | Datei | Inhalt | |---|---| | `CLAUDE.md` | Architekturprinzipien, Konventionen, Modulübersicht, Verweise auf Detail-Docs | | `docs/architecture/gui-overview.md` | GUI-Pakete, Schlüsselklassen, Interaktionsmuster | | `docs/architecture/domain-overview.md` | Domain-Modell, Ports, Use Cases | | `docs/architecture/adapter-overview.md` | Adapter-out, CLI, Bootstrap | ## Nutzung durch Agenten Ein Agent, der an der GUI arbeitet, bekommt im Prompt gezielt mitgegeben: > „Lies CLAUDE.md und docs/architecture/gui-overview.md" Er muss nicht die Domain- oder Adapter-Klassen kennen. ## Akzeptanzkriterien 1. CLAUDE.md verweist auf die modularen Doku-Dateien statt Details selbst zu enthalten 2. Mindestens gui-overview.md, domain-overview.md und adapter-overview.md sind angelegt 3. Jede Übersicht enthält: relevante Pakete, Schlüsselklassen, typische Einstiegspunkte 4. Ein neuer Coding-Agent kann anhand der Doku ohne weitere Erklärung im jeweiligen Bereich arbeiten

marcus changed title from ~~Doku: CLAUDE.md um Klassen- und Paketübersicht erweitern~~ to Doku: Modulare Architektur-Dokumentation für Coding-Agenten

2026-04-27 08:14:40 +02:00

marcus referenced this issue from a commit

2026-04-28 16:22:12 +02:00

Doku: Modulare Architektur-Dokumentation (#34)

marcus closed this issue

2026-04-28 16:24:40 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: marcus/pdf-umbenenner#34