Rules (규칙)
Rules는 사용자가 수동으로 정의하는 에이전트의 제약 조건으로, Global 및 Workspace 수준에서 설정할 수 있습니다. Rules를 통해 사용자는 자신의 사용 사례와 스타일에 맞는 행동을 에이전트가 따르도록 안내할 수 있습니다. 공식 문서
Rules란? 공식 문서 #
공식 문서에 따르면, "Rules는 사용자가 수동으로 정의하는 에이전트의 제약 조건으로, Global 및 Workspace 수준에서 설정할 수 있습니다. Rules를 통해 사용자는 자신의 사용 사례와 스타일에 맞는 행동을 에이전트가 따르도록 안내할 수 있습니다."
Rule은 간단히 말해 에이전트가 따라야 할 제약 조건이 담긴 마크다운 파일입니다. 한 번 설정하면 매번 같은 지시를 반복할 필요 없이, 에이전트가 자동으로 규칙을 따릅니다. 데이터 전처리 방법, 분석 리포트 작성법, 시각화 스타일, 파일 인코딩 규칙, 개인정보 보호 정책 등을 에이전트에게 구체적으로 알려줄 수 있습니다.
Rules 적용 전후 비교
Rules가 없으면 에이전트는 매번 다른 방식으로 작업할 수 있습니다. 다음은 실제 차이를 보여주는 예시입니다:
# 사용자: "sales.csv 파일을 분석해줘"
# 에이전트의 응답 (매번 다를 수 있음):
import pandas as pd
df = pd.read_csv('sales.csv') # 인코딩 미지정 → 한글 깨질 수 있음
df.dropna(inplace=True) # 설명 없이 결측치 전부 삭제
df.describe() # 숫자만 나열, 해석 없음
# 사용자: "sales.csv 파일을 분석해줘"
# 에이전트의 응답 (규칙에 따라 일관된 방식):
import pandas as pd
import matplotlib.pyplot as plt
plt.rcParams['font.family'] = 'Malgun Gothic'
plt.rcParams['axes.unicode_minus'] = False
df = pd.read_csv('sales.csv', encoding='utf-8') # 인코딩 명시
print(f"데이터 크기: {df.shape}")
print(f"\n결측치 현황:\n{df.isnull().sum()}") # 결측 현황 먼저 보고
# 결측 비율: price 컬럼 3.2% → median으로 대체
df['price'].fillna(df['price'].median(), inplace=True)
# ... 시각화 포함, 비즈니스 맥락 해석 제공
왜 Rules가 필요한가?
- 일관성 유지 — 같은 데이터셋에 대해 팀원 누가 작업하든 동일한 전처리 파이프라인이 적용됩니다. 에이전트가 매번 같은 방식으로 데이터를 다룹니다.
- 반복 지시 제거 — "pandas 사용해", "matplotlib으로 그래프 그려", "한글 인코딩 확인해" 같은 지시를 매번 반복할 필요가 없습니다.
- 팀 공유 — Workspace Rules는 Git으로 버전 관리하여 데이터 분석팀 전체가 동일한 컨벤션을 따릅니다.
- 품질 관리 — 결측치 처리 누락, 인코딩 오류, 재현 불가능한 분석 등 자주 발생하는 문제를 사전에 방지합니다.
- 컨텍스트 보존 — 프로젝트의 데이터 소스, 분석 도구, 보고서 형식을 에이전트가 항상 인지합니다.
관련 공식 문서 및 참고 자료
Rules 만들기 공식 문서 #
공식 문서에 따르면, Rules는 에이전트가 따라야 할 제약 조건이 담긴 마크다운 파일입니다. UI를 통해 만들거나 직접 파일을 생성할 수 있습니다.
공식 문서 기준: Rules 생성 방법 (UI)
공식 문서에서 안내하는 Rules 생성 절차는 다음과 같습니다: 공식 문서
- 에디터의 에이전트 패널 상단에 있는 "..." 드롭다운을 통해 Customizations 패널을 엽니다.
- Rules 패널로 이동합니다.
- + Global을 클릭하여 새로운 Global Rules를 생성하거나, + Workspace를 클릭하여 해당 워크스페이스 전용 Rules를 생성합니다.
파일 직접 생성
UI를 사용하지 않고 직접 마크다운 파일을 생성할 수도 있습니다.
- Global Rules의 경우
~/.gemini/GEMINI.md파일을 생성합니다. - Workspace Rules의 경우 워크스페이스 또는 Git 루트의
.agents/rules/디렉터리에 마크다운 파일을 생성합니다. - 마크다운 형식으로 규칙을 작성합니다. 제목(
#), 목록(-), 코드 블록, 강조(**) 등을 자유롭게 활용하세요.
# 데이터 분석 프로젝트의 Rules 구조
.agents/rules/ # 권장 경로 (현재 기본)
├── data-conventions.md # 데이터 전처리 컨벤션
├── csv-handling.md # CSV/Excel 파일 처리 규칙
├── report-format.md # 분석 리포트 작성 규칙
├── visualization-style.md # 시각화 스타일 가이드
└── data-security.md # 데이터 보안/개인정보 규칙
# .agent/rules/ (단수형)도 하위 호환 지원됨
첫 번째 Rule 만들기 (5분 가이드)
- 프로젝트 루트에
.agents/rules/폴더를 생성합니다. - 폴더 안에
korean-comments.md파일을 만듭니다. - 아래 내용을 붙여넣고 저장합니다.
# 한국어 주석 규칙
모든 코드에 한국어 주석을 작성합니다.
## 세부 규칙
- 함수 위에 docstring을 한국어로 작성
- 복잡한 로직에는 인라인 주석 추가
- 변수명은 영어, 주석은 한국어로 작성
## 예시
```python
def calculate_monthly_revenue(df):
"""월별 매출을 계산합니다."""
# 날짜 컬럼을 월 단위로 그룹화
monthly = df.groupby(df['date'].dt.month)['revenue'].sum()
return monthly
```
rule1.md보다 data-conventions.md가 나중에 관리하기 쉽습니다. Manual 모드에서는 파일명이 곧 @멘션 이름이 됩니다.
관련 공식 문서 및 참고 자료
Global vs Workspace Rules 공식 문서 #
공식 문서에 따르면, Rules는 적용 범위에 따라 Global(전역)과 Workspace(워크스페이스) 두 가지로 나뉩니다.
Global Rules (전역)
공식 문서: "~/.gemini/GEMINI.md에 위치하며, 모든 워크스페이스에 적용됩니다." 개인의 분석 스타일이나 기본 설정을 정의하는 데 적합합니다. 공식 문서
# Global Rules 파일 위치
~/.gemini/GEMINI.md # 모든 워크스페이스에 적용
예: 선호하는 시각화 라이브러리(matplotlib vs seaborn), 기본 인코딩 설정, 한국어 응답 선호, 그래프 스타일
Workspace Rules (워크스페이스별)
공식 문서: "워크스페이스 또는 Git 루트의 .agents/rules 폴더에 위치합니다." Git으로 버전 관리하여 팀원 모두가 동일한 분석 규칙을 공유할 수 있습니다. 공식 문서
# Workspace Rules 파일 위치
.agents/rules/규칙이름.md # 현재 기본 (권장)
.agent/rules/규칙이름.md # 하위 호환 지원
예: 이 프로젝트는 pandas 사용, 저 프로젝트는 SQL 기반, 데이터 소스 정의, 리포트 형식
.agents/rules를 기본으로 사용하지만, .agent/rules에 대한 하위 호환도 유지합니다. 기존 프로젝트에서 .agent/rules/를 사용하고 있다면 변경하지 않아도 됩니다.
공식 문서
Global vs Workspace 선택 가이드
| 상황 | Global | Workspace |
|---|---|---|
| 개인 시각화 스타일 (seaborn 선호 등) | 적합 | - |
| 팀 데이터 컨벤션 (결측치 처리 방법 등) | - | 적합 |
| 프로젝트 기술 스택 (pandas vs PySpark) | - | 적합 |
| 공통 보안 정책 (PII 마스킹 등) | 적합 | 적합 |
| 기본 인코딩/로케일 설정 | 적합 | - |
| 프로젝트별 데이터 소스 정의 | - | 적합 |
# Global Rules (전역 - 모든 워크스페이스에 적용)
~/.gemini/GEMINI.md # 공식 문서 기준 경로
# Workspace Rules (프로젝트별)
.agents/rules/*.md # 현재 기본 경로 (권장)
.agent/rules/*.md # 하위 호환 지원
관련 공식 문서 및 참고 자료
활성화 모드 공식 문서 #
공식 문서에 따르면, Workspace Rules는 규칙 수준에서 다음 4가지 활성화 모드(Activation modes)를 지원합니다. 적절한 모드를 선택하면 불필요한 규칙 로딩을 줄이고, 관련 있는 상황에서만 규칙이 동작하도록 할 수 있습니다.
| 모드 | 공식 정의 | 데이터 분석 예시 |
|---|---|---|
| Manual | 에이전트 입력창에서 @ 멘션으로 수동 활성화 | @대용량-데이터 처리 규칙, @웹-스크래핑 규칙 |
| Always On | 항상 적용됨 — 모든 에이전트 대화에 자동 포함 | 데이터 품질 규칙, 인코딩 규칙, 결측치 처리 원칙 |
| Model Decision | 자연어 설명(description)을 기반으로 모델이 적용 여부를 판단 | 시계열 분석 규칙, 통계 검정 규칙, 머신러닝 모델 평가 규칙 |
| Glob | 글로브 패턴(예: *.js, src/**/*.ts)에 매칭되는 파일에 적용 | *.csv → CSV 처리 규칙, *.ipynb → 노트북 작성 규칙 |
모드별 상세 설명 + 실전 시나리오
Manual — 수동 @멘션 활성화
공식 정의: 에이전트 입력창에서 @규칙이름으로 수동 활성화(Manually activated via @ mention)합니다. 대용량 데이터 처리, 웹 스크래핑, 특수 리포트 형식 등 가끔 필요한 규칙에 적합합니다.
공식 문서
실전 시나리오: 평소에는 pandas로 분석하다가, 10GB 로그 파일을 처리해야 할 때 @대용량-데이터를 멘션합니다. 그러면 chunksize 사용, Dask/Polars 전환, 메모리 최적화 규칙이 활성화됩니다.
Always On — 항상 적용
공식 정의: 항상 적용(Always applied)됩니다. 모든 대화에서 자동으로 활성화됩니다. "CSV는 UTF-8로 읽어라", "결측치를 발견하면 비율을 먼저 보고해라" 같은 핵심 데이터 품질 규칙에 사용하세요. 공식 문서
실전 시나리오: "매출 데이터 분석해줘"라고만 말해도 에이전트가 자동으로 한글 폰트를 설정하고, UTF-8로 파일을 읽고, 결측치 현황부터 보고합니다.
Model Decision — 모델 자체 판단
공식 정의: 자연어 설명(description)을 기반으로 모델이 적용 여부를 판단(Based on natural language description, model decides whether to apply)합니다. 통계 검정, 시계열 분석, 머신러닝 평가 등 특정 분석 주제에 적합합니다. 공식 문서
실전 시나리오: "A/B 테스트 결과를 분석해줘"라고 요청하면, 에이전트가 통계 분석 규칙의 설명을 보고 이 규칙이 필요하다고 판단하여 자동 활성화합니다.
Glob — 파일 패턴 매칭
공식 정의: 글로브 패턴(예: *.js, src/**/*.ts)에 매칭되는 파일에 적용(Based on glob pattern, applied to matching files)됩니다. *.csv 파일을 다룰 때는 CSV 처리 규칙이, *.ipynb 파일을 다룰 때는 노트북 작성 규칙이 자동 활성화됩니다.
공식 문서
실전 시나리오: "sales_2024.csv를 분석해줘"라고 요청하면 *.csv Glob에 의해 CSV 처리 규칙이 자동 활성화됩니다.
"특정 파일에서만 필요한가?" (예: CSV 처리, 노트북 작성) → Glob
"에이전트가 알아서 판단할 수 있는가?" (예: 시계열 분석, 통계 검정) → Model Decision
"필요할 때만 직접 활성화하고 싶은가?" (예: 대용량 데이터 처리) → Manual
Always On 모드로 시작하세요. Rules가 안정적으로 동작하는지 확인한 후, 상황에 따라 Model Decision이나 Manual로 전환하면 됩니다. 데이터 분석 관련 Rules는 대부분 Always On이 적합합니다.
관련 공식 문서 및 참고 자료
@ Mentions (파일 참조) 공식 문서 #
공식 문서에 따르면, Rules 파일 내에서 @filename 구문을 사용하여 다른 파일을 참조할 수 있습니다. 이 기능을 통해 Rules 파일이 프로젝트의 다른 파일을 컨텍스트로 포함하도록 지시할 수 있습니다.
경로 해석 규칙
| 경로 유형 | 해석 방식 | 예시 |
|---|---|---|
| 상대 경로 | Rules 파일 위치를 기준으로 상대 경로로 해석됩니다. | @../data/schema.md |
| 절대 경로 | 시스템의 진짜 절대 경로로 해석되며, 찾지 못하면 리포지토리 기준 상대 경로로 시도합니다. | @/path/to/file.md |
@/path/to/file.md는 먼저 /path/to/file.md (절대 경로)를 시도하고, 찾지 못하면 workspace/path/to/file.md (리포지토리 기준)로 시도합니다.
공식 문서
데이터 분석에서의 @ Mentions 활용 예시
# 데이터 전처리 규칙
## 참조 파일
- 프로젝트 의존성은 @requirements.txt 를 참고
- 데이터 스키마는 @/docs/data-schema.md 를 참고
- 컬럼 정의는 @../data/column-definitions.csv 를 참고
## 전처리 원칙
- 위 스키마에 정의된 타입을 반드시 따른다
- 컬럼 이름은 column-definitions에 따라 매핑한다
설정 파일 참조
@requirements.txt나 @pyproject.toml을 참조하여 에이전트가 프로젝트의 의존성과 버전을 항상 인지하도록 합니다.
데이터 스키마 참조
@/docs/data-schema.md를 참조하여 에이전트가 데이터 구조, 컬럼 타입, 관계를 이해한 상태에서 분석을 수행하도록 합니다.
관련 공식 문서 및 참고 자료
실전 Rules 예시 공식 문서 #
데이터 수집과 분석 작업에서 바로 사용할 수 있는 3가지 실전 예시입니다. 각 예시에는 규칙의 내용뿐 아니라, 이 규칙이 없으면 어떤 문제가 발생하는지도 함께 설명합니다.
예시 1: 데이터 전처리 컨벤션
# 데이터 전처리 규칙 (Always On)
## 기본 도구
- 데이터 처리: pandas 사용 (polars는 대용량일 때만)
- 수치 연산: numpy 사용
- 날짜 처리: pd.to_datetime() 사용, 문자열 파싱 금지
## 파일 읽기
- CSV: pd.read_csv(encoding='utf-8') 기본 사용
- 한글이 깨지면 encoding='cp949' 또는 'euc-kr' 시도
- Excel: pd.read_excel(engine='openpyxl') 사용
- 대용량 파일(100MB+): chunksize 파라미터로 분할 읽기
## 결측치 처리
- 먼저 df.isnull().sum()으로 결측 현황을 보고한다
- 결측 비율이 50% 이상인 컬럼은 삭제를 제안한다
- 수치형: median으로 대체하고, 주석으로 대체 이유를 기록한다
- 범주형: 'Unknown' 또는 최빈값으로 대체한다
- 절대로 아무 설명 없이 dropna()를 사용하지 않는다
## 참조 파일
@requirements.txt
@/docs/data-schema.md
df.dropna()를 아무 설명 없이 실행하여 중요한 데이터가 삭제될 수 있습니다. 인코딩을 지정하지 않아 한글이 깨지고, 타입 변환 없이 문자열로 된 숫자를 그대로 분석하여 잘못된 결과를 낼 수 있습니다.
예시 2: 분석 리포트 작성 규칙
# 분석 리포트 작성 규칙 (Always On)
## 구조 원칙
- 결론을 먼저 제시하고, 그다음 근거 데이터를 보여준다
- 모든 분석에는 "그래서 무엇을 해야 하는가"(액션 아이템)를 포함한다
- 숫자만 나열하지 말고, 비즈니스 맥락에서 해석을 제공한다
## 시각화 필수 포함
- 분포 확인: 히스토그램 또는 박스플롯
- 추세 확인: 라인 차트 (시간축 필수)
- 비교: 막대 차트 또는 그룹별 박스플롯
- 상관관계: 히트맵 또는 산점도
- 모든 차트에 제목, 축 레이블, 단위를 포함한다
## 재현 가능성
- 랜덤 시드 사용 시 반드시 random_state=42로 고정
- 데이터 소스 경로와 수집 일자를 명시한다
- 사용한 라이브러리 버전을 기록한다
## 통계 보고 형식
- 평균값에는 반드시 표준편차를 함께 보고: "평균 42.3 (+-5.1)"
- 비율은 소수점 첫째 자리까지: "전환율 12.5%"
- 큰 숫자는 읽기 쉽게 포맷: "1,234,567명"
- p-value는 소수점 셋째 자리까지: "p = 0.003"
df.describe()만 출력하고 끝나는 경우가 많습니다. 시각화 없이 숫자만 나열하거나, 랜덤 시드를 고정하지 않아 다음에 같은 분석을 돌리면 다른 결과가 나올 수 있습니다.
예시 3: 데이터 보안/개인정보 규칙
# 데이터 보안 및 개인정보 규칙 (Always On)
## PII(개인식별정보) 마스킹
- 이름: 첫 글자만 남기고 마스킹 ("김**")
- 전화번호: 가운데 4자리 마스킹 ("010-****-1234")
- 이메일: 아이디 절반 마스킹 ("ki***@gmail.com")
- 주민번호: 절대 원본 노출 금지, 뒤 7자리 마스킹
## 데이터 접근 규칙
- 분석 결과를 공유할 때 원본 데이터 경로를 노출하지 않는다
- 샘플 데이터를 보여줄 때 df.head()는 5행까지만 출력
- 민감한 컬럼(급여, 나이, 주소 등)은 집계 결과만 사용
## 금지 사항
- 개인정보가 포함된 데이터를 외부 API로 전송하지 않는다
- 분석 코드에 DB 비밀번호나 API 키를 하드코딩하지 않는다
- .env 파일이나 환경 변수를 사용하여 인증 정보를 관리한다
df.head(20)으로 개인정보가 포함된 데이터를 대량 출력할 수 있습니다. 고객 이름, 전화번호, 이메일이 마스킹 없이 노출되고, DB 비밀번호가 코드에 하드코딩되어 Git에 커밋될 위험이 있습니다.
# 이름 마스킹
df['name_masked'] = df['name'].apply(lambda x: x[0] + '*' * (len(x)-1) if pd.notna(x) else x)
# 전화번호 마스킹
df['phone_masked'] = df['phone'].str.replace(r'(\d{3})-(\d{4})-(\d{4})', r'\1-****-\3', regex=True)
# 이메일 마스킹
def mask_email(email):
if pd.isna(email): return email
local, domain = email.split('@')
return local[:len(local)//2] + '*' * (len(local) - len(local)//2) + '@' + domain
df['email_masked'] = df['email'].apply(mask_email)
데이터 품질 검증 Rule
데이터를 로드한 후 자동으로 품질 검증을 수행하는 Rule입니다.
# 데이터 품질 자동 검증 Rule
데이터프레임을 로드한 후 반드시 아래 검증을 수행합니다:
1. 결측치 비율 확인 (컬럼별)
2. 데이터 타입 확인 및 자동 변환
3. 중복 행 확인 및 보고
4. 이상치 탐지 (IQR 기반)
5. 기본 통계량 요약 출력
검증 결과는 표 형태로 출력하고, 문제가 발견되면 해결 방안을 제안합니다.
"이 데이터 분석해줘" → 바로 분석 시작, 결측치나 이상치를 놓칠 수 있음
"이 데이터 분석해줘" → 자동으로 품질 검증 → 문제 보고 → 안전하게 분석 진행
관련 공식 문서 및 참고 자료
활용 패턴 공식 문서 #
Rules를 효과적으로 활용하는 실전 패턴 4가지를 소개합니다. 각 패턴에는 활성화 모드, 사용 목적, 실제 예시를 포함합니다.
패턴 1: 데이터 기술 스택 가이드 Always On
프로젝트의 데이터 분석 기술 스택을 에이전트에게 항상 알려주는 규칙입니다.
# 데이터 분석 기술 스택
## 핵심 라이브러리
- **데이터 처리**: pandas 2.x, numpy
- **시각화**: matplotlib + seaborn (기본), plotly (인터랙티브)
- **통계**: scipy.stats, statsmodels
- **머신러닝**: scikit-learn
## 시각화 기본 설정
```python
import matplotlib.pyplot as plt
plt.rcParams['font.family'] = 'Malgun Gothic'
plt.rcParams['axes.unicode_minus'] = False
plt.rcParams['figure.figsize'] = (10, 6)
```
## 참조
@requirements.txt
@pyproject.toml
@requirements.txt로 의존성 파일을 참조하면 에이전트가 사용 가능한 라이브러리를 정확히 파악합니다.
공식 문서
패턴 2: CSV/Excel 파일 처리 규칙 Glob: *.csv, *.xlsx
CSV나 Excel 파일을 다룰 때 자동으로 적용되는 파일 처리 규칙입니다. Glob 패턴으로 해당 파일이 언급될 때만 활성화됩니다.
# CSV/Excel 파일 처리 규칙
## 파일 읽기 전 확인사항
1. 파일 인코딩 확인 (UTF-8, CP949, EUC-KR 순서로 시도)
2. 헤더 행 위치 확인 (header=0이 기본)
3. 구분자 확인 (CSV는 쉼표, TSV는 탭)
4. 파일 크기 확인 (100MB 이상이면 chunksize 사용)
## 읽기 직후 필수 확인
- print(f"Shape: {df.shape}")
- print(df.dtypes)
- print(df.head())
- print(df.isnull().sum())
## 저장 규칙
- CSV 저장 시 항상 index=False, encoding='utf-8-sig'
- 날짜 컬럼은 ISO 형식(YYYY-MM-DD)으로 저장
패턴 3: Jupyter Notebook 작성 규칙 Glob: *.ipynb
Jupyter Notebook을 작성하거나 수정할 때 자동으로 적용되는 규칙입니다.
# Jupyter Notebook 작성 규칙
## 셀 구조 (순서대로)
1. 제목 셀 (마크다운): 분석 제목, 작성자, 날짜
2. 목차 셀 (마크다운): 분석 단계 목록
3. 환경 설정 셀: import, 설정, 시드 고정
4. 데이터 로드 셀: 데이터 읽기 + shape 확인
5. EDA 셀: 탐색적 데이터 분석
6. 전처리 셀: 정제, 변환
7. 분석/모델링 셀: 핵심 분석
8. 결론 셀 (마크다운): 요약 + 액션 아이템
## 마크다운 셀 규칙
- 각 분석 단계 사이에 마크다운 셀로 설명을 추가한다
- "왜 이 방법을 선택했는지"를 반드시 기록한다
- 코드 셀만 연속으로 5개 이상 나열하지 않는다
패턴 4: 통계 분석 규칙 Model Decision
통계 분석이나 가설 검정을 수행할 때 에이전트가 자동으로 판단하여 적용하는 규칙입니다. 공식 문서의 Model Decision 정의에 따라 자연어 설명을 기반으로 모델이 적용 여부를 결정합니다.
# 통계 분석 규칙
# description: 통계 검정, 가설 검정, 유의성 분석, A/B 테스트,
# 상관분석, 회귀분석을 수행할 때 적용
## 검정 방법 선택 가이드
- 두 그룹 비교 (정규분포): 독립표본 t-test
- 두 그룹 비교 (비정규분포): Mann-Whitney U test
- 세 그룹 이상 비교: ANOVA → 사후검정(Tukey HSD)
- 범주형 변수 간 관계: 카이제곱 검정
## 필수 보고 사항
- 귀무가설과 대립가설을 먼저 명시한다
- 유의수준은 0.05를 기본으로 사용한다
- 검정 통계량, p-value, 효과 크기(effect size)를 함께 보고
- "유의하다/유의하지 않다"를 명확히 결론짓는다
## 주의사항
- 정규성 검정(Shapiro-Wilk)을 먼저 수행한다
- 표본 크기가 30 미만이면 비모수 검정을 우선 고려
- 다중 비교 시 보정(Bonferroni 등)을 적용한다
- 상관관계와 인과관계를 혼동하지 않는다
관련 공식 문서 및 참고 자료
MCP (Model Context Protocol) 연동 공식 문서 #
Antigravity 에이전트는 MCP (Model Context Protocol)를 통해 외부 도구 및 데이터 소스와 연동할 수 있습니다. MCP는 에이전트가 외부 시스템의 도구(tool)를 호출하고, 리소스(resource)를 읽어오는 표준 프로토콜입니다. Rules와 함께 사용하면 에이전트가 외부 도구를 활용할 때의 행동 규칙도 정의할 수 있습니다.
MCP 도구(Tool) 활용
MCP 서버가 제공하는 도구를 에이전트가 호출할 수 있습니다. 데이터베이스 쿼리 도구, 파일 시스템 접근 도구, 외부 API 호출 도구 등을 Rules에서 참조하여 에이전트의 활용 방식을 제어합니다. 공식 문서
MCP 리소스(Resource) 참조
MCP 서버가 노출하는 리소스(데이터, 스키마 등)를 에이전트가 읽어올 수 있습니다. Rules에서 "데이터베이스 스키마는 MCP 리소스에서 확인해라"와 같은 지시를 포함할 수 있습니다. 공식 문서
# MCP 연동 규칙 (Model Decision)
# description: 외부 데이터베이스 조회, API 호출이 필요할 때 적용
## MCP 도구 사용 원칙
- DB 쿼리 도구 사용 시 SELECT만 허용, INSERT/UPDATE/DELETE는 확인 후 실행
- API 호출 시 rate limit을 준수하고, 재시도 로직을 포함
- MCP 리소스에서 스키마를 먼저 확인한 후 쿼리를 작성
## 보안 규칙
- MCP를 통해 가져온 데이터에 PII가 포함되어 있으면 즉시 마스킹
- 외부 API 키는 MCP 서버 설정에서 관리 (코드에 노출 금지)
관련 공식 문서 및 참고 자료
흔한 실수와 해결법 공식 문서 #
Rules를 처음 사용할 때 흔히 겪는 실수들과 그 해결 방법을 정리했습니다.
"데이터를 잘 정리해", "분석을 꼼꼼하게 해" 같은 모호한 규칙은 에이전트가 해석하기 어렵습니다. 구체적인 행동 지침이 없으면 규칙이 사실상 무시됩니다.
# 나쁜 예
- 데이터를 잘 정리해라
- 결측치를 적절히 처리해라
# 좋은 예
- 결측치는 median으로 대체하고, 주석으로 대체 이유를 기록한다
- 결측 비율이 50% 이상인 컬럼은 삭제하고 보고한다
- 모든 수치 결과에는 단위를 명시한다 (원, 명, % 등)
모든 규칙을 Always On으로 설정하면 매 대화마다 모든 규칙이 프롬프트에 포함되어 토큰을 과도하게 사용합니다.
- Always On은 3~5개 이내의 핵심 규칙만
- Glob으로 파일별 규칙을 분리 (*.csv, *.ipynb, *.sql)
- Model Decision으로 주제별 규칙을 분리 (통계 검정, 시계열 분석)
- Manual은 가끔 필요한 특수 규칙 (@멘션으로 활성화)
하나의 규칙 파일에 너무 많은 내용을 담으면 12,000자 제한을 초과하여 규칙이 잘리거나 무시됩니다.
# 나쁜 예: 하나의 거대한 파일
.agents/rules/all-rules.md # 15,000자 → 잘림!
# 좋은 예: 주제별 분리
.agents/rules/data-conventions.md # 3,000자
.agents/rules/csv-handling.md # 2,500자
.agents/rules/visualization.md # 2,000자
.agents/rules/report-format.md # 2,500자
Glob 모드에서 파일 패턴을 잘못 지정하면 규칙이 활성화되지 않거나, 의도하지 않은 파일에서 활성화됩니다.
# 공식 문서 예시 형태: *.js, src/**/*.ts
*.csv # 현재 폴더의 CSV 파일만
**/*.csv # 모든 하위 폴더의 CSV 파일 (추천)
src/**/*.ts # src 폴더 및 하위 모든 TS 파일
**/*.ipynb # 모든 Jupyter 노트북
자주 묻는 질문 (FAQ) 공식 문서 #
Rules는 에이전트가 "어떻게 행동해야 하는지"를 정의하는 제약 조건입니다. 예를 들어 "결측치는 median으로 대체해라", "CSV는 UTF-8로 읽어라" 같은 규칙입니다.
반면 Skills는 에이전트가 "무엇을 할 수 있는지"를 확장하는 능력 패키지입니다. SKILL.md 파일에 특정 작업의 전문 지식과 절차를 담아두면, 에이전트가 해당 작업을 요청받았을 때 자동으로 스킬을 참고합니다.
| 구분 | Rules | Skills |
|---|---|---|
| 역할 | 행동 제약 조건 (How) | 전문 지식 패키지 (What) |
| 적용 방식 | 항상/자동/수동 적용 | 관련 작업 시 자동 선택 |
| 파일 위치 | .agents/rules/ | .agents/skills/ |
| 예시 | "한국어로 주석 작성" | "EDA 분석 시 이 절차를 따라라" |
같은 수준의 규칙이 충돌할 경우, 에이전트가 두 규칙을 모두 인지하고 가능한 한 조합하려 시도합니다. 예를 들어 한 규칙이 "코드에 주석을 달아라"이고 다른 규칙이 "코드를 간결하게 유지해라"이면, 에이전트는 간결한 주석을 작성합니다.
충돌을 방지하는 모범 사례:
- Global Rules에는 언어, 포맷 등 범용 규칙만 작성
- Workspace Rules에는 프로젝트 특화 규칙만 작성
- 같은 주제의 규칙을 여러 파일에 분산하지 말 것
- 충돌 가능성이 있다면 규칙 파일 내에 우선순위를 명시
Global Rules는 ~/.gemini/GEMINI.md에 위치하며, 모든 워크스페이스에 공통으로 적용됩니다.
# Global Rules 위치
~/.gemini/GEMINI.md # 모든 프로젝트에 적용되는 전역 규칙
# Workspace Rules 위치
프로젝트/.agents/rules/*.md # 해당 프로젝트에만 적용되는 규칙
일반적으로 Global Rules에는 선호하는 프로그래밍 언어, 응답 언어(한국어), 코딩 스타일 등을 설정하고, Workspace Rules에는 프로젝트별 데이터 처리 규칙, 라이브러리 선호도 등을 설정합니다.
네, Rules 파일 내에서 @filename 구문으로 다른 파일을 참조할 수 있습니다. 이를 통해 규칙을 모듈화하고 재사용할 수 있습니다.
경로 해석 방식:
@utils.md— Rules 파일과 같은 폴더에서 찾기 (상대 경로)@/docs/style-guide.md— 절대 경로를 먼저 시도하고, 없으면 리포지토리 루트 기준 상대 경로로 시도@../shared/common-rules.md— 상위 폴더 참조도 가능
# 데이터 분석 마스터 Rule
아래 규칙들을 모두 따릅니다:
@coding-style.md
@data-quality.md
@visualization-standards.md
세 가지 방법으로 확인할 수 있습니다:
- 직접 질문하기: 에이전트에게 "현재 적용된 규칙을 알려줘" 또는 "이 작업에 어떤 규칙이 적용되고 있어?"라고 물어봅니다. 에이전트가 활성 규칙 목록을 알려줍니다.
- 출력 관찰하기: 에이전트의 코드나 응답이 규칙을 따르는지 확인합니다. 예를 들어 "한국어 주석" 규칙을 설정했다면, 생성된 코드에 한국어 주석이 포함되어야 합니다.
- Customizations 패널: Antigravity 좌측 하단의 Customizations 패널에서 각 규칙의 활성화 상태(Always On / Model Decision / Manual / Glob)를 시각적으로 확인할 수 있습니다.
Glob 패턴은 규칙이 적용될 파일 범위를 지정하는 데 사용됩니다. 핵심 문법:
| 패턴 | 의미 | 예시 |
|---|---|---|
* | 현재 폴더에서 임의의 문자 | *.csv → data.csv, sales.csv |
** | 모든 하위 폴더 포함 | **/*.py → src/main.py, lib/utils/helper.py |
? | 단일 문자 | data?.csv → data1.csv, dataA.csv |
{a,b} | 여러 패턴 중 택 1 | *.{csv,xlsx} → 모든 CSV와 Excel 파일 |
데이터 분석에서 자주 쓰는 패턴:
globs:
- "**/*.csv" # 모든 CSV 파일
- "**/*.ipynb" # 모든 Jupyter 노트북
- "**/*.{xlsx,xls}" # 모든 Excel 파일
- "**/*.sql" # 모든 SQL 파일
- "data/**/*" # data 폴더 내 모든 파일
- "notebooks/**/*.py" # notebooks 폴더의 Python 파일
규칙 파일 개수에 명시적인 상한은 없지만, 실용적으로는 5~10개 정도가 관리하기 좋습니다.
권장 구성 예시 (데이터 분석 프로젝트):
| 파일명 | 활성화 모드 | 내용 |
|---|---|---|
korean-style.md | Always | 한국어 응답, 주석 규칙 |
data-quality.md | Always | 데이터 로드 시 품질 검증 |
coding-convention.md | Always | 코드 스타일, 라이브러리 선호도 |
viz-standards.md | Auto | 시각화 스타일, 폰트, 색상 |
security.md | Always | PII 마스킹, 민감 데이터 처리 |
jupyter-format.md | Auto | 노트북 작성 규칙 (globs: *.ipynb) |
Antigravity는 현재 .agents/ (복수형)를 기본 경로로 사용하지만, .agent/ (단수형)에 대한 하위 호환도 유지합니다.
| 경로 | 상태 | 권장 |
|---|---|---|
.agents/rules/ | 현재 기본 경로 | 권장 |
.agent/rules/ | 하위 호환 지원 | 가능 |
새 프로젝트에서는 반드시 .agents/ (복수형)를 사용하세요. 기존 프로젝트에서 .agent/를 사용 중이라면 당장 변경하지 않아도 되지만, 점진적으로 마이그레이션하는 것을 권장합니다.
# 기존 .agent/를 .agents/로 마이그레이션
mv .agent/rules .agents/rules
# .gitignore에서도 경로 업데이트 확인