에이전트한테 매번 "TypeScript strict 모드 써줘", "테스트는 Jest로 해줘"를 반복 입력하고 있다면 하네스를 제대로 안 쓰고 있는 겁니다. 4편은 Antigravity를 진짜 팀원처럼 동작하게 만드는 설정 레이어를 다룹니다.
핵심 요약
GEMINI.md는 에이전트의 두뇌 역할을 하며 프로젝트 전반에 항상 로드되는 규칙입니다. Rules는 글로벌·프로젝트·에이전트별 3계층으로 우선순위가 나뉘고, Workflows는 슬래시 명령으로 반복 태스크를 원클릭 실행하게 해줍니다. Skills는 필요할 때만 로드되는 도메인 지식 모듈로 SKILL.md 형식을 따릅니다. GEMINI.md와 AGENTS.md는 혼용이 가능하지만 충돌이 생기면 GEMINI.md가 우선합니다. GEMINI.md는 500토큰 이하로 유지하는 게 적정 크기이고, 이를 초과하면 에이전트 응답 품질이 떨어집니다. Skills는 프로젝트 단위로는 .agents/skills/에, 글로벌로는 ~/.gemini/skills/에 저장하며, Workflows는 프로젝트 단위로 .antigravity/workflows/에, 글로벌로 ~/.gemini/antigravity/global_workflows/에 저장합니다.
4가지 설정 레이어 구조
Antigravity의 설정은 우선순위가 다른 4단계 레이어로 구성됩니다. 가장 위에는 시스템 규칙이 있는데, Google DeepMind가 내장한 안전 프로토콜과 핵심 능력 정의로 사용자가 건드릴 수 없는 영역입니다. 그 아래로 글로벌 규칙이 있는데 ~/.gemini/GEMINI.md에 저장되며 "항상 한국어로 답해줘", "TypeScript 선호" 같은 개인 선호가 모든 프로젝트에 적용됩니다. 세 번째는 프로젝트 규칙으로, 프로젝트 루트의 GEMINI.md에 기술 스택, 코딩 컨벤션, 금지 패턴 같은 팀 표준을 적어두면 현재 프로젝트에만 적용됩니다. 마지막으로 에이전트별 규칙은 .agent/rules/에이전트명.md에 저장하며 특정 에이전트에만 적용되는 역할별 특수 지침을 담습니다. Skills와 Workflows는 이 규칙 계층과는 별개로, 필요할 때만 로드되거나 실행되는 방식으로 동작합니다.
실전 1 — GEMINI.md 작성
GEMINI.md는 에이전트가 프로젝트에서 항상 참조하는 핵심 문서로, CLAUDE.md와 역할이 동일합니다. Antigravity 전용 기능은 GEMINI.md에 쓰고, 다른 툴과 공유하는 규칙은 AGENTS.md에 쓰는 식으로 구분하는 게 효율적입니다. 아래는 FastAPI 백엔드와 React 프론트엔드로 구성된 프로젝트의 GEMINI.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를 작성할 때는 모델이 어차피 알고 있는 일반론을 적는 게 토큰 낭비라는 점을 기억해야 합니다. "항상 읽기 쉬운 코드를 작성하세요", "변수명은 의미있게 지으세요", "주석을 충분히 달아주세요" 같은 문장은 모델이 기본적으로 따르는 내용이라 컨텍스트만 잡아먹고 효과는 없습니다. 반대로 "API 응답은 반드시 {data, error, meta} 구조", "migrations/ 폴더는 절대 건드리지 말 것", "새 패키지 추가 시 반드시 사전 확인"처럼 모델이 알 수 없는 프로젝트 특수 규칙을 적어야 실제로 효과가 있습니다.
크기 면에서는 500토큰 이하를 권장합니다. 이를 초과하면 에이전트 응답 품질이 떨어지는 경향이 있기 때문에, 절차적인 다단계 작업은 Skills로 옮기고 반복되는 태스크는 Workflows로 옮겨서 GEMINI.md 자체는 간결하게 유지하는 게 좋습니다.
GEMINI.md vs AGENTS.md 선택
Antigravity만 쓰는 프로젝트라면 GEMINI.md만 써도 충분합니다. 반대로 Claude Code나 Codex 같은 다른 도구와 규칙을 공유해야 한다면 AGENTS.md만 쓰는 게 효율적입니다. 두 도구를 함께 쓰는 환경이라면 AGENTS.md에는 기술 스택이나 코딩 컨벤션 같은 공통 규칙을 담고, GEMINI.md에는 Skills 참조나 브라우저 에이전트 설정처럼 Antigravity 전용 내용을 담는 식으로 역할을 나누면 됩니다. 두 파일의 내용이 충돌하면 GEMINI.md가 우선 적용됩니다.
실전 2 — Skills: 필요할 때만 로드되는 도메인 지식
GEMINI.md가 항상 로드되는 규칙이라면, Skills는 관련 태스크가 발생했을 때만 로드되는 모듈입니다. 컨텍스트를 낭비하지 않으면서 필요한 시점에 전문 지식을 주입할 수 있다는 점이 핵심 장점입니다.
저장 위치는 스코프에 따라 나뉩니다. 프로젝트 스코프는 .agents/skills/ 아래에 각 Skill 폴더를 두고, 그 안에 필수 파일인 SKILL.md와 함께 선택적으로 scripts, references, assets 폴더를 둘 수 있습니다. 글로벌 스코프로 모든 프로젝트에 적용하고 싶다면 ~/.gemini/skills/에 같은 구조로 저장하면 됩니다.
아래는 스테이징 배포를 다루는 SKILL.md 예시입니다. 사전 조건부터 단계별 명령, 검증까지 하나의 문서에 모두 담겨 있어서 에이전트가 이 Skill을 로드하면 전체 절차를 한 번에 파악할 수 있습니다.
---
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 푸시
\`\`\`bash
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 배포
\`\`\`bash
aws ecs update-service \
--cluster staging \
--service app-staging \
--force-new-deployment \
--profile staging
\`\`\`
### 4. 검증
- 배포 완료까지 대기 (약 2분)
- https://staging.myapp.com 접속 확인
- /health 엔드포인트 응답 확인
보안 리뷰처럼 체크리스트 형태가 어울리는 작업도 같은 방식으로 만들 수 있습니다.
---
name: security-review
description: OWASP 기준 보안 코드 리뷰
triggers:
- "보안 검토"
- "security review"
- "취약점 확인"
---
# 보안 리뷰 체크리스트
## 입력 검증
- [ ] 모든 사용자 입력 Pydantic으로 검증
- [ ] SQL 인젝션: ORM 사용, raw query 없음
- [ ] XSS: React 자동 이스케이프 확인
## 인증/인가
- [ ] JWT 만료 시간 설정 (access: 15분, refresh: 7일)
- [ ] 민감 엔드포인트 권한 체크
- [ ] 비밀번호 bcrypt 해싱 확인
## 시크릿 관리
- [ ] 환경변수만 사용, 하드코딩 없음
- [ ] .env 파일 .gitignore 확인
Skills가 로드되는 방식은 두 가지입니다. 자동 트리거 방식은 SKILL.md의 triggers 필드에 등록된 키워드가 감지되면 해당 Skill이 자동으로 활성화됩니다. "스테이징 배포해줘"라고 말하면 deploy-staging Skill이 자동으로 로드되는 식입니다. 수동 트리거 방식은 "@deploy-staging 실행해줘"처럼 에이전트에게 해당 Skill을 명시적으로 참조하도록 지시하는 방식입니다. GEMINI.md에 "배포 작업은 반드시 @deploy-staging Skill 참조"라고 명시해두면 두 방식을 결합해서 신뢰성을 높일 수도 있습니다.
실전 3 — Workflows: 반복 태스크 원클릭 실행
Workflows는 자주 쓰는 태스크를 슬래시 명령으로 저장해서 재사용하는 기능입니다. 프로젝트 단위는 .antigravity/workflows/에, 모든 프로젝트에서 쓰고 싶다면 ~/.gemini/antigravity/global_workflows/에 저장합니다.
단위 테스트를 생성하는 Workflow는 아래처럼 작성할 수 있습니다.
# generate-unit-tests.md
지정된 모듈의 포괄적인 pytest 테스트를 생성합니다.
- test_ 접두사로 테스트 파일 생성
- 모든 public 메서드 커버
- 엣지케이스 + 에러 조건 포함
- 외부 의존성은 fixture 사용
- 반환값과 사이드 이펙트 모두 assert
코드 리뷰나 일일 스탠드업처럼 팀 전체가 반복적으로 수행하는 작업도 Workflow로 만들어두면 효율이 올라갑니다.
# 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처럼 슬래시 명령으로 바로 실행할 수 있습니다. 슬래시를 입력하면 자동완성 목록이 표시되고, 프로젝트 git에 커밋해두면 팀 전체가 동일한 Workflow를 공유해서 사용할 수 있습니다.
실전 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에 커밋할 때는 민감한 아키텍처 정보가 외부에 노출되지 않도록 신경 써야 합니다.
관련 글