Claude Code 공식 거버넌스 vs ai-rules 비교 분석

### 확인 범위

research docs/research/2026-04-06-claude-code-vs-ai-rules-analysis.md

작성일: 2026-04-06 분석 대상: D:\dev-reference\claude-code (Anthropic 공식) vs D:\dev\ai-rules (자체) 목적: 두 시스템의 거버넌스, 안전, 에이전트 제어 아키텍처를 비교하고 상호 보완점을 도출 관련 문서: 커뮤니티 프로젝트 분석은 2026-04-06-community-hooks-analysis.md 참조

0. 분석 방법 및 한계

확인 범위

Claude Code 공식: D:\dev-reference\claude-code 로컬 클론 기준 (anthropics/claude-code). plugins/ (14개), examples/settings/ (3개), CHANGELOG.md, 각 플러그인의 README.md, hooks.json, SKILL.md, agent frontmatter 확인. Anthropic 내부 소스코드(비공개)는 포함하지 않음.
ai-rules: D:\dev\ai-rules 워킹 디렉토리 기준 (branch: feature/260405-pipeline-engine, commit fd6f83f). core/ 11개, extensions/ 9개, adapters/ 7개, agents/ 9개, profiles/ 14개, governance/ 전체.

비교 레이어에 대한 주의

이 문서는 서로 다른 레이어의 시스템을 비교한다:

Claude Code 공식 = 플랫폼 기능 (런타임이 보장하는 기술적 차단, sandbox, permission 시스템)
ai-rules = 운영 프로세스/문서 규칙 (Advisory 텍스트 + shell hook으로 이중화한 정책)

따라서 완전한 apples-to-apples 비교는 아니다. "Claude Code에 없음"은 "확인 범위에서 발견하지 못함"을 의미하며, Anthropic 내부 로드맵이나 비공개 기능을 배제한 판단이다. 마찬가지로 "ai-rules에 없음"은 "현재 구현/문서에서 확인되지 않음"을 뜻한다.

재검증하지 않은 항목

Claude Code 런타임의 실제 sandbox 격리 수준 (문서 기준 분석, 침투 테스트 미수행)
forceRemoteSettingsRefresh의 실제 fail-closed 동작 (설정 문서 기준, 네트워크 단절 시나리오 미검증)
prompt 타입 hook의 LLM 판단 정확도 및 latency 영향

1. 분석 대상 개요

항목	Claude Code (공식)	ai-rules (자체)
성격	Anthropic 공식 플러그인/예제/가이드	개인/팀 운영 규칙 관리 시스템
규모	14+ 플러그인, 설정 예제, 스킬/에이전트 가이드	11개 core, 9개 extension, 7개 adapter, 14개 profile
대상 도구	Claude Code 단일	Claude Code, Cursor, Windsurf, openclaw 등 7개 도구
적용 범위	범용 (모든 사용자)	프로젝트별 맞춤 (14개 프로젝트)

2. 아키텍처 비교

2.1 거버넌스 적용 방식

차원	Claude Code 공식	ai-rules
정책 전달	`settings.json` 계층 (managed → remote → user → local)	`CLAUDE.md` 텍스트 (global → project)
강제력	Deterministic — 설정 파일로 도구 레벨 차단	Advisory + Hook 이중화 — 텍스트 규칙 + shell hook
권한 모델	`ask/deny/allow/auto/bypass` 5단계	`R0/R1/R2` 가역성 3단계
Enterprise	`managed-settings.json` + `forceRemoteSettingsRefresh` (fail-closed)	확인 범위에서 해당 기능 없음 (개인/소규모 팀 대상)

ai-rules가 더 나은 점

가역성(Reversibility) 프레임워크: R0/R1/R2 등급은 Claude Code 공식에 없는 개념. "차단 여부"가 아닌 "되돌릴 수 있는가?"로 판단하는 것은 실용적
확인 문구 재입력 패턴: CONFIRM reset-{db}-{date} — 날짜 포함으로 복붙 방지. Claude Code는 이런 마찰 메커니즘이 없음

Claude Code가 더 나은 점

Deterministic enforcement: permissions.deny: ["WebSearch"]로 설정하면 AI 의지와 무관하게 100% 차단. ai-rules의 텍스트 규칙은 컨텍스트 압박 시 무시될 수 있음
Sandbox: bash 실행 격리, 네트워크 차단, 파일시스템 격리. ai-rules에는 확인 범위에서 대응하는 레이어가 없음
Enterprise managed settings 계층: 조직 → 원격 → 사용자 → 세션 순으로 정책 cascade

2.2 Hook 시스템

차원	Claude Code 공식	ai-rules
Hook 이벤트	8+ 종류 (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart/End, UserPromptSubmit, FileChanged 등)	PreToolUse + Pre-commit (Bash matcher 중심)
Hook 타입	`command` + `prompt` (LLM 기반 판단)	`command`만 (shell script)
Hook 출력	JSON 구조화 (`decision: approve/block/defer`, `updatedInput` 등)	exit code (0=통과, 1=차단)
Hook 입력	stdin JSON (session_id, transcript_path, tool_name, tool_input 등)	`$TOOL_INPUT` 환경변수

Claude Code가 더 나은 점

prompt 타입 hook: LLM이 컨텍스트를 이해해서 판단 — "이 파일 수정이 적절한가?". Shell script로는 불가능한 의미론적 검증
updatedInput: Hook이 tool input을 수정해서 반환 가능 (예: 파일 경로를 안전한 경로로 변경). ai-rules는 차단만 가능
defer decision: Headless resume 시 판단 보류 가능
SessionStart/End, FileChanged, CwdChanged: ai-rules에서는 확인 범위에서 대응하는 라이프사이클 hook이 발견되지 않음

ai-rules가 더 나은 점

MUST-HOOK / SHOULD-HOOK / TEXT-ONLY 분류 체계 (09-hooks-guide.md): "이 규칙은 hook으로 올려야 하는가?"의 명확한 판단 기준. Claude Code 공식 확인 범위에서는 이런 메타 가이드가 발견되지 않음
Advisory → Deterministic 전환 판단 기준 3가지 질문: 되돌릴 수 없는 피해 / 컨텍스트에서 무시된 적 / 절대 실행 불가

2.3 에이전트 패턴

차원	Claude Code 공식	ai-rules
에이전트 정의	`agents/` MD + YAML frontmatter	`agents/` MD + YAML frontmatter (동일)
권한 제한	`tools: [Read, Grep, Glob]`	`tools: [Read, Glob, Grep]` (동일)
트리거	description 필드 + `<example>` 블록으로 자동 트리거	수동 소환 기준 테이블
오케스트레이션	feature-dev 플러그인: 7단계 워크플로 + 병렬 에이전트	`planner → builder → [qa] → reviewer → [security]` 순차 소환
Teammate	공식 기능 (병렬 독립 에이전트)	패턴 문서화만 (`10-subagent-patterns.md`)

Claude Code가 더 나은 점

자동 트리거: description에 "Use this agent when..."과 <example> 블록을 넣으면 사용자 요청을 분석해서 자동 소환. ai-rules는 수동 판단에 의존
feature-dev 플러그인: 7단계 워크플로 + 병렬 에이전트 실행 + 사용자 승인 게이트가 통합된 완성형 오케스트레이션
SubagentStop hook: subagent 완료 시점 제어

ai-rules가 더 나은 점

Context Budget 가이드라인: "탐색 파일 5개 이하 = 메인, 6개 이상 = Subagent 위임" 같은 정량 기준. Claude Code 공식 확인 범위에서는 기본 제공 가이드가 약함
역할별 모델 분리: reviewer/security는 claude-opus-4-6, 나머지는 기본 모델. Claude Code 공식도 지원하지만 명시적 가이드가 약함

3. ai-rules만의 차별화 (Claude Code에 없는 것)

3.1 멀티 AI 도구 동기화

core/ + extensions/ → adapters/ → Claude Code, Cursor, Windsurf, openclaw, plain

동일한 규칙 집합을 7개 AI 도구에 동시 배포. Claude Code는 자체 도구만 대상.

3.2 프로젝트 프로파일 시스템

# profiles/aitem.yaml
project: aitem
target_path: d:/dev/AITEM
tools: [claude-code, cursor, plain]
governance: { preset: saas }
extensions: [aitem-agents, aitem-ci]

14개 프로젝트를 각각 다른 규칙 조합으로 관리. Claude Code 확인 범위에서는 대응하는 멀티 프로젝트 프로파일 시스템이 발견되지 않음.

3.3 가역성 프레임워크 (R0/R1/R2)

4가지 판단 축으로 모든 작업을 분류:

판단 축	질문
데이터 손실	실행 후 데이터가 사라지는가?
외부 시스템	다른 서비스/DB/인프라에 영향이 가는가?
복구 비용	되돌리려면 얼마나 많은 작업이 필요한가?
영향 범위	변경이 1개 행/파일을 초과하는가?

Claude Code는 ask/deny/allow라는 권한 중심 모델만 사용.

3.4 규칙 충돌 해결 체계

명시적 우선순위: security > git > workflow > other
Tie-breaker 4원칙
충돌 판정표 (8가지 시나리오)

Claude Code는 managed > remote > user > local 설정 계층은 있지만, 확인 범위에서 규칙 간 의미론적 충돌 해결 메커니즘은 발견되지 않음.

3.5 세션 핸드오프 프로토콜

---HANDOFF---
date / branch / status / done / next / blocked / failures / first_action
---END---

Claude Code 확인 범위에서는 세션 간 맥락 전달 표준이 발견되지 않음. SessionStart hook으로 환경변수는 설정할 수 있지만, 이전 에이전트의 작업 상태/실패/의사결정을 전달하는 구조화된 프로토콜은 기본 제공 표준이 약함.

3.6 DB 안전 규칙 (07-db)

DB 이름 충돌 방지 (실제 사고 사례 기반)
파괴적 명령어 금지 테이블
Migration 실행 프로세스 표준
PRISMA_USER_CONSENT_FOR_DANGEROUS_AI_ACTION 환경변수 가이드

Claude Code의 security-guidance 플러그인은 일반 보안을 다루지만, 확인 범위에서 DB 특화 안전 규칙(이름 충돌, migration 프로세스 등)은 발견되지 않음.

4. Claude Code만의 차별화 (ai-rules에 없는 것)

4.1 Bash Sandbox

{
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false,
    "network": {
      "allowedDomains": [],
      "allowLocalBinding": false,
      "allowAllUnixSockets": false
    }
  }
}

파일시스템 격리 + 네트워크 차단. ai-rules는 shell hook으로 명령어 패턴만 차단.

4.2 Prompt 타입 Hook

{
  "type": "prompt",
  "prompt": "이 파일 수정이 보안에 적절한가 평가하라: $TOOL_INPUT"
}

LLM 판단으로 의미론적 검증. Shell script의 정규식 매칭으로는 불가능한 수준.

4.3 Plugin Marketplace

공식 마켓플레이스 + strictKnownMarketplaces로 조직 차원 플러그인 제어. ai-rules는 중앙 관리형.

4.4 MCP 통합 가이드

stdio/SSE/HTTP/WebSocket 4가지 서버 타입 + allowedMcpServers/deniedMcpServers 정책. ai-rules에 MCP 서버 디렉토리가 있지만 아직 초기 단계.

4.5 Hookify (사용자 친화 Hook 생성)

/hookify rm -rf 명령어 사용 시 경고해줘

마크다운 YAML frontmatter로 hook 자동 생성. ai-rules의 hook은 직접 shell script 작성 필요.

4.6 Hook Output 구조화 (`updatedInput`)

Hook이 tool input을 변환해서 반환 가능:

{
  "decision": "approve",
  "updatedInput": { "file_path": "/safe/path/file.txt" },
  "systemMessage": "경로가 안전한 위치로 변경되었습니다"
}

ai-rules는 차단(exit 1) 또는 통과(exit 0)만 가능.

4.7 Enterprise 설정 계층

계층	파일	통제 범위
1. Enterprise Managed	`managed-settings.json` + `managed-settings.d/`	조직 정책 (override 불가)
2. Remote Sync	`remote-settings.json`	클라우드 정책 동기화
3. User Config	`.claude/settings.json`	개인 설정
4. Session Override	`.claude/settings.local.json`	임시 설정

forceRemoteSettingsRefresh: true — 원격 정책을 가져올 때까지 시작 차단 (fail-closed).

5. 보완 권장 사항

5.1 즉시 도입 가능 (ai-rules 자체 변경으로 완결)

ai-rules 코드/문서 수정만으로 도입 가능한 항목. Claude Code 플랫폼 업데이트에 의존하지 않음.

우선순위	항목	변경 대상	구체적 작업
P1	prompt 타입 hook 가이드	`09-hooks-guide.md` + `governance/templates/hooks/`	hook 타입에 `prompt` 섹션 추가, 예제 JSON 포함. Claude Code가 이미 지원하는 기능이므로 가이드만 작성하면 즉시 사용 가능
P2	에이전트 `<example>` 블록	`agents/*.md` 9개 파일	각 에이전트 description에 "Use this agent when..." + 2~4개 `<example>` 블록 추가. Claude Code frontmatter 호환 형식
P3	SessionStart hook	`governance/templates/hooks/session-init.sh` + `adapters/tooling.mjs`	`06-session Step 0~5`의 핵심 체크(git status, INTENT.md 존재, HANDOFF 블록)를 SessionStart command hook으로 자동화

5.2 플랫폼 지원 전제 (Claude Code 기능에 의존)

Claude Code 런타임이 제공하는 기능을 활용하므로, 해당 기능의 안정성/호환성 검증이 선행되어야 함.

우선순위	항목	의존하는 플랫폼 기능	전제 조건
P4	Sandbox preset	`settings.json` sandbox 블록	sandbox 격리 수준 실측 필요 (문서 기준으로만 확인, 실제 격리 테스트 미수행). `governance/presets/saas.yaml`에 sandbox 설정 통합
P5	Hookify 패턴 생성	Claude Code hookify 플러그인 `.claude/hookify.*.local.md` 형식	hookify 플러그인의 YAML frontmatter 스펙이 안정화된 후 `adapters/tooling.mjs`에서 생성 지원. 현재 hookify는 공식 플러그인이지만 스펙 변경 가능성 있음
P6	Hook `updatedInput` 활용	Claude Code hook output JSON의 `updatedInput` 필드	현재 ai-rules hook은 exit code만 사용. `updatedInput`으로 tool input 수정(예: 위험 경로를 안전 경로로 변환)을 하려면 hook 스크립트 아키텍처 변경 필요

5.3 ai-rules가 유지해야 할 강점

항목	근거
멀티 도구 동기화	Claude Code만의 세상이 아님. Cursor, Windsurf 사용자도 동일 규칙 필요
R0/R1/R2 가역성	`ask/deny` 이분법보다 실무적. "차단할까?"가 아니라 "되돌릴 수 있는가?"
세션 핸드오프	장시간 작업의 맥락 보존. Claude Code에 아직 없는 영역
DB 안전 규칙	실제 사고 경험 기반. 범용 보안 플러그인으로 대체 불가
규칙 충돌 해결	Advisory 규칙이 많을수록 충돌 해결 체계가 중요
Context Budget 정량 가이드	에이전트 효율의 실무 가이드. 공식 문서에 없음

6. 종합 평가

평가 축	Claude Code 공식	ai-rules	우위
강제력	Deterministic (설정 차단)	Advisory + Hook	Claude Code
유연성	단일 도구 대상	7개 도구 동시 배포	ai-rules
Enterprise	managed settings, remote sync, fail-closed	기본 제공 표준 약함	Claude Code
실무 지혜	범용 가이드	사고 사례 기반 규칙 (DB 충돌, 핸드오프 실패 등)	ai-rules
Hook 고도화	prompt hook, updatedInput, 8+ 이벤트	command hook, 2개 이벤트	Claude Code
에이전트 오케스트레이션	자동 트리거, 병렬 실행	수동 소환, 순차 실행	Claude Code
위험 판단 체계	ask/deny/allow (권한 중심)	R0/R1/R2 (가역성 중심)	ai-rules
세션 연속성	기본 제공 표준 약함	HANDOFF 프로토콜	ai-rules
문서화	플러그인별 분산	체계적 handbook (docs/ 50+)	ai-rules

7. 결론

Claude Code 공식은 플랫폼 레벨의 강제력(sandbox, deterministic hook, managed settings)이 강점이고, ai-rules는 운영 레벨의 실무 지혜(가역성 판단, 세션 핸드오프, DB 안전, 멀티 도구)가 강점이다.

두 시스템은 경쟁이 아닌 상호 보완 관계:

Claude Code 공식 = "무엇을 기술적으로 차단할 수 있는가" (Platform Layer)
ai-rules        = "무엇을 왜, 어떤 기준으로 차단해야 하는가" (Policy Layer)

ai-rules가 Claude Code의 기능 중 즉시 활용 가능한 것(prompt hook 가이드, agent <example> 블록, SessionStart hook)을 우선 채택하고, 플랫폼 의존 항목(sandbox, hookify, updatedInput)은 안정성 검증 후 단계적으로 도입하면 플랫폼 강제력 + 운영 지혜가 결합된 거버넌스 체계에 가까워진다.

커뮤니티 오픈소스 hook 구현체(karanb192, johnlindquist, disler, garrytan 등)와의 비교 분석은 2026-04-06-community-hooks-analysis.md 참조.

8. 우리에게 실제로 필요한 것 Top 3

분석 결과에서 도출한, 지금 당장 착수하면 ROI가 가장 높은 3가지:

Top 1: `09-hooks-guide.md`에 prompt 타입 hook 섹션 추가

왜: shell 정규식으로 잡는 hook은 "명령어 패턴"만 탐지한다. "이 API 변경이 하위 호환성을 깨는가?", "이 파일 수정이 INTENT.md 범위 안인가?" 같은 의미론적 판단은 prompt hook만 가능하다. Claude Code가 이미 지원하는 기능이므로 가이드 문서 추가만으로 즉시 효과.

구체적 산출물:

09-hooks-guide.md에 "Hook 타입: command vs prompt" 비교 섹션
governance/templates/hooks/에 prompt hook 예제 JSON 1~2개
adapters/tooling.mjs에서 prompt hook 설정 생성 지원

Top 2: 에이전트 `<example>` 블록으로 자동 트리거 전환

왜: 현재 agents/*.md는 description만 있어서 메인 에이전트가 "이 상황에 이 에이전트를 소환해야 하나?"를 매번 판단해야 한다. Claude Code의 <example> 패턴을 적용하면 자동 트리거가 가능해져서 04-workflow의 "에이전트 팀 소환 기준" 테이블이 코드로 강제된다.

구체적 산출물:

agents/*.md 9개 파일에 <example> 블록 2~4개씩 추가
adapters/claude-code.mjs에서 .claude/agents/ 출력 시 example 블록 포함 확인

Top 3: SessionStart hook으로 `06-session` Step 0~5 자동화

왜: 세션 시작 시 "INTENT.md 확인 → SESSION.md HANDOFF 확인 → git status 확인"은 지금 advisory (텍스트 규칙)다. 컨텍스트가 길어지면 에이전트가 Step을 건너뛸 수 있다. SessionStart command hook으로 핵심 체크를 자동화하면 세션 시작 프로토콜이 deterministic이 된다.

구체적 산출물:

governance/templates/hooks/session-init.sh — INTENT.md/SESSION.md 존재 확인, HANDOFF 블록 파싱, dirty 상태 경고
adapters/tooling.mjs에서 SessionStart hook 설정 생성
06-session.md에 "이 절차는 SessionStart hook으로 자동화됨" 표기

실행 순서

1. Top 1 (prompt hook 가이드)     ← 문서 변경만, 즉시 착수 가능
2. Top 2 (agent example 블록)     ← 문서 + adapter 변경, 1일 이내
3. Top 3 (SessionStart hook)      ← hook 스크립트 + adapter + core 문서, 2~3일

Claude Code 공식 거버넌스 vs ai-rules 비교 분석

0. 분석 방법 및 한계

확인 범위

비교 레이어에 대한 주의

재검증하지 않은 항목

1. 분석 대상 개요

2. 아키텍처 비교

2.1 거버넌스 적용 방식

ai-rules가 더 나은 점

Claude Code가 더 나은 점

2.2 Hook 시스템

Claude Code가 더 나은 점

ai-rules가 더 나은 점

2.3 에이전트 패턴

Claude Code가 더 나은 점

ai-rules가 더 나은 점

3. ai-rules만의 차별화 (Claude Code에 없는 것)

3.1 멀티 AI 도구 동기화

3.2 프로젝트 프로파일 시스템

3.3 가역성 프레임워크 (R0/R1/R2)

3.4 규칙 충돌 해결 체계

3.5 세션 핸드오프 프로토콜

3.6 DB 안전 규칙 (07-db)

4. Claude Code만의 차별화 (ai-rules에 없는 것)

4.1 Bash Sandbox

4.2 Prompt 타입 Hook

4.3 Plugin Marketplace

4.4 MCP 통합 가이드

4.5 Hookify (사용자 친화 Hook 생성)

4.6 Hook Output 구조화 (updatedInput)

4.7 Enterprise 설정 계층

5. 보완 권장 사항

5.1 즉시 도입 가능 (ai-rules 자체 변경으로 완결)

5.2 플랫폼 지원 전제 (Claude Code 기능에 의존)

5.3 ai-rules가 유지해야 할 강점

6. 종합 평가

7. 결론

8. 우리에게 실제로 필요한 것 Top 3

Top 1: 09-hooks-guide.md에 prompt 타입 hook 섹션 추가

Top 2: 에이전트 <example> 블록으로 자동 트리거 전환

Top 3: SessionStart hook으로 06-session Step 0~5 자동화

실행 순서

4.6 Hook Output 구조화 (`updatedInput`)

Top 1: `09-hooks-guide.md`에 prompt 타입 hook 섹션 추가

Top 2: 에이전트 `<example>` 블록으로 자동 트리거 전환

Top 3: SessionStart hook으로 `06-session` Step 0~5 자동화