bewerb/docs/superpowers/specs/2026-06-12-mkt-umgebung-design.md

Design: Claude-Code-Umgebung „mkt" — Projekterfassung & KI-gestützte Bewerbungen

Datum: 2026-06-12 Status: Freigegeben (Brainstorming abgeschlossen) Sprache der Umgebung: Deutsch

1. Zweck

Eine versionierte Claude-Code-Umgebung im Verzeichnis /home/tlg/mkt, die zwei Arbeitsabläufe unterstützt:

1. Freiberufler-Projekte bewerten und im CRM (EspoCRM) erfassen — über einen bestehenden, aus Claude Cowork übernommenen Skill, der hier erweitert und optimiert wird.
2. Bewerbungen mit KI-Unterstützung schreiben — mit einem persistenten Gedächtnis, das den Schreibstil und bewährte Inhalte über Sessions hinweg lernt, statt dieses Wissen nach jeder Session zu verlieren.

Erfolgskriterien

• Skills sind als echte Claude-Code-Skills aufrufbar und mit dem Repo versioniert.
• Das Gedächtnis wächst nachvollziehbar (Git-Historie): Nach einer Bewerbungssession sind die Stil-/Inhaltsentscheidungen samt Begründung festgehalten.
• Frühere Bewerbungen werden nur dann als Vorlage genutzt, wenn ihre Schwerpunkte zum neuen Projekt passen.
• .secrets/ (CRM-API-Key) bleibt unversioniert und unsynchronisiert.

2. Verzeichnisstruktur

mkt/
├── CLAUDE.md                  # Projekt-Anleitung: Workflows + Gedächtnis-Regeln (lädt automatisch je Session)
├── .gitignore                 # ignoriert .secrets/ und lokale Artefakte
├── .secrets/                  # (existiert) CRM-API-Key — NICHT versioniert, NICHT synchronisiert
│   └── espocrm-api.md
├── .claude/
│   └── skills/                # echte, versionierte Claude-Code-Skills
│       ├── projekt-anlegen/
│       │   └── SKILL.md       #   CRM: Projekt bewerten + im EspoCRM anlegen
│       └── bewerbung-schreiben/
│           └── SKILL.md       #   Bewerbungs-Workflow inkl. Gedächtnis-Update
├── vorgaben/                  # feste inhaltliche Quellen (read-mostly)
│   ├── lebenslauf.md
│   └── marketing.md
├── bewerbungen/               # entstehende Bewerbungen
│   ├── index.md               #   zentrale Registertabelle (eine Zeile je Bewerbung)
│   └── YYYY-MM-DD_<Käufer>_<Projekttitel>_<Einsatzort>/
│                              #   je Bewerbung ein Ordner: Entwürfe + finale Fassung
├── gedaechtnis/               # versioniertes Gedächtnis
│   ├── stil.md                #   gelernte Schreibstil-Regeln
│   ├── inhalte.md             #   bewährte/korrekte inhaltliche Bausteine & Fakten
│   ├── schwerpunkte.md        #   kontrolliertes Vokabular der Schwerpunkt-Schlagworte
│   └── log.md                 #   Chronik: was wann warum geändert wurde
└── docs/superpowers/specs/    # Design-Dokumente (dieses hier)

Begründung Skill-Ort: Claude Code lädt projektlokale Skills nur aus .claude/skills/<name>/SKILL.md. Ein beliebiger Ordner wie skills/ würde nicht erkannt. .claude/ wird mit ins Repo versioniert; lediglich .claude/settings.local.json bleibt lokal (in .gitignore).

3. Gedächtnis

Ein einziges, im Repo versioniertes Gedächtnis unter gedaechtnis/ ist die „Source of Truth". Das eingebaute, nur-lokale Claude-Memory wird nicht als Hauptspeicher genutzt, da es nicht synchronisiert würde.

• stil.md — übertragbare Schreibstil-Regeln (Tonalität, Anrede, Satzbau, Floskeln-Vermeidung, Formulierungspräferenzen).
• inhalte.md — bewährte, faktisch korrekte inhaltliche Bausteine (z. B. wie bestimmte Erfahrungen formuliert werden, was inhaltlich stimmt/nicht stimmt).
• schwerpunkte.md — kontrolliertes Vokabular: Liste erlaubter Schwerpunkt-Schlagworte mit Kurzdefinition, wächst mit der Zeit. Verhindert Tag-Wildwuchs (z. B. „ML" vs. „Machine Learning" vs. „KI").
• log.md — datierte Chronik: was wurde geändert und warum.

Lebenszyklus je Bewerbungssession

• Session-Beginn: CLAUDE.md weist an, vor der Arbeit an einer Bewerbung gedaechtnis/stil.md, gedaechtnis/inhalte.md, gedaechtnis/schwerpunkte.md sowie die vorgaben/ zu lesen.
• Während der Session: Iterative Textkorrekturen mit dem Nutzer bis zur Versandreife.
• Session-Ende (versandreif): Die übertragbaren Erkenntnisse (was geändert, warum) werden in stil.md/inhalte.md destilliert, neue Schlagworte ggf. in schwerpunkte.md ergänzt, ein datierter Eintrag in log.md geschrieben — und committet.

4. Skills

4.1 projekt-anlegen (CRM)

Der bestehende Cowork-Skill, hierher übernommen und schrittweise erweitert/optimiert. Bewertet Freiberufler-Projekte (Must-/Nice-to-have-Match) und legt sie als Opportunity im EspoCRM an. Nutzt die Zugangsdaten aus .secrets/espocrm-api.md (Base-URL https://crm.creature-go.com/api/v1, Header X-Api-Key). Relevante Entitäten/Felder sind dort dokumentiert (Opportunity, Contact, Account, CTag, Custom-Felder cLeadQuelle, cVerguetungsmodell, cVerlustgrund, cAccount1*, cProjektlink).

Hinweis: Inhalt/Format des bestehenden Skills wird beim Übernehmen geprüft und in den Implementierungsplan eingearbeitet.

4.2 bewerbung-schreiben (neu)

Kapselt den wiederholbaren Bewerbungs-Workflow:

1. Gedächtnis + Vorgaben laden.
2. Schwerpunkte des aktuellen Projekts bestimmen (Schlagworte aus schwerpunkte.md, ggf. neue ergänzen).
3. In bewerbungen/index.md frühere Bewerbungen mit überlappenden Schwerpunkten suchen; nur deren finale Fassung als Vorlage laden. Kein Treffer → ohne Vorlage schreiben (nur Vorgaben + Gedächtnis).
4. Bewerbungsordner nach Namensschema anlegen, Entwurf erstellen.
5. Mit dem Nutzer iterieren bis versandreif.
6. Finale Fassung ablegen, index.md aktualisieren, Gedächtnis aktualisieren (siehe §3), committen.

5. Bewerbungen — Register & Namensschema

5.1 Register bewerbungen/index.md

Eine zentrale Tabelle (schnell und vollständig prüfbar), je Bewerbung eine Zeile:

Datum	Käufer	Projekttitel	Einsatzort	Schwerpunkte	finale Fassung	Status
2026-06-10	Aristo Recruitment	AI Engineer Medical Imaging	Remote	medical-imaging, deep-learning, python	…/bewerbung.md	versandt

• Käufer: Agentur (verkauft die Leistung an den Endkunden weiter) oder bei Direktbeauftragung der Endkunde.
• Schwerpunkte: ausschließlich Schlagworte aus gedaechtnis/schwerpunkte.md.
• finale Fassung: Pfad zur versandreifen Datei im Bewerbungsordner.
• Status: z. B. Entwurf, versandreif, versandt.

5.2 Ordnername

Schema: YYYY-MM-DD_<Käufer>_<Projekttitel>_<Einsatzort>

• Käufer: Agentur oder Endkunde (s. o.).
• Projekttitel: der in der Projektbeschreibung verwendete Titel.
• Einsatzort: Remote, Hybrid-<Stadt> oder <Stadt>.

Normalisierungsregel (für dateisystemsichere Namen): Leerzeichen → Bindestrich; Slashes, Klammern und Zusätze wie (m/w/d) entfernen; sonstiger Wortlaut bleibt erhalten.

Beispiel:

2026-06-10_Aristo-Recruitment_AI-Engineer-Medical-Imaging_Remote

6. Git & Synchronisierung

• Lokales Repo initialisiert (Branch main), .gitignore schützt .secrets/.
• Sobald die Remote-URL des (vom Nutzer angelegten) Repos vorliegt, wird sie als Remote origin hinzugefügt und gepusht.
• Jede inhaltliche Änderung (Bewerbung, Gedächtnis-Update, Skill-Änderung) ist ein Commit → nachvollziehbare Historie, auf jedem Rechner verfügbar.

7. Bewusst NICHT enthalten (YAGNI)

• Kein eigenes Datei-pro-Bewerbung-Metaformat zusätzlich zum zentralen Register.
• Keine Nutzung des nur-lokalen Claude-Memory als Hauptgedächtnis.
• Keine Automatisierung des Versands; Bewerbungen werden manuell verschickt.

8. Offene Punkte (vor/in der Implementierung zu klären)

• Bereitstellung der Bestandsdateien: Nutzer legt nach Aufbau der Struktur den Cowork-Skill, lebenslauf.md und marketing.md an den genannten Orten ab.
• Remote-URL des Git-Servers (Nutzer legt Repo gerade an).
• Format/Inhalt des bestehenden Cowork-Skills wird beim Übernehmen geprüft.