Google Antigravity 완전 가이드 4편 — Skills, Rules, Workflows, GEMINI.md로 에이전트를 내 팀원으로 만드는 법

에이전트한테 매번 "TypeScript strict 모드 써줘", "테스트는 Jest로 해줘" 반복 입력하고 있다면 하네스를 안 쓰는 겁니다. 4편은 Antigravity를 진짜 팀원처럼 동작하게 만드는 설정 레이어입니다.

[4편 핵심 요약]
→ GEMINI.md: 에이전트의 두뇌 — 프로젝트 전반에 항상 로드되는 규칙
→ Rules: 글로벌/프로젝트/에이전트별 3계층 우선순위
→ Workflows: /슬래시 명령으로 반복 태스크 원클릭 실행
→ Skills: 필요할 때만 로드되는 도메인 지식 모듈 (SKILL.md)
→ GEMINI.md vs AGENTS.md: 혼용 가능, GEMINI.md가 우선순위 높음
→ GEMINI.md 적정 크기: 500토큰 이하 — 초과 시 성능 저하
→ Skills 저장 위치: .agents/skills/ (프로젝트) / ~/.gemini/skills/ (글로벌)
→ Workflows 저장 위치: .antigravity/workflows/ / ~/.gemini/antigravity/global_workflows/

 

---

4가지 설정 레이어 구조

[Antigravity 설정 레이어 — 우선순위 높은 순]

1. 시스템 규칙 (수정 불가)
→ Google DeepMind 내장 규칙
→ 안전 프로토콜, 핵심 능력 정의
→ 사용자가 건드릴 수 없음

2. 글로벌 규칙 (모든 프로젝트 적용)
→ ~/.gemini/GEMINI.md
→ 개인 선호: "항상 한국어로 답해줘", "TypeScript 선호"

3. 프로젝트 규칙 (현재 프로젝트 적용)
→ 프로젝트 루트/GEMINI.md
→ 팀 표준: 기술 스택, 코딩 컨벤션, 금지 패턴

4. 에이전트별 규칙 (특정 에이전트만)
→ .agent/rules/에이전트명.md
→ 역할별 특수 지침

Skills + Workflows:
→ 규칙과 별개로 필요 시 로드/실행

---

실전 1 — GEMINI.md 작성

GEMINI.md는 에이전트가 프로젝트에서 항상 참조하는 핵심 문서입니다. CLAUDE.md와 역할 동일합니다. Antigravity 전용 기능은 GEMINI.md, 다른 툴과 공유하는 규칙은 AGENTS.md에 씁니다.

# GEMINI.md — 프로젝트 루트에 저장

## 프로젝트
FastAPI 백엔드 + React 18 프론트엔드
PostgreSQL + Redis 캐시

## 기술 스택
backend/   → Python 3.12, FastAPI, SQLAlchemy 2.0, Alembic
frontend/  → TypeScript 5 (strict), React 18, Vite, TailwindCSS
tests/     → pytest (backend), Vitest (frontend)

## 코딩 규칙
- Python: type hint 필수, async/await 우선, unwrap 금지
- TypeScript: strict 모드, any 타입 금지, interface 우선
- API 응답: {data, error, meta} 구조 통일
- 에러: 커스텀 예외 클래스 사용 (AppError, ValidationError)
- 새 기능: 단위 테스트 필수

## 절대 하지 말 것
- 환경변수 하드코딩
- console.log 프로덕션 코드에 남기기
- any 타입 사용
- database/migrations/ 직접 수정

## 파일 소유권 (멀티 에이전트 충돌 방지)
Frontend 에이전트: frontend/src/ 만
Backend 에이전트: backend/app/ 만
Infra 에이전트: infra/, docker/ 만

GEMINI.md 작성 원칙

[좋은 GEMINI.md vs 나쁜 GEMINI.md]

❌ 나쁜 예 (토큰 낭비):
"항상 읽기 쉬운 코드를 작성하세요."
"변수명은 의미있게 지으세요."
"주석을 충분히 달아주세요."
→ 모델이 어차피 하는 것들 → 쓸모없는 토큰 소모

✅ 좋은 예 (구체적 제약):
"API 응답은 반드시 {data, error, meta} 구조"
"migrations/ 폴더는 절대 건드리지 말 것"
"새 패키지 추가 시 반드시 사전 확인"
→ 모델이 모를 수 있는 프로젝트 특수 규칙

[적정 크기]
→ 500 토큰 이하 권장
→ 초과 시: 에이전트 응답 품질 저하
→ 절차적 내용 (다단계 작업) → Skills로 이동
→ 반복 태스크 → Workflows로 이동

GEMINI.md vs AGENTS.md 선택

GEMINI.md만 쓰는 경우:
→ Antigravity 전용 프로젝트

AGENTS.md만 쓰는 경우:
→ Claude Code, Codex와 공유하는 규칙

둘 다 쓰는 경우:
→ AGENTS.md: 공통 규칙 (기술 스택, 코딩 컨벤션)
→ GEMINI.md: Antigravity 전용 (Skills 참조, 브라우저 에이전트 설정)
→ 충돌 시 GEMINI.md 우선

---

실전 2 — Skills: 필요할 때만 로드되는 도메인 지식

GEMINI.md가 항상 로드되는 규칙이라면, Skills는 관련 태스크가 생길 때만 로드되는 모듈입니다. 컨텍스트 낭비 없이 전문 지식을 주입합니다.

[Skills 디렉토리 구조]

프로젝트 스코프:
.agents/
└── skills/
    ├── deploy-staging/
    │   ├── SKILL.md        # 필수: 메타데이터 + 지침
    │   ├── scripts/        # 선택: Python/Bash 스크립트
    │   ├── references/     # 선택: 문서, 템플릿
    │   └── assets/         # 선택: 이미지, 로고
    ├── security-review/
    │   └── SKILL.md
    └── db-migration/
        └── SKILL.md

글로벌 스코프 (모든 프로젝트):
~/.gemini/
└── skills/
    ├── my-coding-style/
    │   └── SKILL.md
    └── korean-docs/
        └── SKILL.md

SKILL.md 작성 예시

---
name: deploy-staging
description: 스테이징 환경에 애플리케이션 배포
triggers:
  - "스테이징 배포"
  - "staging deploy"
  - "테스트 서버에 올려줘"
---

# 스테이징 배포 가이드

## 사전 조건
- Docker 실행 중 확인
- AWS CLI 스테이징 프로파일 설정 (`aws configure --profile staging`)
- 현재 브랜치 CI 통과 확인

## 배포 단계

### 1. 사전 검증
```bash
npm run test
npm run build
docker build -t app:staging .

2. ECR 푸시

aws ecr get-login-password --profile staging | docker login
docker tag app:staging $ECR_URL/app:staging
docker push $ECR_URL/app:staging

3. ECS 배포

aws ecs update-service \
  --cluster staging \
  --service app-staging \
  --force-new-deployment \
  --profile staging

4. 검증

• 배포 완료까지 대기 (약 2분)
• https://staging.myapp.com 접속 확인
• /health 엔드포인트 응답 확인

```markdown
---
name: security-review
description: OWASP 기준 보안 코드 리뷰
triggers:
  - "보안 검토"
  - "security review"
  - "취약점 확인"
---

# 보안 리뷰 체크리스트

## 입력 검증
- [ ] 모든 사용자 입력 Pydantic으로 검증
- [ ] SQL 인젝션: ORM 사용, raw query 없음
- [ ] XSS: React 자동 이스케이프 확인

## 인증/인가
- [ ] JWT 만료 시간 설정 (access: 15분, refresh: 7일)
- [ ] 민감 엔드포인트 권한 체크
- [ ] 비밀번호 bcrypt 해싱 확인

## 시크릿 관리
- [ ] 환경변수만 사용, 하드코딩 없음
- [ ] .env 파일 .gitignore 확인

[Skills 트리거 방식]

자동 트리거:
→ triggers에 등록된 키워드 감지 시 자동 로드
→ "스테이징 배포해줘" → deploy-staging Skill 자동 활성화

수동 트리거:
→ "@deploy-staging 실행해줘"
→ 에이전트가 해당 Skill 명시적 참조

GEMINI.md에 명시:
→ "배포 작업은 반드시 @deploy-staging Skill 참조"

---

실전 3 — Workflows: 반복 태스크 원클릭 실행

Workflows는 자주 쓰는 태스크를 /슬래시 명령으로 저장해서 재사용합니다.

[Workflows 저장 위치]

프로젝트:
.antigravity/workflows/generate-unit-tests.md

글로벌:
~/.gemini/antigravity/global_workflows/generate-unit-tests.md

Workflow 파일 예시

# generate-unit-tests.md
지정된 모듈의 포괄적인 pytest 테스트를 생성합니다.

- test_ 접두사로 테스트 파일 생성
- 모든 public 메서드 커버
- 엣지케이스 + 에러 조건 포함
- 외부 의존성은 fixture 사용
- 반환값과 사이드 이펙트 모두 assert

# code-review.md
현재 변경사항에 대한 코드 리뷰를 수행합니다.

- git diff로 변경 파일 확인
- 버그 가능성 분석
- 성능 문제 체크
- 보안 취약점 스캔 (@security-review Skill 사용)
- 개선 제안 목록 작성
- 심각한 이슈는 명확히 표시

# daily-standup.md
일일 스탠드업 리포트를 생성합니다.

- 어제 완료된 커밋 목록 (git log)
- 현재 열린 PR 상태
- 실패한 CI 테스트 있으면 포함
- 오늘 작업 예정 이슈 목록
- 마크다운 형식으로 Slack 공유용 출력

Workflow 실행

[Agent Manager 채팅창에서]

/generate-unit-tests    → 단위 테스트 자동 생성
/code-review           → 코드 리뷰 실행
/daily-standup         → 스탠드업 리포트 생성
/deploy-staging        → 스테이징 배포

→ 슬래시 입력 시 자동완성 목록 표시
→ 팀 전체가 동일한 Workflow 사용 가능
→ 프로젝트 git에 커밋해서 팀 공유

---

실전 4 — 전체 설정 조합 예시

실제 FastAPI + React 프로젝트의 완성된 설정입니다.

[프로젝트 구조]
my-project/
├── GEMINI.md               # 항상 로드 — 핵심 규칙
├── AGENTS.md               # 다른 툴 공유 규칙
├── .agents/
│   └── skills/
│       ├── deploy-staging/ # 배포 전문 지식
│       ├── security-review/# 보안 리뷰 지식
│       └── db-migration/   # DB 마이그레이션 절차
├── .antigravity/
│   └── workflows/
│       ├── generate-unit-tests.md
│       ├── code-review.md
│       └── daily-standup.md
└── .gemini/
    └── antigravity/
        └── brain/          # 세션 간 자동 저장 (3편 참조)

[설정별 역할 요약]

GEMINI.md (항상 로드):
→ 기술 스택, 코딩 규칙, 금지 사항
→ 500 토큰 이하로 간결하게

Skills (필요 시 로드):
→ 배포 절차, 보안 체크리스트, 도메인 지식
→ 상세한 다단계 절차는 여기

Workflows (원클릭 실행):
→ /테스트생성, /코드리뷰, /배포
→ 반복 태스크 표준화

brain/ (자동 저장):
→ 아키텍처 결정, 세션 간 컨텍스트 유지
→ 건드릴 필요 없음 — 에이전트가 알아서 관리

---

마무리

✅ 설정 레이어 잘 활용하는 경우
→ 팀 전체 에이전트 동작을 표준화하고 싶을 때
→ "매번 같은 규칙 입력"이 귀찮을 때
→ 배포, 리뷰, 테스트 같은 반복 태스크가 많을 때
→ 여러 에이전트가 일관된 방식으로 작업해야 할 때

❌ 주의사항
→ GEMINI.md 500 토큰 초과: 에이전트 품질 저하
→ Skills에 너무 많은 내용: 관련 없는 태스크에서도 로드될 수 있음
→ Workflows 남용: 너무 구체적인 워크플로우는 유연성 떨어짐
→ brain/ git 커밋: 민감한 아키텍처 정보 외부 노출 주의

---

관련 글

• Google Antigravity 완전 가이드 1편 — 탄생 배경과 설치, 첫 세팅까지
• Google Antigravity 완전 가이드 2편 — Agent Manager로 멀티 에이전트 오케스트레이션 실전
• Google Antigravity 완전 가이드 3편 — 브라우저 서브에이전트, 2M 토큰 인덱싱, Google Cloud 배포
• CLAUDE.md 잘 쓰는 법 — 세션마다 시니어 개발자를 고용하는 효과

---