cclayer로 여러 컴퓨터 간 Claude Code 설정(CLAUDE.md, skills, 플러그인, MCP) 동기화하고 팀별로 git 신원 분리하기

Claude Code를 오래 쓰다 보면 ~/.claude 아래에 이것저것 쌓입니다. 전역 CLAUDE.md, 각종 rules, skills, hooks, settings.json의 권한과 플러그인, 그리고 MCP 서버 한 무더기까지요. 저는 평소 여러 대의 컴퓨터에서 Claude Code를 쓰는데, 컴퓨터마다 처음부터 다시 설정해야 했습니다. 한 대에서 규칙을 조금 바꾸면 나머지 컴퓨터에서도 직접 똑같이 고쳐야 했고, 시간이 지나면 컴퓨터마다 설정이 서로 어긋나 있었습니다.

더 골치 아픈 건 프로젝트가 여러 팀에서 온다는 점입니다. 팀마다 git 커밋 신원(사용자 이름, 이메일)이 다르고, 자체 규칙과 hook을 가진 팀도 있습니다. 이런 건 그 팀의 프로젝트 안에서만 적용돼야 하고 다른 프로젝트에 섞이면 안 됩니다. 회사 이메일로 제 오픈소스 저장소에 커밋하는 일은 더더욱 없어야 하고요.

그렇다고 ~/.claude를 통째로 git 저장소에 넣을 수도 없습니다. 로그인 상태, 세션 기록, 이 컴퓨터 전용 권한 설정이 들어 있고, 팀 관련 내용은 공개 저장소에 둘 수 없으니까요. 그래서 이 문제를 해결하려고 cclayer를 만들었습니다.

cclayer란

cclayer는 Claude Code 설정을 두 종류의 “레이어”로 나눕니다.

• 기본 레이어: 모든 컴퓨터에서 똑같은 것들. CLAUDE.md, rules/, skills/, output-styles/, agents/, hook 스크립트, settings.json의 공유 키, 플러그인과 marketplace 목록, MCP 정의. 신원 정보가 전혀 없어서 공개 저장소에 둘 수 있습니다.
• 오버레이: 팀마다 하나씩. 그 팀의 git 신원, hook, 저장소 주소 규칙(예: github.com/acme-inc/*), 그리고 해당 프로젝트에 써 넣을 .claude/settings.local.json과 CLAUDE.local.md를 둡니다. 오버레이는 일치하는 프로젝트에서만 적용되고 ~/.claude에는 아무것도 쓰지 않습니다.

각 컴퓨터는 기본 레이어와 필요한 오버레이만 받아 오고, cclayer apply 한 줄로 전부 깔고, cclayer push 한 줄로 로컬 변경 사항을 다시 올립니다.

레이어는 git 저장소여도 되고, 클라우드 드라이브 동기화 폴더 안의 디렉터리여도 됩니다. git을 쓰고 싶지 않아도 사용할 수 있습니다.

설치

macOS에서는 Homebrew를 씁니다.

1
brew install --cask zhaojiannet/tap/cclayer

나중에 업그레이드할 때:

1
brew upgrade --cask cclayer

Linux와 Windows는 Releases 페이지에서 바이너리를 내려받으면 됩니다. git이 먼저 설치되어 있어야 하고, 플러그인과 MCP 단계는 Claude Code 2.1.288 이상이 필요합니다.

가장 간단한 사용법: 혼자서 컴퓨터 몇 대

나눠야 할 팀이 없다면 기본 레이어 하나면 충분합니다.

첫 번째 컴퓨터

1
cclayer setup

setup은 전체 화면 설정 인터페이스입니다. 왼쪽에는 각 레이어와 이 컴퓨터의 설정이, 오른쪽에는 선택한 항목의 설명과 수정 가능한 필드가 나오고, 저장을 누르기 전까지는 어떤 파일도 쓰지 않습니다. 화면 언어는 중국어 간체, 영어, 일본어를 지원하며 기본값은 시스템 언어를 따릅니다.

입력할 건 두 가지뿐입니다.

1. 기본 레이어: 디렉터리(예: 클라우드 드라이브 안의 ~/Dropbox/cclayer/base)나 비공개 git 저장소 주소를 넣습니다. 디렉터리가 아직 없으면 저장할 때 시작용 layer.toml이 자동으로 만들어집니다.
2. 프로젝트 디렉터리: 코드를 두는 디렉터리. 예: ~/Projects.

“저장 후 적용”을 고른 다음, 이 컴퓨터에 있던 설정을 레이어로 가져옵니다.

1
cclayer capture --add CLAUDE.md --add rules/ --add skills/

경로는 ~/.claude 기준 상대 경로입니다. 가져오기 전에 파일마다 검사를 거치는데, 비밀 키, 이메일, 홈 디렉터리를 가리키는 절대 경로 같은 것은 차단되고 몇 번째 줄에 있는지 알려 줍니다. 혼자만 쓰고 레이어도 비공개 위치에 둔다면 layer.toml의 [layer] 아래에 private = true 한 줄을 추가하면 이메일은 더 이상 차단하지 않습니다.

다른 컴퓨터

cclayer를 설치하고 똑같이 cclayer setup을 실행해 기본 레이어에 같은 주소를 넣고 “저장 후 적용”을 하면 첫 번째 컴퓨터의 설정이 그대로 넘어옵니다. 로컬에 이미 있는데 내용이 다른 파일은 목록으로 보여 주고 덮어쓸지 물어보며, 덮어쓰기 전에 기존 파일은 ~/.local/state/cclayer/backups/에 백업됩니다.

평소 동기화

git 저장소를 레이어로 쓰는 경우:

1
cclayer push          # 업로드: 로컬 변경 사항을 모아 커밋할 내용을 보여 주고, 확인 후 커밋하고 푸시
2
cclayer apply --pull  # 다운로드: 최신 레이어를 풀한 뒤 로컬에 적용

클라우드 드라이브 디렉터리를 레이어로 쓰는 경우에는 동기화는 클라우드 드라이브가 맡으니, 수정한 뒤 cclayer capture를 실행하고 다른 컴퓨터에서 cclayer apply를 실행하면 됩니다.

아래 SessionStart hook을 기본 레이어의 claude/settings.json에 넣고 setup에서 “자동 풀”을 켜 두면, 이후 Claude Code 세션을 열 때마다 자동으로 풀하고 적용합니다.

1
{
2
  "hooks": {
3
    "SessionStart": [{
4
      "matcher": "startup",
5
      "hooks": [{ "type": "command", "command": "command -v cclayer >/dev/null && cclayer apply --hook || true" }]
6
    }]
7
  }
8
}

팀마다 다른 git 신원 설정하기

이게 제가 cclayer를 만든 주된 이유입니다. 먼저 팀용 비공개 저장소를 만들고 루트에 layer.toml을 두어 신원과 일치시킬 저장소를 적습니다.

1
[layer]
2
name = "acme"
3
kind = "overlay"
4

5
[identity]
6
name = "Full Name"
7
email = "me@acme.example"
8

9
[[match]]
10
remote = "github.com/acme-inc/*"

그다음 필요한 컴퓨터에서 이 오버레이를 추가합니다. 저장소 접근 자격 증명을 어떻게 설정할지 물어본 뒤 clone해서 한 번 검사합니다.

1
cclayer layer add acme git@github.com:you/cclayer-acme.git

apply하고 나면 cclayer는 ~/.gitconfig 끝에 include 블록을 추가하고, git의 includeIf "hasconfig:remote.*.url:..."를 이용해 원격 주소가 github.com/acme-inc/*와 일치하는 저장소에서만 이 신원이 적용되게 합니다. ~/.gitconfig의 기존 내용은 전혀 건드리지 않습니다. 기본 신원(default_identity)을 비워 두면 어떤 오버레이와도 일치하지 않는 저장소에서는 git이 커밋을 거부하므로, 엉뚱한 이메일로 커밋하는 일이 다시는 생기지 않습니다.

일치 규칙에는 호스트와 조직을 명시해야 하고 와일드카드로 대신할 수 없습니다. 한 팀의 오버레이가 다른 팀의 저장소까지 가져가는 일을 막기 위해서입니다.

팀마다 Claude Code 로그인, 세션, 프롬프트 기록까지 완전히 나누고 싶다면 profiles 모드를 켜면 됩니다. 각 오버레이가 자기만의 ~/.claude-profiles/<레이어 이름> 설정 디렉터리를 갖게 되고, cclayer env가 해당하는 CLAUDE_CONFIG_DIR를 출력하므로 direnv와 함께 쓰면 들어가는 프로젝트에 맞는 설정이 자동으로 쓰입니다.

보안 처리

동기화된 hook과 skills는 로컬에서 Claude Code가 실행하기 때문에, cclayer는 이 부분에서 꽤 신중합니다.

• hooks, statusLine, enabledPlugins처럼 프로그램을 실행하거나 플러그인을 켜는 설정, 그리고 hooks/, skills/ 아래 파일과 실행 권한이 있는 파일은 쓰기 전에 내용을 보여 주고 확인을 받습니다. 같은 내용은 한 번 확인하면 다시 묻지 않습니다.
• git 설정 조각은 pull.rebase, push.default 같은 흔한 설정만 허용합니다. alias, core.hooksPath, credential.helper처럼 프로그램을 실행할 수 있는 키는 기기 목록에서 해당 레이어를 명시적으로 신뢰해야만 쓸 수 있습니다.
• Claude Code의 로그인 상태, history.jsonl, projects/는 레이어로 읽어 들이지 않고, permissions.allow와 env는 로컬에 남습니다.
• 레이어 안에는 심볼릭 링크를 둘 수 없고, 파일을 쓸 때도 심볼릭 링크를 따라가지 않습니다.

자주 쓰는 명령어

git 저장소 만드는 법, 비공개 저장소 자격 증명, 자주 묻는 질문 등 더 자세한 사용법은 cclayer 튜토리얼(영어)을 참고하세요.

GitHub 프로젝트 주소: https://github.com/zhaojiannet/cclayer