Google Antigravity Rules 설정 꿀팁 — AI 에이전트가 코드부터 짜는 걸 막는 법

AI 코딩 IDE를 써보신 분이라면 한 번쯤 이런 경험이 있을 겁니다.

“이 기능 추가해줘”라고 했더니, AI 에이전트가 아무런 설명 없이 파일 10개를 한꺼번에 수정해버렸다.

결과물을 보면 동작은 합니다. 하지만 왜 이렇게 구현했는지 모르겠고, 내가 원했던 방식인지도 확신이 없습니다. 되돌리자니 이미 너무 많은 파일이 바뀌었고, 수정하자니 AI의 의도를 파악하는 데 시간이 걸립니다.

이 문제의 근본 원인은 단순합니다. 에이전트에게 “계획을 세우고 승인을 받은 뒤에 실행하라”는 규칙을 주지 않았기 때문입니다. Google Antigravity에서는 이것을 Rules와 Workflows로 해결합니다.

Google Antigravity란?

Google Antigravity는 Google DeepMind가 만든 에이전트 퍼스트(Agent-First) AI 코딩 IDE입니다. 2025년 11월 출시되었으며, 현재 퍼블릭 프리뷰로 개인 계정에 무료 제공됩니다.

Cursor나 Windsurf처럼 AI와 함께 코드를 작성하는 도구이지만, 핵심 차이점이 있습니다:

• Gemini 3.1 Pro 기반 (Claude Sonnet/Opus 4.6, GPT-OSS 120B 지원)
• Agent Manager를 통한 멀티 에이전트 오케스트레이션
• 에이전트가 에디터, 터미널, 브라우저에 직접 접근하여 자율적으로 계획, 실행, 검증
• 내장 브라우저로 자동화된 테스트 및 비디오 녹화까지 지원

그리고 에이전트의 행동을 제어하는 핵심 시스템이 바로 Rules와 Workflows입니다.

Customization 패널 접근 방법

Antigravity에서 Rules와 Workflows를 설정하는 경로는 다음과 같습니다:

1단계: Editor 모드에서 우측 상단의 점 세 개 메뉴(…)를 클릭합니다.

2단계: 드롭다운에서 Customization을 선택합니다. (MCP Servers 설정도 같은 메뉴에서 접근 가능합니다.)

3단계: Customization 패널이 열리면 상단에 Rules 탭과 Workflows 탭이 나란히 보입니다.

이 두 탭이 Antigravity 에이전트 커스터마이징의 전부입니다. 하지만 각각의 역할은 완전히 다릅니다.

Rules vs Workflows: 핵심 차이 완벽 정리

Rules — 항상 켜져 있는 시스템 프롬프트

“Rules help guide the behavior of Agent.” — Antigravity 공식 설명

Rules는 에이전트의 시스템 프롬프트(System Prompt)에 주입되는 수동적 제약(Passive Constraints)입니다. 한 번 설정하면 에이전트가 코드를 생성하고, 테스트하고, 문서를 작성할 때 항상 백그라운드에서 작동합니다.

특징:

• 에이전트가 항상 따라야 할 규칙
• 대화 중 별도 명령 없이 자동으로 적용
• 코딩 스타일, 아키텍처 패턴, 프로젝트 제약 조건을 강제

Rules 탭에서의 버튼:

• + Workspace — 현재 워크스페이스 전용 규칙 추가

예시:

Always respond in Korean.
모든 코드는 TypeScript strict 모드로 작성하세요.
any 타입 사용을 금지합니다.
비밀 키나 인증 정보를 절대 커밋하지 마세요.

Workflows — 필요할 때 실행하는 저장된 프롬프트

“Workflows are saved prompts that Agent can follow. To trigger a workflow, type ’/’ in Agent.” — Antigravity 공식 설명

Workflows는 에이전트에게 줄 수 있는 저장된 프롬프트(Saved Prompts)이며, 능동적 절차(Active Procedures)입니다. 사용자가 채팅에서 / 슬래시 커맨드를 입력했을 때만 실행됩니다.

특징:

• 사용자가 명시적으로 호출해야만 실행됨
• / 입력 시 사용 가능한 Workflow 목록이 자동완성으로 표시
• 복잡하고 반복적인 다단계 작업을 한 번의 명령으로 처리

Workflows 탭에서의 버튼:

• + Global — 모든 프로젝트에서 사용 가능한 Workflow 추가
• + Workspace — 현재 워크스페이스 전용 Workflow 추가

예시: /create_blog_post, /deploy, /generate_unit_tests 같은 슬래시 커맨드로 호출

한 눈에 비교

쉽게 비유하면: Rules는 “절대 빨간 불에 건너지 마” 같은 항상 지켜야 할 교통 법규이고, Workflows는 “집에서 회사까지 가는 최적 경로” 같은 필요할 때 꺼내 쓰는 레시피입니다.

Rules 파일 저장 위치와 구조

GUI에서 설정하는 것 외에도, 파일 시스템에서 직접 Rules 파일을 관리할 수 있습니다.

파일 저장 위치

Global Rules 파일 생성

# 전역 규칙 파일 생성
mkdir -p ~/.gemini
touch ~/.gemini/GEMINI.md

~/.gemini/GEMINI.md에 작성한 내용은 Antigravity에서 여는 모든 프로젝트에 자동 적용됩니다.

Workspace Rules 파일 생성

# 프로젝트 루트에서
mkdir -p .agent/rules
touch .agent/rules/code-style-guide.md
touch .agent/rules/architecture-rules.md

.agent/rules/ 폴더 안에 여러 개의 .md 파일을 만들 수 있으며, 각 파일이 하나의 규칙 세트가 됩니다. 파일 이름으로 규칙의 목적을 구분할 수 있어 관리가 편합니다.

Workspace Rules가 Global Rules보다 우선순위가 높습니다. 같은 항목에 대해 두 규칙이 충돌하면 Workspace Rules가 적용됩니다.

Workflows 파일 저장 위치와 구조

Workflows 역시 파일 시스템에서 직접 관리할 수 있으며, 정해진 포맷을 따라야 합니다.

파일 저장 위치

Workflow 파일 필수 포맷

Workflow 파일은 반드시 YAML 프론트매터(frontmatter)로 시작해야 합니다:

---
description: 애플리케이션 배포 자동화
---

1. 프로젝트 빌드
   npm run build

2. 테스트 실행
   npm test

3. 프로덕션 배포
   npm run deploy

필수 조건:

• .agent/workflows/ 디렉토리에 위치해야 함
• .md (마크다운) 파일이어야 함
• YAML 프론트매터에 description 필드가 반드시 포함되어야 함
• 단계는 번호를 매기고 명확하게 작성

Turbo 모드 — 승인 없이 자동 실행

기본적으로 에이전트는 터미널 명령을 실행하기 전에 사용자에게 승인을 요청합니다. 신뢰할 수 있는 Workflow에서는 Turbo 모드를 활성화하여 자동 실행이 가능합니다.

특정 단계만 자동 실행:

---
description: 테스트 실행 후 린트 체크
---

// turbo
1. 유닛 테스트 실행
   npm test

2. 린트 체크 (수동 승인 필요)
   npm run lint

// turbo를 특정 단계 바로 위에 놓으면 그 단계만 승인 없이 자동 실행됩니다.

모든 단계 자동 실행:

---
description: CI 파이프라인 전체 실행
---

// turbo-all

1. 의존성 설치
   npm install

2. 빌드
   npm run build

3. 테스트
   npm test

// turbo-all을 파일 어디에든 넣으면 모든 단계가 승인 없이 순차적으로 자동 실행됩니다.

주의: Turbo 모드는 편리하지만, rm -rf나 git push --force 같은 위험한 명령이 포함된 Workflow에는 사용하지 마세요.

Workflow 호출 방법

Workflow 파일을 만들면 에이전트 채팅에서 / + 파일명으로 호출할 수 있습니다:

/deploy        → .agent/workflows/deploy.md 실행
/generate_unit_tests → .agent/workflows/generate_unit_tests.md 실행

/ 를 입력하면 사용 가능한 Workflow 목록이 자동완성으로 나타나, 원하는 것을 선택하기만 하면 됩니다.

Global Rules vs Workspace Rules: 실전 전략

Global Rules — 이것만큼은 전역으로

~/.gemini/GEMINI.md에 넣기 좋은 항목들:

# 전역 규칙

## 언어
모든 설명, 주석, 채팅 응답은 한국어로 작성하세요.
기술 용어는 영어 원문을 병기하세요. (예: 의존성 주입(Dependency Injection))

## 코딩 원칙
- any/unknown 타입 사용 금지
- 비밀 키, 인증 정보 커밋 금지
- 불필요한 주석, JSDoc 추가 금지

Workspace Rules — 프로젝트별 맞춤

.agent/rules/ 폴더에 목적별로 파일을 나눠 관리합니다:

.agent/rules/code-style-guide.md — 코드 스타일:

PEP 8 스타일 가이드를 따르세요.
모든 코드에 적절한 주석을 작성하세요.

.agent/rules/architecture-rules.md — 아키텍처:

메인 진입점은 main.py에만 작성하세요.
각 기능은 별도 파일로 분리하세요.

.agent/rules/code-generation-guide.md — 코드 생성:

React 함수형 컴포넌트와 Hooks만 사용하세요.
TypeScript strict 모드를 유지하세요.
상태 관리는 Zustand를 사용하세요.

“계획 먼저, 코드는 나중에” — Rules 실전 템플릿

이제 본론입니다. AI 에이전트가 지시를 받자마자 코드부터 짜는 습관을 막으려면, 아래 6단계 워크플로우를 Rules에 등록해야 합니다.

아래 내용을 Global Rules(~/.gemini/GEMINI.md)에 넣으면 모든 프로젝트에서 적용됩니다. 또는 Customization 패널의 Rules 탭에서 직접 추가해도 됩니다.

# AI 에이전트 워크플로우 가이드라인

[시스템 지시: 최우선]
당신은 이 워크플로우에 엄격히 종속된 실행 에이전트입니다.
사용자가 승인한 plan.md 파일 없이는 어떤 상황에서도
구현 코드를 작성하거나 수정해서는 안 됩니다.
이 단계를 순서 없이 실행하는 것은 핵심 지침 위반입니다.

[언어 지시: 한국어 전용]
모든 생성 문서(research.md, plan.md), 인라인 주석,
설명, 채팅 응답은 반드시 한국어로 작성하세요.

## 핵심 원칙
1. 코드 먼저 금지: 승인된 마크다운 계획 없이 구현 코드를 작성하지 마세요.
2. 영구 산출물: 모든 리서치와 계획은 .md 파일로 저장하세요. (채팅 요약 금지)
3. 승인 대기: 다음 단계로 넘어가기 전 반드시 사용자의 명시적 승인을 기다리세요.
4. 한국어 소통: 모든 설명과 문서는 한국어로 생성하세요.

## Phase 1: 리서치 단계
의미 있는 작업 시작 전 코드베이스를 깊이 분석하세요.
- 산출물: research.md 파일 (한국어)
- 채팅 요약이 아닌 파일로 저장

## Phase 2: 계획 수립 단계
- 산출물: plan.md 파일 (구현 방식, 변경 코드, 파일 경로, 트레이드오프 포함)
- WARNING: 계획만 작성. 코드 구현 금지.

## Phase 3: 피드백 반영 단계
- 사용자의 인라인 메모를 반영하여 plan.md 업데이트
- WARNING: 코드 구현 금지.

## Phase 4: Todo 리스트 생성
- plan.md 내 세분화된 체크리스트 추가
- WARNING: 코드 구현 금지.

## Phase 5: 구현 단계
사용자의 실행 명령 후에만 시작:
- plan.md 전체 항목 구현 (선택적 생략 금지)
- 불필요한 주석/JSDoc 추가 금지
- any/unknown 타입 사용 금지
- 지속적 타입 체크 실행
- 완료 시 Todo 체크 표시
- 100% 완료까지 중단 금지

## Phase 6: 구현 중 피드백 대응
- Git 되돌림 + 새 제약 조건 시 → 패치 대신 처음부터 다시 구현

각 Phase 상세 설명

Phase 1 — 리서치: 에이전트에게 구체적으로 어디를 깊이 볼지 지시하면 효과적입니다.

이 프로젝트의 인증 시스템을 분석해서 research.md로 정리해줘.
특히 토큰 갱신 로직과 예외 처리 부분을 깊이 봐줘.

Phase 2 — 계획 수립: “절대 코드를 구현하지 마세요”라는 명시적 금지가 핵심입니다. 이것이 없으면 에이전트가 계획과 동시에 코드를 작성합니다.

Phase 3 — 피드백: 사용자가 plan.md에 직접 메모를 추가합니다.

## 구현 방식
UserService에 validateEmail() 메서드를 추가한다.
<!-- [사용자 메모] 정규식 대신 라이브러리(zod)를 사용할 것 -->

Phase 5 — 구현: 한 번에 “전부 구현해줘”보다는 단계별 실행이 안전합니다.

plan.md의 1번 항목 (UserService 수정)만 먼저 구현해줘.

Phase 6 — 피드백 대응: 잘못된 방향일 때 git checkout -- .로 되돌린 뒤 새 제약 조건과 함께 재지시하면, 에이전트는 패치 대신 처음부터 깨끗하게 다시 구현합니다.

Workflows 실전 활용 예시

Rules로 “항상 지켜야 할 원칙”을 설정했다면, Workflows로는 반복적인 작업을 자동화합니다.

예시 1: 유닛 테스트 자동 생성

.agent/workflows/generate_unit_tests.md:

---
description: 모든 파일에 대해 유닛 테스트를 자동 생성합니다
---

1. 프로젝트 내 모든 소스 파일을 분석하세요
2. 각 파일과 메서드에 대해 유닛 테스트를 생성하세요
3. 테스트 파일 이름은 원본 파일명 앞에 test_ 접두사를 붙이세요
4. 테스트를 실행하세요

// turbo
5. 테스트 결과 리포트를 출력하세요

호출: 채팅에서 /generate_unit_tests 입력

예시 2: 블로그 포스트 작성

.agent/workflows/create_blog_post.md:

---
description: SEO 최적화된 블로그 포스트를 생성합니다
---

1. 사용자에게 주제와 타겟 키워드를 확인하세요
2. 키워드를 바탕으로 제목, 설명, 태그를 생성하세요
3. MDX 파일을 src/content/blog/ 에 생성하세요
4. 3줄 요약 섹션을 포함하세요
5. 본문을 H2/H3 계층 구조로 작성하세요

호출: 채팅에서 /create_blog_post 입력

예시 3: 배포 자동화

.agent/workflows/deploy.md:

---
description: 프로덕션 배포 파이프라인을 실행합니다
---

// turbo-all

1. 린트 체크
   npm run lint

2. 타입 체크
   npx tsc --noEmit

3. 테스트
   npm test

4. 빌드
   npm run build

5. 배포
   npm run deploy

// turbo-all로 모든 단계가 승인 없이 자동 실행됩니다.

Skills — Rules와 Workflows를 넘어서

Antigravity는 Rules, Workflows 외에 Skills라는 세 번째 커스터마이징 시스템도 제공합니다.

Skills는 디렉토리 기반 패키지로, SKILL.md 정의 파일과 보조 에셋으로 구성됩니다. Workflows처럼 사용자가 명시적으로 호출하지 않아도, 에이전트가 사용자의 의도를 파악하여 관련 Skill을 자동으로 로드합니다.

Antigravity 개발 모드 3가지

Rules와 Workflows의 효과는 사용하는 개발 모드에 따라 달라집니다:

Review-driven 모드 + 위의 6단계 Rules 조합이 가장 효과적입니다. 에이전트가 각 Phase를 완료할 때마다 사용자에게 승인을 요청하므로, 의도치 않은 코드 변경을 완벽하게 차단할 수 있습니다.

Antigravity vs Cursor vs Claude Code: 커스터마이징 비교

Antigravity의 가장 큰 장점은 Rules/Workflows/Skills 3단계 커스터마이징 시스템입니다. 항상 적용되는 규칙(Rules), 필요할 때 호출하는 절차(Workflows), 에이전트가 자동으로 감지하는 전문성(Skills)으로 에이전트의 행동을 입체적으로 제어할 수 있습니다.

마무리: Rules와 Workflows, 둘 다 써야 완벽하다

Google Antigravity에서 에이전트를 제대로 활용하려면 Rules와 Workflows를 함께 설정해야 합니다.

• Rules에는 “항상 지켜야 할 원칙”을 넣으세요 — 코딩 스타일, 언어, 계획-실행 분리 워크플로우
• Workflows에는 “반복하는 작업 레시피”를 넣으세요 — 테스트 생성, 배포, 코드 리뷰

지금 바로 적용해보세요:

1. Customization 패널 열기: 우측 상단 ... 메뉴 > Customization
2. Rules 탭에서 6단계 워크플로우 템플릿 등록 (또는 ~/.gemini/GEMINI.md에 직접 작성)
3. Workflows 탭에서 반복 작업 레시피 등록 (또는 .agent/workflows/에 .md 파일 생성)
4. 채팅에서 이 기능 추가해줘라고 하면 이제 research.md부터 작성합니다
5. /deploy를 입력하면 배포 파이프라인이 자동으로 실행됩니다

이 설정들로 AI 에이전트는 더 이상 코드부터 짜지 않고, 필요한 작업은 슬래시 한 번으로 자동화됩니다.

🎁 [부록] 복사해서 바로 쓰는 추천 커스텀 템플릿 세트

아직 감이 안 오신다면, 아래 템플릿들을 복사해서 바로 시작해 보세요!

# AI 에이전트 핵심 실행 수칙

**[시스템 지시: 최우선]**
당신은 이 워크플로우에 엄격히 종속된 실행 에이전트입니다. 어떤 상황에서도 사용자가 승인한 `plan.md` 파일 없이는 구현 코드를 작성하거나 수정해서는 안 됩니다.

**[언어 지시: 한국어 전용]**
모든 문서 생성, 인라인 주석, 소스 코드 설명 및 채팅 응답은 오직 **한국어로만** 작성하세요.

## 🌟 핵심 원칙
1. **코드 먼저 작성 금지**: 승인된 마크다운 계획 없이 절대 코드를 변경하지 마세요.
2. **영구적 산출물**: 모든 분석과 계획은 채팅 요약이 아닌 `.md` 파일로 저장하세요.
3. **승인 대기**: 다음 단계 진행 전 항상 사용자의 명시적 승인을 기다리세요.

## 단축 워크플로우
- **Plan**: `research.md`를 작성하고, 승인을 받으면 `plan.md`(구현 계획+Todo)를 작성합니다.
- **Execute**: 사용자가 "실행해"라고 하면, plan의 항목을 100% 완료할 때까지 타입 체크를 병행하며 코드를 작성합니다.
- **Feedback**: 중간에 방향이 틀렸다면 코드를 기웠다 떼었다 하지 말고, Git을 되돌리고 처음부터 다시 작업합니다.

---
description: 현재 브랜치 변경사항 한글 코드 리뷰
---

1. git diff --staged 커맨드로 변경사항 확인
2. 보안 취약점이나 성능 이슈가 없는지 분석
3. PR 본문에 들어갈 3줄 요약 작성

// turbo
4. 리뷰 결과를 Markdown 포맷으로 출력

📚 관련 글 더 읽어보기

Cursor AI 한국어로 바꾸는 법 + 실무에서 바로 쓰는 rules 설정까지

Cursor AI 한국어 설정을 UI 언어팩 설치부터 .cursorrules로 AI 응답까지 완벽하게 한글화하는 방법을 단계별로 정리했습니다. 실무에서 바로 복붙 가능한 cursorrules 템플릿 5종도 제공합니다.

읽어보기 →