여러 코딩 에이전트가 규칙 한 폴더를 공유하게 한다

Cursor용으로 작성한 프로젝트 규칙은 Claude Code에는 보이지 않았고, Codex에서는 누군가 파일을 열어야만 적용됐다. 규칙을 다른 폴더로 복사하는 스크립트는 문제를 해결하는 동시에 진실의 원천을 둘로 만들었다. 이 글은 가능한 한 규칙을 .agents 한 곳에서 관리하고, 도구별 링크와 설정으로 연결하는 방법을 설명한다.

도구마다 읽는 파일이 다르다

각 도구는 다른 도구의 규칙 폴더를 자동으로 읽지 않는다. .cursor/rules에만 있는 규칙은 Claude에 보이지 않고, AGENTS.md만 읽는 도구는 CLAUDE.md를 읽지 않는다. 파일 이름과 설정 형식도 다르다. Cursor는 .cursor/rules의 .md 파일을 읽지 않고 .mdc를 요구한다. Claude Code는 .mdc를 읽지 않고 .md와 paths 키를 사용한다. Kiro는 inclusion을 사용한다.

`.agents`에 규칙을 두고 링크하기

규칙 원본은 .agents에서 편집하고, Cursor와 Claude에는 각 도구가 인식하는 이름의 심볼릭 링크를 둔다. 예를 들어 .agents/rules/devices-api.md를 .cursor/rules/devices-api.mdc와 .claude/rules/devices-api.md로 연결한다. 대상 파일은 .md로 유지한다. 반대 방향으로 연결해 Claude가 .mdc를 대상으로 읽게 하면 규칙을 건너뛴다.

링크는 저장소 안에 둬야 한다. Claude는 작업 디렉터리 바깥을 가리키는 링크를 외부 가져오기로 취급해 승인을 요구하며, 승인 후에도 paths가 없는 규칙만 읽는다. Windows에서 Git이 링크를 만들려면 복제 전에 core.symlinks를 켜야 한다. 그렇지 않으면 심볼릭 링크가 경로 문자열이 든 작은 텍스트 파일로 기록된다.

같은 규칙 파일의 머리말에는 도구별 키를 함께 둘 수 있다. 각 도구는 자신이 모르는 키를 무시한다. 경로 목록은 Cursor의 globs, Claude의 paths, Kiro의 fileMatchPattern에서 같아야 한다. Antigravity는 trigger: glob과 쉼표로 구분된 문자열 globs를 사용한다. YAML 목록을 쓰면 cannot unmarshal !!seq into string 오류가 발생했다.

항상 적용할 규칙은 AGENTS.md에 필요한 문장을 두고, Claude Code에서는 CLAUDE.md가 .agents/rules의 파일을 가져오게 할 수 있다. Claude의 가져오기는 @./.agents/...처럼 ./를 포함해야 한다. paths가 없는 규칙을 .claude/rules에 심볼릭 링크로 넣으면 항상 적용되는 규칙으로 취급될 수 있으므로, 이 방식은 피한다. 경로별 규칙은 .claude/rules에 링크할 수 있다. 요청에 따라 적용하는 규칙은 Cursor의 설명과 alwaysApply: false, Kiro의 inclusion: manual 등으로 구성할 수 있지만 Claude에는 같은 방식이 없다.

도구별 예외와 한계

Codex는 .cursor/rules를 자동으로 찾지 않는다. 규칙이 필요하면 AGENTS.md에서 파일을 지정하거나 코드 옆에 중첩 AGENTS.md를 둬야 한다. 여러 경로에 걸친 규칙은 .agents/rules에 두고 경로 목록을 맞추는 방법을 제안한다. ZCode는 ~/.zcode/AGENTS.md 다음에 작업공간의 AGENTS.md를 읽지만 @ 가져오기를 확장하거나 경로 일치로 규칙을 적용하지 않는다. .agents/skills는 이미 읽는다.

Kiro는 루트 및 코드 가까이에 있는 AGENTS.md를 읽지만, AGENTS.md에는 항상 적용되는 설정만 둘 수 있다. 경로 범위는 steering 파일로 지정한다. 문서에 나온 #[[file:...]] 참조와 .kiro/steering의 심볼릭 링크를 시험했지만, 둘 다 규칙을 불러오지 못했다. Kiro는 해당 폴더의 일반 파일만 읽으므로 수정 전까지 규칙 본문을 복사해야 한다. 이 문제는 kirodotdev/Kiro#2921에 열려 있다. Kiro와 Kiro Crew는 같은 폴더를 읽지만, Kiro IDE는 일치하는 파일을 열었을 때 fileMatch 규칙을 적용하는 반면 Kiro Crew는 세션 시작 때 steering을 불러오고 이후 경로에 따라 규칙을 적용하지 않는다.

현재 Claude Code 2.1.277 이상은 저장소에 CLAUDE.md가 없으면 AGENTS.md를 읽는다. CLAUDE.md가 있으면 그 파일을 읽고 AGENTS.md는 무시한다. 프로젝트 지침 설정을 바꾸거나 파일을 가져와야 한다. 2.0.9에는 이 기능이 없다. OpenCode, Amp, Zed, Windsurf, Junie, Jules도 루트 AGENTS.md를 읽는다고 하지만, 해당 도구들은 설치하지 않아 비교표에는 포함하지 않았다.

스킬도 한곳에서 관리할 수 있다

스킬은 SKILL.md가 들어 있는 폴더다. Codex와 ZCode는 .agents/skills를 읽고, Cursor와 Claude Code에는 각자의 스킬 폴더를 가리키는 디렉터리 심볼릭 링크를 둘 수 있다. Cursor는 스킬 파일에 name과 description 머리말이 없으면 Error parsing skill을 표시한다. name은 폴더 이름과 맞추고, description은 에이전트가 스킬 적용 여부를 판단하는 데 쓴다. 새 링크를 만든 뒤에는 Cursor 창을 다시 불러와야 한다.

Claude Code에서는 스킬이 /rspec-focused-runs 같은 명령으로 표시되며 /skills로 확인할 수 있다. 이 명령은 현재 버전에 있지만 2025년에 npm install -g로 설치된 2.0.9에는 없다. 터미널에서 실행하는 claude와 편집기 안의 Claude 버전이 다를 수 있으므로 claude --version으로 확인해야 한다.

앱별 확인 결과와 권장하지 않는 방식

각 앱에서 새 세션을 열고 같은 세 가지 질문을 했다. Cursor와 Claude는 항상 적용되는 문장을 읽었고, 경로 규칙은 지정된 템플릿 파일에서만 확인됐다. ChatGPT, ZCode, Antigravity는 AGENTS.md의 문장은 읽었지만 경로 일치만으로 규칙을 불러오지 않았다. Kiro는 steering 파일에 규칙 본문을 넣은 뒤 항상 적용 규칙을 읽었고, 템플릿 경로 규칙도 읽었다. Kiro Crew는 경로 규칙을 읽지 않았다.

GitHub Copilot 데스크톱 앱은 gatsby-post-check 스킬을 표시했지만 AGENTS.md의 문장은 읽지 않았다. 저장소 전체 지침용 .github/copilot-instructions.md와 경로별 *.instructions.md 파일도 추가했지만 앱은 읽지 않아 삭제했다. Copilot CLI는 AGENTS.md를 읽었다. Gemini CLI는 비공개 Google 계정으로 로그인할 수 없어 확인하지 않았다.

모든 규칙을 커밋 때마다 다른 폴더에 생성하는 방식은 피하라고 제안한다. 생성 파일을 나중에 직접 수정하면 커밋 훅이 이를 거부하거나 다음 생성 때 덮어쓸 수 있다. 모든 Cursor 규칙을 Claude 폴더에 링크하는 것도 권하지 않는다. 경로가 없는 규칙은 Claude에서 항상 적용되는 것으로 취급될 수 있다. 저장소 밖의 규칙 폴더를 가리키는 링크도 경로별 규칙을 불러오지 못한다.

최종 구조에서는 AGENTS.md를 여러 도구가 공유하는 입구로 짧게 유지하고, .agents/rules와 .agents/skills를 편집 원본으로 둔다. Cursor와 Claude는 필요한 파일을 링크하고, Kiro steering은 지원 문제가 해결될 때까지 별도 복사본을 둔다. CI에서는 링크가 모두 유효한지, globs, paths, fileMatchPattern의 경로 목록이 같은지 확인한다.

ZCode 문서