KeystoneHub 쉽게 이해하기

한눈에 보기

KeystoneHub가 무엇이고 왜 필요한지, 운영 루프가 어떻게 도는지를 처음 읽는 사람 기준으로 설명합니다.

• 핵심 질문: 흩어진 에이전트 런타임 설정을 어떻게 하나의 운영 시스템으로 묶는가?
• 읽는 대상: KeystoneHub를 처음 접하는 방문자와 운영자
• 연결 문서: System Architecture, Architecture Overview, Runtime Contract

한 줄 정의

KeystoneHub는 Claude Code와 Codex를 같은 기준으로 운영하기 위한 개인/팀용 AgentOps 레이어입니다. ~/.claude, ~/.codex에 흩어진 skills, hooks, rules, MCP, Memory Bank, 자동 점검 루프를 Git으로 관리하고, OS/회사/머신별 차이를 레이어로 분리합니다.

왜 필요한가

AI 에이전트 환경은 조금만 커져도 다음 문제가 반복됩니다.

• Claude에는 있는데 Codex에는 없는 skill/hook이 생긴다.
• macOS와 Windows 경로가 섞여 설정이 깨진다.
• MCP 서버가 임시로 추가된 뒤 allowlist 없이 남는다.
• Memory Bank, 노트 시스템, plugin cache처럼 런타임 상태가 계속 drift된다.
• 작업 완료 후 커밋, push, main 병합 같은 반복 절차가 저장소마다 다르다.
• 에이전트가 “다 했다”고 말하지만 실제 검증/증거가 부족하다.

KeystoneHub는 이 문제를 “좋은 프롬프트”가 아니라 파일, hook, doctor, scheduler, Git policy로 막습니다.

핵심 모델

KeystoneHub는 세 가지 방향의 흐름을 관리합니다.

방향	명령/루프	의미
Git → Runtime	apply.sh --profile <profile>	레이어 파일을 ~/.claude, ~/.codex로 배포
Runtime → Git	sync.sh --profile <profile>	로컬 런타임 변경을 레이어 후보로 역동기화
Runtime 검증	health loop + doctor	drift를 감지하고 pending/issue/repair 흐름으로 승격

쉽게 말하면:

layers/                       Git에 저장된 의도한 운영 상태
  ↓ apply.sh
~/.claude + ~/.codex          실제 에이전트 런타임
  ↓ doctor / health loop
pending files + GitHub issues 검토/복구가 필요한 신호

레이어 구조

layers/는 이 프로젝트의 중심입니다.

레이어	역할
00-universal	모든 환경 공통 rules, hooks, skills, scripts, settings
10-os-macos	macOS 경로, LaunchAgent, macOS 전용 script
10-os-windows	Windows/Git Bash/Task Scheduler 전용 script
20-company-personal	개인 프로젝트용 skills, agents, memory, rules
20-company-bs	회사 도메인 전용 레이어
30-machine-local	시크릿/머신별 설정 template만 추적

프로파일은 어떤 레이어를 어떤 순서로 적용할지 정합니다.

profiles/personal-macos.txt
00-universal
10-os-macos
20-company-personal
30-machine-local

설정은 아래 순서로 겹쳐집니다.

00-universal → 10-os-{os} → 20-company-{domain} → 30-machine-local

settings.json은 deep merge되고, 일반 파일은 상위 레이어가 덮어씁니다.

주요 구성요소

구성요소	역할
Apply	레이어를 runtime에 배포하고 Claude/Codex parity를 맞춘다
Sync	runtime 변경을 Git 레이어 후보로 가져온다
Doctor	hook, skill, MCP, Memory Bank, scheduler, Git policy 상태를 검사한다
Doctor issue	doctor finding을 GitHub issue/digest로 승격한다
Approved repair	승인된 low-risk 후보만 repair script로 연결한다
Health loop	scheduled repo/runtime 점검과 pending signal 생성
Memory loop	Memory Bank import/export/index 유지
Completion policy	저장소별 자동 commit/push/main merge 정책

자동화 흐름

1. 기본 운영 루프

1. launchd 또는 Task Scheduler가 health loop를 실행한다.
2. doctor가 repo/runtime 배선을 검사한다.
3. sync/apply dry-run으로 양방향 drift를 본다.
4. 문제가 있으면 pending 디렉토리에 JSON signal을 남긴다.
5. 선택적으로 doctor finding을 GitHub issue/digest로 올린다.
6. 승인된 low-risk Keystone-owned 후보만 제한된 repair로 실행한다.

2. GitHub approval 기반 repair

승인 라벨이 있다고 전부 자동 수정하지 않습니다.

후보 유형	자동 적용
auto_apply_allowed=true, scope=keystone-owned	가능
MCP allowlist, external config	불가
Memory Bank/노트/runtime user state	불가
issue-only, pr-only	불가

Digest 이슈는 stale approval을 막기 위해 더 엄격합니다.

• digest 이슈의 승인 라벨은 항목 승인으로 쓰지 않는다.
• fingerprint 없는 /approve 댓글도 항목 승인으로 쓰지 않는다.
• 자동 repair에는 /approve <fingerprint> 댓글만 인정한다.

3. 저장소별 completion git policy

completion 정책 파일이 있는 저장소만 자동 Git 처리가 가능합니다.

• feature/fix/chore/docs/refactor 브랜치에서만 동작
• 검증 명령 통과 필수
• commit 후 branch push
• main으로 ff-only 병합
• origin/main push
• 병합된 작업 브랜치 삭제

이 정책은 다른 저장소로 자동 전파되지 않습니다.

안전장치

KeystoneHub의 안전 모델은 “자동화는 하되, 위험한 경계는 파일로 막는다”에 가깝습니다.

경계	장치
시크릿 유출	로컬 시크릿 파일과 token/secret 경로는 apply/sync/git policy에서 제외
MCP 무분별 추가	MCP allowlist + doctor 검사
외부 레퍼런스 무단 병합	Hue reference upstream에 대한 reference-only 정책, 자동 동기화 scheduler 비활성화
stale approval	digest fingerprint approval 강제
긴 scheduler 실행	health check timeout (기본 300초)
Codex/Claude drift	apply 변환, doctor parity 검사, skill sanitizer
완료 허위 보고	QA/claim/completion 관련 hooks와 repo verification

이 프로젝트가 제공하는 가치

운영자 입장

• “내 AI 개발 환경이 지금 정상인가?”를 doctor 한 번으로 확인할 수 있다.
• 새 머신/OS에서도 같은 profile을 적용하면 비슷한 환경이 재현된다.
• Memory Bank와 Codex/Claude hook drift를 주기적으로 감지한다.
• 반복 실수를 rule/hook/doctor/check로 승격하는 경로가 있다.

외부 솔루션 관점

KeystoneHub는 단순 dotfiles가 아니라 다음 범주의 제품화 가능한 솔루션입니다.

• Agent runtime configuration management
• Claude/Codex parity layer
• AI 작업 품질 gate와 evidence workflow
• Memory-backed self-improvement loop
• Scheduler 기반 drift detection
• GitHub issue 기반 human-approved repair
• 저장소별 completion automation policy

운영자가 기억할 것

1. 새 규칙이나 hook은 먼저 layers/에 넣고 apply로 배포한다.
2. 로컬 runtime에서 바꾼 것은 sync dry-run으로 보고 레이어에 반영한다.
3. MCP나 외부 도구는 allowlist 없이 켜지 않는다.
4. 자동 repair는 low-risk Keystone-owned만 허용한다.
5. digest issue는 /approve <fingerprint>로만 항목 승인한다.
6. 자동 commit/push/merge는 completion 정책 파일이 있는 저장소에서만 실행한다.

한 문장으로 설명하기

“KeystoneHub는 Claude와 Codex를 한 팀처럼 안정적으로 운영하기 위해, 설정 배포, drift 검사, Memory Bank, approval 기반 복구, Git 완료 정책을 하나의 레이어형 AgentOps 시스템으로 묶은 프로젝트다.”

Source Notes

이 문서는 KeystoneHub 내부 운영 문서를 공개용으로 정리한 것입니다. 내부 스크립트 경로와 머신별 식별자는 제거하거나 일반화했고, 외부 레퍼런스 저장소는 Hue reference upstream으로 표기했습니다. Provenance: keystone-native.