ai-rules Console 설계 문서

ai-rules는 이미 규칙 통합(core/extensions) + 멀티 도구 출력(adapters) + 프로젝트별 적용(profiles/sync) 체계를 갖추고 있다. 하지만 "지금 내 프로젝트들이 어떤 상태인지" 한눈에 보고, 직접 제어하고, AI

design docs/design/CONSOLE.md

Status: Draft Date: 2026-04-17 Author: ai-rules maintainer + Claude Opus 4.6

Context

ai-rules는 이미 규칙 통합(core/extensions) + 멀티 도구 출력(adapters) + 프로젝트별 적용(profiles/sync) 체계를 갖추고 있다. 하지만 "지금 내 프로젝트들이 어떤 상태인지" 한눈에 보고, 직접 제어하고, AI 어시스턴트로 문의/개발/배포까지 하는 통합 인터페이스가 없다.

현재 분산된 도구들:

viewer/ (Astro 정적 사이트) — 규칙 문서 열람 (읽기 전용)
tmp_page.html + scripts/permissions-ui.mjs — 퍼미션 토글, 서비스 제어
터미널 CLI — sync, 커밋, PR, 배포

이것들을 ai-rules console로 통합한다.

왜 필요한가

플랫폼이 해주지 않는 것: Claude Code, Cursor 등은 자체 AI 기능을 확장하지만, "여러 도구에 걸친 AI 에이전트 규칙 통합 관리"는 범위 밖이다.
조직 맞춤 거버넌스: 각 회사/팀의 보안·코딩·배포 정책은 범용 도구가 커버할 수 없다.
도구 이동 자유: 특정 플랫폼에 lock-in 되지 않는 규칙 레이어가 필요하다.
가시성: CLI로 설정 가능하지만, 전체 상태를 한눈에 보려면 UI가 필요하다.

목표

AI 에이전트 거버넌스 플랫폼:

모니터링 — 프로젝트 상태, sync 현황, 에이전트 세션 히스토리, 건강도
제어 — 설정 토글, 프로파일 편집, 서비스 관리, sync 트리거
정책 관리 — 조직 내부 정책(코드프리즈, 배포 정책)을 동적으로 반영
팀 관리 — 팀별 프로젝트 매핑, 역할, 규칙 오버라이드
AI 채팅 — 규칙 문의, 상태 분석, 내부 문서 연동 (하이브리드)
개발/배포 — 이슈 감지 → AI 코드 수정 → 리뷰 → PR → 배포 트리거
외부 접근 — 인증 + Cloudflare Tunnel로 어디서든 접근
도구 비의존 — 모든 변경은 profiles yaml → sync → adapter 출력

시스템 아키텍처

+--------------------------------------------------+
|              ai-rules Console (SPA)               |
|  +---------+  +---------+  +-------+  +--------+ |
|  |Dashboard|  | Control |  | Chat  |  | Deploy | |
|  | (read)  |  | (write) |  |(hybrid|  |(trigger| |
|  +---------+  +---------+  +-------+  +--------+ |
+--------------------------------------------------+
                       |
              HTTPS / SSE
                       |
+--------------------------------------------------+
|          Console API Server (Node.js)             |
|  Hono framework                                   |
|  +--------+  +--------+  +--------+  +--------+  |
|  |  Read  |  | Write  |  |  Chat  |  | Events |  |
|  |  API   |  |  API   |  |  API   |  |  SSE   |  |
+--------------------------------------------------+
                       |
        +----------------------------+
        |    기존 인프라 (재사용)      |
        | profiles/*.yaml (SoT)     |
        | sync.mjs pipeline         |
        | export-viewer.mjs         |
        | health-check.mjs          |
        | Claude API (chat)         |
        | GitHub API (deploy/PR)    |
        +----------------------------+

핵심 설계 원칙

profiles yaml이 Single Source of Truth — console은 절대 CLAUDE.md/.cursorrules 직접 수정 안 함
기존 스크립트 재사용 — sync.mjs, export-viewer.mjs, health-check.mjs를 import 또는 child_process로 호출
SSE로 실시간 이벤트 — sync 진행, 서비스 로그, 건강도 업데이트
Claude API로 채팅 — Claude Code 세션 스폰이 아닌 직접 API 호출 (도구 비의존)
범용 기능은 외부 의존 — 코드 에디터, AI 코드 작성 등은 기존 도구에 맡김. console은 거버넌스에 집중.

페이지 구조

ai-rules console
├── Dashboard   ← 프로젝트 상태 매트릭스, sync 현황, 건강도 점수
├── Rules       ← 규칙 문서 열람 (기존 viewer 대체)
├── Profiles    ← 프로파일별 설정 편집 (MCP, 에이전트 모드, extensions)
├── Policies    ← 조직 정책 관리 (코드프리즈, 배포 정책, 조건부 규칙)
├── Teams       ← 팀별 관리 (팀→프로젝트 매핑, 역할, 규칙 오버라이드)
├── Governance  ← 거버넌스 프리셋 비교, 프로젝트별 적용 현황
├── Services    ← 서비스 상태/제어 (dev server, docker)
├── Sessions    ← HANDOFF 히스토리, 에이전트 활동 로그
├── Deploy      ← staging/production 배포 트리거
└── Chat        ← AI 어시스턴트 (규칙 문의 + 상태 분석 + 내부 문서 연동)

API 설계

Read (인증 불필요 옵션)

GET  /api/dashboard          — 프로젝트 매트릭스, 건강도, 최근 sync
GET  /api/profiles           — 전체 프로파일 목록
GET  /api/profiles/:id       — 개별 프로파일 상세
GET  /api/rules              — 규칙 목록 + 요약
GET  /api/rules/:id          — 개별 규칙 내용
GET  /api/health             — 건강도 체크 결과
GET  /api/governance/presets — 거버넌스 프리셋 (solo/small-team/saas)
GET  /api/policies           — 정책 목록 (활성/예정/만료)
GET  /api/teams              — 팀 목록 + 프로젝트 매핑
GET  /api/services/status    — 서비스 상태
GET  /api/events             — SSE 실시간 이벤트 스트림

Write (인증 필수)

PATCH /api/profiles/:id      — 프로파일 YAML 패치 → 자동 sync
POST  /api/sync              — sync 트리거 (per-project 또는 all)
POST  /api/services/:id/start — 서비스 시작
POST  /api/services/:id/stop  — 서비스 중지
POST  /api/permissions/toggle — 퍼미션 토글
POST  /api/policies           — 정책 생성
PATCH /api/policies/:id       — 정책 수정 (활성/비활성 토글 포함)
POST  /api/teams              — 팀 생성
PATCH /api/teams/:id          — 팀 수정 (멤버, 프로젝트, 오버라이드)
POST  /api/deploy             — 배포 트리거 (GitHub Actions)

Chat

POST /api/chat               — AI 채팅 (SSE 스트리밍 응답 + 액션 제안)

AI 채팅 하이브리드 설계

UI로 하는 것 (즉시, 무료)	Chat으로 하는 것 (AI)
MCP 토글	"이 프로젝트 보안 규칙 요약해줘"
에이전트 모드 전환	"AITEM이랑 lro-engine 규칙 차이가 뭐야"
sync 실행	"최근 세션에서 뭐가 blocked 됐어?"
서비스 시작/중지	"이 에러 왜 발생한 거야"
배포 버튼	"이 프로젝트에 거버넌스 프리셋 뭐가 좋을까?"
코드프리즈 토글	"지금 AITEM 배포해도 돼?"

액션 제안: AI가 actionable 요청 감지 시 구조화된 액션 버튼 반환 → 사용자 클릭으로 실행

프롬프트 캐싱: 시스템 컨텍스트(data.json, 규칙 요약)를 cache_control로 캐싱 → 후속 메시지 비용 ~90% 절감

컨텍스트 소스 (Chat이 참조하는 정보)

소스	예시	용도
ai-rules 규칙	core/extensions 전체	"보안 규칙 요약해줘"
프로파일	profiles/*.yaml	"AITEM은 어떤 규칙 쓰고 있어?"
정책	policies/*.yaml	"지금 활성화된 정책이 뭐야?"
팀	teams/*.yaml	"백엔드팀 담당 프로젝트 뭐야?"
세션 히스토리	HANDOFF 로그	"최근에 뭐가 blocked 됐어?"
건강도	health-check 결과	"어떤 프로젝트가 sync 안 됐어?"
내부 wiki/Notion	외부 연동 (Phase 후반)	"우리 팀 배포 정책이 뭐야?"

상황 인식 질의 예시

사용자: "지금 AITEM 배포해도 돼?"

AI가 확인하는 것:
1. 활성 정책 → 코드프리즈 중인가?
2. 프로젝트 건강도 → sync 최신인가?
3. 세션 히스토리 → blocked 이슈 있나?
4. 거버넌스 → 배포 승인 조건 충족했나?

응답: "현재 코드프리즈 정책(~4/25)이 활성 상태입니다. 배포가 차단되어 있습니다.
       해제 후 배포하시겠습니까? [코드프리즈 해제] [취소]"

Policies — 조직 정책 관리

조직의 내부 정책과 개발 상황을 ai-rules 규칙 체계에 동적으로 반영한다.

정책 유형

유형	예시	적용 방식
상시 정책	"인증은 JWT 필수", "SQL 직접 쿼리 금지"	core/extensions에 규칙으로 존재 (기존)
시한부 정책	"4/20~4/25 코드프리즈", "보안 감사 기간 엄격 모드"	policies에 기간 설정 → 자동 활성/비활성
조건부 정책	"장애 발생 시 배포 중단", "PR 3개+ 대기 시 리뷰 우선"	policies에 트리거 조건 → 이벤트 기반 자동 전환
프로젝트별 정책	"AITEM은 금요일 배포 금지", "lro-engine은 auto-push"	profiles 오버라이드 (기존) + policies 연동

정책 데이터 모델

# console/policies/code-freeze-q2.yaml
id: code-freeze-q2
name: "Q2 코드프리즈"
type: scheduled          # scheduled | conditional | permanent
status: active           # active | inactive | scheduled
scope:
  projects: ["aitem", "lro-engine"]   # 또는 all
  teams: ["backend"]                  # 또는 all
schedule:
  start: "2026-04-20T00:00:00+09:00"
  end: "2026-04-25T23:59:59+09:00"
effects:
  - agent_mode: manual                # 에이전트 모드 강제 전환
  - deploy: blocked                   # 배포 차단
  - governance_preset: saas           # 거버넌스 레벨 상승
notification:
  on_activate: "코드프리즈 시작 — 배포 차단됨"
  on_deactivate: "코드프리즈 해제 — 정상 운영 복귀"

# console/policies/incident-freeze.yaml
id: incident-freeze
name: "장애 시 배포 중단"
type: conditional
status: active
trigger:
  type: webhook          # webhook | health_check | manual
  condition: "incident.severity >= P1"
effects:
  - deploy: blocked
  - agent_mode: manual
  - notification: "P1 장애 감지 — 배포 자동 중단됨"
auto_resolve:
  condition: "incident.resolved == true"
  effects:
    - deploy: normal
    - notification: "장애 해소 — 배포 재개"

정책 → 규칙 연동 흐름

정책 활성화
    ↓
console이 해당 프로젝트 profiles에 오버라이드 주입
    ↓
sync 자동 실행
    ↓
각 도구 (CLAUDE.md, .cursorrules 등)에 반영
    ↓
에이전트가 다음 세션부터 변경된 규칙으로 동작

규칙 우선순위

core (글로벌) < team overrides < project profile < policy overrides (최우선)

정책(policy)이 가장 높은 우선순위 — "코드프리즈"가 팀/프로젝트 설정을 덮는다.

console UI

Policies 페이지: 활성/예정/만료 정책 목록, 타임라인 뷰
즉시 토글: "코드프리즈 ON" 버튼 → 대상 프로젝트 선택 → 즉시 적용
예약: 달력에서 기간 선택 → 자동 활성/비활성
이력: 언제 어떤 정책이 활성/비활성되었는지 감사 로그

Teams — 팀별 관리

멀티 팀 환경에서 프로젝트-팀-역할-규칙의 관계를 관리한다.

팀 데이터 모델

# console/teams/backend.yaml
id: backend
name: "백엔드팀"
members:
  - { id: lead-dev, role: admin }
  - { id: dev01, role: operator }
  - { id: intern01, role: viewer }
projects: [aitem, lro-engine, rag-chat]
rule_overrides:
  extensions: [backend-fastapi, aitem-backend]  # 팀 공통 extensions
  governance_preset: small-team
  agent_mode: auto-push

팀 → 프로젝트 매트릭스

            aitem  lro-engine  print-studio  slide-studio
backend      ●        ●           ○             ○
frontend     ●        ○           ●             ●
devops       ●        ●           ●             ●

● = 담당  ○ = 비담당

역할별 권한 매트릭스

권한	admin	operator	viewer
규칙 열람	O	O	O
프로파일 편집	O	X	X
sync 실행	O	O	X
서비스 관리	O	O	X
정책 생성/수정	O	X	X
배포 (staging)	O	O	X
배포 (production)	O	X	X
AI Chat (액션 실행)	O	O	X
AI Chat (질의만)	O	O	O

console UI

Teams 페이지: 팀 목록, 멤버 관리, 프로젝트 매핑
팀 대시보드: 해당 팀이 담당하는 프로젝트들의 상태만 필터링
온보딩: 신규 멤버 추가 → 역할 선택 → 해당 팀 프로젝트 접근 자동 설정

인증 & 보안

Solo 모드 (기본)

비밀번호 인증 (bcrypt hash → .env)
JWT 세션 쿠키 (24시간)

Team 모드 (엔터프라이즈)

GitHub OAuth
역할: admin / operator / viewer (Teams 섹션 참조)

외부 접근

추천: Cloudflare Tunnel (포트 포워딩 불필요, 무료, Access로 추가 인증)
대안: Tailscale, nginx + Let's Encrypt

감사 로그

모든 write 작업 console/audit.jsonl에 기록
형식: {ts, user, action, target, payload, result}
정책 활성/비활성 이력도 감사 대상

Phase Plan

Phase 0: Foundation

console/ 디렉토리 생성 (server + client)
Hono 서버에 permissions-ui.mjs API 포팅
SPA 스켈레톤 + 기존 3개 탭 (Permissions, Services, Projects) 포팅
npm run console 스크립트

Phase 1: Dashboard + Read API

/api/dashboard 엔드포인트 (export-viewer.mjs + health-check.mjs 재사용)
Dashboard 페이지: 프로젝트 매트릭스, sync 상태, 건강도
Rules 페이지: 규칙 열람 (기존 viewer 대체)
SSE /api/events 실시간 업데이트

Phase 2: Control Panel + Write API

프로파일 편집기 (YAML 시각적 폼)
Sync 제어 (진행률 SSE 스트리밍)
서비스 관리 (라이브 로그)
감사 로그 기록

Phase 3: AI Chat

Claude API 연동 (/api/chat)
컨텍스트 주입 (data.json + 프로파일 + 정책 + 팀)
액션 제안 UI
프롬프트 캐싱

Phase 4: Policies + Teams

정책 CRUD + 시한부/조건부 자동 전환
팀 관리 + 역할별 권한
정책 → profiles 오버라이드 → sync 자동 연동

Phase 5: 인증 + 외부 접근

Solo 모드 비밀번호 인증
Team 모드 GitHub OAuth
Cloudflare Tunnel 가이드
Rate limiting

Phase 6: 개발 + 배포

GitHub Actions 배포 트리거
HANDOFF 로그 뷰어
PR 생성 워크플로우
이슈 감지 → AI 수정 파이프라인
내부 wiki/Notion 연동 (Chat 컨텍스트 확장)

디렉토리 구조

ai-rules/
  console/
    package.json
    vite.config.ts
    config.yaml               # 인증, 역할, 서비스 정의
    .env                      # ANTHROPIC_API_KEY, CONSOLE_SECRET
    audit.jsonl               # 감사 로그
    policies/                 # 정책 YAML 파일
      code-freeze-q2.yaml
      incident-freeze.yaml
    teams/                    # 팀 YAML 파일
      backend.yaml
      frontend.yaml
    server/
      index.ts                # Hono 앱 진입점
      routes/
        dashboard.ts
        profiles.ts
        policies.ts           # 정책 CRUD + 자동 전환
        teams.ts              # 팀 관리
        sync.ts
        services.ts
        permissions.ts
        chat.ts
        deploy.ts
        events.ts             # SSE
      middleware/
        auth.ts
        audit.ts
        rate-limit.ts
        policy-engine.ts      # 시한부/조건부 정책 평가
    client/
      index.html
      src/
        main.tsx
        routes/                # 페이지별 컴포넌트
        components/            # 공용 컴포넌트
        hooks/                 # useSSE, useChat, useDashboard
        lib/                   # API 클라이언트, 타입

마이그레이션

permissions-ui.mjs → console server routes로 포팅 → Phase 2 완료 후 deprecate
viewer/ (Astro) → console client로 대체 → Phase 1 완료 후 공개용만 유지 가능
tmp_page.html → console에 흡수 → Phase 0 완료 후 삭제

핵심 파일 (구현 시 참조)

scripts/permissions-ui.mjs — 포팅 대상 (API + 서비스 정의)
scripts/sync.mjs — Write API가 호출하는 핵심 파이프라인
scripts/export-viewer.mjs — Read API 데이터 소스
profiles/_default.yaml — 프로파일 스키마 (편집기 폼 설계용)
viewer/src/layouts/Shell.astro — 기존 UI 레이아웃 참조
governance/presets/*.yaml — 거버넌스 프리셋 (정책 연동)

검증 방법

Phase 0: npm run console → localhost:3333 접속 → 기존 permissions-ui와 동일 동작 확인
Phase 1: Dashboard에서 14개 프로젝트 상태 매트릭스 표시 확인
Phase 2: 프로파일 MCP 토글 → sync 자동 실행 → 해당 프로젝트 CLAUDE.md 반영 확인
Phase 3: Chat에서 "aitem 보안 규칙 요약" → 정확한 응답 + "sync aitem" 액션 버튼 동작
Phase 4: 코드프리즈 정책 생성 → 대상 프로젝트 에이전트 모드 자동 전환 확인
Phase 5: 외부 기기에서 Cloudflare Tunnel 경유 접속 → 인증 후 정상 동작
Phase 6: Deploy 버튼 → GitHub Actions workflow 트리거 확인