Lernziel Modul 8

„Pro Workflow-Phase" ist der Schlüssel: die Primitive sind keine Sammlung von Gadgets, sondern die Werkzeugleiste zum Phasen-Workflow aus Modul 5.

Inhalt

Vier Primitive, vier Ladezeitpunkte

Anatomie einer SKILL.md

---
name: build
description: Build + push cgsit-finance images to GHCR — either a LOCAL Docker
  build (run inside a subagent so the build logs stay OUT of the main context)
  or by triggering the GitHub CI pipeline. Use when the user wants to
  build/push images (not deploy).
disable-model-invocation: false
user-invocable: true
allowed-tools: Bash(*), Read, Agent, AskUserQuestion
argument-hint: [local | ci [--skip-e2e] | <version>]
---

cgsit-finance/.claude/skills/build/SKILL.md — Frontmatter wörtlich, description gekürzt.

Die Frontmatter-Felder

Der Help-Pfad: ein Skill, der nichts tut

## Help (no-op path)
If the argument is `help`, `-h` or `--help`: print ONLY this usage and STOP — run no tests.
> **Usage:** `/test [backend|frontend|all]` — run local unit tests, compact pass/fail.
> • `all` (default) — backend `mvn test` + frontend `ng test` • `backend` / `frontend` — one only
> • e2e is NOT here (CI job). Run before `/build` — the local build does not test.

Wörtlich aus cgsit-finance/.claude/skills/test/SKILL.md. Dasselbe Muster in build, deploy, ship.

Skills als Context-Firewall

## How to run — in a SUBAGENT (context hygiene)

The Maven/Karma output is hundreds of lines. Run each suite in a **subagent**
that returns ONLY a compact result: `{scope, passed, failed, failing_tests[], rc}`.
Do NOT paste raw test logs into the main thread — only the failing-test names
+ the assertion line on failure.

Skills pro Phase

Analyse & Planung: der rfcs-Skill

---
name: rfcs
description: Manage cgsit-finance RFCs and GitHub Tickets. Decide RFC vs
  ticket-only, create/update specs in docs/rfcs/, create/link/close GitHub
  Issues, manage sub-tickets under an RFC.
user-invocable: true
allowed-tools: Read, Edit, Write, Glob, Grep, Bash(ls *), Bash(gh issue *), Bash(gh label *)
argument-hint: [list|status|new "title"|ticket "title"|update NNN status|close NNN]
---

Architecture-Review als Skill

---
name: review-architecture
description: Review code changes against the project's architecture definition
  and Sensitive-Area invariants. Use when reviewing PRs, after implementing a
  feature, or as PFLICHT-Subagent-Review in RFC-169 Self-Review Discipline
  (Stripe / Auth / Securities-Core / Portfolio-Ledger / Money /
  Migration-on-Large-Table / Cross-Tenant).
---

Delivery-Phase: die Kette

Chains the three stages into one flow. **The deploy gate is always an
interactive human confirmation** (CLAUDE.md Push & Deploy Policy — deploy is
never autonomous).

Commands vs. Skills

# Review Current Changes

Review the code changes in the current branch against project standards.

1. Run `git diff main --name-only` to see changed files
2. Use the code-reviewer agent (`.claude/agents/code-reviewer.md`) checklist
3. Use the architecture-reviewer skill to check architecture compliance
4. Read `.claude/rules/` for relevant coding rules

Report findings grouped by severity (Critical → Warning → Suggestion).
If everything looks good, say so — don't invent issues.

cgsit-finance/.claude/commands/review.md — wörtlich, gekürzt. Vier Commands im Repo, elf Skills.

Rules: Wissen, das sich selbst holt

---
globs: ["**/db/migration/**/*.sql",
        "**/db/migration/**/V*.sql",
        "**/src/main/resources/**/V*.sql"]
---

# Flyway Migration Safety (Quarkus + Postgres)

**Auto-loaded** for every `V*.sql` edit. This is the **load-bearing** rule:
a bad migration can put prod into a Flyway crash-loop until the next hotfix,
lock big tables for minutes, or silently corrupt cross-tenant data.

Neun Rules im Repo: java-conventions, quarkus-backend, api-rules, database-rules, testing-rules, angular-conventions, ui-theming, money-fx, migration-safety.

Hooks: bitten vs. garantieren

Hooks registrieren: settings.json

"hooks": {
  "PreToolUse": [
    { "matcher": "Bash",
      "hooks": [
        { "type": "command",
          "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/claude-hooks/block-prod-compose-down.py\"" },
        { "type": "command",
          "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/claude-hooks/block-parallel-docker-build.py\"" }
      ] }
  ],
  "PostToolUse": [
    { "matcher": "Edit|Write|MultiEdit",
      "hooks": [
        { "type": "command",
          "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/claude-hooks/postedit-guardrails.py\"" },
        { "type": "command",
          "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/claude-hooks/rfc-gate-guardrails.py\"" }
      ] }
  ]
}

Der Vertrag: stdin, exit-Code, fail open

"""Contract: reads the PreToolUse JSON on stdin. Exit 0 = allow, exit 2 = block
(stderr shown to the model). Fails OPEN on any error so it never blocks
unrelated work."""
try:
    payload = json.load(sys.stdin)
except Exception:
    sys.exit(0)          # fail-open: never block on a parsing hiccup

if payload.get("tool_name") != "Bash":
    sys.exit(0)

cmd = payload.get("tool_input", {}).get("command", "")

Ein echter PostToolUse-Hook

# PostToolUse = the edit already happened; this is a **nudge**, not a block.
# Exit 0 = clean/irrelevant, exit 2 = surface the reminder to the model.

fp = payload.get("tool_input", {}).get("file_path", "")

# --- SCSS (cgsit-finance-web) — ui-theming.md ---
if fp.endswith(".scss") and "cgsit-finance-web" in fp:
    for i, ln in enumerate(lines, 1):
        if varfallback.search(ln):
            findings.append(f"  L{i}: var(--cgs-*, <fallback>) — hex-Fallback "
                            f"versteckt fehlende Var im Dark-Mode (ui-theming.md §4.2)")
        elif hexrgb.search(ln):
            findings.append(f"  L{i}: rohe Farbe (#hex/rgb) — via var(--cgs-*) lösen")

if findings:
    sys.stderr.write(f"Guardrail-Grep für {fp} — bitte prüfen (Nudge, kein Block):\n" ...)
    sys.exit(2)
sys.exit(0)

Gute Hooks haben ein Datum — und ein Skalpell

# `docker` must be the EXECUTOR (argv0), not merely a substring in a shell
# that quotes the phrase (git commit -m "...docker build...").
EXEC_BUILD_RE = re.compile(r"^(\S*/)?docker\s+(buildx\s+)?build\b")

# Local dev `docker compose down` is left alone (the dev DB is disposable).
is_executor      = first_token in ("ssh", "docker", "docker-compose")
has_compose_down = re.search(r"docker[-\s]+compose\s+down", low) is not None
targets_prod     = (PROD_EIP in cmd) or ("ssh " in low)

if is_executor and has_compose_down and targets_prod:
    sys.stderr.write("BLOCKED: `docker compose down` on prod deletes the "
                     "PostgreSQL volume — use `up -d --force-recreate`, or `stop`/`start`.")
    sys.exit(2)

Was ein Hook nicht kann

"""Was der Hook KANN (Mechanik/Evidenz):
  - Struktur-Lint (Pflichtfelder vollstaendig)
  - Accepted / In Review  -> Analyse-Review-Notiz (+ Datum) vorhanden?
  - In Progress           -> Design-Freigabe-Haken `- [x]` (oder Skip-Begruendung)?
  - Done                  -> Closeout-Notiz (+ Datum) vorhanden?
Was er NICHT kann: das *Urteil* des Reviews ersetzen — das bleibt der
architecture-reviewer-Subagent. Der Hook prueft nur, DASS der Review
dokumentiert ist, nicht ob er gut war."""

Autonomes Git-Handling — die CGS-Freigabetabelle

Permissions: der deny-Zaun

"permissions": {
  "allow": [ "Read(**)", "Write(**)", "Bash(**)" ],
  "deny": [
    "Bash(rm -rf /)",
    "Bash(git push --force *)",
    "Bash(git reset --hard*)",
    "Bash(git clean -fd*)",
    "Bash(docker compose down -v*)",
    "Bash(*DROP DATABASE*)",
    "Bash(aws rds delete-db-instance*)",
    "Bash(aws s3 rm*--recursive*)",
    "Bash(npm publish*)",
    "Bash(*pastebin*)", "Bash(*transfer.sh*)", "Bash(*file.io*)"
  ]
}

Commit-Konvention als Skill

---
name: commit
description: Create git commits following cgsit-finance project conventions.
  Use when the user asks to commit changes.
disable-model-invocation: true
user-invocable: true
allowed-tools: Bash(git *)
argument-hint: [message or "push"]
---

## Rules
- **NEVER** add "Co-Authored-By" lines
- **NEVER** add "Generated by" or similar AI attribution
- Commit message format: `module: short description`
- Use imperative mood (add, fix, update, remove — not added, fixed)

MCP: das Vokabular

Ein MCP-Server in der Praxis

// cgsit-finance/.mcp.json
{
  "mcpServers": {
    "angular": {
      "command": "npx",
      "args": ["-p", "@angular/cli", "ng", "mcp"],
      "cwd": "/root/projects/cgsit-finance/cgsit-finance-web"
    }
  }
}

// .claude/settings.local.json — Aktivierung ist ein SEPARATER Schritt
"enableAllProjectMcpServers": true,
"enabledMcpjsonServers": [ "angular" ]

MCP vs. CLI: Token Overhead

Open Source & Vendor Lock-in

Prüffrage fürs eigene Repo: Wenn morgen ein anderes Werkzeug käme — was wäre weg, und was bliebe?

Modul 8 in fünf Sätzen

Übung 8 — Skill und Hook bauen

Dauer ca. 35 Minuten · Zweiergruppen