Claude Code 스킬과 설정을 DB로 옮기기: 어느 기기에서나 같은 하네스

Claude Code로 일을 오래 하다 보면 ~/.claude 폴더가 점점 무거워집니다. 저는 스킬 26개와 설정 7개가 컴퓨터 한 대의 폴더 안에 쌓여 있었습니다. 블로그 문체 규칙, 메일 초안을 만드는 절차, 앱 출시 순서처럼 몇 달에 걸쳐 고쳐 온 것들입니다.

문제는 그 폴더 밖에서 드러났습니다. 같은 계정으로 휴대폰에서 Claude를 열면 그 스킬을 하나도 쓸 수 없었습니다. 새 컴퓨터를 준비하는 일은 그 폴더를 기억해서 다시 만드는 일이었고, 두 기계에서 같은 스킬을 따로 고치면 어느 쪽이 맞는지 알 길이 없었습니다. 그래서 스킬과 설정의 정본을 파일에서 사내 문서 시스템의 데이터베이스로 옮기고, 각 기기는 MCP 커넥터를 통해 그 정본을 받아 쓰도록 바꿨습니다.

파일 하나가 문서 하나, 본문은 파일 그대로

처음 정한 원칙은 변환하지 않는다는 것이었습니다. SKILL.md 하나가 문서 하나가 되고, 본문은 frontmatter까지 파일 내용 그대로 들어갑니다. 스킬에 딸린 참고 문서나 스크립트는 <스킬 이름>/<경로>를 제목으로 하는 문서가 됩니다. 이렇게 하면 한 폴더에 모아도 이름이 부딪치지 않습니다.

변환하지 않는 이유는 비교 때문입니다. 받은 사본의 지문과 데이터베이스 본문이 한 글자라도 다르면, 누가 어디서 고쳤는지 따질 수가 없습니다. 그래서 동기화 도구는 서버가 쓰는 것과 같은 방식으로 각 기기에서도 지문을 계산하고, 기록 없이 로컬에서 고쳐진 파일을 그 자리에서 찾아냅니다.

실행 파일에는 태그를 붙여 받을 때 실행 권한을 다시 붙이게 했습니다. 이미지 같은 바이너리는 본문에 넣지 않고, 저장소 주소와 sha256, 바이트 수만 적었습니다. 옮긴 뒤 스킬 파일 56개를 빈 홈 폴더에 다시 받아 원본과 비교해 보았고, 실행 권한까지 바이트 단위로 같았습니다.

받기는 자동, 실행되는 것은 받을 때도 확인

보통의 동기화는 받기를 자동으로 하고 올리기를 확인합니다. 저도 그렇게 시작했는데, 훅과 권한 규칙에서 멈췄습니다.

훅은 Claude Code가 도구를 쓰기 전후나 세션이 시작될 때 실행하는 셸 명령입니다. 휴대폰이나 웹 화면에서 고친 훅이 확인 없이 모든 컴퓨터에 내려가 실행된다면, 그것은 동기화가 아니라 원격 실행입니다. 그래서 실행되는 것만은 받을 때도 한 번 더 묻도록 했습니다. 스킬 본문은 자동으로 받고, 훅과 settings.json은 차이를 보여 준 뒤 승인해야 받습니다.

settings.json은 통째로 올리지 않았습니다. 다른 앱이 기기마다 자기 훅을 써 넣는 경우가 있어서, 관리하는 부분만 정본에 두고 기기 고유의 부분은 받을 때 다시 얹습니다. 훅 명령에 들어가는 홈 경로는 $HOME으로 바꿨습니다. 기기마다 사용자 이름이 달라도 같은 파일이 그대로 동작해야 하기 때문입니다.

비밀값처럼 보이는 줄(키, 토큰, 개인 키, 긴 hex나 base64 문자열)이 있는 파일은 아예 올리지 않습니다. 이때도 값은 화면에 찍지 않고, 몇 번째 줄인지만 알려 줍니다.

휴대폰에는 읽기 도구 두 개면 충분했던 구조

휴대폰과 웹의 Claude는 셸이 없으니, 파일을 받는 대신 MCP 커넥터로 스킬을 직접 읽게 했습니다. 도구는 두 개만 더했습니다. skill_list는 스킬마다 이름과 설명, 어디서 쓸 수 있는지를 돌려주고, skill_get은 본문과 딸린 파일 목록을 돌려줍니다. 커넥터 안내문에는 「작업이 스킬에 맞으면 목록에서 고르고 읽은 뒤 그대로 따른다」는 한 줄을 넣었습니다.

MCP에는 prompts라는 기능도 있지만 쓰지 않았습니다. 클라이언트마다 지원이 다른데, 도구 호출은 어디서나 되기 때문입니다.

까다로운 쪽은 휴대폰에서 끝까지 해낼 수 없는 스킬이었습니다. 처음에는 스킬에 스크립트 파일이 있는지만 보고 컴퓨터 전용 여부를 정했습니다. 그런데 스크립트 파일 없이 본문 전체가 셸 명령인 스킬이 표시 없이 빠져나가고 있었습니다. 그래서 스킬마다 직접 따져서 태그를 다시 붙였습니다. 어디서나 되는 것이 6개, 일부 단계만 컴퓨터가 필요한 것이 4개, 컴퓨터 전용이 15개였습니다. 컴퓨터 전용 스킬을 휴대폰에서 읽으면 skill_get이 맨 위에 「여기서는 시작하지 말고 사용자에게 말한다」를 붙여 줍니다.

컴퓨터 전용이던 스킬 일부는 이참에 옮길 수 있었습니다. 셸 스크립트가 하던 일을 서버 쪽 MCP 도구로 바꾸자, 박람회 일정 넣기나 거래처 정보 갱신 같은 스킬이 휴대폰에서도 처음부터 끝까지 되었습니다.

클라이언트 스크립트에 있던 안전장치의 서버 이전

문서를 저장하고 발행하던 CLI가 하나 있었습니다. 1,223줄짜리였고, 데이터베이스에 직접 붙어 일했습니다. 이 CLI는 몇 가지 규칙도 지키고 있었습니다. 본문에 옛 주소의 링크가 남아 있으면 발행하지 않는 것, 같은 제목으로 발행 중인 글이 있으면 새로 만들지 않는 것 같은 규칙입니다.

이 규칙들은 그 CLI를 거칠 때만 걸렸습니다. 휴대폰에서 MCP로 같은 일을 하면 아무것도 막지 않았습니다. 그래서 CLI가 하던 일을 MCP 도구로 옮기면서 안전장치도 함께 서버로 옮겼습니다. 이제 어느 클라이언트에서 부르든 같은 규칙이 걸립니다. CLI에는 컴퓨터의 파일을 다루는 명령 두 개만 남았고, 문서 시스템의 MCP 도구는 26개에서 39개가 되었습니다.

덮어쓰는 도구는 모두 버전을 받게 했습니다. 읽을 때 받은 버전과 지금 버전이 다르면 저장하지 않고 409를 돌려줍니다. 휴대폰과 컴퓨터에서 같은 스킬을 동시에 고쳐도, 늦게 저장하는 쪽이 앞의 수정을 조용히 지우지 못합니다.

반대로 일부러 열지 않은 것도 있습니다. 사업용 AI 비서에도 MCP 서버 목록이 있는데, 거기에는 이 문서 시스템을 넣지 않았습니다. 넣으면 스킬을 읽는 것뿐 아니라 메일 보내기 도구까지 비서에게 열리기 때문입니다. 커넥터는 기능 단위로 나뉘어 있고, 도구를 하나 더하는 순간 그 커넥터를 가진 모든 곳에 같은 권한이 생깁니다. 저는 이 점이 MCP 커넥터를 나눌 때 가장 먼저 따져야 할 기준이라고 봅니다.

옮기다 발견한, 돌지 않던 훅

옮기는 작업에서 가장 쓸모 있었던 것은 사실 이 대목입니다. 설정 파일에는 세션이 시작될 때 설계 지침을 맥락에 넣는 훅과, 스키마를 바꾼 커밋을 한 번 멈춰 세우는 설계 리뷰 관문이 등록되어 있었습니다. 그런데 그 훅이 부르는 스크립트 파일이 실제로는 없었습니다. 설정은 그 스크립트가 있다고 믿고 있었고, 저도 그렇게 믿고 있었습니다.

훅은 스크립트를 찾지 못해도 작업을 멈추지 않습니다. 그래서 지침이 들어가지 않은 세션과 관문을 거치지 않은 커밋이 아무 경고 없이 이어지고 있었습니다. 파일을 하나하나 정본으로 옮기며 「이 설정이 부르는 파일이 어디 있나」를 확인하다가 처음 알았습니다. 반대로 비밀값 노출을 막는 훅은 정본 어디에도 없이 그 컴퓨터 한 대에만 있었습니다. 그 컴퓨터를 정리했다면 그대로 사라졌을 것입니다.

설정이 흩어져 있을 때는 이런 것이 보이지 않습니다. 「이 기계에만 있는 것」과 「있다고 적혀만 있는 것」이 같은 폴더 안에 섞여 있기 때문입니다. 정본을 한 곳에 두고 빈 홈 폴더로 다시 받아 보는 시험이, 무엇이 실제로 있는지 확인하는 가장 확실한 방법이었습니다.

아직 확인하지 못한 부분

휴대폰 앱이 정말 스킬 목록부터 부르는지는 아직 확인하지 못했습니다. 도구와 안내문은 준비했지만, 커넥터 안내문을 따를지는 클라이언트가 정합니다. 「할 일 보여줘」처럼 어디서나 되는 요청과 「앱 출시해줘」처럼 컴퓨터 전용인 요청을 실제로 넣어 보고, 앞의 것은 끝까지 하는지, 뒤의 것은 시작하지 않고 말하는지 보려고 합니다.

다음으로는 스킬과 설정 바깥의 하네스, 그러니까 세션별 역할과 리뷰·검증 흐름도 같은 방식으로 구조화하려고 합니다. 스킬을 옮기며 배운 원칙, 그러니까 변환하지 않기와 실행되는 것은 받을 때도 확인하기가 거기서도 그대로 통할지가 가장 궁금한 부분입니다.