Workflows (워크플로우)

Workflows는 서비스 배포나 PR 코멘트 응답 같은 반복적인 일련의 작업을 에이전트가 수행하도록 안내하는 단계별 절차를 정의합니다. 마크다운 파일로 저장되어 쉽게 반복 실행할 수 있으며, /workflow-name 형식의 슬래시 명령으로 호출합니다. 공식 문서

Workflows란? 공식 문서 #

공식 문서에 따르면, "Workflows는 서비스 배포나 PR 코멘트 응답 같은 반복적인 일련의 작업을 에이전트가 수행하도록 안내하는 단계(steps)를 정의합니다." Workflows는 마크다운 파일로 저장되므로, 핵심 프로세스를 쉽게 반복 실행할 수 있는 방법을 제공합니다. 저장된 Workflows는 에이전트에서 /workflow-name 형식의 슬래시 명령으로 호출할 수 있습니다. 공식 문서

워크플로우 없이 (매번 반복)

"먼저 데이터 로드해줘" → "결측치 확인해줘" → "describe 돌려줘" → "히스토그램 그려줘" → "상관관계 확인해줘" → "인사이트 정리해줘"

매번 6번의 요청을 반복하고, 순서를 빠뜨리거나 단계를 잊기 쉽습니다.

워크플로우 사용

/run-eda

한 줄로 끝! 에이전트가 정의된 모든 단계를 자동으로 순서대로 실행하고, 결과를 정리해서 보고합니다.

공식 문서 정의

공식 문서 원문: "Workflows enable you to define a series of steps to guide the Agent through a repetitive set of tasks, such as deploying a service or responding to PR comments. These Workflows are saved as markdown files, allowing you to have an easy repeatable way to run key processes. Once saved, Workflows can be invoked in Agent via a slash command with the format /workflow-name."

쉽게 이해하기

Workflows는 "요리 레시피"와 같습니다. 레시피에 "1. 재료 준비 → 2. 볶기 → 3. 양념 → 4. 플레이팅" 순서가 적혀있듯이, Workflow에 "1. 데이터 로드 → 2. 전처리 → 3. 분석 → 4. 보고서 생성" 순서를 적어두면 에이전트가 순서대로 실행합니다.

핵심 특징

마크다운 파일로 저장되며, 제목(title), 설명(description), 에이전트가 따를 구체적인 지시가 포함된 단계(steps)로 구성됩니다 공식 문서
슬래시 명령(/workflow-name)으로 즉시 실행 가능 - 입력창에 /run-eda만 치면 탐색적 분석 시작
글로벌(Global) 워크플로우: 모든 워크스페이스에서 접근 가능 / 워크스페이스(Workspace) 워크플로우: 현재 워크스페이스 전용
워크플로우 안에서 다른 워크플로우를 호출할 수 있음 (중첩 호출, Nesting) 공식 문서
에이전트에게 요청하여 자동 생성 가능 - 대화 기록을 분석하여 워크플로우를 생성해줍니다
워크플로우 파일당 최대 12,000자 제한 공식 문서
Git으로 버전 관리 및 팀 공유 가능 - 절차의 재현성 보장
워크플로우 내에서 MCP 도구를 활용하거나 브라우저 서브에이전트를 호출할 수 있음

Rules와 Workflows의 차이 (공식 정의) 공식 문서 #

공식 문서에 따르면: "Rules는 프롬프트 수준에서 지속적이고 재사용 가능한 컨텍스트를 제공하여 모델에 가이드를 주는 반면, Workflows는 궤적(trajectory) 수준에서 구조화된 단계 또는 프롬프트의 시퀀스를 제공하여, 모델이 상호 연결된 일련의 작업이나 행동을 수행하도록 안내합니다."

공식 문서 원문

"While Rules provide models with guidance by providing persistent, reusable context at the prompt level, Workflows provide a structured sequence of steps or prompts at the trajectory level, guiding the model through a series of interconnected tasks or actions."

Rules (규칙)

프롬프트 수준에서 작동합니다. 모든 대화에 자동으로 적용되는 지속적이고 재사용 가능한 컨텍스트입니다. 예: "항상 한국어로 응답해", "데이터 분석 시 결측치를 먼저 확인해" 공식 문서

Workflows (워크플로우)

궤적(trajectory) 수준에서 작동합니다. 구조화된 단계의 시퀀스로, 모델이 상호 연결된 일련의 작업을 순차적으로 수행하도록 안내합니다. 예: /run-eda로 데이터 로드 → 기술통계 → 시각화 → 인사이트 정리를 순서대로 실행 공식 문서

구분	Rules	Workflows
목적	행동 규칙 정의	작업 절차 자동화
실행 방식	자동 적용 (항상/자동/수동)	슬래시 명령으로 수동 실행
구조	Markdown 규칙 문서	Markdown Step-by-Step 문서
예시	"한국어 주석 달기"	"/weekly-report 실행"
재사용	모든 대화에 자동 적용	필요할 때 명시적 호출

언제 Workflows를 사용해야 할까?

Workflows가 적합한 경우

서비스 배포, PR 코멘트 응답, 데이터 수집 파이프라인, 주간 리포트 생성, 웹 크롤링 절차, 탐색적 데이터 분석(EDA) 등 정해진 순서가 있는 반복적 작업

Rules가 더 적합한 경우

코딩 스타일, 변수 네이밍 규칙, 응답 언어 설정 등 모든 대화에 일관되게 적용해야 하는 지속적인 가이드라인. 순서가 없고 항상 참인 제약 조건은 Rules가 적합합니다.

파일 형식과 구조 공식 문서 #

공식 문서에 따르면, "Workflows는 마크다운 파일로 저장되며, 제목(title), 설명(description), 그리고 에이전트가 따를 구체적인 지시가 포함된 일련의 단계(steps)로 구성됩니다. 워크플로우 파일은 각각 최대 12,000자로 제한됩니다." 공식 문서

마크다운 작성 구조

      워크플로우 기본 구조
      # 워크플로우 제목 (Title)

## 설명 (Description)
이 워크플로우가 무엇을 하는지 설명합니다.

## 단계 (Steps)

### Step 1: 첫 번째 작업
에이전트가 수행할 구체적인 지시사항을 작성합니다.

### Step 2: 두 번째 작업
다음 단계의 지시사항을 작성합니다.

### Step 3: 세 번째 작업
마지막 단계의 지시사항을 작성합니다.
    

데이터 분석 워크플로우 템플릿

      데이터 분석 템플릿
      # 매출 데이터 탐색적 분석

## 설명
CSV 매출 데이터를 로드하여 기술통계, 시각화, 인사이트 도출까지 수행합니다.

## 사전 조건
- data/ 폴더에 매출 CSV 파일이 있어야 합니다
- Python 환경에 pandas, matplotlib, seaborn이 설치되어야 합니다

## 단계

### Step 1: 데이터 로드 및 확인
data/ 폴더의 CSV 파일을 pandas로 로드합니다.
shape, dtypes, head(5)를 출력하여 데이터 구조를 파악합니다.

### Step 2: 데이터 품질 검사
결측치 비율, 중복 행, 이상치를 확인합니다.
결측치가 5% 이상인 컬럼은 별도로 보고합니다.

### Step 3: 기술통계 및 시각화
describe()로 기술통계를 계산하고,
주요 수치형 컬럼의 히스토그램과 박스플롯을 생성합니다.

### Step 4: 인사이트 정리
발견한 패턴, 이상치, 추가 분석이 필요한 사항을 정리합니다.
    

12,000자 제한: 워크플로우 파일은 각각 최대 12,000자로 제한됩니다. 초과하는 경우 여러 워크플로우로 분리한 뒤 중첩 호출로 연결하세요. 예: /collect-data, /run-eda, /generate-report로 분리. 공식 문서

저장 경로

워크플로우 파일은 용도에 따라 워크스페이스(프로젝트) 범위 또는 글로벌(사용자 전체) 범위로 저장할 수 있습니다.

      워크스페이스 경로
      # 현재 프로젝트에서만 사용 가능 (Git에 커밋하면 팀 전체 공유)
프로젝트루트/.agents/workflows/워크플로우이름.md

# 하위 호환 경로 (이전 버전도 지원)
프로젝트루트/.agent/workflows/워크플로우이름.md
    

      글로벌 경로
      # 모든 워크스페이스에서 접근 가능
~/.gemini/antigravity/workflows/워크플로우이름.md
    

파일명 규칙

워크플로우 파일명이 곧 슬래시 명령이 됩니다. 파일명에는 하이픈(-)을 사용하고, 확장자는 반드시 .md여야 합니다.

파일명	슬래시 명령	설명
`run-eda.md`	`/run-eda`	탐색적 데이터 분석
`collect-data.md`	`/collect-data`	데이터 수집
`weekly-report.md`	`/weekly-report`	주간 리포트 생성
`crawl-site.md`	`/crawl-site`	웹 크롤링 데이터 수집

Workflows 만들기 공식 문서 #

공식 문서에 따른 워크플로우 생성 방법입니다. Customizations 패널을 통해 UI에서 직접 만들거나, 에이전트에게 생성을 요청할 수 있습니다.

공식 생성 절차 (UI에서 만들기)

에디터의 에이전트 패널 상단에 있는 "..." 드롭다운을 통해 Customizations 패널을 엽니다. 공식 문서
Workflows 패널로 이동합니다.
+ Global 버튼을 클릭하면 모든 워크스페이스에서 접근할 수 있는 글로벌 워크플로우를 생성하고, + Workspace 버튼을 클릭하면 현재 워크스페이스 전용 워크플로우를 생성합니다. 공식 문서
제목(title), 설명(description), 단계(steps)를 마크다운으로 작성합니다.

에이전트에게 생성 요청하기

공식 문서에 따르면, "에이전트에게 Workflows를 생성해 달라고 요청할 수도 있습니다! 이 방법은 에이전트와 수동으로 일련의 단계를 진행한 뒤에 특히 효과적입니다. 에이전트가 대화 기록을 사용하여 Workflow를 생성할 수 있기 때문입니다." 공식 문서

      에이전트에게 요청
      # 수동 작업 후 워크플로우로 변환:
"방금 한 데이터 분석 과정을 워크플로우로 만들어줘"
"이 EDA 절차를 /run-eda 워크플로우로 저장해줘"

# 처음부터 자연어로 생성 요청:
"CSV 데이터를 로드하고 품질 검사하는 워크플로우를 만들어줘"
"웹 크롤링으로 가격 데이터를 수집하는 워크플로우를 만들어줘"
"주간 KPI 리포트를 자동 생성하는 워크플로우를 만들어줘"
    

팁: 에이전트가 생성한 워크플로우는 반드시 한 번 리뷰하세요. 불필요한 단계가 포함되거나, 핵심 단계가 누락되었을 수 있습니다. 수동으로 작업한 후 대화 기록을 기반으로 생성하면 더 정확한 워크플로우가 만들어집니다.

바로 사용할 수 있는 워크플로우 템플릿

아래 내용을 .agents/workflows/weekly-report.md에 저장하면 /weekly-report 명령으로 실행할 수 있습니다.

      # 주간 데이터 분석 보고서

매주 반복되는 데이터 분석 보고서를 자동으로 생성합니다.

## Step 1: 데이터 수집
- data/ 폴더에서 이번 주 CSV 파일들을 모두 로드
- 각 파일의 행 수와 기간을 확인

## Step 2: 데이터 전처리
- 결측치 처리 (수치형: 중앙값, 범주형: 최빈값)
- 날짜 컬럼을 datetime으로 변환
- 이상치 확인 및 보고

## Step 3: 핵심 지표 분석
- 주간 매출 합계 및 전주 대비 증감률
- 카테고리별 매출 비중
- 상위 10개 인기 상품

## Step 4: 시각화
- 일별 매출 추이 라인 차트
- 카테고리별 매출 파이 차트
- 전주 대비 비교 바 차트

## Step 5: 보고서 생성
- 분석 결과를 reports/weekly_YYYYMMDD.md로 저장
- 핵심 인사이트 3가지를 요약
    

실행 방법: Antigravity 프롬프트에서 /weekly-report를 입력하면 위 단계가 순차적으로 실행됩니다. 각 Step 사이에 에이전트가 진행 상황을 보고합니다.

워크플로우 작성 시 흔한 실수

실수	증상	해결 방법
단계가 너무 모호함	"데이터를 분석하세요" → 에이전트가 무엇을 할지 모름	구체적 도구와 방법을 명시 (예: "pandas describe()로 기술통계 생성")
단계 간 의존성 불명확	이전 단계 결과를 다음 단계에서 찾지 못함	결과물 파일명과 저장 경로를 명시
검증 단계 누락	중간 오류가 발생해도 계속 진행	각 단계 후 "결과를 확인하고 이상이 있으면 보고" 추가
12,000자 초과	워크플로우가 로드되지 않음	하위 워크플로우로 분리하고 중첩 호출
파일명에 공백 포함	슬래시 명령어가 인식되지 않음	하이픈 사용 (예: `weekly-report.md`)

Workflows 실행하기 공식 문서 #

공식 문서에 따르면, "워크플로우를 실행하려면 에이전트에서 /workflow-name 명령을 사용하여 호출하면 됩니다." 호출 시, 에이전트는 워크플로우에 정의된 각 단계를 순차적으로 처리하며, 지정된 대로 작업을 수행하거나 응답을 생성합니다. 공식 문서

      실행 예시
      # 에이전트 입력창에 입력:
/collect-data      # 데이터 수집 워크플로우
/run-eda          # 탐색적 분석 워크플로우
/weekly-report    # 주간 리포트 생성 워크플로우
/crawl-site       # 웹 크롤링 워크플로우
    

실행 라이프사이클

실행 흐름

공식 문서에 따르면, 호출 시 에이전트는 워크플로우에 정의된 각 단계를 순차적으로 처리하며, 지정된 대로 작업을 수행하거나 응답을 생성합니다.

워크플로우 로드

슬래시 명령을 입력하면 해당 마크다운 파일을 읽어들입니다. 사전 조건이 있으면 먼저 확인합니다.

단계별 순차 처리

에이전트가 워크플로우에 정의된 각 단계를 순차적으로 처리합니다. 각 단계에서 지정된 대로 작업을 수행하거나 응답을 생성합니다.

결과 보고

모든 단계가 완료되면 결과를 요약하여 보고합니다. 생성된 파일 목록, 발견된 인사이트, 주의사항 등을 정리합니다.

Workflow 중첩 호출 (Nesting) 공식 문서 #

공식 문서에 따르면, "워크플로우 안에서 다른 워크플로우를 호출할 수 있습니다! 예를 들어, /workflow-1이 'Call /workflow-2'와 'Call /workflow-3'라는 지시를 포함할 수 있습니다. 호출 시, 에이전트는 워크플로우에 정의된 각 단계를 순차적으로 처리하며, 지정된 대로 작업을 수행하거나 응답을 생성합니다." 공식 문서

공식 문서 원문

"You can call other Workflows from within a workflow! For example, /workflow-1 can include instructions like 'Call /workflow-2' and 'Call /workflow-3'. Upon invocation, Agent sequentially processes each step defined in the workflow, performing actions or generating responses as specified."

중첩 호출 작성 예시

      full-analysis.md
      # 전체 데이터 분석 파이프라인

## 설명
데이터 수집부터 리포트 생성까지 전체 분석 파이프라인을 실행합니다.

### Step 1: 데이터 수집 및 전처리
Call /collect-data 워크플로우를 실행합니다.
이 단계가 완료되어야 다음 단계로 진행할 수 있습니다.

### Step 2: 탐색적 데이터 분석
Call /run-eda 워크플로우를 실행합니다.
Step 1에서 생성된 정제 데이터를 입력으로 사용합니다.

### Step 3: 리포트 생성
Call /generate-report 워크플로우를 실행합니다.
Step 2의 분석 결과와 시각화를 포함하여 최종 리포트를 생성합니다.
    

주의: 중첩 호출 시 순환 참조에 주의하세요. A가 B를 호출하고, B가 다시 A를 호출하면 무한 루프에 빠질 수 있습니다. 또한 서브 워크플로우의 이름이 정확한지 반드시 확인하세요.

중첩 활용 예시: /full-analysis 워크플로우 안에서 /clean-data와 /generate-charts를 호출하면, 데이터 정제 → 차트 생성이 자동으로 연결됩니다. 각 워크플로우를 독립적으로도 사용할 수 있어 재사용성이 높습니다.

에이전트가 Workflow를 자동 생성 (Agent-Generated Workflows) 공식 문서 #

공식 문서에 따르면, "에이전트에게 Workflows를 생성해 달라고 요청할 수도 있습니다! 이 방법은 에이전트와 수동으로 일련의 단계를 진행한 뒤에 특히 효과적입니다. 에이전트가 대화 기록(conversation history)을 사용하여 Workflow를 생성할 수 있기 때문입니다." 공식 문서

공식 문서 원문

"You can also ask Agent to generate Workflows for you! This works particularly well after manually working with Agent through a series of steps since it can use the conversation history to create the Workflow."

자동 생성 과정

에이전트와 수동으로 일련의 단계를 진행합니다. 예를 들어, 데이터 로드, 전처리, 시각화 등을 차례로 수행합니다.
작업이 끝나면 워크플로우 생성을 요청합니다. "방금 한 과정을 워크플로우로 만들어줘"라고 입력합니다.
에이전트가 대화 기록(conversation history)을 분석합니다. 수행한 단계를 추출하여 구조화된 마크다운 워크플로우를 생성합니다.

팁: 에이전트에게 자연어로 원하는 절차를 설명하는 것만으로도 워크플로우를 생성할 수 있지만, 이전에 수동으로 작업한 기록이 있을 때 특히 효과적입니다. 대화 기록을 기반으로 하면 에이전트가 실제 수행한 명령어와 확인 사항을 정확하게 반영하기 때문입니다. 공식 문서

에이전트 모드와 워크플로우 실행 공식 문서 #

Antigravity 에이전트는 두 가지 실행 모드를 제공하며, 각 모드에 따라 워크플로우의 실행 방식이 달라집니다.

Planning 모드 (계획 모드)

워크플로우의 각 단계를 실행하기 전에 전체 계획을 먼저 수립합니다. 단계 간 의존성과 데이터 흐름을 분석한 뒤 최적의 실행 전략을 세웁니다. 복잡한 분석 파이프라인이나 조건부 분기가 많은 워크플로우에 적합합니다.

Fast 모드 (빠른 모드)

워크플로우의 각 단계를 즉시 실행합니다. 계획 단계를 건너뛰고 바로 실행에 들어가므로 속도가 빠릅니다. 간단한 데이터 수집이나 정형화된 리포트 생성 등 단순한 워크플로우에 적합합니다.

모드 선택 팁: 워크플로우에 조건부 분기, 에러 핸들링, 중첩 호출 등이 포함된 경우 Planning 모드를 사용하세요. 단순 순차 실행만 필요한 경우 Fast 모드가 더 효율적입니다. 공식 문서

워크플로우와 에이전트 모드: 복잡한 워크플로우(5단계 이상)는 Planning 모드에서 실행하는 것을 권장합니다. 에이전트가 전체 계획을 먼저 세운 후 단계별로 실행하므로, 중간에 오류가 발생해도 복구가 쉽습니다. 간단한 워크플로우는 Fast 모드로 빠르게 처리할 수 있습니다.

MCP 도구 및 브라우저 서브에이전트 연동 MCP 문서 브라우저 문서 #

워크플로우는 MCP(Model Context Protocol) 도구와 브라우저 서브에이전트를 활용하여 외부 시스템과 연동할 수 있습니다. 이를 통해 단순한 파일 처리를 넘어 웹 기반 데이터 수집, API 호출, 데이터베이스 쿼리 등 다양한 작업을 워크플로우에 포함할 수 있습니다.

MCP 도구 활용

MCP는 에이전트가 외부 도구와 서비스에 접근할 수 있게 해주는 프로토콜입니다. 워크플로우의 각 단계에서 MCP 도구를 호출하여 데이터베이스 조회, 클라우드 스토리지 접근, 외부 API 호출 등을 수행할 수 있습니다.

      MCP 도구 활용 워크플로우 예시
      ### Step 1: 데이터베이스에서 최신 데이터 조회
MCP PostgreSQL 도구를 사용하여 최신 주문 데이터를 조회합니다.
쿼리: SELECT * FROM orders WHERE order_date >= CURRENT_DATE - INTERVAL '7 days'
결과를 data/db_orders.csv로 저장합니다.

### Step 2: 클라우드 스토리지에서 참조 데이터 가져오기
MCP GCS 도구를 사용하여 gs://data-bucket/reference/products.csv를 다운로드합니다.
data/reference/ 폴더에 저장합니다.
    

브라우저 서브에이전트 활용

워크플로우에서 브라우저 서브에이전트를 호출하여 웹 페이지 탐색, 데이터 스크래핑, 스크린샷 캡처 등의 작업을 수행할 수 있습니다.

      브라우저 서브에이전트 활용 예시
      ### Step 1: 경쟁사 가격 데이터 수집
브라우저 서브에이전트를 사용하여 다음 작업을 수행합니다:
1. 대상 사이트에 접속합니다
2. 카테고리별 상위 10개 제품의 가격을 수집합니다
3. 수집한 데이터를 data/competitor_prices.csv로 저장합니다

### Step 2: 대시보드 스크린샷 캡처
브라우저 서브에이전트를 사용하여 내부 대시보드의
주요 KPI 화면을 스크린샷으로 캡처합니다.
    

참고: MCP 도구와 브라우저 서브에이전트를 사용하려면 해당 기능이 에이전트 환경에 설정되어 있어야 합니다. MCP 문서 브라우저 문서

데이터 분석 활용 예시 #

실제 데이터 분석 업무에서 바로 활용할 수 있는 워크플로우 예시입니다. 각 예시의 마크다운을 복사하여 바로 사용하거나, 프로젝트에 맞게 수정하세요. 공식 문서

실전 예시 요약

워크플로우	용도	단계 수	난이도	예상 소요
`/collect-and-clean`	데이터 수집 + 전처리	5단계	입문	2~5분
`/run-eda`	탐색적 데이터 분석	4단계	중급	3~8분
`/weekly-report`	주간 KPI 리포트	5단계	중급	5~10분
`/crawl-data`	웹 크롤링 데이터 수집	4단계	고급	사이트에 따라 다름

예시 1: 데이터 수집 및 전처리 워크플로우 (/collect-and-clean)

원천 데이터를 수집하고, 분석 가능한 상태로 정제하는 워크플로우입니다. 공식 문서

      collect-and-clean.md
      # 데이터 수집 및 전처리

## 설명
원천 데이터를 수집하고, 분석 가능한 상태로 정제합니다.

### Step 1: 데이터 소스 확인
data/raw/ 폴더에 CSV 파일이 있는지 확인합니다.
데이터 소스 목록과 각 파일의 크기, 최종 수정일을 보고합니다.

### Step 2: 데이터 로드
pandas의 read_csv()로 데이터를 로드합니다.
인코딩은 utf-8을 먼저 시도하고, 실패하면 cp949, euc-kr 순으로 시도합니다.
로드 후 shape, columns, dtypes를 출력합니다.

### Step 3: 데이터 품질 검사
각 컬럼별 결측치 수와 비율, 완전 중복 행의 수,
수치형 컬럼의 IQR 기반 이상치를 탐지합니다.

### Step 4: 전처리 수행
- 결측치: 수치형은 중앙값, 범주형은 최빈값으로 대체
- 타입 변환: 날짜 컬럼을 datetime으로 변환
처리 전후의 데이터 요약을 비교합니다.

### Step 5: 정제된 데이터 저장
processed/ 폴더에 정제된 데이터를 저장합니다.
파일명: cleaned_[원본이름]_[날짜].csv
    

예시 2: 탐색적 데이터 분석(EDA) 워크플로우 (/run-eda)

정제된 데이터를 바탕으로 기술통계, 시각화, 인사이트 도출까지 수행하는 워크플로우입니다. 공식 문서

      run-eda.md
      # 탐색적 데이터 분석 (EDA)

## 설명
정제된 데이터에 대해 탐색적 분석을 수행하고 인사이트를 도출합니다.

## 사전 조건
- processed/ 폴더에 정제된 CSV 파일이 있어야 합니다

### Step 1: 데이터 개요 파악
데이터의 shape, dtypes, head(10), 수치형/범주형 컬럼 분류를 확인합니다.

### Step 2: 기술통계 계산
describe()로 수치형 컬럼의 요약 통계를 계산하고,
범주형 컬럼의 value_counts() 상위 10개를 확인합니다.

### Step 3: 시각화 생성
수치형 컬럼의 히스토그램, 범주형 컬럼의 막대 차트,
박스플롯, 수치형 컬럼 간 상관관계 히트맵을 생성합니다.
모든 차트를 figures/ 폴더에 PNG로 저장합니다.

### Step 4: 인사이트 정리
주요 패턴, 이상치, 변수 간 상관관계, 추가 분석 필요 사항을
마크다운 형태로 정리합니다.
    

예시 3: 주간 리포트 생성 (/weekly-report)

매주 반복되는 KPI 리포트를 자동으로 생성하는 워크플로우입니다. 공식 문서

      weekly-report.md
      # 주간 분석 리포트 생성

## 설명
최신 데이터를 기반으로 주간 KPI 리포트를 생성합니다.

### Step 1: 최신 데이터 가져오기
data/ 폴더에서 가장 최근 주의 데이터를 로드합니다.
이전 주 데이터도 함께 로드하여 비교 분석을 준비합니다.

### Step 2: KPI 지표 계산
총 매출, 주문 수, 평균 주문 금액, 전주 대비 변화율,
카테고리별 매출 비중, 상위 10개 제품 매출 순위를 계산합니다.

### Step 3: 시각화 생성
주간 매출 트렌드 라인 차트 (최근 8주), 카테고리별 매출 비교 바 차트,
전주 대비 KPI 변화 요약 차트를 생성합니다.

### Step 4: 마크다운 리포트 작성
요약, KPI 대시보드, 상세 분석, 주요 인사이트 및 액션 아이템을 포함합니다.

### Step 5: 리포트 저장
reports/ 폴더에 weekly_report_[날짜].md로 저장합니다.
    

예시 4: 웹 크롤링 데이터 수집 (/crawl-data)

웹 사이트에서 데이터를 수집하고 구조화된 형태로 저장하는 워크플로우입니다. 공식 문서

      crawl-data.md
      # 웹 크롤링 데이터 수집

## 설명
대상 웹사이트에서 데이터를 크롤링하여 구조화된 CSV/JSON으로 저장합니다.

## 사전 조건
- requests, beautifulsoup4 패키지가 설치되어야 합니다
- config/crawl_targets.yaml에 대상 URL이 정의되어야 합니다

### Step 1: 대상 사이트 확인
robots.txt를 확인하고, 크롤링이 허용된 경로인지 검증합니다.
허용되지 않으면 사용자에게 보고하고 워크플로우를 중단합니다.

### Step 2: 크롤러 실행
requests로 페이지를 요청합니다.
요청 간 1~2초 간격을 두고, 실패 시 최대 3회 재시도합니다.

### Step 3: 데이터 파싱
BeautifulSoup으로 HTML을 파싱하고,
CSS 선택자로 필요한 데이터를 추출하여 구조화합니다.

### Step 4: 데이터 저장 및 검증
data/crawled/ 폴더에 저장하고,
수집된 총 건수와 필수 필드 누락 여부를 확인합니다.
    

워크플로우 활용 팁: 위 예시들을 그대로 복사하지 말고, 자신의 프로젝트에 맞게 파일 경로, 컬럼명, 분석 방법을 수정하세요. 먼저 에이전트와 수동으로 작업을 한 번 수행한 뒤, "방금 한 작업을 워크플로우로 만들어줘"라고 요청하면 프로젝트에 최적화된 워크플로우가 자동 생성됩니다.

팀에서 Workflow 공유하기 공식 문서 #

워크플로우는 마크다운 파일이므로 Git으로 버전 관리가 가능합니다. 팀 저장소에 포함하면 모든 팀원이 동일한 절차를 사용할 수 있습니다.

      프로젝트 구조 예시
      data-analysis-project/
├── .agents/
│   └── workflows/              # 워크스페이스 워크플로우
│       ├── collect-data.md      # 데이터 수집
│       ├── clean-data.md        # 데이터 전처리
│       ├── run-eda.md           # 탐색적 분석
│       ├── weekly-report.md     # 주간 리포트
│       ├── crawl-data.md        # 웹 크롤링
│       └── full-analysis.md     # 전체 파이프라인 (중첩 호출)
├── data/
│   ├── raw/                     # 원천 데이터
│   └── processed/               # 정제된 데이터
├── figures/                     # 시각화 결과
├── reports/                     # 생성된 리포트
└── requirements.txt
    

네이밍 컨벤션

일관된 이름 규칙을 사용하면 워크플로우를 쉽게 찾고 기억할 수 있습니다. 동사-명사 패턴을 권장합니다.

좋은 예시

/collect-data - 동사-명사, 명확
/run-eda - 짧고 의미 전달
/generate-report - 동작이 분명
/crawl-data - 하이픈으로 구분

피할 예시

/data-analysis-v2-final - 버전을 이름에 넣지 마세요
/d - 너무 짧아 의미 불명
/Run_Weekly_Report - 언더스코어 대신 하이픈
/김대리의분석 - 개인 이름 사용 지양

팁: 워크플로우 파일을 변경할 때도 PR을 통해 리뷰를 받으세요. 워크플로우 변경은 팀 전체의 프로세스에 영향을 미치므로, 코드 리뷰와 동일한 수준의 검토가 필요합니다. 공식 문서

Git을 통한 워크플로우 공유

      # 팀 워크플로우를 Git으로 공유하기
mkdir -p .agents/workflows
cp ~/my-workflows/*.md .agents/workflows/

# 커밋하여 팀원들과 공유
git add .agents/workflows/
git commit -m "feat: 팀 데이터 분석 워크플로우 추가"
git push
    

팀 운영 팁: 워크플로우 파일에 주석으로 작성자와 버전을 기록해두면 관리가 편합니다. 예: 

고급 워크플로우 패턴 공식 문서 #

워크플로우를 더 유연하고 강력하게 만드는 고급 패턴들입니다. 조건부 로직과 에러 처리가 가능한 정교한 파이프라인을 설계할 수 있습니다.

패턴 1: 조건부 분기

데이터의 크기나 특성에 따라 다른 처리 로직을 적용합니다.

      조건부 분기 예시
      ### Step 2: 데이터 크기에 따른 처리 분기
데이터프레임의 행 수를 확인합니다.

#### 100만 행 미만인 경우:
pandas로 메모리 내에서 전체 데이터를 처리합니다.

#### 100만 행 이상인 경우:
청크(chunk) 단위로 나누어 처리하거나 dask를 활용합니다.

#### 1억 행 이상인 경우:
사용자에게 보고하고, 샘플링 전략을 확인받습니다.
    

패턴 2: 에러 핸들링과 재시도

외부 데이터 소스 접근 시 발생할 수 있는 오류에 대비합니다.

      에러 핸들링 예시
      ### Step 1: API에서 데이터 수집
설정된 API 엔드포인트에서 데이터를 요청합니다.

#### 실패 시 대응:
- HTTP 429 (Rate Limit): 30초 대기 후 재시도 (최대 3회)
- HTTP 500 (서버 에러): 1분 대기 후 재시도 (최대 2회)
- Timeout: 타임아웃을 60초로 늘려 재시도
- 3회 재시도 후에도 실패하면 워크플로우를 중단하고
  마지막 에러 메시지를 사용자에게 보고합니다.
    

패턴 3: 파라미터화

워크플로우 실행 시 사용자가 파라미터를 지정할 수 있도록 합니다.

      파라미터화 예시
      ### Step 1: 분석 파라미터 확인
사용자에게 다음 파라미터를 확인합니다:
- [시작일]: 분석 시작 날짜 (기본값: 7일 전)
- [종료일]: 분석 종료 날짜 (기본값: 오늘)
- [타겟컬럼]: 분석 대상 지표 (기본값: revenue)

# 파라미터를 메시지로 전달:
/run-eda 시작일: 2024-01-01, 종료일: 2024-03-31, 타겟: revenue
    

조건부 실행 패턴

워크플로우 안에서 조건에 따라 다른 작업을 수행하는 패턴입니다.

      # 스마트 데이터 분석

## Step 1: 데이터 로드 및 형식 확인
파일을 로드하고 데이터 형식을 확인합니다.

## Step 2: 형식별 처리
- CSV 파일인 경우: pandas로 직접 로드
- Excel 파일인 경우: openpyxl로 시트별 로드
- JSON 파일인 경우: 중첩 구조를 flatten 후 로드
- 데이터베이스인 경우: SQLAlchemy로 쿼리 실행

## Step 3: 데이터 크기별 분석 전략
- 10만 행 미만: 전체 데이터 분석
- 10만~100만 행: 샘플링 후 분석, 필요시 전체 분석
- 100만 행 이상: chunked processing으로 분석

## Step 4: 결과 보고
분석 결과와 함께 사용한 전략을 보고합니다.
    

Workflow 디버깅 가이드 공식 문서 #

워크플로우가 의도한 대로 동작하지 않을 때 확인해야 할 일반적인 문제와 해결 방법입니다.

문제 1: 워크플로우가 실행되지 않음

증상: 슬래시 명령을 입력해도 워크플로우가 시작되지 않음

해결 방법:

워크플로우 파일이 올바른 디렉토리에 있는지 확인하세요 (워크스페이스: .agents/workflows/, 글로벌: ~/.gemini/antigravity/workflows/)
파일 이름과 슬래시 명령이 일치하는지 확인하세요 (예: run-eda.md → /run-eda)
파일 확장자가 .md인지 확인하세요
Customizations 패널에서 워크플로우가 목록에 나타나는지 확인하세요

문제 2: 단계가 건너뛰어짐

증상: 에이전트가 일부 Step을 실행하지 않고 다음 단계로 넘어감

해결 방법:

각 Step 제목을 구체적으로 작성하세요
실행할 명령어나 코드를 코드 블록으로 명시하세요
각 단계에 성공/실패 판단 기준을 포함하세요

문제 3: 12,000자 제한 초과

증상: 워크플로우 파일이 너무 길어서 에이전트가 전체를 읽지 못함

해결 방법: 공식 문서에 따르면 워크플로우 파일은 각각 12,000자로 제한됩니다. 워크플로우를 논리적 단위로 분리하고 중첩 호출로 연결하세요. 공식 문서

문제 4: 중간에 멈춤

증상: 특정 단계에서 에이전트가 진행하지 못하고 멈춤

해결 방법:

각 단계에 "실패 시 대응" 섹션을 추가하세요
예상 가능한 오류를 미리 기술하세요
"해결할 수 없는 오류가 발생하면 사용자에게 보고하고 대기하세요"라는 지시를 추가하세요

자주 묻는 질문 (FAQ) #

Q1: Workflow는 자동으로 실행되나요?

아니요. 워크플로우는 사용자가 슬래시 명령(/workflow-name)을 입력할 때만 실행됩니다.

커스터마이징	실행 방식	활성화 조건
Rules	자동 적용	모든 대화에서 항상
Skills	자동 감지	관련 작업이 감지될 때
Workflows	명시적 호출	사용자가 `/명령어`를 입력할 때만

팁: 워크플로우 이름이 곧 슬래시 명령어가 됩니다. 파일명을 weekly-report.md로 만들면 /weekly-report로 호출합니다.

공식 문서

Q2: 워크플로우 안에서 다른 워크플로우를 호출할 수 있나요?

네! 워크플로우 안에서 다른 워크플로우를 호출하여 복잡한 파이프라인을 구성할 수 있습니다.

## /data-pipeline (메인 워크플로우)

1단계: 데이터 수집
- Call /crawl-data 로 웹에서 최신 데이터 수집

2단계: 데이터 정제
- Call /clean-data 로 결측치 처리 및 형식 통일

3단계: 분석 및 보고
- Call /generate-report 로 분석 결과 보고서 생성

순차 실행: 각 하위 워크플로우가 완료된 후 다음 단계로 진행
컨텍스트 공유: 이전 워크플로우의 결과가 다음 워크플로우에 전달됨
깊이 제한: 너무 깊은 중첩은 컨텍스트 소비가 크므로 2~3단계 이내 권장

공식 문서

Q3: 에이전트가 워크플로우를 자동으로 만들어줄 수 있나요?

네! 에이전트에게 워크플로우 생성을 요청할 수 있습니다. 특히 수동으로 작업을 진행한 후에 효과적입니다.

작업 수행: 에이전트와 함께 원하는 작업을 수동으로 한 번 진행 (예: 데이터 정제 → 분석 → 시각화)
워크플로우 생성 요청: "방금 한 작업을 워크플로우로 만들어줘"라고 요청
자동 생성: 에이전트가 대화 기록을 분석하여 단계별 워크플로우 파일을 생성
검토 및 수정: 생성된 워크플로우를 확인하고 필요시 수정

효과적인 요청 예시: "지금까지 한 데이터 분석 과정을 /weekly-eda 워크플로우로 만들어줘. 각 단계에 검증 포인트도 추가해줘."

공식 문서

Q4: 워크플로우 파일의 크기 제한이 있나요?

네, 워크플로우 파일은 각각 최대 12,000자로 제한됩니다.

상황	권장 방법	예시
12,000자 이내	단일 파일로 유지	간단한 5단계 워크플로우
12,000자 초과	여러 파일로 분리 + 중첩 호출	메인 → 서브 워크플로우 구조
반복 패턴 존재	공통 부분을 별도 워크플로우로 추출	`/common-setup` → `/analysis`

## 분리 전 (15,000자 - 초과!)
/full-pipeline: 데이터 수집 → 정제 → 분석 → 시각화 → 보고서

## 분리 후 (각 5,000자 이내)
/data-collect: 데이터 수집 + 정제 (Call /data-collect)
/data-analyze: 분석 + 시각화 (Call /data-analyze)
/data-report: 보고서 생성 (Call /data-report)

공식 문서

Q5: Rules와 Workflows의 핵심 차이는 무엇인가요?

Rules는 프롬프트 수준에서 지속적인 가이드를, Workflows는 궤적 수준에서 구조화된 단계를 제공합니다.

구분	Rules (규칙)	Workflows (워크플로우)
동작 수준	프롬프트 수준 (컨텍스트)	궤적 수준 (단계별 실행)
실행 방식	자동 적용	슬래시 명령으로 호출
내용 유형	"~해야 한다" (지침)	"1단계 → 2단계 → 3단계" (절차)
비유	교통 법규 (항상 준수)	요리 레시피 (필요할 때 따라함)
재사용성	모든 대화에 자동 적용	호출할 때마다 동일하게 반복
적합한 작업	코딩 스타일, 응답 언어 설정	주간 보고서, 데이터 파이프라인

함께 사용하기: Rules로 "분석 결과는 항상 한국어로 작성"을 설정하고, Workflow로 "/weekly-report" 분석 절차를 정의하면, 워크플로우 실행 시 Rules가 자동으로 함께 적용됩니다.

공식 문서

Q6: 워크플로우 파일은 어디에 저장하나요?

워크스페이스(프로젝트)와 글로벌(사용자 전체) 두 가지 범위로 저장할 수 있습니다.

# 워크스페이스 범위 (프로젝트별)
프로젝트/.agents/workflows/
  ├── weekly-report.md      # /weekly-report 로 호출
  ├── data-pipeline.md      # /data-pipeline 로 호출
  └── code-review.md        # /code-review 로 호출

# 글로벌 범위 (모든 프로젝트에서 사용)
~/.gemini/antigravity/workflows/
  ├── git-commit.md         # /git-commit 로 호출
  └── daily-standup.md      # /daily-standup 로 호출

범위	저장 위치	적합한 용도
Workspace	`.agents/workflows/`	프로젝트 고유 작업 (데이터 분석, 빌드)
Global	`~/.gemini/antigravity/workflows/`	공통 작업 (Git, 일일 보고 등)

생성 방법: Customizations 패널에서 + Global 또는 + Workspace 버튼을 클릭하거나, 직접 해당 경로에 .md 파일을 생성하면 됩니다.

공식 문서

Q7: 워크플로우에서 MCP 도구나 브라우저를 사용할 수 있나요?

네. 워크플로우의 각 단계에서 MCP 도구와 브라우저 서브에이전트를 활용할 수 있습니다.

## /market-research 워크플로우 예시

1단계: 데이터 수집 (MCP 활용)
- BigQuery MCP로 내부 매출 데이터 조회
- Google Sheets MCP로 경쟁사 비교 데이터 로드

2단계: 웹 리서치 (브라우저 서브에이전트)
- 브라우저로 최신 시장 트렌드 검색
- 관련 뉴스 기사 3건 수집 및 요약

3단계: 종합 보고서 작성
- 수집된 데이터를 기반으로 분석 보고서 생성
- 차트와 테이블 포함

MCP 도구: 데이터베이스 쿼리, 외부 API 호출, 파일 시스템 접근
브라우저 서브에이전트: 웹 페이지 탐색, 스크래핑, 폼 입력
조합 사용: 한 워크플로우 내에서 MCP와 브라우저를 함께 사용 가능

MCP 문서 브라우저 문서

Q8: Planning 모드와 Fast 모드의 차이는 무엇인가요?

워크플로우 실행 시 에이전트의 동작 방식을 결정하는 두 가지 모드입니다.

구분	Planning 모드	Fast 모드
동작 방식	전체 계획 수립 후 실행	계획 없이 즉시 실행
실행 속도	느림 (계획 수립 시간 포함)	빠름
정확도	높음 (전체 맥락 파악 후 실행)	보통 (단계별 즉시 처리)
컨텍스트 사용	많음	적음
적합한 워크플로우	복잡한 다단계 파이프라인	단순한 3~5단계 작업

선택 기준: 워크플로우 단계가 5개 이상이거나 단계 간 의존성이 복잡하면 Planning 모드를, 단순 반복 작업이면 Fast 모드를 사용하세요. 설정에서 기본 모드를 변경할 수 있습니다.

공식 문서

공식 문서에서 더 알아보기

Rules & Workflows 공식 문서 열기 → Skills (스킬) 공식 문서 에이전트 모드/설정 문서 MCP (Model Context Protocol) 문서 브라우저 서브에이전트 문서 Antigravity 전체 문서