Blueprint: TPO-Projektstruktur für Claude Code
Version: 1.0
Zielgruppe: Technical Product Owner mit dokumentenlastigen Projekten
Stand: Januar 2026
1. Big Picture: Das Gesamtsystem
┌─────────────────────────────────────────────────────────────────────────────────┐
│ CLAUDE CODE PROJEKT │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ KONTEXT-SCHICHTEN │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ CLAUDE │ │ PROJEKT │ │ DEIN │ │ │
│ │ │ KONTEXT │ │ KONTEXT │ │ KONTEXT │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ CLAUDE.md │ │ /docs │ │ /notes │ │ │
│ │ │ .claude/ │ │ /context │ │ /scratch │ │ │
│ │ │ settings │ │ /refs │ │ journals │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │ │ │ │
│ │ └──────────────────┼──────────────────┘ │ │
│ │ ▼ │ │
│ │ ┌──────────────────────────────────────────────────────────────────┐ │ │
│ │ │ ARBEITS-TOOLS │ │ │
│ │ │ │ │ │
│ │ │ INTERAKTIV AUTONOM │ │ │
│ │ │ ════════════ ════════ │ │ │
│ │ │ │ │ │
│ │ │ Commands ──→ Schnelle Aktionen Prompts ──→ Pipeline-Stufen │ │ │
│ │ │ Skills ────→ Dialog-Werkzeuge Workflows → Orchestrierung │ │ │
│ │ │ Sub-Agents → Parallelisierung │ │ │
│ │ │ │ │ │
│ │ └──────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌──────────────────────────────────────────────────────────────────┐ │ │
│ │ │ EXTERNE ANBINDUNGEN │ │ │
│ │ │ │ │ │
│ │ │ MCP-Server ────→ Filesystem, GitHub, Notion, Confluence │ │ │
│ │ │ RAG (lightweight) → JSON-Relations + Runtime-Extraktion │ │ │
│ │ │ APIs ──────────→ Kunden-Systeme, Figma, etc. │ │ │
│ │ │ │ │ │
│ │ └──────────────────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ▼ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ OUTPUTS │ │
│ │ │ │
│ │ /output → Verarbeitete Dokumente │ │
│ │ /src/viewer → MD-Browser für Präsentationen │ │
│ │ /src/poc → Prototypen & Tools │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
2. Ordnerstruktur: Das Skelett
📁 projekt/
│
├── 📄 CLAUDE.md ← Entry-Point für Claude Code
│
├── 📁 .claude/
│ ├── 📄 settings.json ← Verhalten & Permissions
│ ├── 📁 commands/ ← Schnelle Slash-Commands
│ │ ├── 📄 status.md
│ │ └── 📄 sync.md
│ └── 📁 skills/ ← Interaktive Werkzeuge
│ ├── 📁 analyze/
│ │ └── 📄 SKILL.md
│ └── 📁 review/
│ └── 📄 SKILL.md
│
├── 📁 docs/
│ ├── 📁 architecture/ ← ADRs & Entscheidungen
│ │ └── 📄 001-wissensgraph.md
│ ├── 📁 context/ ← Domain-Wissen (exportiert aus Mac Projects)
│ │ └── 📄 kunde-abc-analyse.md
│ ├── 📁 prompts/ ← Autonome Pipeline-Prompts
│ │ ├── 📄 README.md ← Workflow-Dokumentation
│ │ ├── 📄 01_extract.md
│ │ ├── 📄 02_transform.md
│ │ └── 📄 03_generate.md
│ └── 📁 templates/ ← Wiederverwendbare Vorlagen
│ └── 📄 workshop-agenda.md
│
├── 📁 refs/ ← Relationen zu externen Quellen
│ ├── 📄 _INDEX.json ← Zentrale Relation-Map
│ ├── 📄 confluence-links.json
│ └── 📄 figma-links.json
│
├── 📁 input/ ← Rohmaterial (von Kunden, Stakeholdern)
│ ├── 📁 raw/ ← Unverarbeitet
│ └── 📁 processed/ ← Nach Pipeline-Durchlauf
│
├── 📁 output/ ← Ergebnisse & Deliverables
│ ├── 📁 reports/
│ └── 📁 presentations/
│
├── 📁 notes/ ← Dein persönlicher Workspace
│ ├── 📄 journal.md ← Tägliche Notizen
│ └── 📁 scratch/ ← Temporäre Arbeitsdateien
│
└── 📁 src/ ← Code & Tools
├── 📁 viewer/ ← MD-Browser für Dokumente
└── 📁 poc/ ← Prototypen
3. Konzept-Glossar: Die Bausteine
3.1 Kontext-Ebenen
| Ebene |
Ordner |
Zweck |
Wer pflegt |
| Claude-Kontext |
CLAUDE.md, .claude/ |
WIE Claude arbeitet |
Du (einmalig + iterativ) |
| Projekt-Kontext |
/docs, /refs |
WAS das Projekt ist |
Du + Claude |
| Dein Kontext |
/notes |
DEINE Gedanken |
Nur du |
INTERAKTIV AUTONOM
══════════ ══════
┌─────────────────────────────────┐ ┌─────────────────────────────────┐
│ COMMANDS │ │ PROMPTS │
│ │ │ │
│ Trigger: /command │ │ Trigger: "Führe Prompt X aus" │
│ Umfang: 1-5 Zeilen │ │ Umfang: Vollständige Anweisung│
│ Dialog: Minimal │ │ Dialog: Keiner │
│ Beispiel: /status, /sync │ │ Beispiel: 01_extract.md │
│ │ │ │
│ → Schnelle, wiederkehrende │ │ → Reproduzierbare │
│ Aktionen │ │ Transformationen │
└─────────────────────────────────┘ └─────────────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────┐ ┌─────────────────────────────────┐
│ SKILLS │ │ WORKFLOWS │
│ │ │ │
│ Trigger: "Nutze Skill X" │ │ Trigger: "Führe Workflow aus" │
│ Umfang: Mehrstufig │ │ Umfang: Prompt-Kette │
│ Dialog: Ja, iterativ │ │ Dialog: Nur bei Fehlern │
│ Beispiel: analyze-jsonld │ │ Beispiel: README.md in /prompts│
│ │ │ │
│ → Du steuerst, Claude führt │ │ → Claude orchestriert │
│ aus und fragt nach │ │ mehrere Schritte │
└─────────────────────────────────┘ └─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ SUB-AGENTS │
│ │
│ Was: Parallele Ausführung │
│ Wann: Unabhängige Teilaufgaben│
│ Vorteil: Geschwindigkeit │
│ Beispiel: 3 Dokumente parallel │
│ konvertieren │
│ │
│ → Skalierung ohne Komplexität │
└─────────────────────────────────┘
3.3 Entscheidungsbaum: Was nutze ich wann?
START: Ich habe eine wiederkehrende Aufgabe
│
▼
┌───────────────────────┐
│ Brauche ich Feedback │
│ während der Ausführung?│
└───────────┬───────────┘
│
┌─────────┴─────────┐
▼ ▼
JA NEIN
│ │
▼ ▼
┌───────────┐ ┌───────────────┐
│ Wie viel │ │ Wie komplex? │
│ Dialog? │ └───────┬───────┘
└─────┬─────┘ │
│ ┌─────┴─────┐
┌─────┴─────┐ ▼ ▼
▼ ▼ EINFACH KOMPLEX
WENIG VIEL │ │
│ │ ▼ ▼
▼ ▼ ┌───────┐ ┌───────────┐
┌───────┐ ┌───────┐│PROMPT │ │ WORKFLOW │
│COMMAND│ │ SKILL ││ (1x) │ │ (Kette) │
└───────┘ └───────┘└───────┘ └───────────┘
4. Dateien im Detail
4.1 CLAUDE.md – Der Entry-Point
# Projekt: [Name]
## Was ist das hier?
[1-2 Sätze Kontext]
## Aktueller Fokus
- [ ] Task 1
- [ ] Task 2
## Wichtige Entscheidungen
Siehe `/docs/architecture/` für ADRs.
## Kontext-Dokumente
- `/docs/context/` – Domain-Wissen
- `/refs/_INDEX.json` – Externe Verknüpfungen
## Verfügbare Tools
- Commands: `/status`, `/sync`
- Skills: `analyze`, `review`
- Prompts: Siehe `/docs/prompts/README.md`
4.2 .claude/settings.json – Das Verhalten
{
"permissions": {
"allow": ["read", "write", "mcp"],
"deny": ["bash(rm -rf *)"]
},
"model": "claude-sonnet-4-20250514",
"preferences": {
"language": "de",
"style": "structured",
"explainConcepts": true,
"useSubAgents": true
}
}
4.3 Command-Beispiel: .claude/commands/status.md
# /status
Zeige den aktuellen Projektstatus:
1. Lies `CLAUDE.md` → Aktueller Fokus
2. Zähle Dateien in `/input/raw/` vs `/input/processed/`
3. Liste offene TODOs in `/notes/journal.md`
**Output-Format:**
- Fokus: [aktuelle Tasks]
- Pipeline: X von Y Dokumenten verarbeitet
- Offene Notizen: [Anzahl]
4.4 Skill-Beispiel: .claude/skills/analyze/SKILL.md
# Skill: JSON-LD Analyzer
## Trigger
"Analysiere die strukturierten Daten von [URL]"
## Ablauf
1. Extrahiere JSON-LD von der URL
2. **FRAGE:** "Welche Entitäten sind relevant? (Product/Organization/Brand)"
3. Zeige Gap-Analyse als Tabelle
4. **FRAGE:** "Soll ich Quick Wins priorisieren?"
5. Erstelle Report in `/output/reports/`
## Abhängigkeiten
- MCP: Browser-Tool für Live-Extraktion
- Kontext: `/docs/context/` für Vergleichsdaten
# 01 – Document Extraction
## Variablen
- `INPUT_DIR`: /input/raw/
- `OUTPUT_DIR`: /input/processed/
## Anweisungen
1. Scanne `INPUT_DIR` nach neuen Dateien (PDF, DOCX)
2. Für jede Datei:
- Extrahiere Text mit pandoc
- Konvertiere zu Markdown
- Speichere in `OUTPUT_DIR`
3. Aktualisiere `/input/processed/_INDEX.md`
## Modus
- **Automatisch** – keine Rückfragen
- **Delta-Erkennung** – nur neue Dateien
- **Sub-Agents** – parallele Verarbeitung bei >3 Dateien
## Output-Format
```markdown
# Extracted: [Dateiname]
- Source: [Originalpfad]
- Extracted: [Timestamp]
- Pages: [Anzahl]
[Inhalt]
4.6 Workflow-Dokumentation: docs/prompts/README.md
# Prompts – Workflow-Dokumentation
## Übersicht
| Nr. | Prompt | Zweck | Modus |
|-----|--------|-------|-------|
| 01 | extract.md | Dokumente konvertieren | Automatisch |
| 02 | transform.md | Struktur aufbereiten | Automatisch |
| 03 | generate.md | Output erstellen | Automatisch |
## Workflow
/input/raw/ → [01] → /input/processed/
↓
[02]
↓
/docs/context/
↓
[03]
↓
/output/reports/
## Nutzung
"Führe docs/prompts/01_extract.md aus"
oder
"Führe den kompletten Workflow aus (01 → 02 → 03)"
4.7 Relationen-Map: refs/_INDEX.json
{
"meta": {
"project": "Kunde-ABC Workshop",
"updated": "2026-01-31"
},
"entities": {
"kunde-abc-pdp": {
"type": "analysis",
"local": "/docs/context/kunde-abc-analyse.md",
"external": {
"confluence": "https://confluence.agentur.de/x/ABC123",
"figma": "https://figma.com/file/xyz",
"live": "https://www.kunde-abc.com/de-de/p/icba-5123-2451430"
}
},
"wissensgraph-konzept": {
"type": "architecture",
"local": "/docs/architecture/001-wissensgraph.md",
"external": {
"miro": "https://miro.com/board/abc"
}
}
}
}
5. Ausbaustufen
Jetzt (Basis)
| Komponente |
Status |
Priorität |
CLAUDE.md |
✅ Pflicht |
Sofort |
.claude/settings.json |
✅ Pflicht |
Sofort |
/docs/context/ |
✅ Pflicht |
Sofort |
/docs/architecture/ |
🟡 Empfohlen |
Woche 1 |
/refs/_INDEX.json |
🟡 Empfohlen |
Woche 1 |
Bald (Automatisierung)
| Komponente |
Status |
Priorität |
| Commands |
🟡 Nach Bedarf |
Woche 2-4 |
| Skills |
🟡 Nach Bedarf |
Woche 2-4 |
| Prompts + README |
🔵 Wenn Pipeline klar |
Monat 2 |
| Sub-Agents |
🔵 Wenn Prompts stabil |
Monat 2 |
Später (Skalierung)
| Komponente |
Status |
Priorität |
/src/viewer/ |
🔵 Nice-to-have |
Monat 3+ |
| MCP-Erweiterungen |
🔵 Nach Bedarf |
Monat 3+ |
| RAG-Integration |
⚪ Zukunft |
Wenn nötig |
6. Anti-Patterns
| ❌ Nicht tun |
✅ Stattdessen |
| Alles in CLAUDE.md packen |
Modular in /docs/ aufteilen |
| Prompts ohne README |
Immer Workflow dokumentieren |
| Skills für alles |
Commands für Einzeiler |
| Sofort Sub-Agents |
Erst einzelner Prompt, dann skalieren |
| Externe Links in Markdown |
Zentral in /refs/_INDEX.json |
7. Checkliste: Neues Projekt aufsetzen
## Projekt-Setup Checkliste
### Minimal (Tag 1)
- [ ] CLAUDE.md erstellt
- [ ] .claude/settings.json konfiguriert
- [ ] /docs/context/ mit erstem Dokument
- [ ] /input/raw/ und /input/processed/ angelegt
### Basis (Woche 1)
- [ ] /docs/architecture/ mit erstem ADR
- [ ] /refs/_INDEX.json mit externen Links
- [ ] /notes/journal.md gestartet
- [ ] Erster Command erstellt (z.B. /status)
### Automatisierung (Monat 1)
- [ ] Wiederkehrende Aufgabe identifiziert
- [ ] Entscheidung: Skill oder Prompt?
- [ ] Erster Prompt in /docs/prompts/
- [ ] README.md für Workflow geschrieben
### Skalierung (Nach Bedarf)
- [ ] Sub-Agents für parallele Verarbeitung
- [ ] /src/viewer/ für Präsentationen
- [ ] MCP-Anbindung erweitert
Blueprint erstellt: Januar 2026