Cross-Tool Deployment Guide

한눈에 보기

Cross-Tool Deployment Guide는 ai-rules sync와 keystone-hub apply가 함께 움직이는 배포 흐름을 설명합니다. 프로젝트 안의 정책 파일과 사용자 홈 디렉터리의 런타임 표면을 분리하되, Claude Code, Codex, Cursor가 같은 guardrail 아래에서 작동하도록 맞춥니다.

• 핵심 질문: 정책 배포와 런타임 배포를 어떻게 분리하고 다시 연결할 것인가?
• 읽는 대상: 여러 AI 개발 도구를 같은 운영 기준으로 맞추려는 사람
• 연결 문서: Cross-Tool Sync, ai-rules x keystone-hub Guide, Commands & Guardrails

이 문서에서 확인할 것

• ai-rules sync가 프로젝트 정책 산출물을 만드는 과정
• keystone-hub apply가 사용자 런타임을 구성하는 과정
• overwrite, ifNotExists, mergeJson을 나누는 쓰기 전략

두 개의 배포 파이프라인

ai-rules sync는 프로젝트 규칙을 생성하고, keystone-hub apply는 사용자 도구 환경을 구성합니다. 둘은 서로 다른 대상을 다루지만, 목표는 같습니다. Claude Code, Codex, Cursor 같은 도구가 같은 운영 원칙을 읽고 같은 guardrail 아래에서 움직이게 만드는 것입니다.

sequenceDiagram
  participant Rule as ai-rules source
  participant Sync as sync.mjs
  participant Output as output/project
  participant Project as target project
  participant Hub as keystone-hub
  participant Runtime as ~/.claude / ~/.codex

  Rule->>Sync: core + extensions + agents + profile
  Sync->>Output: adapter output 생성
  Output->>Project: --apply로 프로젝트에 배포
  Hub->>Hub: profile layer merge
  Hub->>Runtime: hooks, skills, commands, settings 배포
  Project-->>Runtime: 프로젝트 정책과 런타임 guardrail이 만남

ai-rules sync

단계	설명
Source	core/, extensions/, agents/, agents-ext/
Profile	프로젝트별 YAML이 어떤 블록을 포함할지 결정
Adapter	Claude Code, Cursor, Windsurf, OpenClaw, governance, tooling 형식으로 변환
Output	중간 산출물을 만든 뒤 필요하면 target project로 적용

핵심 규칙은 간단합니다. 자동 생성물은 직접 수정하지 않고, 항상 원천 파일을 수정한 뒤 다시 sync합니다.

keystone-hub apply

flowchart LR
  U["00-universal<br/>공통 hooks/skills/rules"] --> O["10-os-*<br/>OS별 경로와 도구"]
  O --> C["20-company-*<br/>회사/개인 워크플로우"]
  C --> L["30-machine-local<br/>시크릿 템플릿"]
  L --> R["runtime<br/>~/.claude / ~/.codex"]

레이어	포함할 것	포함하지 않을 것
00-universal	어떤 머신에서도 안전한 공통 hook, skill, rule	특정 회사나 OS 경로
10-os-*	macOS/Windows 경로, shell 차이, statusline	도메인 지식
20-company-*	회사/개인별 agent, workflow, memory	토큰과 계정 비밀값
30-machine-local	템플릿과 로컬 전용 파일	git에 올라갈 실제 secret

쓰기 전략

전략	대상	운영 의미
overwrite	생성된 hook, agent, rule	원천 저장소가 정본
ifNotExists	husky, commitlint, lint-staged	프로젝트 커스터마이징 허용
mergeJson	.claude/settings.json	기존 설정 보존 + hook union

직접 수정해도 되는 파일과 안 되는 파일을 구분하는 것이 중요합니다. overwrite 대상은 다음 sync/apply에서 덮입니다.

충돌을 줄이는 원칙

• CLAUDE.md 같은 프로젝트 정책 파일은 ai-rules가 관리한다.
• 홈 디렉터리 runtime hooks와 settings는 keystone-hub가 관리한다.
• 머신별 시크릿은 settings.local.json 또는 local layer에 둔다.
• $HOME 같은 포터블 경로를 쓰고, 절대 사용자 경로를 문서에 남기지 않는다.
• 공개 가이드는 명령 이름과 역할만 설명하고 개인 경로는 제거한다.

운영 체크리스트

1. 정책 변경이면 ai-rules 원천을 수정한다.
2. 도구 실행 표면 변경이면 keystone-hub 레이어를 수정한다.
3. 변경 전 dry-run이나 diff로 적용 범위를 본다.
4. settings merge가 hook을 중복 등록하지 않는지 확인한다.
5. 새 hook은 replay fixture나 최소 검증 명령을 둔다.
6. 공개 문서에는 “왜 필요한가”와 “어디까지 공개 가능한가”를 남긴다.

배포 후 확인

확인	질문
Rule parity	Claude, Cursor, Codex가 같은 원칙을 읽는가?
Runtime parity	Claude hooks와 Codex skills가 같은 의도를 실행하는가?
Secret boundary	local-only 값이 git과 공개 문서 밖에 있는가?
Recovery	잘못 적용했을 때 되돌릴 경로가 있는가?
Evidence	build, hook, doctor, QA 결과가 남았는가?

Source Notes

이 문서는 ai-rules의 Sync Operations와 keystone-hub의 README, apply profile, layer design을 기반으로 작성했습니다.