PanisHandsome/ai-rules-sync

AI 코딩 에이전트 (AI coding-agent) 규칙을 위한 단일 진실 공급원 (One source of truth).

🔗 라이브 플레이그라운드 (Live playground): https://panishandsome.github.io/ai-rules-sync/

. Codex는 AGENTS.md를 읽습니다.

. Claude Code는 CLAUDE.md를 읽습니다.

. Cursor는 .cursorrules를 읽습니다.

. Copilot은 .github/copilot-instructions.md를 읽습니다.

이 파일들을 수동으로 동기화하는 것은 지루하며 내용이 어긋나기 쉽습니다. agentsync는 이 모든 파일 간의 변환을 수행하거나, 짧은 명세(spec)로부터 깔끔한 AGENTS.md를 생성합니다.

의존성(Dependencies)이 전혀 없습니다. CLI와 브라우저 플레이그라운드 모두 동일한 엔진(src/core/agentsync.js)으로 구동됩니다.

npm install -g @panishandsome/agentsync # `agentsync` 명령어를 설치합니다.
# 또는 설치 없이 실행:
npx @panishandsome/agentsync --help

또는 단순히 클론(clone)하여 소스에서 실행할 수 있습니다. 의존성이 없습니다:

git clone https://github.com/PanisHandsome/ai-rules-sync
cd ai-rules-sync
node bin/agentsync.mjs --help

agentsync setup

이것이 가장 편한 방법입니다. 저장소(repo)에서 이 명령은 다음을 수행합니다: 프로젝트를 스캔하여 AGENTS.md를 생성하고, agentsync.json을 작성하며, 첫 번째 동기화를 실행하고, 모든 커밋(commit) 시 파일들이 동기화 상태를 유지하도록 git 프리커밋 훅(pre-commit hook)을 설치합니다. 그 이후부터는 AGENTS.md만 수정하고 커밋하면 됩니다. agentsync setup --auto를 사용하면 훅이 모든 규칙 파일의 수정을 허용하도록 설정할 수 있으며, --no-hook을 사용하면 훅을 건너뛸 수 있습니다.

# 저장소를 지정하여 `AGENTS.md`를 자동으로 작성하게 합니다.
agentsync init
# 기존 규칙 파일을 변환합니다.
...

AGENTS.md를 한 번만 작성하면 다른 도구들의 파일은 그로부터 생성되도록 하세요. 설정(config)을 생성합니다 (이미 가지고 있는 규칙 파일들을 자동으로 감지합니다):

agentsync sync --init # agentsync.json을 작성합니다

{
"source": "AGENTS.md",
"targets": ["CLAUDE.md", ".cursorrules", ".github/copilot-instructions.md"]
...
}

agentsync sync # AGENTS.md로부터 모든 타겟(target)을 재생성합니다.
agentsync sync --watch # 저장할 때마다 재생성합니다.
agentsync sync --check # CI: 동기화가 맞지 않는 것이 있으면 0이 아닌 값으로 종료합니다.

프리커밋 훅(pre-commit hook)을 통해 자동화하세요 (커밋되는 파일들이 항상 동기화된 상태를 유지하도록):

npx husky init
echo "npx agentsync sync && git add -A" > .husky/pre-commit

AGENTS.md만 수정하세요.

그 이후부터는 — 다른 파일들은 생성된 결과물입니다.

--auto 옵션을 사용하면

현재 사용 중인 도구가 선호하는 어떠한 파일이든 수정할 수 있습니다 (Claude Code의 CLAUDE.md, Cursor의 .cursorrules, Codex의 AGENTS.md 등...). agentsync는 .agentsync-state.json에 스냅샷을 추적하여, 어떤 파일이 변경되었는지 파악한 후 해당 파일을 바탕으로 나머지를 다시 생성합니다:

agentsync sync --auto

마지막 동기화 이후 두 개의 파일을 수정했다면, 실행을 멈추고 어떤 파일이 우선권을 가질지 묻습니다:

agentsync sync --auto --source CLAUDE.md

동일한 방식으로 훅(hook)을 연결하세요: echo "npx agentsync sync --auto && git add -A" > .husky/pre-commit

이미 여러 개의 규칙 파일이 있나요? 이를 하나의 AGENTS.md로 통합하세요:

agentsync merge CLAUDE.md .cursorrules -o AGENTS.md

→ https://panishandsome.github.io/ai-rules-sync/ — 왼쪽에는 아무 규칙 파일이나 붙여넣고, 오른쪽에서 변환된 출력을 확인하거나, Generate (생성) 모드로 전환하여 짧은 양식을 채우세요. 완전히 클라이언트 측(client-side)에서 실행되며, 아무것도 업로드되지 않습니다.

플레이그라운드(playground)를 로컬에서 실행하려면:

npm run web # → http://localhost:5173

id	file	tool
agents	AGENTS.md	Codex / open standard
claude	CLAUDE.md	Claude Code
cursor	.cursorrules	Cursor
copilot	.github/copilot-instructions.md	GitHub Copilot
windsurf	.windsurfrules	Windsurf
cline	.clinerules	Cline
aider	CONVENTIONS.md	Aider
gemini	GEMINI.md	Gemini CLI

agentsync formats를 실행하면 목록을 볼 수 있습니다.

모든 형식은 하나의 정규화된 중간 표현(normalized intermediate representation) (섹션, 서론, 파일 글로브(file globs), 경고)으로 파싱된 다음, 대상 형식으로 렌더링됩니다. 새로운 도구를 추가한다는 것은 하나의 파서(parser)와 하나의 렌더러(renderer)를 작성하는 것을 의미하며 — 그 외에는 아무것도 변경되지 않습니다. 변환되지 않는 도구별 구성 요소(Cursor의 globs 프론트매터(frontmatter), Claude의 @path 임포트(imports))는 조용히 삭제되는 대신 **경고(warnings)**로 나타납니다.

평면적이고 헤딩(heading)이 없는 규칙 파일들은 의미론적으로 분류됩니다. 명령줄(command lines), 스타일 노트(style notes), 금지 사항(prohibitions)은 하나의 덩어리로 쏟아지는 대신 각각 적절한 Build & test commands, Code style, Do not 섹션으로 분류됩니다.

agentsync init [dir] [-o <out>] [--force]
agentsync sync [--check] [--watch]
agentsync convert <file> [--to <fmt>] [--from <fmt>] [-o <out>] [--json]
...

npm test

CONTRIBUTING.md를 참조하세요. 이 저장소 자체의 AGENTS.md는 agentsync 자체(agentsync generate)에 의해 생성되었으므로, 코딩 에이전트가 어떤 작업에 착수하기 전에 컨벤션(conventions)을 파악할 수 있습니다.

CHANGELOG.md를 참조하세요. 짧은 빌드 저널(build journal)은 docs/JOURNAL.md에 있습니다.

MIT — LICENSE를 참조하세요.