02 시스템 아키텍처 Markdown

ai-rules x keystone-hub Guide

ai-rules와 keystone-hub를 하나의 AI 운영체계로 읽는 공개용 가이드

Source: src/content/docs/ai-rules-keystone-hub-guide.md
Order: 30

한눈에 보기

이 가이드는 ai-rules와 keystone-hub를 따로 떨어진 저장소가 아니라 하나의 AI 운영체계로 읽는 방법을 설명합니다. 정책은 ai-rules에서 만들고, 실행 표면은 keystone-hub에서 배포하며, 공개 가능한 설명은 이 사이트에서 정제합니다.

핵심 질문: 정책 원천과 런타임 실행 환경을 어떻게 분리하면서도 같은 방향으로 유지할 것인가?
읽는 대상: KeystoneHub 전체 구조를 저장소 책임 경계 기준으로 이해하려는 사람
연결 문서: System Architecture, Cross-Tool Deployment Guide, Public / Private Boundary

이 문서에서 확인할 것

ai-rules, keystone-hub, keystone-portfolio의 책임 분리
프로젝트 정책과 사용자 홈 런타임이 만나는 지점
공개 가이드로 재작성할 때 제거해야 하는 내부 정보

한 줄 요약

ai-rules는 정책을 만들고, keystone-hub는 그 정책이 실제 도구 표면에서 작동하도록 배포합니다. 두 저장소를 합쳐 보면 단순한 설정 모음이 아니라, AI 코딩 에이전트를 운영하기 위한 작은 운영체계에 가깝습니다.

flowchart TD
  A["ai-rules<br/>정책 원천"]
  B["profiles<br/>프로젝트별 조합"]
  C["adapters<br/>도구별 변환"]
  D["project output<br/>CLAUDE.md / Cursor rules / governance"]
  E["keystone-hub<br/>로컬 실행 허브"]
  F["layers<br/>universal / OS / company / local"]
  G["runtime surface<br/>hooks / skills / commands / settings"]
  H["keystone-portfolio<br/>공개 정제본"]

  A --> B --> C --> D
  E --> F --> G
  D --> G
  A --> H
  E --> H

왜 둘로 나누는가

AI 운영에는 두 종류의 문제가 있습니다.

문제	담당	이유
여러 프로젝트가 같은 규칙을 쓰게 만들기	`ai-rules`	core, extensions, profiles, adapters로 정책을 중앙 관리
여러 머신과 도구가 같은 실행 환경을 쓰게 만들기	`keystone-hub`	hooks, settings, skills, commands를 레이어로 배포
공개 가능한 설명을 따로 유지하기	`keystone-portfolio`	로컬 경로, 토큰, 회사 맥락을 제거한 정제본만 게시

ai-rules가 프로젝트 안의 행동 기준을 관리한다면, keystone-hub는 사용자 홈 디렉터리의 실행 환경을 관리합니다. 경계를 나누면 프로젝트 규칙과 머신 설정이 서로 덮어쓰지 않습니다.

책임 경계

영역	Owner	공개 사이트에서 다루는 방식
프로젝트 `CLAUDE.md`, `.cursor/rules/`	`ai-rules`	규칙 계층과 동기화 구조만 설명
프로젝트별 governance 설정	`ai-rules`	gate, risk, verdict 모델로 추상화
`~/.claude/hooks/`, `settings.json`	`keystone-hub`	hook 카테고리와 레이어 원칙만 설명
Claude commands, Codex skills	`keystone-hub`	작업 표면과 사용 시나리오 중심으로 설명
머신별 토큰, 로컬 경로, 개인 설정	사용자 로컬	공개하지 않음

운영 지도

mindmap
  root((Keystone AI Ops))
    Policy
      core rules
      extensions
      profiles
      adapters
    Runtime
      hooks
      commands
      skills
      settings
    Knowledge
      memory facts
      decisions
      failure learning
      public guide
    Verification
      build
      browser QA
      eval
      evidence labels

읽는 순서

ai-rules에서 정책이 어떻게 만들어지는지 본다.
keystone-hub에서 정책이 어떤 hooks, commands, skills로 실행되는지 본다.
반복 실패가 문서, 규칙, hook, eval 중 어디로 승격되는지 본다.
공개 가능한 부분만 keystone-portfolio 문서로 재작성한다.

공개 문서화 원칙

이 사이트의 문서는 내부 저장소를 그대로 복사하지 않습니다. 공개 가능한 설명은 아래 조건을 통과해야 합니다.

항목	공개 가능	공개 금지
운영 철학	실패를 규칙과 자동화로 승격하는 방식	개인별 세션 원문
아키텍처	레이어, 정책, 하네스 구조	절대 경로, 토큰, webhook
에이전트	역할, 승인 모델, 이벤트 원장	특정 고객/회사 내부 워크플로우
검증	build, QA, eval의 판단 구조	raw log, 보안 우회 절차

작성 템플릿

새로운 공개 가이드를 만들 때는 이 순서를 따릅니다.

문제를 한 문장으로 적는다.
내부 원천 저장소의 역할을 책임 경계로 정리한다.
Mermaid 다이어그램으로 흐름을 먼저 보여준다.
사람이 바로 적용할 수 있는 체크리스트를 붙인다.
공개하지 않는 데이터를 명시한다.

Source Notes

이 문서는 ai-rules의 README, architecture overview, harness guide와 keystone-hub의 README, layer guide, runtime bridge 내용을 공개용으로 재구성한 것입니다. 로컬 경로, 비밀값, 회사별 세부 운영값은 의도적으로 제외했습니다.