BizGuard: Eine Geschäftsregel-Schutzschicht für KI-Programmierassistenten

BizGuard ist ein Open-Source-Validierungsprojekt: Bevor ein KI-Programmierassistent Code ändert, prüft es, ob die Änderung leicht übersehbare Geschäftsregeln des Systems verletzt.

Es kann mit Programmierassistenten wie Claude Code oder Codex zusammenarbeiten: Der Assistent schreibt den Code, BizGuard liefert nachvollziehbare Sperrentscheidungen, wenn kritische Regeln verletzt werden. Es ist kein produktionsreifes Sicherheitsprodukt und ersetzt keine menschliche Beurteilung.

Welches Problem löst es?

KI ist sehr gut darin, Code nach Anforderungen zu ändern, weiß aber nicht unbedingt, welche "unantastbaren" Regeln in deinem System gelten. Erschwerend kommt hinzu, dass diese Regeln oft nicht in Kommentaren dokumentiert sind: Zum Beispiel darf ein Coupon nur einmal eingelöst werden, der Buchungsstatus muss konsistent sein, und nach außen zurückgegebene Datenfelder dürfen nicht stillschweigend entfernt werden.

Ein Beispiel: Wenn die KI die Coupon-Einlösungslogik ändert und dabei aus "Vereinfachungsgründen" die Prüfung des Idempotenzschlüssels entfernt. Der Idempotenzschlüssel kann als "eindeutige Kennung dieser Anfrage" verstanden werden; mit ihm führt ein doppelter Klick oder ein Netzwerk-Retry nicht dazu, dass derselbe Coupon zweimal eingelöst wird. Der Code kompiliert vielleicht weiterhin, und normale Tests könnten ebenfalls bestehen, aber bei wiederholter Übermittlung durch den Benutzer kann es zu einer doppelten Einlösung kommen.

Traditionelle LLM-Code-Reviews sind eher wie ein nachträgliches Raten durch eine andere KI, ob "hier ein Risiko besteht": hilfreich, aber das Ergebnis ist probabilistisch. BizGuard hingegen wandelt klare Geschäftsregeln in ausführbare Policies um, bevor eine Änderung den nächsten Schritt erreicht, und trifft mithilfe von Syntaxbaum-Prüfungen (AST, Programmstruktur statt reinem Text) und festen Regeln deterministische Entscheidungen: Dieselbe Eingabe kann offline wiedergegeben werden, die Entscheidung hängt nicht von der Spontanleistung des Modells ab.

Related MCP server: Architect-to-Product (A2P)

Warum dieses Projekt?

Komplexe Geschäftssysteme enthalten viele Geschäftsinvarianten – also Einschränkungen, die "unabhängig von Änderungen immer gelten müssen", zum Beispiel:

• Idempotenz: Wiederholte Anfragen dürfen nicht zu doppelten Abbuchungen, Einlösungen oder Lieferungen führen;

• Buchungskonsistenz: Transaktionsstatus und Buchungsdatensätze dürfen sich nicht widersprechen;

• DTO-Kompatibilität: DTOs sind Datenstrukturen, die zwischen Diensten ausgetauscht werden; nach außen gerichtete Felder dürfen Aufrufer nicht stillschweigend brechen.

Dieses Wissen ist oft über historische Vorfälle, Schnittstellenverträge, Teamdokumentationen und mehrere Dienste verstreut. Bestehende Lösungen wie CodeRabbit verlassen sich hauptsächlich auf nachträgliche LLM-Reviews; sie eignen sich zum Auffinden von Hinweisen, können aber nicht garantieren, dass versteckte Invarianten jedes Mal erkannt werden.

BizGuard organisiert wichtige Invarianten in Policies und stützt Entscheidungen auf AST-Validierung, Auswirkungsanalyse und Evidenzketten. Es folgt drei Grundprinzipien:

• Determinismus: Entscheidungen können offline wiedergegeben werden;

• Evidenzkette: Jedes BLOCK lässt sich auf Regel, Änderung und zugehörige Beweise zurückführen;

• Unbekanntes nicht als sicher ausgeben: Bei unvollständigen Informationen wird CHECK_INCOMPLETE oder REQUIRE_APPROVAL zurückgegeben, statt vorschnell ALLOW zu setzen.

Technische Architektur

Das Projekt wird schrittweise von P0 bis P5 aufgebaut; das "P" hier ist eine Phasennummer, keine Aufforderung, manuell in einer bestimmten Reihenfolge vorzugehen.

flowchart LR
    P0[P0：3 个 Java 脱敏 fixture 仓库\n语义 catalog] --> P1[P1：领域契约\n黄金基准]
    P1 --> P2[P2：知识 Hub\n混合检索]
    P2 --> P3[P3：跨服务影响图谱\n8 类节点 · 真 BFS]
    P3 --> P4[P4：Context Compiler\n8 个 MCP Tool]
    P4 --> P5[P5：四态决策 · 审批 · CI\n5 组消融]
    P5 --> D[带证据的安全结论]

• P0: Bereitstellung von drei anonymisierten Java-Fixture-Repositories (coupon-core, coupon-contract, merchant-service) sowie einem semantischen Katalog, der Geschäftsfähigkeiten, Regeln und Verantwortliche beschreibt.

• P1: Fixierung der Domänenverträge als verifizierbare Gold-Basislinie, um ein Abdriften der Regeln von der Implementierung zu verhindern.

• P2: Ein Wissens-Hub bündelt verwaltetes Teamwissen; hybride Suche kombiniert semantische Vektoren mit Stichwort-Ergebnissen. Das eingefrorene Evaluierungsset mit Recall@5=1.0 bedeutet nur, dass in dieser festen kleinen Menge die Top-5-Ergebnisse das Ziel abdecken, nicht eine allgemeine Recall-Rate in der Produktion.

• P3: Aufbau eines dienstübergreifenden Auswirkungsgraphen mit 8 Knotentypen: Organisation, Bereitstellung, Code, Schnittstelle, Daten, Nachrichten, Laufzeit, Geschäft; Verwendung echter BFS (Breitensuche) zur Ermittlung des kürzesten Auswirkungspfads, mit Beweisen entlang des Pfads. Nicht bestätigbare dynamische Grenzen werden explizit als unbekannt markiert.

• P4: Der Context Compiler kompiliert Aufgabe, Repositories, Basisversion, Regeln, Auswirkungen und Pflichttests in ein schreibgeschütztes Kontextpaket; Bereitstellung über 8 MCP-Tools für den Agenten.

• P5: Aggregation zu einer Vier-Zustands-Entscheidung, Anbindung an Genehmigungsworkflows und CI-Nachprüfung, sowie 5 Gruppen offline wiederholbarer Ablationsvergleiche: Naive Baseline, Rules Only, RAG Only, Context, Full.

Die Bedeutung der vier Zustände ist klar: ALLOW (kann fortfahren), ALLOW_WITH_TESTS (kann nach Ergänzung der angegebenen Tests fortfahren), REQUIRE_APPROVAL (menschliche Bestätigung erforderlich) und BLOCK (kritische Verletzung gefunden, Sperre). Wenn die alte Prüfpipeline einen Fall nicht prüfen kann, wird explizit CHECK_INCOMPLETE zurückgegeben und auf ein "nicht automatisch freigeben"-Ergebnis abgebildet.

Projektstruktur

biz-guard/
├── src/bizguard/        # 核心：规则、决策、图谱、检索、CLI 与 CI
├── agents_mcp/          # MCP 协议适配层，供 AI 编程助手调用
├── fixtures/            # 三个脱敏 Java 微服务 fixture 与辅助编译脚本
├── sample/              # Python 示例代码与可复现的 diff
├── policy/              # 业务不变量与策略注册表
├── registry/            # 领域契约登记数据
├── knowledge/           # 已发布知识、ADR 与检索素材
├── bench/               # 黄金基准、决策 fixture、五组消融任务
├── tests/               # 自动化测试
├── scripts/             # Demo、安装验证和 benchmark 脚本
└── docs/                # 架构决策记录

Demo: Dieselbe Änderung, zwei Ergebnisse

Führe im Projektstammverzeichnis aus:

./scripts/demo.sh

Das Skript demonstriert, dass eine "native Coding-Agent-Kontrollgruppe" (offline, deterministische scripted Simulations-Basislinie) die Änderung für plausibel hält und freigibt; anschließend prüft BizGuard denselben Diff und gibt BLOCK zurück. Dies ist keine Messung der Fähigkeiten von echtem Claude Code oder Codex; nur im --live-Modus des Benchmarks mit konfigurierten echten Agent-Befehlen wird ein echter Agent ausgeführt.

Du kannst dir auch direkt ein Verletzungsbeispiel ansehen:

bizguard check --diff sample/diffs/diff_violation_1.diff

Dieser Diff entfernt IdempotencyStore.check(idempotency_key). BizGuard gibt BLOCK aus und liefert die "entfernte Idempotenzprüfung" als Finding/Evidence zurück; so kannst du nachvollziehen, "warum blockiert wurde", statt nur ein Blackbox-"nicht bestanden" zu erhalten.

Schnellstart

Umgebungsanforderungen

• Python 3.12+

• Java 17 (für Kompilierung/Validierung der Java-Fixtures)

git clone https://github.com/PureBlueFrank/biz-guard.git
cd biz-guard

# 常规安装
pip install -e .

# 运行当前工作区的全部测试（当前可收集 259 个）
pytest

Für Offline-Umgebungen bereite bitte zuerst die Build-Abhängigkeit hatchling in einer virtuellen Umgebung oder über eine interne Paketquelle vor und verwende dann:

pip install --no-build-isolation -e .

pip install -e . erstellt standardmäßig eine isolierte Build-Umgebung; offline kann dabei versucht werden, hatchling herunterzuladen.

Häufig verwendete CLI

Die folgenden Befehle setzen voraus, dass das aktuelle Verzeichnis das Projektstammverzeichnis ist. prepare erfordert Aufgabe, beteiligte Repositories und Basisversion; impact liefert Pfade und Beweise basierend auf dem echten Fixture-Graphen.

# 编译 Agent 可读的上下文包
bizguard prepare --task "检查优惠券状态字段变更" \
  --repos coupon-core coupon-contract \
  --base-revisions bench/fixtures/phase3-revisions.yaml --json

# 检查 unified diff 是否违反 Policy
bizguard check --diff sample/diffs/diff_violation_1.diff

# 分析跨服务影响
bizguard impact analyze \
  --diff bench/fixtures/phase3/dto-status.diff \
  --repos fixtures/java-microservices \
  --revision-set bench/fixtures/phase3-revisions.yaml --format json

# 搜索受治理的团队知识
bizguard knowledge search --query "优惠券核销必须使用幂等键" \
  --scope coupon_redemption --revision semantic-seed-v1 \
  --roles engineering --json

Die 8 MCP-Tools

MCP (Model Context Protocol) ist eine Standardschnittstelle, über die KI-Assistenten externe Fähigkeiten aufrufen können. BizGuard stellt die folgenden 8 Tools bereit:

1. prepare_change: Kompiliert ein schreibgeschütztes Context Pack;

2. search_team_knowledge: Durchsucht berechtigtes Teamwissen;

3. explain_symbol: Erklärt indizierte Symbole und deren Graphen-Beweise;

4. analyze_impact: Analysiert Auswirkungspfade, unbekannte Grenzen und Pflichttests;

5. validate_patch: Deterministische Validierung von Unified Diffs;

6. get_required_tests: Ermittelt gemäß Policy die auszuführenden Tests;

7. request_approval: Stellt derzeit nur das Genehmigungs-Schema bereit, erstellt keine Genehmigungsdatensätze;

8. get_change_decision: Gibt die aggregierte Vier-Zustands-Entscheidung, Beweise, Tests und Genehmiger zurück.

Installations-Validierungsschleife

./scripts/verify_install.sh --offline

Dieses Skript prüft lokale Diagnosen und langsame CI-Nachprüfungen; standardmäßig wird das dienstübergreifende DTO-Änderungs-Fixture verwendet.

Ehrliche Erklärung und Einschränkungen

• BizGuard ist ein Open-Source-Validierungsprojekt, kein System, das bereits für Produktionssperren validiert wurde.

• Die Java-Unterstützung deckt nur die drei anonymisierten Fixture-Repositories ab, keinen vollständigen Java-Ökosystem-Analysator.

• Die Agent-Spur des Offline-Benchmarks ist eine scripted/heuristische Basislinie; nur mit --live und konfigurierten echten Agent-Befehlen wird ein echter Agent ausgeführt.

• Das Ziel-Embedding-Modell für die Suche ist Zhipu embedding-3; offline wird auf lokale lexikalische Suche zurückgegriffen, wobei die Degradierung explizit gekennzeichnet wird. Diese Ergebnisse eignen sich für Entwicklung und Demo, sind aber nicht als produktionsrelevante Abnahme gleichwertig mit echten Embeddings.

• Durch Policies geschützte Diffs werden im Speicher auf die aktuellen Fixture-Basen angewendet, bevor die AST-Validierung erfolgt; der Arbeitsbereich wird nicht verändert. Wenn ein Diff nicht angewendet werden kann oder Regeln nicht abdecken, rät das System nicht zur Sicherheit.

Mitwirkung und Feedback

Wir freuen uns über den Beitragsleitfaden und Diskussionen über neue Geschäftsinvarianten, Fixtures und reproduzierbare Fälle über Issues oder PRs.