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파일을 생성합니다. - 크로스 플랫폼 규칙의 경우
AGENTS.md파일을 프로젝트 루트에 생성합니다. v1.20.3+ - 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
```
# 규칙 파일 크기 확인 (macOS / Linux)
wc -m .agents/rules/data-conventions.md
# 출력 예: 4523 .agents/rules/data-conventions.md (4,523자 — 안전)
# 여러 파일 한번에 확인
wc -m .agents/rules/*.md
# 12,000 이상인 파일은 분리 필요
rule1.md보다 data-conventions.md가 나중에 관리하기 쉽습니다. Manual 모드에서는 파일명이 곧 @멘션 이름이 됩니다.
관련 공식 문서 및 참고 자료
Global vs Workspace Rules 공식 문서 #
공식 문서에 따르면, Rules는 적용 범위에 따라 Global(전역)과 Workspace(워크스페이스) 두 가지로 나뉩니다.
Global Rules (전역)
공식 문서: "~/.gemini/GEMINI.md에 위치하며, 모든 워크스페이스에 적용됩니다." 개인의 분석 스타일이나 기본 설정을 정의하는 데 적합합니다. 공식 문서
# Global Rules 파일 위치 (운영체제별 실제 경로)
~/.gemini/GEMINI.md # 공통 표기 (홈 디렉터리 ~ 사용)
# macOS / Linux
/Users/<사용자명>/.gemini/GEMINI.md # macOS
/home/<사용자명>/.gemini/GEMINI.md # Linux
# Windows (PowerShell·cmd 모두 동일)
C:\Users\<사용자명>\.gemini\GEMINI.md # 절대 경로
%USERPROFILE%\.gemini\GEMINI.md # 환경변수 표기 (cmd)
$env:USERPROFILE\.gemini\GEMINI.md # 환경변수 표기 (PowerShell)
예: 선호하는 시각화 라이브러리(matplotlib vs plotly), 기본 인코딩 설정, 한국어 응답 선호, 그래프 스타일
운영체제별 파일 생성 명령
# 디렉터리·파일이 없으면 생성하고 기본 편집기로 열기
mkdir -p ~/.gemini
touch ~/.gemini/GEMINI.md
open ~/.gemini/GEMINI.md # macOS — 기본 앱으로 열기
xdg-open ~/.gemini/GEMINI.md # Linux — 기본 앱으로 열기
# 또는 즉시 편집
nano ~/.gemini/GEMINI.md
# 또는 VS Code·Antigravity 등 사용 중인 에디터로
code ~/.gemini/GEMINI.md
# 디렉터리·파일이 없으면 생성
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini" | Out-Null
New-Item -ItemType File -Force -Path "$env:USERPROFILE\.gemini\GEMINI.md" | Out-Null
# 메모장으로 열기
notepad "$env:USERPROFILE\.gemini\GEMINI.md"
# 또는 VS Code·Antigravity 등으로 열기
code "$env:USERPROFILE\.gemini\GEMINI.md"
if not exist "%USERPROFILE%\.gemini" mkdir "%USERPROFILE%\.gemini"
type nul > "%USERPROFILE%\.gemini\GEMINI.md"
notepad "%USERPROFILE%\.gemini\GEMINI.md"
주의 (Windows): 파일 탐색기에서 .gemini처럼 점(.)으로 시작하는 폴더를 직접 만들면 이름이 잘릴 수 있습니다. 위 명령처럼 PowerShell·cmd로 만들거나, 탐색기에서 만든 후 이름 끝에 점을 하나 더 붙여(.gemini.) 저장하면 자동으로 마지막 점이 제거되며 정상 생성됩니다. 한글 사용자명이 포함된 경로(C:\Users\홍길동\.gemini\)도 정상 동작하지만, 일부 외부 도구는 한글 경로에서 인코딩 문제가 발생할 수 있어 가급적 영문 사용자명을 권장합니다.
Workspace Rules (워크스페이스별)
공식 문서: "워크스페이스 또는 Git 루트의 .agents/rules 폴더에 위치합니다." Git으로 버전 관리하여 팀원 모두가 동일한 분석 규칙을 공유할 수 있습니다. 공식 문서
# Workspace Rules 파일 위치
.agents/rules/규칙이름.md # 현재 기본 (권장)
.agent/rules/규칙이름.md # 하위 호환 지원
예: 이 프로젝트는 pandas 사용, 저 프로젝트는 SQL 기반, 데이터 소스 정의, 리포트 형식
AGENTS.md (크로스 플랫폼) v1.20.3+
v1.20.3부터 Antigravity는 GEMINI.md 외에 AGENTS.md 파일도 읽습니다. AGENTS.md는 여러 AI 코딩 도구에서 공통으로 사용할 수 있는 크로스 플랫폼 규칙 파일입니다.
# AGENTS.md 파일 위치
프로젝트_루트/AGENTS.md # 크로스 플랫폼 공유 규칙
프로젝트_루트/하위폴더/AGENTS.md # 하위 디렉터리별 규칙도 가능
.agents/rules를 기본으로 사용하지만, .agent/rules에 대한 하위 호환도 유지합니다. 기존 프로젝트에서 .agent/rules/를 사용하고 있다면 변경하지 않아도 됩니다.
공식 문서
Global vs Workspace 선택 가이드
| 상황 | Global | Workspace |
|---|---|---|
| 한국어 응답 선호 | 적합 | - |
| 팀 데이터 컨벤션 (결측치 처리 방법 등) | - | 적합 |
| 프로젝트 기술 스택 (pandas vs PySpark) | - | 적합 |
| 공통 보안 정책 (PII 마스킹 등) | 적합 | 적합 |
| 기본 인코딩/로케일 설정 | 적합 | - |
| 프로젝트별 데이터 소스 정의 | - | 적합 |
# Global Rules (전역 - 모든 워크스페이스에 적용)
~/.gemini/GEMINI.md # 공식 문서 기준 경로
# 크로스 플랫폼 규칙 (v1.20.3+)
AGENTS.md # 여러 AI 도구에서 공통 사용
# Workspace Rules (프로젝트별)
.agents/rules/*.md # 현재 기본 경로 (권장)
.agent/rules/*.md # 하위 호환 지원
# 우선순위: GEMINI.md > AGENTS.md > .agents/rules/
~/.gemini/GEMINI.md)에 "항상 seaborn 사용"이라고 정의해도, 특정 프로젝트의 Workspace Rules에서 "이 프로젝트는 plotly 사용"이라고 명시하면 Workspace 설정이 우선합니다. 팀 프로젝트에서 개인의 글로벌 설정과 충돌 없이 프로젝트별 일관성을 유지할 수 있습니다.
관련 공식 문서 및 참고 자료
활성화 모드 공식 문서 #
공식 문서에 따르면, 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
Model Decision Rules vs Skills — 무엇이 다른가?
둘 다 "에이전트가 자동으로 적절한 시점에 불러오는" 메커니즘이라 헷갈리기 쉽습니다. 핵심 차이는 역할(규칙 vs 절차)과 로딩 방식(설명만 항상 vs 호출 시 본문 로드)입니다.
| 비교 항목 | Model Decision Rules | Skills |
|---|---|---|
| 본질 | 규칙·정책·컨벤션 (행동 지침) | 다단계 절차·도구 묶음 (작업 수행) |
| 대답하는 질문 | "어떻게 해야 하는가" (코딩 규칙, 분석 기준) | "무엇을 어떤 순서로 할 것인가" (PR 리뷰, 데이터 정제 워크플로) |
| 트리거 | 자연어 description과 사용자 요청 의미가 맞으면 모델이 자동 적용 |
슬래시 명령(/skill-name)으로 명시 호출 또는 description 매칭으로 자동 호출 |
| 컨텍스트 비용 | description은 항상 컨텍스트에 상주, 본문은 모델이 적용 결정 시 주입 | 호출 전엔 이름·설명만 노출, 호출 시점에 SKILL.md 본문 + 보조 파일 로드 |
| 분량/구성 | 짧은 지침 (수백~수천 자, 단일 .md 파일) | 다단계 워크플로 + 코드 스니펫 + 보조 파일까지 포함 가능 (디렉터리 단위) |
| 위치 | .agents/rules/*.md, ~/.gemini/GEMINI.md |
.agents/skills/<name>/SKILL.md (자세한 내용은 Skills 페이지) |
| 예시 | "통계 검정 시 p-value 0.05 기준 사용", "CSV 인코딩 cp949 우선 시도" | "/data-cleanup — CSV 로드 → 결측치 리포트 → 이상치 제거 → 정제본 저장" |
Rules 파일 헤더 주석 필드 참조
Workspace Rules 파일(.md)의 맨 위에 아래 주석 필드를 추가하면 에이전트가 규칙의 메타데이터를 더 잘 인식합니다.
| 필드 | 필수/선택 | 역할 | 작성 예시 |
|---|---|---|---|
# description: |
Model Decision 시 필수 | 에이전트가 이 규칙을 언제 사용할지 판단하는 자연어 설명. 관련 키워드를 포함하세요. | # description: 통계 검정, 가설 검정, A/B 테스트를 수행할 때 적용 |
# globs: |
Glob 모드 시 필수 | 이 규칙이 적용될 파일 패턴. Always On이나 Model Decision에서는 불필요. | # globs: **/*.csv, **/*.xlsx |
# version: |
선택 | 규칙 버전 추적. 팀에서 규칙을 공유할 때 변경 이력 관리에 유용. | # version: 1.2.0 |
# author: |
선택 | 규칙 작성자. 팀 환경에서 책임자 파악 용도. | # author: data-team |
# description: CSV/Excel 파일의 결측치 처리, 데이터 품질 검사를 수행할 때 적용
# globs: **/*.csv, **/*.xlsx
# version: 1.1.0
# author: data-team
## 결측치 처리 원칙
- 분석 시작 전 결측치 비율을 먼저 계산하고 보고
- 비율 5% 미만: 행 제거 허용
- 비율 5~20%: KNN 보간 사용
- 비율 20% 초과: 사용자에게 경고 후 판단 요청
Always On 모드로 시작하세요. Rules가 안정적으로 동작하는지 확인한 후, 상황에 따라 Model Decision이나 Manual로 전환하면 됩니다. 데이터 분석 관련 Rules는 대부분 Always On이 적합합니다.
- 일회성 지시사항 — "이번 분석에서만 월별로 집계해줘"는 Rules가 아닌 대화창에 직접 입력하세요. Rules는 반복 적용되므로, 일회성 지시를 넣으면 불필요하게 매번 활성화됩니다.
- 민감 정보 — API 키, 비밀번호, 개인정보가 포함된 데이터를 Rules에 직접 삽입하지 마세요. 환경 변수나 별도 비밀 관리 도구를 사용하세요.
- 지나치게 모호한 지시 — "코드를 잘 작성해라"처럼 해석이 불분명한 지시는 에이전트가 일관되게 따르기 어렵습니다. 구체적인 행동 지침으로 바꿔 작성하세요.
- 대용량 참조 파일 — @멘션으로 참조하는 파일이 수백 KB라면 Rules 자체가 토큰 한도를 넘겨 무시될 수 있습니다.
관련 공식 문서 및 참고 자료
@ Mentions (파일 참조) 공식 문서 #
Rules 파일 내에서 @filename 구문으로 프로젝트의 다른 파일을 직접 참조할 수 있습니다. 에이전트는 대화 시작 시 해당 파일의 내용을 자동으로 컨텍스트에 포함합니다. 데이터 스키마, 의존성 목록, API 문서처럼 에이전트가 항상 인지해야 할 정보를 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를 참조하여 에이전트가 데이터 구조, 컬럼 타입, 관계를 이해한 상태에서 분석을 수행하도록 합니다.
@ Mentions 활용 권장 파일 유형
| 파일 유형 | 예시 | 권장 여부 | 이유 |
|---|---|---|---|
| 의존성 목록 | @requirements.txt |
권장 | 파일이 작고 에이전트가 패키지 버전을 인지해야 할 때 |
| 데이터 스키마 | @docs/schema.md |
권장 | 컬럼 정의, 타입, 관계를 에이전트가 항상 알아야 할 때 |
| API 문서 | @docs/api.md |
조건부 | 길이가 짧으면 OK, 수백 줄이면 핵심만 발췌해서 별도 파일로 |
| 원본 데이터 파일 | @data/sales.csv |
비권장 | 대용량 CSV는 수십만 토큰을 소비하여 응답 불가 상태 유발 |
관련 공식 문서 및 참고 자료
실전 Rules 예시 공식 문서 #
데이터 수집과 분석 작업에서 바로 사용할 수 있는 5가지 실전 예시입니다. 각 예시에는 규칙의 내용뿐 아니라, 이 규칙이 없으면 어떤 문제가 발생하는지도 함께 설명합니다.
사용자: "CSV 분석해줘"
에이전트: CP949로 파일을 읽어 한글 깨짐, 결측치 보고 없이 바로 분석 진행, 차트에 한글 폰트 미설정으로 □□□ 출력
→ 사용자가 매 대화마다 "UTF-8로 읽고, 결측치 먼저 보고하고, 한글 폰트 설정해줘"를 반복 입력해야 함
사용자: "CSV 분석해줘"
에이전트: UTF-8로 파일 로드 완료 → 결측치 현황 자동 보고(category: 2.3%) → 시각화 시 한글 폰트(AppleGothic) 자동 설정
→ 반복 지시 없이 Always On Rules로 일관된 분석 품질 유지
예시 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. 기본 통계량 요약 출력
검증 결과는 표 형태로 출력하고, 문제가 발견되면 해결 방안을 제안합니다.
"이 데이터 분석해줘" → 바로 분석 시작, 결측치나 이상치를 놓칠 수 있음
"이 데이터 분석해줘" → 자동으로 품질 검증 → 문제 보고 → 안전하게 분석 진행
예시 4: 코드 스타일 가이드 (code-style-guide)
공식 문서에서 소개하는 code-style-guide 패턴입니다. 코딩 컨벤션을 일관되게 유지합니다.
# 코드 스타일 가이드 (Always On)
## Python 스타일 규칙
- PEP 8 준수: 들여쓰기 4칸(스페이스), 한 줄 최대 79자
- 변수명: snake_case 사용 (camelCase 금지)
- 클래스명: PascalCase 사용
- 상수: UPPER_SNAKE_CASE 사용
## 주석 규칙
- 함수/클래스에는 반드시 한국어 독스트링 작성
- 복잡한 로직에는 인라인 주석으로 의도 설명
- TODO, FIXME 태그를 적극 활용
## 예시
# 좋은 예:
def calculate_monthly_revenue(transactions: list) -> float:
"""월별 매출을 계산합니다.
Args:
transactions: 거래 내역 리스트
Returns:
월별 총 매출 (float)
"""
return sum(t['amount'] for t in transactions if t['status'] == 'completed')
camelCase와 snake_case를 섞어 쓰거나, 영어 주석과 한국어 주석을 일관성 없이 혼용합니다. 독스트링이 없는 함수가 생겨 코드 가독성이 떨어집니다.
예시 5: 코드 생성 가이드 (code-generation-guide)
공식 문서에서 소개하는 code-generation-guide 패턴입니다. 파일 구조와 모듈 분리 방식을 지정합니다.
# 코드 생성 가이드 (Always On)
## 파일 구조 원칙
- 진입점은 반드시 main.py에 위치시킨다
- 기능별로 별도 파일 분리: feature_x.py, utils.py
- 한 파일의 최대 길이는 300줄. 초과 시 모듈 분리를 제안한다
- 공통 유틸리티는 utils.py에 집중
## 의존성 관리
- 외부 라이브러리는 requirements.txt에 버전과 함께 기록
- 상대 import 사용 금지, 절대 import 사용
## 예시 구조
my_project/
├── main.py # 진입점: CLI 파라미터 파싱, 실행 흐름 조율
├── feature_x.py # X 기능 구현
├── feature_y.py # Y 기능 구현
├── utils.py # 공통 유틸리티
└── requirements.txt # 의존성 목록
종단 간 테스트: Rules + Workflows 연동 실습
공식 문서에서 소개하는 Rules와 Workflows를 함께 사용하는 실습 예시입니다. code-generation-guide와 generate-unit-tests를 함께 써보세요.
- 아래 스켈레톤
main.py파일을 생성합니다:main.pydef main(): pass if __name__ == "__main__": main() - 에이전트에게 요청합니다: "이진 탐색(binary search)과 버블 정렬(bubble sort)을 구현해줘"
code-generation-guideRule이 적용되어 3개 파일이 생성됩니다:main.py— 각 기능 예시를 호출하는 진입점binary_search.py— 이진 탐색 구현bubble_sort.py— 버블 정렬 구현
- 채팅창에
/generate를 입력하고generate-unit-tests를 선택합니다. - 에이전트가 2개 테스트 파일을 자동 생성합니다:
test_binary_search.py— 이진 탐색 단위 테스트test_bubble_sort.py— 버블 정렬 단위 테스트 (여러 메서드 포함)
관련 공식 문서 및 참고 자료
활용 패턴 공식 문서 #
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 서버 설정에서 관리 (코드에 노출 금지)
~/.gemini/antigravity/mcp_config.json을 수정하면 Antigravity 앱을 완전히 재시작해야 변경사항이 반영됩니다. 재시작 없이 Rules에서 MCP 도구를 참조하면 에이전트가 도구를 인식하지 못하거나 오래된 버전을 사용할 수 있습니다. MCP 서버 추가 또는 설정 변경 시 항상 앱 재시작을 확인하세요.
MCP 연동 디버깅 팁
| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 에이전트가 MCP 도구를 모름 | 앱 재시작 안 함 | Antigravity 완전 재시작 (Quit → 재실행) |
| MCP 서버 연결 실패 | 서버 프로세스 미실행 또는 포트 충돌 | MCP 서버가 실행 중인지 확인, mcp_config.json의 포트 설정 점검 |
| Rules에서 MCP 도구 참조 시 오류 | 도구 이름 불일치 | MCP 서버가 노출하는 실제 도구 이름과 Rules의 참조 이름을 대조 확인 |
관련 공식 문서 및 참고 자료
흔한 실수와 해결법 공식 문서 #
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에 위치하며, 모든 워크스페이스에 공통으로 적용됩니다. v1.20.3부터는 AGENTS.md도 지원합니다.
# Global Rules 위치
~/.gemini/GEMINI.md # 모든 프로젝트에 적용되는 전역 규칙
# 크로스 플랫폼 규칙 (v1.20.3+)
프로젝트/AGENTS.md # 여러 AI 코딩 도구에서 공통 사용
# Workspace Rules 위치
프로젝트/.agents/rules/*.md # 해당 프로젝트에만 적용되는 규칙
# 우선순위: GEMINI.md > AGENTS.md > .agents/rules/
일반적으로 Global Rules에는 선호하는 프로그래밍 언어, 응답 언어(한국어), 코딩 스타일 등을 설정하고, Workspace Rules에는 프로젝트별 데이터 처리 규칙, 라이브러리 선호도 등을 설정합니다. 크로스 플랫폼 규칙은 AGENTS.md에 작성하면 다른 AI 도구에서도 공통으로 적용됩니다.
네, Rules 파일 내에서 @filename 구문으로 다른 파일을 참조할 수 있습니다. 이를 통해 규칙을 모듈화하고 재사용할 수 있습니다.
경로 해석 방식:
@utils.md— Rules 파일과 같은 폴더에서 찾기 (상대 경로)@/docs/style-guide.md— 절대 경로를 먼저 시도하고, 없으면 리포지토리 루트 기준 상대 경로로 시도@../shared/common-rules.md— 상위 폴더 참조도 가능
# 데이터 분석 마스터 Rule
아래 규칙들을 모두 따릅니다:
@coding-style.md
@data-quality.md
@visualization-standards.md
- 파일 없음 오류:
@utils.md를 참조했는데 파일이 없으면 에이전트가 "참조 파일을 찾을 수 없음"이라고 알립니다. 실제 파일 경로를 확인하거나 파일을 먼저 생성하세요. - 경로 디버깅: Rules 파일을 ���고 에이전트에게 "이 규칙 파일의 @mentions 참조가 모두 올바른지 확인해줘"라고 요청하면 깨진 참조를 찾아줍니다.
- 권장 구조: 참조 파일들을 같은 폴더(
.agents/rules/)에 두면 상대 경로 오류를 줄일 수 있습니다.
세 가지 방법으로 확인할 수 있습니다:
- 직접 질문하기: 에이전트에게 "현재 적용된 규칙을 알려줘" 또는 "이 작업에 어떤 규칙이 적용되고 있어?"라고 물어봅니다. 에이전트가 활성 규칙 목록을 알려줍니다.
- 출력 관찰하기: 에이전트의 코드나 응답이 규칙을 따르는지 확인합니다. 예를 들어 "한국어 주석" 규칙을 설정했다면, 생성된 코드에 한국어 주석이 포함되어야 합니다.
- Customizations 패널: Antigravity Agent Manager 좌측 사이드바 하단의 ✨ (스파클/별) 아이콘 또는 Settings (
Cmd+,) → "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에서도 경로 업데이트 확인