Antigravity 100% 활용 가이드

Antigravity 100% 활용 가이드: AI Agent와 함께하는 코딩의 미래

"단순한 챗봇이 아닙니다. 당신의 주니어 개발자이자, 든든한 페어 프로그래밍 파트너입니다."

1. Antigravity의 정체성 (Identity)

🚀 Agentic Mode란?

기존의 AI 코딩 도구(Copilot 등)가 단순히 "코드 자동 완성"이나 "질문 답변"에 그쳤다면,
Antigravity는 "목표를 주면 스스로 계획하고, 실행하고, 검증하는" 자율형 에이전트(Autonomous Agent)입니다.

핵심 철학 (3단계 사고 과정):

Planning (계획): 무작정 코드를 짜지 않습니다. 먼저 요구사항을 분석하고 implementation_plan.md를 만들어 당신과 합의합니다.
Execution (실행): 합의된 계획에 따라 코드를 작성하고 수정합니다.
Verification (검증): 작성한 코드가 제대로 동작하는지 테스트하고, 그 결과를 walkthrough.md로 보고합니다.

2. 핵심 용어 정의 (Terminology)

Antigravity와 원활하게 소통하기 위해 꼭 알아야 할 용어들입니다.

용어	설명	비유
Context (컨텍스트)	에이전트가 기억하고 있는 대화, 파일, 프로젝트 정보	개발자의 "기억력"
Artifacts (아티팩트)	에이전트가 생성한 주요 산출물 (`task.md`, `implementation_plan.md` 등)	업무 일지 및 기획서
Task Boundary	작업의 시작과 끝을 명확히 구분하는 경계선. "지금부터 A 작업 시작해"	업무 모드 전환 버튼
Subagent	본체 에이전트가 특정 작업(브라우징, 터미널 실행)을 위임하는 하위 에이전트	전문 분야 외주 직원
Workflow	자주 반복되는 작업 절차를 정의해둔 매크로	업무 매뉴얼

3. 단계별 설정 가이드 (Step-by-Step Setup)

Antigravity를 처음 시작할 때, 이 순서대로 설정하면 가장 효율적입니다.

Step 1. 전역 규칙 설정 (`.cursorrules` vs `.agent/rules`)

프로젝트의 **"헌법"**을 만드는 단계입니다.
가장 표준적인 방법은 프로젝트 최상위 루트에 .cursorrules 파일을 만드는 것입니다.

하지만 규칙이 많아지면 관리가 어렵습니다. "멀티 룰(Multi-Rule)" 패턴을 추천합니다.

1. 메인 규칙 파일 생성 (.cursorrules)
이 파일은 에이전트가 가장 먼저 읽는 진입점(Entry Point)입니다.

markdown

# 프로젝트 전역 규칙 (Master Rule)

1. **Rule Reference:**
   - 코딩 스타일은 `.agent/rules/coding-style.md`를 따르세요.
   - 아키텍처 원칙은 `.agent/rules/architecture.md`를 참고하세요.

2. **Language:** 한국어(Korean)로 대화하세요.
3. **Behavior:**
   - 코드를 수정하기 전에는 항상 `implementation_plan.md`를 먼저 작성하세요.
   - **Task Management:**
     - `task.md`를 프로젝트 루트에 생성하고 항상 최신 상태로 유지하세요.
     - 완료된 작업은 `[x]`, 진행 중은 `[/]`, 대기 중은 `[ ]`로 표시하세요.

2. 모듈화된 규칙 생성 (.agent/rules/*.md)
규칙을 주제별로 쪼개서 관리합니다.

.agent/rules/coding-style.md: (예: 변수명 규칙, JPA 엔티티 패턴)
.agent/rules/architecture.md: (예: Layered Architecture, 의존성 규칙)

핵심: 에이전트는 .cursorrules를 먼저 읽고, 그 안의 지시에 따라 필요한 상세 규칙 파일을 스스로 찾아 읽게 됩니다.

Step 2. 초기화 (Initialize)

에이전트에게 프로젝트 파악을 시킵니다.
별도의 규칙이 없어도 기본적으로 task.md를 잘 만들지만, Step 1의 .cursorrules에 정의된 형식이 있다면 그에 맞춰 생성합니다.

채팅창에 다음 명령어를 입력하세요.

User: "현재 프로젝트 구조를 분석하고, task.md를 생성해서 앞으로 할 일들을 정리해줘."

Step 3. 워크플로우 정의 (Workflows)

반복되는 작업은 워크플로우로 만듭니다. .agent/workflows/ 폴더에 .md 파일로 저장합니다.

예시 (.agent/workflows/deploy.md):

markdown

---
description: 배포 프로세스 자동화
---

1. 프로젝트 빌드 (`./gradlew build -x test`)
2. Docker 이미지 생성
3. 배포 서버로 전송 (`scp ...`)
4. 기존 컨테이너 중지 및 새 컨테이너 실행

이제 채팅창에 **"/deploy"**라고 치면 에이전트가 이 절차를 수행합니다.

4. 스킬 (Skills): 에이전트에게 전문 지식 가르치기

프로젝트마다 고유한 규칙이나 복잡한 설정법이 있나요? 매번 채팅으로 설명하지 말고 **"스킬"**로 만드세요.

📌 스킬 만드는 법

.agent/skills/ 폴더 생성
my-skill/SKILL.md 파일 생성
자세한 지침 작성

예시 (.agent/skills/payment-system/SKILL.md):

markdown

# 사내 결제 시스템 연동 가이드

## 규칙
1. 결제 요청 시 반드시 `pg_token`을 헤더에 포함해야 함
2. 타임아웃은 3000ms로 설정할 것
3. 재시도 로직은 `RetryTemplate` 사용 필수

## 예제 코드
...

이제 에이전트가 결제 관련 코드를 짤 때, 스스로 이 파일을 찾아보고 규칙을 지킵니다.

🤔 어떻게 자동으로 찾나요? (작동 원리)

에이전트는 작업을 시작할 때(Planning 단계), .agent/skills/ 폴더 목록을 스캔합니다.
사용자의 요청(예: "결제", "Payment")과 일치하는 폴더 이름(payment-system)이 있다면,
"아, 이건 결제 관련 작업이구나!" 하고 알아서 SKILL.md를 열어봅니다.

Tip: 폴더 이름을 payment-system, aws-deployment 처럼 직관적으로 지어야 에이전트가 잘 찾아냅니다.

5. 멀티 에이전트 (Multi-Agent): 팀으로 일하기

Antigravity는 단순히 기능이 많은 봇이 아니라, **"역할(Role)에 특화된 여러 에이전트들의 팀(Team)"**입니다.
메인 에이전트(저)를 중심으로, 필요할 때마다 전문가 에이전트를 호출하여 협업합니다.

🌐 Browser Subagent (정보 수집가 - Researcher)

최신 기술 문서, 라이브러리 버전, 에러 해결법을 웹에서 직접 찾아오는 역할입니다.

활용 예시:
- "Spring Boot 3.2 마이그레이션 가이드를 찾아보고 요약해줘."
- "이 라이브러리의 최신 버전과 호환성 이슈를 조사해줘."

💻 Terminal Executor (실행 전문가 - Runner)

코드를 작성하는 것과 별개로, 직접 실행하고 결과를 검증하는 역할입니다.

활용 예시:
- "모든 테스트를 실행하고, 실패한 테스트만 골라서 원인을 분석해줘."
- "Git 커밋하고 원격 저장소에 푸시해줘."

🔌 MCP Specialists (확장 전문가 - Connector)

외부 시스템(DB, 클라우드, 메신저 등)과 연결하여 특정 도메인 작업을 수행하는 역할입니다. (Model Context Protocol)

Database Agent: "로컬 DB의 users 테이블 스키마를 읽어와서 Entity랑 비교해줘."

추천(MCP): @modelcontextprotocol/server-postgres
(공식 PostgreSQL 서버로, 스키마 조회 및 읽기 전용 쿼리 실행에 최적화되어 있습니다.)
DevOps Agent: "AWS EC2 인스턴스 목록을 조회하고, 상태가 멈춘 서버를 재시작해줘."
QA Agent: "Playwright로 메인 페이지 접속 시나리오를 테스트해줘."

핵심: 여러분은 메인 에이전트에게 지시만 내리면, 제가 내부적으로 적절한 전문가(Browser, Terminal, MCP Tool)를 호출하여 알아서 협업하고 결과를 종합합니다.

6. 실전 활용 시나리오 (Use Cases)

✅ Case A: Spring Boot 프로젝트 초기 세팅

규칙 설정: .cursorrules에 "Java 21, Spring Boot 4, Gradle(Kotlin)" 명시
명령: "이 프로젝트에 JPA, QueryDSL, MySQL 의존성을 추가하고, 기본 Member 엔티티와 Repository를 만들어줘."
결과: 에이전트가 build.gradle 수정 -> Member.java (Template 적용) -> MemberRepository.java 생성 -> 컴파일 확인까지 완료.

✅ Case B: 버그 수정 (Debugging)

문제 발생: "로그인 시 500 에러가 발생해. 로그 파일(logs/error.log) 확인해줘."
분석(Planning): 에이전트가 로그를 읽고 NPE(NullPointerException) 위치 파악
수정(Execution): 해당 코드에 Optional 처리가 누락된 것을 발견하고 수정
검증(Verification): "수정 완료했습니다. 테스트 케이스를 만들어서 통과하는지 확인하겠습니다." -> 테스트 실행

7. 마치며: Antigravity와 함께 성장하기

Antigravity는 여러분이 **"단순 반복 코딩"**에서 벗어나 **"설계와 아키텍처"**에 집중하도록 돕습니다.
지금 바로 .cursorrules 파일을 만들고, 첫 번째 워크플로우를 정의해 보세요.

🚀 Happy Coding with Antigravity!

Antigravity 100% 활용 가이드

중년개발자