07 크로스 도구 동기화 Markdown

Cross-Tool Sync

Claude Code ↔ Codex 양방향 동기화, 멀티OS 배포, $HOME 경로 확장

Source: src/content/docs/cross-tool-sync.md
Order: 8

한눈에 보기

Cross-Tool Sync는 Claude Code, Codex, Cursor가 같은 정책과 실행 표면을 읽도록 맞추는 배포 구조입니다. 핵심은 특정 머신의 절대 경로가 아니라, 레이어와 $HOME 기반 경로로 여러 OS와 도구를 같은 원칙 아래 묶는 것입니다.

핵심 질문: 여러 도구와 OS에서 같은 AI 운영 규칙을 어떻게 유지할 것인가?
읽는 대상: Claude/Codex/Cursor 환경을 함께 운영하려는 사람
연결 문서: Cross-Tool Deployment Guide, System Architecture, Capabilities

이 문서에서 확인할 것

keystone-hub apply 흐름과 레이어 병합 구조
$HOME 경로 확장으로 OS별 차이를 줄이는 방식
Claude commands와 Codex skills를 동기화하는 기준

동기화 전체 흐름

flowchart TD
  K["keystone-hub (Git)"]
  M["apply.sh --profile personal-macos"]
  W["apply.sh --profile personal-windows"]
  L["layers merge<br/>skills, hooks, rules, scripts, agents"]
  S["settings deep merge<br/>$HOME 경로 확장"]
  C["Claude commands<br/>~/.claude/commands"]
  X["Codex skills<br/>~/.codex/skills 자동 변환"]
  U["cc-sync upstream"]
  P["/upstream-sync"]
  R["flat to layered 매핑<br/>keystone-hub 흡수"]

  K --> M --> L --> S --> C --> X
  K --> W --> L
  U --> P --> R --> K

apply.sh가 하는 일

단계	동작
1. Layer merge	00-universal → 10-os-* → 20-company-* → 30-machine-local 순서로 덮어쓰기
2. Settings merge	hooks 배열은 합산, 스칼라는 상위 레이어 우선 (Python deep merge)
3. Path expansion	settings.json 내 `$HOME` → 실제 home 디렉토리로 치환
4. Stale cleanup	폐기된 hook 자동 제거
5. Commands sync	ai-rules/.claude/commands/ → ~/.claude/commands/ 복사
6. Codex sync	Claude skills + commands → ~/.codex/skills/ SKILL.md 변환
7. Tools check	bun, node, clawd-on-desk 설치 여부 확인

경로 포터블화

settings.json 소스에서 절대 경로 대신 $HOME/을 사용:

// 레이어 소스 (keystone-hub)
"command": "$HOME/.claude/hooks/qa-gate-before-push.sh"

// apply.sh 적용 후 (macOS)
"command": "/Users/choa712-mac/.claude/hooks/qa-gate-before-push.sh"

// apply.sh 적용 후 (Windows Git Bash)
"command": "/c/Users/username/.claude/hooks/qa-gate-before-push.sh"

새 사용자가 clone + apply.sh 실행만 하면 자동으로 올바른 경로가 설정됩니다.

Claude ↔ Codex 스킬 동기화

Claude Code	Codex CLI
`~/.claude/skills/*/SKILL.md`	`~/.codex/skills/*/SKILL.md`
`~/.claude/commands/*.md`	`~/.codex/skills/*/SKILL.md` (디렉토리 변환)
`/skill-name`으로 호출	`$skill-name`으로 호출

apply.sh가 자동으로:

Claude skills 디렉토리를 Codex에 복사 (SKILL.md 있는 것만)
Claude commands (.md 단일 파일)를 Codex skills (디렉토리/SKILL.md) 구조로 변환

신규 셋업 (한 줄)

git clone <keystone-hub> ~/lucy/keystone-hub
git clone <ai-rules> ~/lucy/ai-rules
cd ~/lucy/keystone-hub && ./apply.sh --profile personal-macos

이후 업데이트:

cd ~/lucy/keystone-hub && git pull && ./apply.sh --profile personal-macos