최근 AI 에이전트(AI Agent) 도구의 선택지가 늘어나면서, Claude Code뿐만 아니라 Codex나 Cursor 등 여러 도구를 사용하게 되었습니다. 하지만 도구마다 설정 파일의 위치가 제각각이라, 동일한 내용을 각각의 파일에 일일이 옮겨 적어야 합니다. 다른 AI 에이전트로 전환했을 때 rule이나 skill이 반영되어 있지 않아 작업을 다시 해야 하는 경우도 있었습니다.

이 문제를 해결할 수 없을까 고민하던 중, X에서 우연히 발견한 것이 rulesync라는 CLI 도구였습니다.

rulesync란

rulesync는 .rulesync/ 디렉토리에 작성한 내용을 정본(Source of Truth)으로 하여, 각 AI 에이전트 도구용 설정 파일을 생성해 주는 CLI 도구입니다.

예를 들어 Claude Code, Codex, Cursor 세 가지를 사용하여 작업하고 있다면, skill은 다음 경로에 두게 됩니다.

• Claude Code → .claude/skills/<name>/SKILL.md
• Codex → .agents/skills/<name>/SKILL.md
• Cursor → .cursor/skills/<name>/SKILL.md

내용은 동일한 파일입니다. 위치만 다를 뿐이기에, skill을 하나 수정할 때마다 세 곳을 복사하여 붙여넣어야 합니다. rule(CLAUDE.md나 AGENTS.md)에서도 같은 일이 발생합니다.

rulesync를 사용하면 작성하는 곳은 .rulesync/ 한 곳뿐입니다. rulesync generate를 한 번 실행하면 이러한 경로들에 각각의 형식으로 배포해 주므로, 수정은 .rulesync/ 쪽에서만 하면 됩니다.

rulesync가 없다면 내용이 같은 SKILL.md를 세 곳에 두어야 하며, 하나를 수정할 때마다 세 곳 분량의 복사 붙여넣기가 발생합니다. rulesync가 있다면 .rulesync/에 한 곳만 작성하고 명령어를 한 번 실행하는 것만으로 각 도구의 경로로 자동 배포됩니다.

배포할 수 있는 것은 rule뿐만이 아닙니다. rulesync는 배포하는 대상의 종류를 「feature」라고 부르며, 주로 다음 8가지 종류가 준비되어 있습니다.

즉, rule뿐만 아니라 MCP 서버 설정이나 hooks와 같이 「도구마다 다시 작성하기 번거로운 것들」을 모두 .rulesync/ 쪽으로 모을 수 있습니다. 이 기사의 설정 예제에서 사용하는 것은 이 중 rules와 skills 두 가지입니다.

지원하는 도구 또한 Claude Code, Codex, Cursor뿐만 아니라 GitHub Copilot, Cline, Roo Code, OpenCode, Zed 등 30종 이상이 있습니다. 다만 도구마다 지원하는 feature에는 차이가 있으므로, 공식 리포지토리(Repository)의 README에 있는 대응표를 확인하는 것이 확실합니다.

도입 절차

도입은 6단계입니다. 이후 절차는 이 순서대로 진행합니다.

1. 설치

npm 또는 Homebrew로 설치할 수 있습니다 (그 외에 싱글 바이너리 배포도 있습니다).

# npm: 해당 프로젝트 내에서만 사용하는 경우
npm install -D rulesync
# npm: 어느 디렉토리에서든 사용할 수 있게 하는 경우
...

npm의 -D를 사용하면 프로젝트의 devDependencies에 포함되며, npx rulesync나 npm script를 통해 호출합니다. -g와 Homebrew는 머신 전체에 설치되므로, package.json이 없는 리포지토리에서도 바로 rulesync를 입력하여 사용할 수 있습니다.

-D로 설치하는 경우에는 npm scripts를 함께 준비해 두면 호출하기가 더 편리합니다.

{
"scripts": {
"rules:generate": "rulesync generate",
...

2. 초기화하기

rulesync init

.rulesync/ 디렉토리와 설정 파일인 rulesync.jsonc의 템플릿이 생성됩니다. 설정은 예를 들어 다음과 같습니다.

{
"$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/config-schema.json",
"targets": ["claudecode", "codexcli", "cursor", "opencode"],
...

• targets: 배포 대상 도구입니다.
• features: 배포할 종류입니다. 여기서는 rule과 skill 두 가지만 지정되어 있습니다.
• outputRoots: 생성 대상 루트 디렉토리입니다.
• delete: 생성 전에 출력 대상의 기존 파일을 삭제합니다. .rulesync/에서 삭제된 항목이 생성 대상 위치에도 남지 않습니다.
• gitignoreTargetsOnly: rulesync gitignore 명령어가 .gitignore에 기록하는 대상을 targets에 나열된 도구로만 제한합니다.

이와 함께, rule의 샘플로서 .rulesync/rules/overview.md가 생성됩니다. 내용은 다음과 같은 frontmatter로 시작합니다.

---
root: true
targets: ["*"]
...

여기서 핵심적인 역할을 하는 것은 root입니다. rule은 이 값에 따라 출력 위치가 달라집니다.

root: true인 rule은 리포지토리 최상단(root)에 출력되며 항상 로드됩니다. 이는 단 하나만 둘 수 있습니다. root: false인 rule은 도구별 rule 디렉토리에 출력되며, globs 패턴과 일치할 때만 로드됩니다.

overview라는 파일명 자체에는 의미가 없습니다. rulesync init이 만드는 템플릿의 이름이 그럴 뿐이며, rulesync add rule --name <이름>으로 추가한 rule은 루트가 아닌 rule이 됩니다.

루트가 아닌 rule에는 globs를 사용하여 "이 파일을 다룰 때만 로드한다"라는 조건을 붙일 수 있습니다. 항상 적용하고 싶은 전체 방침은 루트 rule에, 특정 작업에서만 적용하고 싶은 내용은 그 외의 rule에 두는 방식으로 구분하여 사용합니다.

3. 공식 skill 추가하기

rulesync는 자신의 사용법을 정리한 skill을 공식적으로 배포하고 있습니다. README에서도 권장 사항으로 안내하고 있으므로 설치해 두는 것이 좋습니다.

rulesync fetch dyoshikawa/rulesync --features skills

.rulesync/skills/rulesync/ 디렉토리에 SKILL.md와 각 기능의 레퍼런스(cli-commands.md, configuration.md, file-formats.md 등)가 들어갑니다. 이것이 있으면 rulesync 조작을 AI 에이전트에게 맡겼을 때, 명령어 형식이나 설정 항목을 사용자가 직접 찾아보고 알려줄 필요가 없습니다.

4. 기존 설정 가져오기

이미 CLAUDE.md 등을 작성해 두었다면, 처음부터 .rulesync/ 형식으로 다시 쓸 필요는 없습니다. import 명령어가 기존 설정 파일을 .rulesync/ 형식으로 변환하여 수집해 줍니다.

rulesync import --targets claudecode # CLAUDE.md에서 가져오기
rulesync import --targets cursor # Cursor의 규칙 설정에서 가져오기
rulesync import --targets codexcli # AGENTS.md에서 가져오기

import는 generate의 역방향입니다. 도구별로 파편화되어 성장해온 설정들을 .rulesync/ 하위로 한데 모아 집약할 수 있습니다. 이후에는 이곳만 수정하고 generate를 통해 각 도구로 다시 배포합니다.

5. 각 도구로 배포하기

rulesync generate

rulesync.jsonc에서 지정한 targets와 features에 따라 파일이 생성됩니다. 위의 설정이라면 다음 파일들이 출력됩니다.

• CLAUDE.md, AGENTS.md (리포지토리 루트)
• .cursor/rules/*.mdc
• .claude/skills/, .agents/skills/, .cursor/skills/, .opencode/skills/

Cursor용 .mdc 파일에는 globs: **/*라는 frontmatter가 자동으로 붙어 항상 읽히는 형태가 됩니다. 도구별 서식(format)의 차이는 rulesync가 흡수해주므로, 사용자가 직접 신경 쓸 필요는 없습니다.

일부만 업데이트하고 싶을 때는 -t (--targets)와 -f (--features)로 대상을 지정합니다.

rulesync generate --targets cursor --features rules

6. 생성된 파일을 직접 편집하지 않도록 하기

생성된 CLAUDE.md나 AGENTS.md를 직접 편집하더라도, 다음 generate 실행 시 덮어쓰여져 사라집니다. 따라서 "생성된 파일은 편집하지 않는다. 수정할 때는 반드시 .rulesync/를 수정한다"를 프로젝트 규칙으로 명문화합니다.

기계적인 탐지를 위해서는 rulesync generate --check (npm run rules:check로 미리 준비한 것)를 사용합니다. 원본(source of truth)과 생성된 파일의 내용이 일치하지 않을 경우 종료 코드 1로 실패하므로, .pre-commit-config.yaml에 등록해두면 커밋 시점에 차이를 인지할 수 있습니다.

repos:
- repo: local
hooks:
...

원본과 생성된 파일 사이의 불일치는 커밋 시점에 자동으로 탐지할 수 있습니다.

도입 후 무엇이 변했는가

가장 컸던 변화는 AI 에이전트를 전환할 때의 스트레스가 사라졌다는 점입니다.

이전에는 Codex에서 Claude Code로 전환했을 때, CLAUDE.md의 내용만 옛날 상태로 남아있거나 Codex 측에서 만든 skill이 아예 포함되어 있지 않은 경우가 있었습니다. 게다가 작업을 시작한 후에야 "이게 반영되지 않았네"라고 깨닫게 되어 그때마다 흐름이 끊기곤 했습니다.

지금은 어떤 도구로 열어도 동일한 설정이 적용된 상태이므로, 이러한 불일치를 걱정할 필요가 없어졌습니다. 덕분에 AI 에이전트를 전환하는 것 자체에 대한 심리적 장벽도 낮아졌습니다.

요약

• rulesync는 .rulesync/를 원본으로 하여 각 AI 에이전트 도구용 설정 파일을 생성하는 CLI 도구입니다. 규칙(rule)뿐만 아니라 skill, MCP 서버 설정, hooks 등도 배포 대상입니다.
• 이미 CLAUDE.md 등을 작성해 두었더라도 rulesync import로 가져올 수 있어 다시 쓸 필요가 없습니다.
• 생성된 파일은 직접 편집하지 마세요. rulesync generate --check를 통해 원본과의 차이를 탐지할 수 있도록 설정해두면 안심할 수 있습니다.

Discussion