BizGuard: AI 코딩 어시스턴트에 비즈니스 안전 게이트 추가

BizGuard는 오픈소스 검증 프로젝트입니다. AI 코딩 어시스턴트가 코드를 수정하기 전에, 시스템에서 간과하기 쉬운 비즈니스 규칙을 위반하는지 검사합니다.

Claude Code, Codex 같은 코딩 어시스턴트와 함께 사용할 수 있습니다. 어시스턴트는 코드를 작성하고, BizGuard는 핵심 규칙이 위반되었을 때 추적 가능한 차단 결론을 제공합니다. 프로덕션급 보안 제품이 아니며, 인간의 판단을 대체하지도 않습니다.

어떤 문제를 해결하나요?

AI는 요구사항에 따라 코드를 잘 수정하지만, 시스템에 "건드리면 안 되는" 규칙을 반드시 아는 것은 아닙니다. 더 골치 아픈 것은 이러한 규칙이 주석에 적혀 있지 않은 경우가 많다는 점입니다. 예: 쿠폰은 한 번만 사용 가능, 원장 상태는 일관성을 유지해야 함, 외부에 반환하는 데이터 필드를 임의로 삭제할 수 없음.

예를 들어, AI가 쿠폰 사용 로직을 수정하면서 "코드 간소화"를 위해 멱등 키 검사를 삭제했다고 가정해 봅시다. 멱등 키는 "이 요청의 고유 번호"로 이해할 수 있습니다. 이것이 있으면 중복 클릭이나 네트워크 재시도가 동일한 쿠폰을 두 번 사용하지 않게 합니다. 코드는 여전히 컴파일되고 일반 테스트도 통과할 수 있지만, 사용자가 중복 제출하면 쿠폰이 중복 사용될 수 있습니다.

기존의 LLM 코드 리뷰는 사후에 다른 AI에게 "여기에 위험이 있는지" 추측을 요청하는 것에 가깝습니다. 도움이 되지만 결과는 확률적입니다. BizGuard는 변경이 다음 단계로 진행되기 전에 명확한 비즈니스 규칙을 실행 가능한 Policy(정책)로 만들어, 구문 트리 검사(AST, 순수 텍스트가 아닌 프로그램 구조)와 고정 규칙을 통해 결정적 결론을 도출합니다. 동일한 입력은 오프라인에서 재생 가능하며, 결론이 모델의 즉흥 판단에 의존하지 않습니다.

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

왜 이 프로젝트를 만들었나요?

복잡한 비즈니스 시스템에는 많은 비즈니스 불변식, 즉 "어떻게 수정하든 항상 성립해야 하는" 제약이 숨어 있습니다. 예:

• 멱등성: 중복 요청이 중복 결제, 사용, 배송을 발생시키지 않아야 함;

• 원장 일관성: 거래 상태와 원장 기록이 서로 모순되지 않아야 함;

• DTO 호환성: DTO는 서비스 간에 전달되는 데이터 구조로, 외부 필드를 조용히 깨뜨리면 안 됨.

이러한 지식은 과거 장애 사고, 인터페이스 계약, 팀 문서, 여러 서비스에 흩어져 있는 경우가 많습니다. 기존 CodeRabbit 등의 솔루션은 주로 사후 LLM 리뷰에 의존하며, 단서를 발견하는 데는 적합하지만 숨겨진 불변식을 매번 식별한다고 보장할 수는 없습니다.

BizGuard의 접근 방식은 중요한 불변식을 Policy로 정리하고, AST 검증, 영향 분석, 증거 체인으로 의사 결정을 뒷받침하는 것입니다. 세 가지 원칙을 따릅니다:

• 결정성: 결론을 오프라인에서 재생할 수 있음;

• 증거 체인: 모든 BLOCK은 규칙, 변경 사항, 관련 증거로 추적 가능;

• 모르는 것을 안전하다고 가장하지 않음: 정보가 불완전하면 CHECK_INCOMPLETE 또는 REQUIRE_APPROVAL을 반환하고, 임의로 ALLOW하지 않음.

기술 아키텍처

프로젝트는 P0부터 P5까지 단계적으로 구축됩니다. 여기서 "P"는 단계 번호이며, 순서대로 수동으로 작업해야 한다는 의미는 아닙니다.

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: coupon-core, coupon-contract, merchant-service 세 개의 비식별화된 Java fixture 저장소와 비즈니스 기능, 규칙, 담당자를 설명하는 시맨틱 카탈로그 제공.

• P1: 도메인 계약을 검증 가능한 골든 기준으로 고정하여 규칙이 구현과 함께 표류하는 것을 방지.

• P2: 지식 Hub가 관리되는 팀 지식을 집결. 하이브리드 검색이 시맨틱 벡터와 키워드 결과를 결합. 고정 평가 세트의 Recall@5=1.0은 해당 고정 소규모 집합에서 상위 5개 결과가 대상을 포함한다는 의미일 뿐, 프로덕션 환경의 일반적인 재현율을 나타내지 않음.

• P3: 조직, 배포, 코드, 인터페이스, 데이터, 메시지, 런타임, 비즈니스 등 8가지 노드 유형을 포함하는 서비스 간 영향 그래프 구축. 실제 BFS(너비 우선 탐색)로 최단 영향 경로를 찾고, 경로와 함께 증거를 반환. 동적 경계를 확인할 수 없으면 명시적으로 미지로 표시.

• P4: Context Compiler가 작업, 저장소, 기준 버전, 규칙, 영향, 필수 테스트 항목을 읽기 전용 컨텍스트 패키지로 컴파일. 8개의 MCP Tool로 Agent가 호출 가능.

• P5: 4가지 상태로 집계된 의사 결정으로 통합하고, 승인 워크플로우 및 CI 재검사에 연결. 5개 그룹의 오프라인 재생 가능한 절제 대조 제공: Naive Baseline, Rules Only, RAG Only, Context, Full.

4가지 상태의 의미는 직관적입니다: ALLOW(계속 가능), ALLOW_WITH_TESTS(지정된 테스트를 보완하면 계속 가능), REQUIRE_APPROVAL(인간 확인 필요), BLOCK(핵심 위반 발견, 차단). 기존 검사 파이프라인에서 검사할 수 없는 경우 CHECK_INCOMPLETE를 명시적으로 제공하고, "자동 승인하지 않음" 결과로 매핑합니다.

프로젝트 구조

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: 동일한 변경, 두 가지 결과

프로젝트 루트 디렉터리에서 실행:

./scripts/demo.sh

스크립트는 "네이티브 Coding Agent 대조군"(오프라인, 결정적 scripted 시뮬레이션 기준)이 변경이 타당해 보인다고 판단하여 승인하는 것을 시연합니다. 이후 BizGuard가 동일한 diff를 검사하고 BLOCK을 반환합니다. 이는 실제 Claude Code 또는 Codex의 능력을 측정한 것이 아닙니다. benchmark의 --live 모드에서 실제 Agent 명령을 구성한 경우에만 실제 Agent가 실행됩니다.

위반 샘플을 직접 확인할 수도 있습니다:

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

이 diff는 IdempotencyStore.check(idempotency_key)를 삭제합니다. BizGuard는 BLOCK을 출력하고 "삭제된 멱등 검사"를 finding/evidence로 반환합니다. 따라서 "왜 차단되었는지"를 추적할 수 있으며, 단지 블랙박스의 "불통과"만 받는 것이 아닙니다.

빠른 시작

환경 요구 사항

• Python 3.12+

• Java 17(Java fixture 컴파일/검증용)

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

# 常规安装
pip install -e .

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

오프라인 환경에서는 먼저 가상 환경 또는 내부 패키지 소스에 빌드 의존성 hatchling을 준비한 후 다음을 사용하세요:

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

pip install -e .는 기본적으로 격리된 빌드 환경을 생성하며, 오프라인에서는 hatchling을 다운로드하려고 시도할 수 있습니다.

일반적인 CLI

다음 명령은 현재 디렉터리가 프로젝트 루트라고 가정합니다. prepare는 작업, 관련 저장소, 기준 버전을 지정해야 합니다. impact는 실제 fixture 그래프를 기반으로 경로와 증거를 제공합니다.

# 编译 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

8개의 MCP Tool

MCP(Model Context Protocol)는 AI 어시스턴트가 외부 기능을 호출할 수 있게 하는 표준 인터페이스입니다. BizGuard는 다음 8가지 도구를 제공합니다:

1. prepare_change: 읽기 전용 Context Pack 컴파일;

2. search_team_knowledge: 권한이 있는 팀 지식 검색;

3. explain_symbol: 인덱싱된 심볼과 그래프 증거 설명;

4. analyze_impact: 영향 경로, 미지 경계, 필수 테스트 항목 분석;

5. validate_patch: unified diff 결정적 검증;

6. get_required_tests: Policy에 따라 실행해야 할 테스트 식별;

7. request_approval: 현재는 승인 스키마만 제공하며, 승인 기록을 생성하지 않음;

8. get_change_decision: 4가지 상태로 집계된 결정, 증거, 테스트, 승인자 반환.

설치 폐쇄 루프 검증

./scripts/verify_install.sh --offline

이 스크립트는 로컬 진단과 CI 느린 재검사를 확인하며, 기본적으로 서비스 간 DTO 변경 fixture를 사용합니다.

정직한 선언 및 제한 사항

• BizGuard는 오픈소스 검증 프로젝트이며, 프로덕션 차단에 검증된 시스템이 아닙니다.

• Java 지원은 세 개의 비식별화된 fixture 저장소만 다루며, 완전한 Java 생태계 분석기가 아닙니다.

• 오프라인 benchmark의 Agent 트랙은 scripted/휴리스틱 기준선입니다. --live를 전달하고 실제 Agent 명령을 구성한 경우에만 실제 Agent가 실행됩니다.

• 검색 대상 embedding 모델은 Zhipu embedding-3입니다. 오프라인에서는 로컬 어휘 검색으로 대체되며, 대체되었음을 명시적으로 표시합니다. 이 결과는 개발 및 데모에 적합하며, 실제 embedding과 동등한 프로덕션 승인으로 간주할 수 없습니다.

• Policy로 보호되는 diff는 메모리에서 현재 fixture 베이스에 적용된 후 AST 검증을 수행합니다. 작업 공간은 수정되지 않습니다. diff를 적용할 수 없거나 규칙이 적용되지 않는 경우, 시스템은 안전하다고 추측하지 않습니다.

참여 및 피드백

기여 가이드를 읽고, issue 또는 PR을 통해 새로운 비즈니스 불변식, fixture, 재현 가능한 사례를 논의해 주시기 바랍니다.