CGS IT Solutions GmbH — Claude Code Training · Modul 2 · Der Claude-Code-Baukasten · v0.11.5

Modul 2

Der Claude-Code-Baukasten

Tag 1 · ca. 150 Minuten (zwei Blöcke)

Inhalt

1Die Landkarte — Bausteine, Fragen, Ablageorte 2Was soll Claude Code wissen? — CLAUDE.md, Rules + echte Beispiele Übung 2a und 2b — zwei Rules mit verschiedenem Geltungsbereich 3Was soll Claude Code können? — Skills, Commands-Merge, Rule vs. Skill, Spec-Muster 4Wie soll Claude Code arbeiten? — Hooks + Übung, Output Styles 5Wer soll arbeiten? — Subagents, und was Hintergrund sonst noch heißt 6Woran soll Claude Code andocken? — MCP, Plugins 7Entscheiden — Ich-will-X-Tabelle, die klassischen Verwechslungen

Lernziel Modul 2

Der Teilnehmer kann jedes Claude-Code-Primitiv benennen, sein Einsatzgebiet erklären und weiß, welches Werkzeug für welchen Zweck gedacht ist.

  1. Benennen — jedes Primitiv mit Namen kennen: CLAUDE.md, Rules, Skills, Subagents, Hooks, Output Styles, MCP, Plugins.
  2. Einordnen — zu jedem sagen können, welche Frage es beantwortet und wann es in den Kontext lädt.
  3. Abgrenzen — bei einem neuen Bedürfnis das passende Werkzeug wählen, nicht das zuletzt gelernte.
Benennen, einordnen, abgrenzen — gebaut wird an Tag 2 und 3.

Der Baukasten

Neun Primitive, ein Baukasten — heute wird benannt und eingeordnet; gebaut wird an Tag 2 und 3.

CLAUDE.md

Dauerwissen, immer im Kontext

Rules

Wissen, das nur bei Bedarf lädt

Skills

Abrufbares Verfahren mit Anleitung

Commands vs. Skills

Heute zu einem Primitiv verschmolzen — die Auslöser-Frage bleibt

Subagents

Arbeit in fremdem Kontext

Hooks

Deterministische Automatik

Output Styles

Wie geantwortet wird

MCP

Anschluss an fremde Systeme

Plugins

Das teilbare Bündel

Von der Frage zum Werkzeug

Alle Primitive beantworten genau eine von fünf Fragen — wer die Frage kennt, findet das Werkzeug, nicht umgekehrt.

Was soll Claude Code wissen?
CLAUDE.md · Rules
überlebt die Session
Was soll Claude Code können?
Skills · Commands
Verfahren auf Abruf
Wie soll Claude Code arbeiten?
Hooks · Output Styles
Automatik und Form
Wer soll arbeiten?
Subagents
Arbeit in fremdem Kontext
Woran soll Claude Code andocken?
MCP · Plugins
fremde Systeme, teilbare Bündel
je Zeile: die Frage — die Primitive, die sie beantworten — was sie leisten
Jedes Primitiv ist eine Antwort auf stateless aus Modul 1: Was der Agent nicht behält, muss im Repo liegen — und dort so liegen, dass es zur richtigen Zeit im Kontext landet.

Wo das alles physisch liegt

Zwei Ebenen: das Repo (Team-Eigentum, versioniert) und dein Home (persönlich, gilt in allen Projekten).

  1. Repo = Team-Eigentum — reviewbar, teilbar (Modul 10).
  2. *.local.* bleibt privat — gehört in die .gitignore.
  3. User-Ebene lädt zuerst — Projekt-Vorgaben gewinnen.
  4. Neues gehört in skills/ — commands/ ist Legacy.
projekt/ CLAUDE.md Projektwissen — immer geladen CLAUDE.local.md persönlich (.gitignore!) .mcp.json MCP-Server des Projekts .claude/ settings.json Permissions + Hooks (im Repo) settings.local.json persönliche Ergänzung rules/ *.md — laden je nach paths: skills/<name>/SKILL.md commands/<name>.md Legacy — Teil der Skills agents/<name>.md Subagents output-styles/<name>.md ~/.claude/ User-Ebene: CLAUDE.md, rules/, skills/, output-styles/
Tipp: Achte auf eine korrekte .gitignore für alle lokalen Artefakte — CLAUDE.local.md, settings.local.json, .env …
checked am 2026-07-23 gegen code.claude.com

Was soll Claude Code wissen?

CLAUDE.md

Eine Markdown-Datei im Repo, bei jedem Start automatisch im Kontext — das Onboarding-Dokument aus Modul 1, nur dass Claude Code es jeden Morgen neu liest.

Dafür gedacht

Build- und Testbefehle, Architekturüberblick, verbindliche Konventionen, Workflow-Regeln, Verweise auf tiefere Doku.

Dafür nicht

Alles, was nur selten gebraucht wird. Jede Zeile kostet in jeder Session Tokens — auch in denen, in denen sie niemanden interessiert.

Vertiefung in Modul 7: Aufbau, Umfang, Pitfalls — und wie man misst, ob sie überhaupt wirkt.

Rules

Regeldateien unter .claude/rules/ — die Ladepolitik steht im Dateikopf: paths: entscheidet, wann die Regel in den Kontext kommt.

Ablage

projekt/
  .claude/
    CLAUDE.md
    rules/
      java-conventions.md
      migration-safety.md
      money-fx.md
~/.claude/rules/  # persönlich, alle Projekte

Unterordner und Symlinks erlaubt — eine Datei je Thema.

Konfiguration im Dateikopf

---
paths:
  - "**/db/migration/**/V*.sql"
  - "**/src/main/resources/**/V*.sql"
---
# Flyway Migration Safety
- Never modify an already-applied migration …

Ohne paths: lädt die Regel immer (wie CLAUDE.md) — mit paths: erst, wenn der Agent eine passende Datei liest.

Faustregel: „gilt immer" gehört in die CLAUDE.md — „gilt nur, wenn ich X anfasse" gehört in eine Rule mit paths:.
Das spart Kontext und hält die CLAUDE.md kurz.
checked am 2026-07-22 gegen code.claude.com

Eine echte Rule: api-rules.md

Aus cgsit-finance/.claude/rules/ — feuert genau dann, wenn eine REST-Resource oder ein DTO angefasst wird:

--- paths: ["**/api/*Resource.java", "**/api/dto/*.java"] ---
# API / REST Resource Rules (Quarkus / JAX-RS)
**Stack: Quarkus + JAX-RS (`jakarta.ws.rs.*`), NOT Spring.** If you're about to type
`@RestController` / `@RequestMapping` / `ResponseEntity`, stop — wrong framework.
## Request/Response — validate input with `@Valid` + Jakarta Bean Validation;
never expose entities — always map to DTOs (records)
## Error Responses — RFC 9457 — `application/problem+json`, never stack traces;
`400` validation · `404` missing · `409` conflict · always `errorCode` + `severity`
## Documentation — OpenAPI annotations only if the project uses them, else RFC / spec

Präzise Muster

*Resource.java, dto/*.java — lädt nur bei API-Arbeit.

Häufigsten Fehler abfangen

Millionen Spring-Beispiele im Training — die Regel kontert die wahrscheinlichste Verwechslung.

Pflicht-Kategorien

Validation, Error-Format, Doku-Politik — wie im offiziellen Doku-Beispiel, nur produktionsreif.

Eine gute Rule kontert konkrete Fehler an einer präzisen Stelle und regelt die Pflicht-Kategorien — nicht „schreib guten Code" überall.

Übung 2a — Rule 1: für alle Java-Dateien

Die erste Regel, die euch gehört — aus einem echten Ärgernis der letzten zwei Stunden, nicht aus guten Vorsätzen.

  1. /init noch einmal. Jetzt gibt es Code und eure Datei — es schlägt Verbesserungen vor. Was davon hat es im Code gelesen?
  2. Was hat euch geärgert? Genau eine Sache. Nicht fünf.
  3. Als .claude/rules/java-conventions.md schreiben — prüfbar formuliert, nicht als Vorsatz. paths: im Kopf sagt, wann sie lädt.
  4. Und eine zweite Zeile, die verweist: die Ablage aus eurer CLAUDE.md nach docs/architecture.md umziehen, die Regel zeigt nur noch dorthin.
  5. Nachweis: frische Session, Auftrag bei dem sie greift — ohne sie zu erwähnen. Sie wird befolgt.
  6. Gegenprobe: Regel raus, gleicher Auftrag. Altes Verhalten zurück.
# .claude/rules/java-conventions.md
---
description: Java-Konventionen in diesem Projekt
paths: "**/*.java"
---

# paths: entscheidet, WANN sie laedt
# Kandidaten — nehmt EINEN
- Tests immer mit `mvn -q test` starten,
  nie ein einzelnes Modul.
- Keine Zusammenfassung am Ende der Antwort.

# und die Zeile, die verweist statt zu wiederholen
- Dateiablage und Benennung:
  siehe `docs/architecture.md`
Der Schlüssel heißt paths: — nicht globs:. Den wertet Claude Code nicht aus, die Regel lädt dann immer.

Dauer ca. 12 Minuten · Partnerarbeit

Übung 2b — Rule 2: nur für die Schnittstelle

Dieselbe Bauform, anderer Geltungsbereich.
Erst mit zwei Rules nebeneinander wird sichtbar, wozu paths: gut ist.

  1. .claude/rules/api-rules.md anlegen — paths: nur auf eure Resource-Klassen. Erst nachsehen, wie sie wirklich heißen — paths: trifft keine Klasse, die Controller heißt.
  2. Zwei bis drei Regeln, die nur für die Schnittstelle gelten: Statuscodes, Fehlerform, Benennung der Pfade.
  3. Nachweis: Änderung an einer Resource — sie greift. Änderung an der Fachlogik — sie greift nicht.
  4. Notiert eine Frage, die offen bleibt: Warum eigentlich Rules und nicht etwas anderes? Die Antwort kommt am Deckende — erst müsst ihr die übrigen Bausteine kennen.
Schritt 3 ist der Punkt der Übung: Geltungsbereich ist steuerbar — und kostet nur dort Kontext, wo er gebraucht wird.
# .claude/rules/api-rules.md
---
description: Regeln für die REST-Schnittstelle
paths: "**/api/*Resource.java"
---

- Die Resource rechnet nicht — sie ruft die
  Fachlogik auf und formt die Antwort.
- Nicht gefunden antwortet 404, nie 200 mit
  leerem Körper. Ungültige Eingabe: 400.
- Pfade in der Mehrzahl und klein: `/seminare`.
- Kein Stacktrace im Antwortkörper.

Dauer ca. 8 Minuten · Partnerarbeit · hier ist Pause — Auflösung danach

Praxisbeispiel: ein Endpunkt mit Rules im Rücken

Der Auftrag ist kurz, weil die Konventionen schon geschrieben stehen.
Dasselbe Muster wie in Übung 1a2 — eine Stufe höher.

  1. Prompt absetzen. Er nennt keine Statuscodes, keine Pfadkonventionen, keine Testregel.
  2. Nachprüfen: Hält sich der neue Endpunkt an beide Rules? Zeigt die Stelle.
  3. Und der Gegencheck: Welche Regel hätte gegriffen, wenn ihr die Fachlogik geändert hättet — und welche nicht?
Erst die Grundlage, dann der knappe Auftrag. Was einmal geschrieben steht, muss nie wieder gesagt werden.
Prompt · neuer EndpunktErgänze einen Endpunkt, der ein Seminar anhand seiner Kennung liefert. Konventionen stehen in den Rules.

Weiter im Baukasten — die Auflösung zu diesen beiden Übungen kommt am Deckende, wenn alle neun Bausteine auf dem Tisch liegen.

Nachsehen statt raten: Was ist wirklich geladen?

Eine Rule, die nicht lädt, meldet sich nicht.
Drei Wege, das zu prüfen — von schnell bis genau.

  1. /context — Kategorie Memory Files zeigt, was im Fenster liegt. Fehlt eine Datei dort, sieht Claude Code sie nicht.
  2. /memory — listet die Speicherorte und öffnet die Datei; auch für Orte, an denen noch nichts liegt.
  3. Der InstructionsLoaded-Hook — protokolliert jede geladene Instruktionsdatei mit Grund.
Für pfadabhängige Rules ist der Hook das genaue Werkzeug: Er sagt nicht nur ob, sondern warum geladen wurde — und welche Datei es ausgelöst hat.
// Nutzlast des InstructionsLoaded-Hooks
file_path welche Datei
memory_type User | Project | Local | Managed
load_reason session_start
              | path_glob_match
              | nested_traversal
              | include | compact
trigger_file_path welche Datei löste aus
globs, parent_file_path optional
checked am 2026-07-28 gegen CLI 2.1.220

Was soll Claude Code können?

Skills

Ein Skill ist ein dokumentiertes Verfahren in einem eigenen Ordner — liegt bereit und wird erst geladen, wenn es gebraucht wird.

Beschreibung

Wofür ist der Skill da? Daran erkennt der Agent, ob er passt.

Anleitung

Die eigentlichen Schritte — so ausführlich wie nötig, ohne Kontextkosten im Normalfall.

Erlaubte Werkzeuge

Ein Skill kann einschränken, womit er arbeiten darf.

checked am 2026-07-21 gegen cgsit-finance

Commands vs. Skills — heute ein Primitiv

Früher zwei getrennte Bausteine — inzwischen sind Custom Commands in Skills aufgegangen; beide Ablagen erzeugen denselben /name-Aufruf:

Ablage · zwei Orte
Legacy, läuft weiter.claude/commands/deploy.md
aktueller Weg.claude/skills/deploy/SKILL.md
Aufruf · einer
/deployderselbe Befehl aus beiden Ablagen
Auslöser · Frontmatter im Skill
ich, jedes Malnur per /deploy
der Agent selbstwenn die Beschreibung passt
Prozess Daten
Die richtige Frage bleibt: Wer löst aus? Nur die Antwort ist heute keine Ordner-Wahl mehr, sondern ein Frontmatter-Feld im Skill — „nur ich per /name" bis „der Agent, wann immer die Beschreibung passt".
checked am 2026-07-23 gegen code.claude.com

Ein echter Skill: deploy/SKILL.md

Aus einem CGS-Produkt-Repository.
Der Kopf liegt immer im Kontext, der Rumpf erst beim Aufruf — hier rund 200 Zeilen Verfahren.

  1. Die Beschreibung ist der Suchindex. Nur sie ist immer präsent. Steht dort nicht, wann der Skill dran ist, findet ihn niemand — auch das System nicht.
  2. allowed-tools ist die Allowlist. Was nicht drinsteht, darf der Skill nicht anfassen.
  3. Zwei Schalter für „wer löst aus?" user-invocable für mich per /deploy, disable-model-invocation gegen das System.
Ein Skill ist die Antwort auf: „Das mache ich jedes Mal gleich — und vergesse jedes Mal den vierten Schritt."
# .claude/skills/deploy/SKILL.md
---
name: deploy
description: Rollt die fertigen Images aus.
  Use when the user asks to deploy.
user-invocable: true
disable-model-invocation: false
allowed-tools: Bash(*), Read, AskUserQuestion
argument-hint: [skip-e2e | local | <version>]
---
# Deploy to Production
## Mode selection 3 Wege, wann welcher
## Mode 1 … Schritte, jeder mit Abnahme
… ~200 Zeilen, die erst /deploy lädt
checked am 2026-07-28 gegen cgsit-finance

Übung 2c — ein Deploy-Skill für euer Projekt

Die Miniatur davon, im eigenen Projekt: bauen, das Artefakt unter release/ ablegen — und nachweisen, dass es dort läuft.

  1. .claude/skills/deploy/SKILL.md anlegen: Beschreibung, user-invocable, dann die Schritte in Reihenfolge.
  2. Was er tun soll: bauen · Version aus pom.xml lesen · das Ergebnis nach release/<version>/ legen · melden, was abgelegt wurde.
  3. Bricht der Build, wird nichts kopiert. Das gehört in den Skill, nicht in euren Kopf.
  4. Abnahme: frische Session, /deploy, dann das Abgelegte starten — ohne das Projekt.
# frische Session, dann:
/deploy

# und die eigentliche Prüfung:
cd release/1.0-SNAPSHOT
java -jar quarkus-app/quarkus-run.jar
curl "localhost:8080/seminare/
     freie-plaetze?kapazitaet=10&gebucht=3"
Ein Skill, dessen Ergebnis niemand startet, ist eine Notiz. Erst der Startversuch macht ihn zum Verfahren.

Rule, Skill — oder beides?

Am REST-Service durchgespielt: dieselbe Domäne, zwei Werkzeuge — und eine klare Arbeitsteilung:

Rule — die Invarianten

Was immer gilt, sobald API-Dateien angefasst werden: RFC 9457, @Valid, DTOs statt Entities, 404 statt 403.

Passiv: feuert auch beim Drei-Zeilen-Fix, an den niemand denkt — das Sicherheitsnetz.

Skill — das Verfahren

/new-endpoint: Resource + DTOs + ExceptionMapper + Pflicht-Tests anlegen — in Reihenfolge, mit Verifikation.

On-demand: der Body kostet erst beim Aufruf Kontext — der Happy Path für die große Aufgabe.

Antwort: beides. Wissen (gilt immer bei X) Rule · Können (Aufgabe mit Schritten) Skill · Müssen (Garantie) Hook.
Anti-Pattern: Invarianten in den Skill kopieren — referenzieren statt duplizieren (nächste Folie).

Eine Wahrheit, viele Eingänge

Die vierte Zutat: eine neutrale Spezifikation als Markdown im Repo — werkzeugunabhängig, lesbar für Menschen und Agenten:

Prozesse · die drei Verweiser
Rulelädt die Invarianten zur richtigen Zeit
SkillVerfahren verweist auf die Spec
Hookerzwingt das maschinell Prüfbare
Daten · die eine Quelle
docs/api-conventions.mdneutrale Spezifikation
„die Wahrheit“
Prozess Daten
Referenzieren statt kopieren: ändert sich die Spec, ziehen Rule, Skill und Hook mit — kein Drift zwischen vier Kopien derselben Vorgabe.
Vertiefung: Modul 7 (Doku als Fundament, RFCs, Markdown-Handoffs).
checked am 2026-07-22 gegen cgsit-finance

Wie soll Claude Code arbeiten?

Hooks — das Einzige, was sicher passiert

Ein Hook ist ein Programm, das Claude Code selbst an festen Punkten ausführt — vor oder nach einem Tool-Call — unabhängig davon, was das Modell gerade für richtig hält.

Dafür gedacht

  • Formatieren & Linten nach dem Schreiben
  • verbotene Muster abfangen
  • Nachweise erzwingen — Test grün, Review dokumentiert
  • gefährliche Befehle stoppen

Dafür nicht

Alles, was ein Urteil erfordert: ein Hook prüft, dass etwas da ist — nicht, ob es gut ist. Und jeder Fehlalarm erzieht zum Ignorieren.

Regeln und Anweisungen sind Bitten an ein nicht-deterministisches Modell.
Ein Hook ist Code.
Was garantiert sein muss, gehört in einen Hook — nicht in einen weiteren Merksatz in der CLAUDE.md.

Ein echter Hook — der Auslöser

Ein Hook entsteht dort, wo eine Zusicherung gebraucht wird, die ein nicht-deterministischer Agent nicht von sich aus garantiert.

Ausgangslage: eine Bitte

  • Freigabe-Gate in cgsit-finance: Status „Accepted" nur mit dokumentiertem Review.
  • Das hing allein an Disziplin — einer Bitte an den Agenten.
  • Beim nicht-deterministischen Agenten ist Disziplin keine Zusicherung: mal gemacht, mal vergessen.

Auslöser wird Code

  • Aus der Bitte wird ein Prüfprogramm (der Hook).
  • Läuft nach jeder Änderung an einem RFC-Dokument.
  • Meldet ein fehlendes Nachweis-Artefakt sofort zurück.
Regel = Bitte, skaliert breit, aber überschreibbar.
Hook = Code, nur der eine bekannte Fall, dafür garantiert.
Beides zusammen — nicht statt.
checked am 2026-07-21 gegen cgsit-finance

Ein echter Hook — der Gate-Checker im Code

Aus der Bitte wurde ein Prüfprogramm: registriert in settings.json, die Logik in einem Python-Skript (149 Zeilen).

// .claude/settings.json — Registrierung: Event + Matcher + Kommando
"PostToolUse": [{ "matcher": "Edit|Write|MultiEdit",
  "hooks": [{ "type": "command",
    "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/claude-hooks/rfc-gate-guardrails.py\"" }] }]

# rfc-gate-guardrails.py — die Essenz (aus dem Docstring)
if file_path nicht docs/rfcs/NNN-*.md exit 0  # feiner Eigenfilter, zuerst
Status Accepted / In Review Analyse-Review-Notiz (+ Datum) vorhanden?
Status Done Closeout-Notiz vorhanden?
Exit 0 = clean/irrelevant · exit 2 = Feedback an das Modell · fails OPEN bei eigenen Fehlern
  1. Matcher (grob): matcht den Tool-Namen Edit|Write|MultiEdit — feuert nach jedem Edit/Write.
  2. Skript (fein): filtert selbst auf docs/rfcs/NNN-*.md und steigt sonst sofort mit exit 0 aus.
  3. Prüft, dass der Review dokumentiert ist — nicht, ob er gut war. Das Urteil bleibt beim Reviewer.
  4. Fail open: nur RFC-Dateien, bei Draft still, bei eigenen Fehlern durchlassen — jeder Fehlalarm erzieht zum Ignorieren.
Ausgelöst von Claude Code, nicht vom Modell: PreToolUse läuft vor dem Tool-Call und blockt ihn mit exit 2 (so die block-*-Hooks auf Bash); PostToolUse wie hier läuft danach — exit 2 ist nur Feedback, der Edit ist schon passiert.
checked am 2026-07-24 gegen cgsit-finance + code.claude.com

Übung 2d — ein Hook, der System.out findet

Dieselbe Vorgabe wie eine Rule — nur diesmal als Programm.
Es fragt das Modell nicht, es läuft.

  1. Registrieren in settings.json: Ereignis PostToolUse, Matcher Edit|Write. Der Matcher trifft den Werkzeugnamen, nicht den Dateinamen.
  2. Filtern im Skript: alles, was nicht .java ist, sofort mit exit 0 durchlassen. Grob der Matcher, fein das Skript — wie beim echten Hook von vorhin.
  3. Nachweis: Claude Code eine Debug-Ausgabe in Seminar.java schreiben lassen. Die Meldung kommt zurück, ohne dass ihr den Hook erwähnt.
  4. Gegenprobe: dasselbe in einer Nicht-Java-Datei — still.
// .claude/settings.json
"PostToolUse": [{ "matcher": "Edit|Write",
  "hooks": [{ "type": "command", "command":
    "python3 .claude/hooks/no-sysout.py" }] }]

# no-sysout.py — die Essenz
payload = json.load(sys.stdin)
fp = payload["tool_input"]["file_path"]
if not fp.endswith(".java"): sys.exit(0)
if "System.out." in open(fp).read():
    sys.stderr.write("System.out in " + fp)
    sys.exit(2) # geht ans Modell
sys.exit(0)
checked am 2026-07-28 gegen CLI 2.1.220

Was von den Hooks bleibt

Ein Hook ist die einzige Stelle im Baukasten, an der etwas garantiert passiert — Code, den Claude Code an einem Lifecycle-Event selbst ausführt.

  1. Ausgelöst von Claude Code an einem Event — deterministisch, nicht vom Modell entschieden.
  2. Der Matcher trifft den Tool-Namen: PreToolUse läuft davor und kann blocken, PostToolUse danach als Feedback.
  3. exit 2 ist der Hebel — blockt (Pre) oder gibt Feedback (Post); exit 0 = clean; fails open bei eigenen Fehlern.
  4. Prüft dass, nicht ob gut — Mechanik erzwingen; das Urteil bleibt bei Mensch und Subagent.
Das Modell will ein Tool benutzen
PreToolUse
blockt mit exit 2
Tool-CallBash, Edit, Write …
PostToolUse
meldet mit exit 2
rot: die zwei Stellen, an denen euer Code läuft
Vertiefung in Modul 8: mehrere Hooks pro Event registrieren, echtes Blocken mit den block-*-PreToolUse-Hooks, die Denylist — und in Übung 8 baut ihr einen eigenen Hook.
Vollständige Referenz aller Events und Exit-Codes: code.claude.com/docs/en/hooks
checked am 2026-07-24 gegen code.claude.com

Output Styles

Steuert, wie geantwortet wird, nicht was getan wird — ein Markdown-File, das den System-Prompt modifiziert:

# .claude/output-styles/diagrams-first.md  (oder ~/.claude/output-styles/)
---
name: Diagrams first
description: Lead every explanation with a diagram
keep-coding-instructions: true  # ohne dies entfallen die Software-Engineering-Instruktionen!
---
When explaining code or architecture, start with a Mermaid diagram
showing the structure, then explain in prose. Keep diagrams under 15 nodes.
  • Aktivieren: /config Output style — oder Settings-Key "outputStyle": "Diagrams first".
  • Wirkt ab /clear bzw. der nächsten Session (System-Prompt wird einmal gelesen) — gilt nicht für Subagents.

Dafür gedacht

Rolle, Tonfall, Antwortformat — konsistent über jede Antwort: knapp für Geübte, erklärend für Einarbeitung und Lehre.

Dafür nicht

Fachliche Regeln, Verfahren, Sicherheitsvorgaben — Stil ist nicht Inhalt.

checked am 2026-07-23 gegen code.claude.com

Ein echter Output Style: Terse

Gegen das häufigste Ärgernis überhaupt: Claude Code wiederholt in Prosa, was es gerade geschrieben hat — und ihr lest es zweimal.

# .claude/output-styles/terse.md
---
name: Terse
description: Kein Prosa-Echo von generiertem Code
keep-coding-instructions: true
---

## Antworten nach Dateiänderungen

Wiederhole niemals Code, den du gerade geschrieben
oder geändert hast — weder vollständig, noch als
Auszug, noch Zeile für Zeile. Die Datei ist die
Quelle der Wahrheit; der Nutzer liest sie im Editor.

Höchstens drei Zeilen:
1. Was fachlich geändert wurde — nicht, welche
   Syntax dafür verwendet wurde
2. Was als Nächstes zu wissen ist: Build-Befehl,
   getroffene Annahme, bewusst offen Gelassenes
3. Sonst nichts

Keine abschließenden Zusammenfassungen. Keine
Aufzählung geänderter Zeilen. Keine Wiederholung
von Signaturen, Annotationen oder Imports.

Gut

OrderResource.java — POST-Endpunkt ergänzt, Validierung am Boundary. Annahme: Fehlerformat wie in ProblemDetail.

Schlecht

„Ich habe eine Methode createOrder hinzugefügt, die ein OrderRequest entgegennimmt, mit @Valid annotiert ist, und im Fehlerfall …“

keep-coding-instructions: true ist hier nicht optional. Ohne das Feld fallen die eingebauten Software-Engineering-Instruktionen weg — ihr wollt weniger Prosa, nicht schlechteren Code.
checked am 2026-07-28 gegen CLI 2.1.220

Wer soll arbeiten?

Arbeit außer Haus — und wo sie hingeht

Subagents

Ein Subagent bearbeitet eine abgegrenzte Aufgabe im eigenen Kontextfenster — sein Input kommt aus zwei Quellen: dem Auftrag des Aufrufers und seiner eigenen Konfiguration.

  1. Auftrag vom Aufrufer — die Delegations-Nachricht der Hauptsession.
  2. Eigener System-Prompt aus der Config — der Markdown-Body von .claude/agents/<name>.md; das Frontmatter regelt Tools, Modell, Skills.
  3. Dazu geladen: CLAUDE.md-Hierarchie + Git-Status — aber nie der Gesprächsverlauf.
  4. Zurück kommt nur das Ergebnis — typisch für Recherche, Testläufe, unabhängige Reviews.
Daten · zwei Quellen
AuftragDelegations-Prompt
der Hauptsession
Configagents/<name>.md
System-Prompt · Tools · Modell
Prozess
Subagenteigenes Kontextfenster · kennt den Verlauf nicht
Daten
nur das
Ergebnis
Prozess Daten
NOGO: Aufgaben, bei denen man den Weg mitlesen will — und alles, was den Gesprächsverlauf braucht.
Der Subagent kennt ihn nicht und produziert dann plausiblen Unsinn.
checked am 2026-07-23 gegen code.claude.com

Ein echter Subagent: researcher.md

Aus cgsit-finance/.claude/agents/ — der Anti-Halluzinations-Rechercheur, der Bibliotheken prüft, bevor sie verwendet werden:

---
name: researcher
description: Investigates APIs and libraries before use — verify, never invent
tools: WebSearch, WebFetch, Read, Grep  # bewusst OHNE Edit/Write
model: sonnet
---
# Researcher — You are a technical researcher. …
**NEVER recommend a library, API, or pattern without verifying it exists.**
- Always provide the Maven/Gradle coordinates with exact version numbers
- Never invent method signatures — look them up
- If a library seems to match but you can't verify it, flag it as "unverified"

description = Delegations-Trigger

Daran erkennt Claude Code, wann es selbst an diesen Subagent übergibt.

Body = System-Prompt

Der ganze Anti-Halluzinations-Katalog wird zur Arbeitsanweisung — kontert direkt den Cut-off aus Modul 1.

Frontmatter = Grenzen

Recherche braucht Web und Lesen — kein Edit, kein teures Modell. Rechte und Kosten pro Rolle.

Tipp: Der Subagent ist der Ort, an dem man Verhalten hart eingrenzen kann — weniger Tools, billigeres Modell, ein Fokus.
Genau das macht ihn teamtauglich.
checked am 2026-07-23 gegen cgsit-finance

Subagent, Hintergrund, Kopie

Alle „laufen nebenher".
Sie unterscheiden sich in drei Dingen: wessen Kontext, ob ihr wartet, wo das Ergebnis landet.

Was Kontext Ihr wartet? Ergebnis Wofür
Subagent
.claude/agents/*.md
Claude Code löst aus		eigener, leerje nach Aufruf
mehrere parallel		nur die Antwort kommt zurücklaute Arbeit aus dem Fenster halten
/subtaskeuer ganzerja — daher einer zur Zeitkommt hierher zurückTeilaufgabe, die den Verlauf braucht
/forkeuer ganzer, kopiertneinläuft daneben weiterzweite Spur, ohne diese anzuhalten
/bgdiese Sitzung wandertneinEingabe ist frei, Sitzung geparktlange Läufe wegschieben
claude --bgfrisch, nichts geerbtneineigene Sitzungunabhängiger Auftrag

„Ihr wartet" heißt: die Eingabe ist belegt — blockiert wird ihr, nicht das Projekt. · Subagenten im Detail: Modul 8 („ein Skill orchestriert Subagenten“), Team-Sicht in Modul 10.

Nur der Subagent ist ein Baustein im Repo — eine Datei, die das Team teilt.
Die vier Kommandos sind Bedienung: Sie verschieben Arbeit, sie definieren keine.
checked am 2026-07-28 gegen CLI 2.1.220

Woran soll Claude Code andocken?

MCP — Anschluss an fremde Systeme

Ein offenes Protokoll für Werkzeuge und Daten außerhalb der Codebasis (Tickets, Datenbank, Doku) — ein Server stellt bereit, der Client nutzt.

Dafür gedacht

Systeme, für die es keine brauchbare Kommandozeile gibt — oder wo eine strukturierte Schnittstelle deutlich verlässlicher ist als Textausgabe.

Dafür nicht

Alles, was ein vorhandenes CLI schon kann. Jeder angebundene Server legt seine Werkzeugbeschreibungen in jeden Kontext — Modul 1 lässt grüßen.

checked am 2026-07-21 gegen cgsit-finance

Ein echter MCP-Anschluss: .mcp.json

Aus cgsit-finance — genau ein Server, und der aus gutem Grund:

  1. Ablage im Repo-Root — .mcp.json ist Team-Konfiguration; jeder Server wird beim ersten Start einzeln freigegeben.
  2. Der eine Eintrag: der offizielle Angular-CLI-Server (ng mcp via npx) — strukturierte Projekt-Auskunft, die kein Text-Parsing ersetzt.
  3. Die Disziplin: ein Server, nicht fünf — jeder legt seine Tool-Beschreibungen in jeden Kontext.
  4. Prüfen: /mcp zeigt Status und Werkzeuge der verbundenen Server.
// .mcp.json — Repo-Wurzelverzeichnis
{
  "mcpServers": {
    "angular": {
      "command": "npx",
      "args": ["-p", "@angular/cli", "ng", "mcp"],
      "cwd": "…/cgsit-finance-web"
    }
  }
}
Was der Server anbietet: u. a. get_best_practices, list_projects, search_documentation, run_target (Build/Test/Lint) — volle Liste & Doku: angular.dev/ai/mcp.
In cgsit-finance sind nur die ersten beiden freigegeben.
checked am 2026-07-24 gegen cgsit-finance + angular.dev

MCP-Transport: lokaler Prozess oder Remote-Dienst

Ein MCP-Server läuft entweder als lokaler Prozess (stdio) oder als Remote-Dienst (HTTP) — die Config verrät sofort, welcher.

  1. stdio (lokal): command + args starten einen Child-Process auf deiner Maschine; Claude Code redet über stdin/stdout — kein Netzwerk.
  2. HTTP (remote): type: "http" + url — Verbindung zu einem laufenden Dienst über das Netz.
  3. Faustregel: steht command drin, ist es lokal; steht url drin, ist es remote.
// stdio — lokaler Prozess
"angular": {
  "command": "npx",
  "args": ["-p", "@angular/cli", "ng", "mcp"]
}

// http — Remote-Dienst
"stripe": {
  "type": "http",
  "url": "https://mcp.stripe.com"
}
Der Angular-Server in cgsit-finance ist ein command-Server — also stdio, lokal.
Kein Remote-Endpoint, keine URL.
checked am 2026-07-24 gegen code.claude.com

Was npx … ng mcp wirklich tut

Der Angular-Server ist ein lokaler stdio-Prozess — Internet berührt nur der einmalige Paket-Download, kein Live-Dienst.

  1. npx — führt ein npm-Paket-Binary aus.
  2. -p @angular/cli — stellt das Paket bereit; einmaliger Download aus der npm-Registry, falls nicht schon im node_modules/Cache.
  3. ng mcp — startet den Angular-MCP-Server als lokalen stdio-Prozess im cwd.
  4. Internet nur hier: der Paket-Download — eine npm-Abhängigkeit, kein laufender Dienst. Bei cgsit-finance ohnehin schon installiert (@angular/cli@21).
npx # npm-Paket-Runner
  -p @angular/cli # Paket bereitstellen
  ng mcp # ng-Binary, Befehl 'mcp'

# startet lokal, spricht stdio:
Claude Code <--stdin/stdout--> ng mcp
# kein Port, keine URL, kein Netz
„Läuft das übers Netz?" — Nein: stdio, lokaler Child-Process.
Der einzige Vertrauenspunkt ist das npm-Paket @angular/cli selbst, das ihr sowieso zum Bauen nutzt.
checked am 2026-07-24 gegen cgsit-finance

Plugins

Ein Plugin verpackt mehrere Primitive — Skills, Agents, Hooks, MCP-Anbindung — zu einer installierbaren, verteilbaren Einheit.

  1. Bündeln — was zusammengehört, wird gemeinsam installiert und gemeinsam versioniert.
  2. Teilen — andere Teams bekommen den Arbeitsstand, ohne Dateien abzuschreiben.
  3. Weiterentwickeln — gepflegt wie eine interne Bibliothek, mit Reviews und Releases.
ein Plugin
Skills
Agents
Hooks
MCP-Anbindung
ein Install
Team A
Team B
Team C
eine Version im Bündel — drei Repos, die sie bekommen
Plugins sind die Team-Antwort auf den Baukasten.
Für einen Einzelnen sind sie Overhead, für fünf Teams sind sie der einzige Weg — Vertiefung in Modul 10.

So sieht ein Plugin aus

Ein Ordner bündelt alles — das Manifest ist sogar optional (Auto-Discovery, Name = Ordnername):

  1. Ein Ordner = ein Plugin — Skills, Agents, Hooks, MCP gemeinsam versioniert.
  2. Zwei Verteilwege: Marketplace-Installation — oder direkt im Repo unter .claude/skills/ (lädt nach Trust-Dialog als name@skills-dir).
  3. Sicherheit im Projekt-Scope: gebündelte MCP-Server werden trotzdem einzeln freigegeben.
  4. Reihenfolge: erst Inhalte, die funktionieren — dann bündeln.
cgs-workflow/ # ein Ordner = ein Plugin
  .claude-plugin/plugin.json # Manifest, optional: name, version, description
  skills/rfcs/SKILL.md # wird zu /rfcs
  agents/researcher.md
  hooks/hooks.json
  .mcp.json

# Installation über einen Marketplace:
claude plugin install cgs-workflow@cgs-marketplace --scope project
# oder ohne Marketplace: Ordner unter .claude/skills/ ablegen
Tipp: Der leichteste Einstieg ist das Skills-dir-Plugin im eigenen Repo — ein Marketplace lohnt erst, wenn ein zweites Team zieht.
checked am 2026-07-23 gegen code.claude.com

Ich will X ich benutze Y

Der ganze Baukasten als Entscheidungshilfe — vom Bedürfnis links zum Werkzeug rechts.

Ich will… Werkzeug weil…
…dass Claude Code unsere Build- und Testbefehle immer kenntCLAUDE.mdgilt in jeder Session, ohne Auslöser
…Konventionen nur beim Anfassen bestimmter DateienRulelädt gezielt, spart Kontext
…ein mehrstufiges Verfahren, das das System selbst erkenntSkillBeschreibung macht ihn auffindbar
…einen Prompt, den ich täglich selbst auslöseSkill (per /name)ich bin der Auslöser — per Frontmatter auf Nur-User gestellt
…Recherche oder Testlauf ohne KontextmüllSubagenteigener Kontext, nur Ergebnis kommt zurück
…eine Garantie, dass etwas passiertHookCode statt Bitte — deterministisch
…dass ein Befehl nie ausgeführt wirdPermissions (deny)harte Grenze vor der Ausführung
…knappere oder erklärendere AntwortenOutput Stylebetrifft die Form, nicht die Sache
…Zugriff auf ein System außerhalb des ReposMCPstrukturierte Schnittstelle statt Textparsen
…all das an andere Teams weitergebenPluginein Bündel, versioniert und installierbar

Die klassischen Verwechslungen

Wo die Zuordnung im Alltag kippt: vier Paare, die regelmäßig verwechselt werden.

1CLAUDE.md oder Rule? Gilt es immer — oder nur beim Anfassen bestimmter Dateien? Alles, was „immer" ist, ohne es zu sein, ist Dauerbelastung des Kontextfensters.
2Wer löst den Skill aus? Ich jedes Mal per /name — oder soll der Agent selbst merken, dass es dran ist? (Frontmatter-Entscheidung)
3Skill oder Subagent? Der Skill sagt wie etwas geht, der Subagent wo es passiert. Beides zusammen ist der Normalfall, nicht die Ausnahme.
4Rule oder Hook? Soll es befolgt werden — oder erzwungen? Wer eine Zusicherung braucht, bekommt sie nur vom Hook.
CLAUDE.md
gilt immer
Ladezeitpunkt
Rule
gilt bei passenden Dateien
ich per /name
Auslöser
der Agent
wenn die Beschreibung passt
Skill
wie es geht
Ort
Subagent
wo es passiert
Rule
wird befolgt
Verbindlichkeit
Hook
wird erzwungen
je Zeile: die Achse in der Mitte, ihre beiden Pole links und rechts

Wo es weitergeht

Jedes Primitiv wird an Tag 2 und 3 genau dort vertieft, wo der Arbeitsablauf es braucht.

Primitiv Vertiefung Dort geht es um…
CLAUDE.mdModul 7Aufbau, Umfang, Pitfalls, agent-ready Codebase
SubagentsModul 5Parallel Agent Development, Review-Loops
Skills, Rules, Commands, HooksModul 8selbst bauen, pro Workflow-Phase
MCPModul 8Server, Tools, Resources — und MCP vs. CLI
Permissions & GrenzenModul 9Blast Radius, Security-Gates in der CI
PluginsModul 10Team-Asset, Versionierung, Konsolidierung
Modul 2 ist die Landkarte.
Ab hier wird jedes Primitiv genau dort ausgepackt, wo der Arbeitsablauf es braucht — nicht früher.

Auflösung Übung 2a, 2b und 2c

Zwei Rules (gelten ohne Aufruf, die eine für alles, die andere für einen Ausschnitt) und ein Skill (kommt erst auf Zuruf).
Jede Zuordnung steht und fällt mit ihrer Achse.

Szenario Primitiv Achse / Begründung
(a) Build & Test soll jeder Agent kennenCLAUDE.mdLadezeitpunkt: immer, ohne Auslöser
(b) Vor jedem Commit garantiert formatierenHookVerbindlichkeit: Code statt Bitte
(c) Sonderregeln bei SQL-MigrationenRuleLadezeitpunkt: nur bei passenden Dateien (paths:)
(d) Zwölf-Schritte-Release, den niemand auswendig kannSkillAuslöser: das System erkennt es per Beschreibung
(e) Jeden Morgen dieselbe StatusabfrageSkill (per /name)Auslöser: ich, jedes Mal — früher „Command"
(f) Recherche ohne KontextmüllSubagentOrt: eigener Kontext, nur Ergebnis zurück
(g) Ticketsystem lesenMCPOrt: außerhalb der Codebasis, strukturierte Schnittstelle
(h) Arbeitsstand ans zweite TeamPluginOrt/Verbindlichkeit: ein versioniertes, installierbares Bündel
Bewertet wird die Achse in der Begründung, nicht das Wort: bei (d)/(e) sind seit dem Commands-Merge beide Antworten richtig, solange die Auslöser-Frage sauber beantwortet ist.

© 2026 CGS IT Solutions GmbH

Alle Rechte vorbehalten

Diese Schulungsunterlagen sind urheberrechtlich geschützt. Vervielfältigung, Weitergabe oder kommerzielle Nutzung — auch in Auszügen — nur mit ausdrücklicher schriftlicher Genehmigung der CGS IT Solutions GmbH.

cgsit-claude-training · Modul 2 · v0.11.5