[AI 주식 알람] 하나의 규칙, 세 개의 AI 도구: Cursor・Claude Code・Antigravity 동시 운영기

앞선 글에서는 SRS의 요구사항을 실제 개발 태스크와 커밋 단위로 분해하는 generate-tasks-from-srs 스킬을 만들었다.

하지만 스킬을 만들고 나니 또 다른 문제가 생겼다.

이번 프로젝트는 처음부터 하나의 AI 개발 도구로만 진행하지 않았다. 화면과 코드를 함께 보며 빠르게 수정할 때는 Cursor를 사용했고, 비교적 긴 작업이나 서브에이전트가 필요한 경우에는 Claude Code를 사용했다. 상황에 따라 Google Antigravity도 함께 활용했다.

문제는 도구를 바꿀 때마다 프로젝트 규칙을 읽는 방식이 달라진다는 점이었다.

Cursor에만 규칙을 작성해 두면 Claude Code에서는 해당 규칙을 알지 못한다. Claude Code용 파일만 수정하면 Antigravity에서 이전 결정대로 코드를 작성할 수 있다.

 

결국 AI 도구를 여러 개 사용한다는 것은 단순히 모델을 바꿔 쓰는 문제가 아니었다.

도구를 바꿔도 같은 프로젝트를 보고 있다고 느끼게 만드는 구조가 필요했다.

 

이번 글에서는 이를 해결하기 위해 적용한  "지식은 중앙화하고, 제어는 분산화한다”는 원칙을 정리한다.

1. 하나의 프로젝트인데 규칙의 입구는 세 개였다

각 도구에는 프로젝트 지침과 반복 작업을 정의하는 자체적인 위치가 있다.

이번 프로젝트에서 사용한 연결 구조를 단순화하면 다음과 같다.

Cursor는 프로젝트 규칙과 AGENTS.md를 지원하고, Claude Code는 기본적으로 CLAUDE.md를 읽는다. Antigravity는 워크스페이스 규칙을 .agents/rules에, 스킬을 .agents/skills에 둘 수 있다.

표만 보면 단순해 보이지만, 이 구조를 정리하기 전에는 규칙이 여러 파일에 흩어져 있었다.

예를 들어 다음과 같은 제품 원칙이 있었다.

메인 화면에는 사용자의 판단에 필요한 정보를 먼저 보여준다.
차트는 핵심 정보가 아니라 보조 정보로 배치한다.

 

이 규칙을 Cursor, Claude Code, Antigravity용 파일에 각각 복사해 두면 당장은 잘 동작한다.

문제는 규칙을 수정할 때 발생했다.

2. 첫 번째 시도: 같은 규칙을 세 번 복사하기

초기에는 가장 단순한 방법을 사용했다.

• Cursor 규칙 파일에 제품 원칙 작성
• CLAUDE.md에도 같은 내용 작성
• Antigravity 규칙 파일에도 다시 작성

규칙의 양이 적을 때는 큰 문제가 없어 보였다.

하지만 프로젝트가 진행되면서 ADR, UI 원칙, API 정책, 테스트 기준이 계속 추가됐다. 같은 문장이 여러 파일에 복사되기 시작했고, 어느 파일이 최신 버전인지 확인하기 어려워졌다. 실제로 다음과 같은 일이 있었다.

홈 화면에 차트를 직접 노출하지 않기로 결정한 뒤 Cursor의 규칙은 수정했지만, Claude Code 쪽 규칙은 이전 상태로 남아 있었다.

이후 Claude Code로 작업을 이어가자 이미 폐기한 화면 구성을 다시 구현하려고 했다.

AI가 이전 결정을 무시한 것이 아니었다. Claude Code의 관점에서는 자신이 읽은 규칙이 여전히 최신이었기 때문이다.

도구마다 서로 다른 프로젝트를 보고 있는 것과 같은 상태였다.

이 문제를 겪고 나서 규칙을 여러 곳에 복사하는 방식은 오래 유지하기 어렵다고 판단했다.

3. 해법: AGENTS.md를 공통 원본으로 사용하기

프로젝트 루트에 AGENTS.md를 만들고, 세 도구가 공통으로 알아야 하는 내용을 이 파일에 모았다.

AGENTS.md는 사람을 위한 README.md와 비슷하지만, AI 코딩 에이전트가 프로젝트에서 지켜야 할 규칙을 전달하기 위한 파

이 파일에는 특정 도구의 기능이나 명령어가 아니라 다음과 같은 도구에 종속되지 않는 지식을 넣었다.

• 제품의 핵심 원칙
• PRD와 SRS 위치
• 주요 ADR
• 기술 스택
• 코드 작성 규칙
• 테스트 기준
• 커밋 및 PR 규칙
• 절대 변경하면 안 되는 결정

예시는 다음과 같다.

# AGENTS.md — Cross-tool project rules

## Sources of truth

1. `docs/PRD_v1.md`
   - 제품 비전
   - KPI
   - 주요 ADR

2. `docs/SRS-v1.md`
   - 기능 요구사항
   - 비기능 요구사항
   - API 및 데이터 모델
   - Acceptance Criteria

## Non-negotiable product decisions

- 홈 화면에서는 판단 정보를 먼저 보여준다.
- 차트는 판단 정보 아래의 보조 영역에 배치한다.
- 시장 조건이 불명확하면 억지로 BUY 또는 SELL을 생성하지 않는다.
- No Call 결과와 실패 기록도 숨기지 않는다.

## Shared engineering rules

- 입력과 출력에는 Zod 스키마를 정의한다.
- 새 요구사항은 SRS의 AC와 연결한다.
- 하나의 커밋에는 하나의 목적만 포함한다.
- 완료 전 typecheck와 관련 테스트를 실행한다.

 

여기서 중요한 것은 AGENTS.md가 모든 문서를 대신하도록 만들지 않았다는 점이다.

PRD와 SRS의 내용을 전부 복사하면 AGENTS.md가 지나치게 길어지고, 어떤 규칙이 중요한지 오히려 구분하기 어려워진다.

따라서 역할을 다음과 같이 나눴다.

PRD
└─ 무엇을 만들고 왜 만드는가

SRS
└─ 어떤 조건을 만족해야 하는가

AGENTS.md
└─ AI 에이전트가 프로젝트에서 항상 지켜야 할 것은 무엇인가

Skill
└─ 특정 작업을 어떤 절차로 수행하는가

 

AGENTS.md에는 항상 필요한 원칙만 남기고, 긴 작업 절차는 스킬로 분리했다.

항상 로드되는 규칙 파일이 지나치게 길어지면 컨텍스트를 많이 사용하고 지침 준수율도 떨어질 수 있기 때문이다. Claude Code 공식 문서 역시 긴 상시 지침보다 경로별 규칙이나 스킬로 분리하는 방식을 권장하고 있다.

4. 도구 전용 파일은 얇은 어댑터로 만든다

AGENTS.md를 만들었다고 해서 세 도구가 아무 설정 없이 완전히 같은 방식으로 읽는 것은 아니다.

특히 Claude Code는 AGENTS.md를 직접 읽지 않고 CLAUDE.md를 기본 프로젝트 지침으로 사용한다.

따라서 CLAUDE.md에서 같은 내용을 다시 작성하는 대신, 다음과 같이 공통 파일을 가져오도록 했다.

@AGENTS.md

# Claude Code-specific rules

- 복잡한 변경은 구현 전에 계획을 작성한다.
- 독립적으로 검토 가능한 작업은 서브에이전트에 위임할 수 있다.
- 코드 변경 후 관련 테스트와 typecheck를 실행한다.

 

Claude Code의 @파일경로 문법을 사용하면 참조 파일의 내용이 세션 시작 시 함께 로드된다. 단순히 “AGENTS.md를 참고하라”고 문장으로 작성하는 것보다 @AGENTS.md로 명시적으로 가져오는 편이 확실하다. Cursor와 Antigravity의 전용 규칙 파일에도 공통 제품 원칙을 다시 복사하지 않았다. 대신 각 도구에서만 필요한 내용만 남겼다.

예를 들면 다음과 같다.

 

Cursor 전용 규칙

• 특정 파일 패턴에만 적용할 규칙
• 프론트엔드 작업에서 확인할 컴포넌트 경로
• UI 변경 후 브라우저에서 검증할 항목
• 에이전트가 자동으로 수정하면 안 되는 파일

Claude Code 전용 규칙

• 서브에이전트를 사용해야 하는 작업
• 사용할 수 있는 도구와 권한
• 컨텍스트를 분리해야 하는 작업
• 작업 완료 후 실행할 훅

Antigravity 전용 규칙

• 워크플로 실행 조건
• 브라우저 또는 터미널 사용 기준
• 파일 패턴별 Rule 활성화 조건
• Antigravity에서만 사용하는 승인 절차

이렇게 하면 공통 파일과 도구 전용 파일의 역할이 분명해진다.

AGENTS.md
└─ 세 도구가 공유하는 프로젝트 지식

도구 전용 규칙
└─ 해당 도구가 그 지식을 어떤 방식으로 실행할 것인가

[스크린샷 삽입 위치: 저장소 루트에서 AGENTS.md, CLAUDE.md, .cursor/, .agents/, .claude/가 함께 보이는 파일 트리]

5. 스킬도 세 벌 만들지 않는다

규칙뿐만 아니라 반복 작업을 정의한 스킬도 중복될 가능성이 있었다.

이번 프로젝트에서 만든 대표적인 스킬은 다음과 같다.

generate-tasks-from-srs
010-decision-layer-product-gates

generate-tasks-from-srs는 SRS를 구현 태스크로 분해하는 절차를 정의한다.

010-decision-layer-product-gates는 추천 카드 중심의 제품 원칙과 기능 게이트를 확인하는 역할을 한다.

이 스킬을 도구별 폴더에 각각 복사하면 다시 같은 문제가 발생한다.

.cursor/skills/generate-tasks-from-srs/SKILL.md
.claude/skills/generate-tasks-from-srs/SKILL.md
.agents/skills/generate-tasks-from-srs/SKILL.md

파일 세 개의 내용은 처음에는 같더라도 수정 과정에서 쉽게 달라질 수 있다.

그래서 현재 프로젝트에서는 실제 스킬 파일을 .cursor/skills 한 곳에만 두고, 나머지 경로는 심볼릭 링크로 연결했다.

mkdir -p .claude .agents

# Claude Code
ln -sfn ../.cursor/skills .claude/skills

# Antigravity
ln -sfn ../.cursor/skills .agents/skills

폴더 구조로 보면 다음과 같다.

.
├── AGENTS.md
├── CLAUDE.md
│
├── .cursor/
│   ├── rules/
│   └── skills/
│       ├── generate-tasks-from-srs/
│       │   └── SKILL.md
│       └── 010-decision-layer-product-gates/
│           └── SKILL.md
│
├── .claude/
│   ├── agents/
│   └── skills -> ../.cursor/skills
│
├── .agents/
│   ├── rules/
│   └── skills -> ../.cursor/skills
│
└── docs/
    ├── PRD_v1.md
    └── SRS-v1.md

이 구조에서는 스킬 내용을 한 번만 수정하면 세 도구가 같은 파일을 사용한다.

Claude Code와 Antigravity 모두 SKILL.md 기반의 Agent Skills 구조를 지원하며, Claude Code는 프로젝트 스킬의 심볼릭 링크도 지원한다. 다만 심볼릭 링크는 운영체제와 Git 설정의 영향을 받을 수 있다.

macOS나 Linux에서는 비교적 간단하지만, Windows 환경이 포함된 팀이라면 링크 생성 권한과 체크아웃 동작을 먼저 확인해야 한다. 여러 운영체제를 사용하는 팀에서는 링크를 생성하는 초기화 스크립트를 별도로 두는 방식도 고려할 수 있다.

---

6. 모든 것을 공통화하지는 않았다

공통 규칙과 스킬을 한곳에 모으기 시작하면, 모든 설정을 하나의 포맷으로 통합하고 싶어진다.

하지만 이번 프로젝트에서는 서브에이전트와 훅까지 억지로 공통화하지 않았다.

이 영역은 프로젝트의 지식보다 각 도구의 실행 엔진에 더 가깝기 때문이다.

예를 들어 Claude Code의 서브에이전트는 다음과 같은 설정을 가질 수 있다.

• 사용할 모델
• 허용하거나 차단할 도구
• 시작할 때 미리 주입할 스킬
• 독립적인 컨텍스트
• 서브에이전트 전용 메모리
• 작업 전후에 실행할 훅

Claude Code는 서브에이전트에 스킬을 미리 로드하거나, 별도 컨텍스트와 도구 권한을 부여하는 기능을 제

Cursor와 Antigravity에도 에이전트, 규칙, 워크플로, 훅 기능이 있지만 세부 포맷과 실행 시점은 다르다.

이를 하나의 공통 파일로 추상화하면 각 도구가 가진 장점을 사용하기 어려워진다.

결국 다음과 같은 최소공배수만 남게 된다.

역할 설명
간단한 지침
공통으로 사용할 수 있는 몇 개의 도구

형식은 하나로 통일되지만, 어느 도구에서도 충분히 강력하지 않은 설정이 될 가능성이 높다.

그래서 다음 항목은 도구별로 따로 관리했다.

• 서브에이전트 정의
• 도구 권한
• 훅과 이벤트
• 파일 패턴별 규칙 활성화
• 승인 및 실행 정책
• 모델 선택
• 컨텍스트 분리 방식

대신 도구별 사용법을 설명하는 문서를 분리했다.

README-cursor-harness.md
README-claude-harness.md
README-antigravity-harness.md

이 문서들은 프로젝트의 제품 원칙을 다시 설명하지 않는다.

각 도구를 시작하는 방법, 규칙을 확인하는 방법, 스킬과 에이전트를 호출하는 방법처럼 운영 방법만 설명한다.

7. 지식은 중앙화하고, 제어는 분산화한다

세 도구를 함께 운영하면서 정리된 구조는 다음과 같다.

                    ┌─ Cursor Rules / Agents / Hooks
PRD ─┐              │
     ├─ AGENTS.md ──┼─ Claude Rules / Agents / Hooks
SRS ─┘              │
                    └─ Antigravity Rules / Workflows / Hooks

Shared Skills
└─ 하나의 원본을 각 도구의 스킬 경로에서 참조

여기서 AGENTS.md와 공유 스킬은 지식 계층이다.

• 무엇을 만들어야 하는가
• 어떤 결정을 지켜야 하는가
• 어떤 절차로 작업해야 하는가
• 무엇을 완료 조건으로 볼 것인가

반면 도구별 규칙, 서브에이전트, 훅은 제어 계층이다.

• 어떤 상황에서 규칙을 활성화할 것인가
• 어떤 에이전트에게 작업을 맡길 것인가
• 어떤 도구의 사용을 허용할 것인가
• 어느 시점에 테스트나 검증을 실행할 것인가

이를 한 문장으로 정리하면 다음과 같다.

공유해야 하는 것은 프로젝트의 판단 기준이고, 분리해야 하는 것은 각 도구의 실행 방식이다.

 

이 구분을 적용한 뒤에는 도구를 변경할 때마다 프로젝트 규칙을 다시 설명하는 일이 줄어들었다.

Cursor에서 작업하던 내용을 Claude Code로 넘겨도 같은 제품 원칙을 기준으로 판단했고, Antigravity를 사용해도 동일한 스킬의 절차를 참조할 수 있었다.

동시에 각 도구의 서브에이전트, 훅, 파일 패턴 규칙 같은 고유 기능은 그대로 사용할 수 있었다.

8. 마무리

여러 AI 개발 도구를 함께 사용하는 데 가장 큰 문제는 모델의 성능 차이가 아니었다.

도구를 바꿀 때 프로젝트의 기억이 함께 사라지는 것이 더 큰 문제였다.

같은 저장소를 열었더라도 각 도구가 서로 다른 규칙과 문서를 읽는다면, 실제로는 서로 다른 프로젝트를 구현하게 된다.

이번 프로젝트에서는 이를 다음과 같이 정리했다.

제품 원칙과 공통 규칙
→ AGENTS.md

상세 요구사항
→ PRD와 SRS

반복 가능한 작업 절차
→ Shared Skills

도구별 실행 방식
→ Rules, Subagents, Hooks

 

모든 설정을 하나로 합치려고 하지 않았다. 대신 한 번만 작성해야 하는 지식과, 도구별로 달라야 하는 제어를 구분했다.

그 결과 Cursor, Claude Code, Antigravity를 바꿔가며 사용해도 프로젝트의 기본 판단 기준은 유지하면서 각 도구의 장점을 사용할 수 있었다.

다음 편에서는 이 구조 위에서 Claude Code 서브에이전트를 실제로 여섯 개 역할로 나눈 기준을 다룰 예정이다.

어떤 작업을 메인 에이전트가 담당하고, 어떤 작업을 별도 컨텍스트로 분리했는지, 그리고 서브에이전트를 너무 세분화하지 않기 위해 어떤 기준을 사용했는지 정리해 보려 한다.

프로젝트 저장소

AI Stock Alarm App
https://github.com/hy2207/ai-stock-alarm-app

GitHub - hy2207/ai-stock-alarm-app