bag-epl-mcp: Instructions file for Claude Code

CLAUDE.md

Teil 1 — Portfolio-weite Konventionen

Vor der Arbeit

Klon-Aktualität prüfen — Standard-Branch ermitteln, nicht main annehmen:

B=$(git ls-remote --symref origin HEAD | sed -n 's|^ref: refs/heads/\([^[:space:]]*\).*|\1|p')
git fetch origin "${B:?Standard-Branch nicht ermittelbar}" &&
  git rev-list --count HEAD..FETCH_HEAD

Drei Server im Portfolio heissen ihren Standard-Branch master (openlex-mcp, swiss-courts-mcp, swisstopo-mcp); dort scheitert ein fest verdrahtetes origin/main mit «couldn't find remote ref main». Wer das für ein Netzproblem hält, arbeitet weiter auf genau dem veralteten Klon, vor dem dieser Absatz warnt. Den :?-Schutz nicht weglassen: Bei leerem B fetcht git still den Remote-HEAD und endet mit 0.

Ein veralteter Klon erzeugt eine rote CI, deren Ursache nicht im Diff steht. Am 3.8.2026 zweimal passiert — beide Male fehlten genau die Commits, die das Gate einführten, an dem der Branch scheiterte.

In bag-epl-mcp nimmt ein SessionStart-Hook diesen Handgriff ab (Teil 2). In den übrigen Repos des Portfolios nicht — dort bleibt der Befehl oben Handarbeit, und auch hier gilt er weiter, sobald man ohne Claude Code arbeitet: Der Hook läuft am Sessionstart, nicht im blanken Terminal.

Gates lokal fahren, mit der GEPINNTEN ruff-Version aus der CI. Eine andere Version meldet Abweichungen, die niemand verursacht hat.

Tests

Gegenprobe ist Pflicht. Ein Test, der grün bleibt, wenn man die Implementierung entfernt, prüft nichts. Jede neue Zusicherung einzeln neutralisieren und zeigen, dass genau die zugehörigen Tests fallen. Zwei Fallen, die beide grün blieben:

• Eine Fake-Uhr, die nur beim Schlafen vorrückt, kann eine Zusicherung über echte Zeit nicht widerlegen.
• monkeypatch.setattr(modul.asyncio, "sleep", ...) greift ins Modul asyncio selbst und entschärft die Mechanik im ganzen Prozess. Patche einen Modul-Alias (_sleep = asyncio.sleep), nicht das fremde Modul.

Handgeschriebene Fixtures kodieren die Annahme des Autors und können sie nicht widerlegen. Mindestens eine aufgezeichnete Antwort pro externem Endpunkt, mit Aufnahmedatum.