02 시스템 아키텍처 Markdown

System Architecture

비공개 운영 원천과 공개 포트폴리오 계층으로 나뉜 Keystone 시스템 구조

Source: src/content/docs/architecture.md
Order: 3

한눈에 보기

System Architecture는 KeystoneHub가 어떤 원천 저장소, 공개 계층, 런타임 레이어로 나뉘는지 보여줍니다. 외부 독자는 여기서 전체 지도를 먼저 보고, 이후 문서에서 각 영역의 세부 운영 방식을 따라가면 됩니다.

핵심 질문: 정책, 지식, 실행 장치, 공개 문서는 각각 어디에서 관리되는가?
읽는 대상: KeystoneHub의 저장소 구조와 데이터 흐름을 파악하려는 사람
연결 문서: Public / Private Boundary, Cross-Tool Sync, ai-rules x keystone-hub Guide

이 문서에서 확인할 것

private source와 public surface의 역할 분리
Memory → PKB → rules → hub → public docs로 이어지는 순환
universal, OS, company, local 레이어가 충돌을 줄이는 방식

프로젝트 생태계

Keystone은 비공개 운영 원천과 공개 전시 계층을 분리합니다. 원천은 내부에서 관리하고, 공개 가능한 정제본만 포트폴리오로 게시합니다.

프로젝트	역할	핵심 산출물
ai-rules	비공개 규칙 원천	agent rules, commands, skills, documentation policy
pkb-wiki	비공개 지식 원천	curated decisions, failure learning, operating notes
keystone-hub	비공개 배포 원천	hooks, settings, skills, agents, scripts
ai-rules-public	공개 OSS 원천	distributable rules package, examples, public docs
keystone-portfolio	공개 전시 계층	architecture notes, case studies, public methodology
product projects	실전 적용 대상	하네스가 적용되는 실제 제품과 작업 저장소

데이터 흐름 (5단계 순환)

flowchart TD
  A["1. 개발 세션<br/>Claude Code / Codex 작업 수행"]
  B["2. 자동 회상<br/>Memory Bank 검색과 사실 축적"]
  C["3. 선별 문서화<br/>/pkb-capture, decisions, failure learning"]
  D["4. 규칙 승격<br/>ai-rules rule / command / skill"]
  E["5. 배포<br/>keystone-hub apply, sync"]
  F["6. 공개 정제<br/>keystone-portfolio / ai-rules-public"]

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

레이어 아키텍처

keystone-hub는 4단계 레이어로 설정을 분리합니다:

flowchart TD
  U["00-universal<br/>모든 머신, OS, 회사 공통"]
  O["10-os-{macos|windows}<br/>OS별 경로, 도구, statusLine"]
  C["20-company-{personal|bs}<br/>회사별 에이전트, 스킬, 규칙"]
  L["30-machine-local<br/>시크릿, 토큰, 로컬 템플릿"]

  U -->|덮어씀| O -->|덮어씀| C -->|템플릿만| L

apply.sh --profile personal-macos 한 줄로 전체 배포:

$HOME 경로 자동 확장 (어떤 사용자든 동작)
settings.json 레이어별 deep merge (hooks 배열 합산)
commands, Codex skills 자동 동기화

공개 사이트는 이 배포 레이어를 그대로 복사하지 않습니다. 내부 경로와 훅 세부값을 제거한 정제본만 게시합니다.

규칙 3계층

계층	소스	배포 대상	예시
Universal	ai-rules core	모든 프로젝트 CLAUDE.md	시크릿 금지, force-push 금지, R2 차단
Company	keystone-hub layers	~/.claude/rules/	브랜치 전략, QA 프로세스, 커밋 컨벤션
Personal	keystone-hub 20-company-personal	~/.claude/rules/	응답 언어, 신뢰도 레이블, 에이전트 모드