02 시스템 아키텍처 Markdown

Rules Architecture Overview

규칙 소스 → 조합 → 변환 → 배포로 이어지는 KeystoneHub 규칙 아키텍처를 5분 안에 파악하는 지도

Source: src/content/docs/architecture-overview.md
Order: 51

한눈에 보기

규칙 원천(ai-rules)이 KeystoneHub 안에서 어떻게 조합·변환·배포되는지 전체 구조를 보여주는 개요 문서입니다.

핵심 질문: 규칙 소스, 프로파일, adapter, runtime target은 서로 어떻게 연결되는가?
읽는 대상: 규칙 배포 파이프라인의 전체 그림을 빠르게 파악하려는 사람
연결 문서: KeystoneHub 쉽게 이해하기, ai-rules x keystone-hub Guide, Git Flow Hygiene

규칙 원천은 KeystoneHub 안의 정책 source와 handbook 도메인으로 통합되었습니다. KeystoneHub가 AI 코딩 에이전트의 규칙, runtime 자산, project adapter output을 한 곳에서 관리합니다.

1. 시스템 아키텍처 맵

규칙 소스 → 조합 → 변환 → 배포의 한 방향 흐름. 역방향 수정은 sync 시 덮어씌워집니다.

graph TB
  subgraph SRC["규칙 소스"]
    CORE["ai-rules-source/core<br/>공통 규칙"]
    EXT["ai-rules-source/extensions<br/>프로젝트-스택별 확장"]
    AGT["ai-rules-source/agents<br/>에이전트 정의"]
    LAYER["layers<br/>runtime rules/skills/hooks"]
  end

  subgraph ENGINE["조합 & 변환 엔진"]
    PROF["profiles<br/>runtime layer 조합"]
    ADAPT["adapter export<br/>project adapter"]
    APPLY["apply<br/>runtime apply"]
  end

  subgraph GOV["거버넌스"]
    CROSS["3-Round<br/>교차 검증"]
    HOOKS["Hook 세트<br/>자동 검증"]
  end

  subgraph OUT["출력"]
    OUTPUT["adapter output<br/>project rule files"]
    TARGET["runtime target<br/>Claude / Codex 홈 디렉토리"]
  end

  CORE --> ADAPT
  EXT --> ADAPT
  AGT --> ADAPT
  LAYER --> APPLY
  PROF --> APPLY
  ADAPT --> OUTPUT
  APPLY --> TARGET
  CROSS -.-> TARGET
  HOOKS -.-> TARGET

2. 규칙 3계층

규칙을 “공통 / 선택 / 조합”으로 분리해 관리 부담을 줄입니다.

계층	위치	역할	예시
Core	규칙 소스 core/	모든 프로젝트 공통 정책	00-critical, 01-git, 03-security
Extensions	규칙 소스 extensions/	도메인/스택별 추가 규칙	backend-fastapi, frontend-react
Layers	layers/	runtime rules/commands/hooks/skills	00-universal, 20-company-personal

Core 규칙 카탈로그

번호	파일	한줄 설명	로딩
00	critical	파괴적 git/보안/데이터 HARD STOP	always-on
00	identity	페르소나, 언어, 신뢰도 레이블, 규칙 우선순위	always-on
01	git	브랜치 전략, 커밋, push, conflict 규칙	always-on
02	code	아키텍처 원칙 (스택 중립)	always-on
03	security	STRIDE, 가역성, 에이전트 보안	always-on
04	lifecycle	모드, Gate, Plan Mode, 에스컬레이션	always-on
05	responses	신뢰도 레이블, 완료 보고 형식	always-on
07	db	DB 안전 규칙	on-demand
08	local-env	로컬 개발 환경 보안	on-demand
08	ui-first	UI 자산 우선 원칙	on-demand
09	design	디자인 시스템	on-demand
09	hooks-guide	Hook 활용 가이드	on-demand
10	subagent-patterns	Subagent 활용 패턴	always-on

always-on: 항상 프로젝트 규칙 파일에 포함
on-demand: 해당 작업 시에만 활성화 (DB 작업 → 07-db 로드)

Extensions 분류

분류	예시
프로젝트별	프로젝트 전용 backend/frontend/contract extension
스택별	`backend-fastapi`, `frontend-react`
기능별	`llm-multi-model`, `saas-billing`, `security-ai-defense`

3. 에이전트 팀 & 파이프라인

각 에이전트는 하나의 역할만 수행하고, orchestrator가 순서를 강제합니다.

graph LR
  USER["사용자 요청"] --> PLAN["planner<br/>계획 수립"]
  PLAN --> ARCH["architect<br/>설계"]
  ARCH --> BUILD["builder<br/>구현"]
  BUILD --> QA["qa<br/>검증"]
  QA --> SPEC["spec-reviewer<br/>범위 검증"]
  SPEC --> CODE["code-reviewer<br/>코드 품질"]
  CODE --> SEC["security<br/>보안 감사"]
  SEC --> DONE["완료"]

  ORCH["orchestrator"] -.->|Gate 강제| PLAN
  ORCH -.->|Gate 강제| BUILD
  ORCH -.->|Gate 강제| QA

  INV["investigator"] -.->|오류 2회 시| BUILD
  DES["designer"] -.->|UI 작업 시| ARCH

에이전트 카탈로그

에이전트	역할	투입 시점
planner	INTENT 작성, 작업 분해	새 기능/작업 시작
architect	DESIGN 작성, 상태 전이/API 설계	API 2개+, DB 변경, 서비스 3개+
builder	코드 구현, 버그 수정	planner 승인 후
qa	테스트 작성/실행, FAILURE_LOG 관리	구현 완료 후
spec-reviewer	INTENT 범위 준수, API 계약 검증	PR 생성 전 (1단계)
code-reviewer	STRIDE, 아키텍처, 성능, 코드 품질	PR 생성 전 (2단계)
security	STRIDE 위협 분석, 인증/인가 검증	인증/결제/권한 변경 시
orchestrator	Gate 통과 강제, 소환 순서 관리	파이프라인 전체
investigator	반복 오류 근본 원인 분석	동일 오류 2회 시
designer	디자인 토큰, UI/UX 가이드	UI 변경 시
reviewer	통합 리뷰 (간소화 필요 시)	spec+code 통합

규모별 라우팅

규모	파일 수	경로
Small	3개 이하	builder 직행 (planner 스킵)
Medium	4~15개	표준 파이프라인
Large	16개+	TaskCreate + 병렬 실행

4. Git Flow & 거버넌스

브랜치가 main에 가까울수록 제약이 강해집니다.

graph LR
  F["feature<br/>permissive"] -->|PR 자동 생성+병합| D["develop<br/>moderate"]
  D -->|PR 자동 생성<br/>병합은 수동| M["main<br/>strict"]

  subgraph GATES["Gate 체계"]
    G1["G1<br/>계획 → 설계<br/>의도 확인"]
    G2["G2<br/>설계 → 구현<br/>DESIGN 문서"]
    G3["G3<br/>구현 → 리뷰<br/>lint+type 통과<br/>건너뛰기 불가"]
    G4["G4<br/>리뷰 → 배포<br/>APPROVE+보안"]
  end

  G1 --> G2 --> G3 --> G4

브랜치 안전 수준

브랜치	Preset	merge —no-ff	Plan Mode	Push 승인
feature/*	permissive	허용	선택적	불필요
develop	moderate	허용	20줄+ 자동	불필요
main/master	strict	금지	필수	필수

가역성 등급

등급	의미	에이전트 행동	예시
R0	완전 가역	자동 실행	로컬 파일 수정
R1	제한적 가역	사람 승인 필요	git revert, 브랜치 삭제
R2	비가역	확인 문구 재입력	DROP TABLE, force-push

에이전트 작업 모드

모드	커밋	Push	feature→develop PR	핵심 의도
manual	자동	차단	차단	한 스텝씩 확인
auto	자동	자동	차단	push까지 자동
auto-push	자동	자동	자동 생성+병합	develop까지 자동 (기본)
staging	자동	자동	자동 생성+병합	stg까지 자동
production	자동	자동	자동 생성+병합	main까지 자동
idle	자동	자동	자동 생성+병합	질문 금지, 자율 실행

5. Export / Apply 배포 흐름

source를 수정하면 project adapter output과 runtime target을 별도 경로로 생성합니다.

graph TB
  subgraph INPUT["입력"]
    C["core 규칙"]
    E["extensions 규칙"]
    A["agents 정의"]
    L["layers"]
  end

  P["profiles<br/>runtime layer 조합"]
  AD["adapter export"]
  AP["apply"]

  subgraph ADAPTERS["Project Adapter Output"]
    CC["프로젝트 규칙 파일"]
    AG["에이전트 규칙 파일"]
    CU["에디터별 규칙 디렉토리"]
    CP["코파일럿 instructions"]
  end

  C --> AD
  E --> AD
  A --> AD
  AD --> CC
  AD --> AG
  AD --> CU
  AD --> CP

  L --> AP
  P --> AP
  AP --> RT["Claude / Codex 런타임 홈"]

  CC --> OUT["generated adapters 디렉토리"]
  OUT --> T["타겟 프로젝트"]

CLI 명령

명령	설명
`npm run sync`	output 생성만 (미리보기)
`npm run sync:apply`	실제 프로젝트에 적용
`npm run sync:dry`	변경 diff만 출력

6. Hook 트리거 체계

Hook은 규칙을 강제하는 자동 검증 장치입니다. 에이전트가 규칙을 잊어도 hook이 차단합니다.

graph TB
  subgraph PRE["PreToolUse — 실행 전 차단"]
    GB["guard-branch<br/>보호 브랜치 차단"]
    GS["guard-secrets<br/>시크릿 탐지"]
    GPF["guard-push-force<br/>force push 차단"]
    GR["guard-reversibility<br/>R2 작업 차단"]
    GDB["guard-destructive-db<br/>파괴적 DB 차단"]
  end

  subgraph POST["PostToolUse — 실행 후 감지"]
    LOS["lint-on-save<br/>저장 시 lint"]
    GPM["guide-plan-mode<br/>Plan Mode 권장"]
    GPR["guide-push-report<br/>push 후 보고 형식"]
  end

  subgraph STOP["Stop — 응답 완료 시 감지"]
    DMQ["detect-mid-question<br/>불필요한 질문 감지"]
    DPC["detect-premature-completion<br/>조기 완료 감지"]
  end

  subgraph NOTIFY["Notification"]
    SB["session-bootstrap<br/>세션 초기화"]
  end

Hook 카탈로그

분류	Hook	동작
guard (차단)	guard-branch	보호 브랜치(main/develop) 직접 커밋 차단
guard (차단)	guard-secrets	API 키, 토큰 등 시크릿 하드코딩 차단
guard (차단)	guard-push-force	force push 실행 차단
guard (차단)	guard-reversibility	R2(비가역) 작업 감지 및 확인 요청
guard (차단)	guard-destructive-db	DROP, TRUNCATE 등 파괴적 DB 명령 차단
detect (감지)	detect-mid-question	에이전트의 불필요한 중간 질문 감지
detect (감지)	detect-premature-completion	자가 검증 없이 “완료” 선언 감지
guide (권장)	guide-plan-mode	변경 규모 초과 시 Plan Mode 권장
guide (권장)	guide-push-report	push 후 응답 형식 가이드
기타	lint-on-save	파일 수정 후 자동 lint
기타	session-bootstrap	세션 시작 시 규칙/도구 자동 로드

7. 슬래시 커맨드 카탈로그

/명령어로 워크플로우를 한 번에 실행합니다.

분류	커맨드	설명
계획	`/planning`	Plan Mode 진입 + 분석 + 계획 + 승인
계획	`/design-doc`	ADR/RFC 작성 (G2 게이트 연동)
구현	`/tdd`	RED-GREEN-REFACTOR 순환
구현	`/debugging`	체계적 진단 + stash 스냅샷 + 검증
구현	`/refactoring`	동작 보존 구조 개선
검증	`/code-review`	2단계 리뷰 (spec + code)
검증	`/qa-cycle`	Self-Challenge 표 기반 QA
배포	`/commit`	브랜치 확인 + diff 검토 + 커밋 + push
배포	`/pr-create`	충돌 확인 + 리뷰 + PR 생성
배포	`/sync`	규칙 동기화 (모든 프로젝트)
보고	`/daily-scrum`	일일 현황 리포트
보고	`/weekly-report`	주간 보고서
운영	`/self-improve`	위반 패턴 분석 + 규칙 보강
운영	`/agent-retro`	에이전트 작업 성공/실패 라벨링
지식	`/pkb`	Memory Bank/노트에서 과거 결정 검색
지식	`/pkb-capture`	현재 세션의 핵심 결론을 정리된 후보 노트로 캡처
로그	`/logs`	원본 transcript 증거가 필요할 때만 수동 수집

8. 더 알아보기

주제	문서
하네스 설계 배경	Harness Engineering
에이전트 운영 모델	Agent Operating Model
Git Flow 상세	Git Flow Hygiene
런타임 계약	Runtime Contract
기억과 문서화 역할 분리	Memory & Documentation Policy
실패 학습	WORKLOG & Failure Learning

Source Notes

이 문서는 KeystoneHub 규칙 원천의 아키텍처 개요를 공개용으로 정리한 것입니다. 내부 스크립트 파일명, 프로젝트 전용 extension 이름, 비공개 가이드 링크는 일반화하거나 공개 문서 링크로 대체했습니다. Provenance: keystone-native.