책에 포함된 노트Google Antigravity 실전 활용법: 코딩을 넘어 오케스트레이션으로

Antigravity로 만드는 개인·팀 개발 시스템: 워크플로 템플릿 10선

2026-03-23Views 6약 11분

'툴'에서 '시스템'으로: 템플릿이 만드는 차이

Antigravity를 오래 쓰다 보면 실감하는 지점이 있다. 모델을 바꾸거나 프롬프트를 더 길게 쓰는 것보다, 반복 업무를 '정해진 절차'로 고정했을 때 결과 품질이 급격히 안정된다. 개인에게는 "매번 다시 설명하지 않는 환경"이 되고, 팀에게는 "누가 실행하든 같은 수준의 산출물"이 된다.

핵심은 두 가지 계층을 갖추는 것이다.

첫째, Rules(규칙) 는 프로젝트의 헌법이다. Antigravity는 규칙을 통해 코드 스타일, 테스트 기준, 문서 톤, 작업 금지 구역 같은 행동 가이드를 지속적으로 주입할 수 있다.¹²³

둘째, Workflows(워크플로) 는 반복 작업을 호출 가능한 절차로 고정하는 장치다. "버그 재현→수정→회귀 테스트 추가"처럼 여러 단계가 필요한 작업을 / 명령으로 실행 가능한 저장 프롬프트로 만들 수 있다.¹²³

여기에 Artifacts(아티팩트) 를 결합하면, 결과를 말로만 보고받지 않고 "증거물"로 검증하게 된다. Antigravity가 강조하는 작업 단위는 결국 '작업 대화'가 아니라 '검증 가능한 산출물'이다.³

또 하나의 실전 팁은 "플러그인보다 파일"이다. 좋은 시스템은 특정 IDE 화면에만 갇히지 않는다. 규칙, 컨텍스트, 체크리스트를 텍스트 파일로 남기면 빈 폴더도 빠르게 '일하는 공간'으로 바꿀 수 있다.⁴

템플릿을 저장하는 표준 위치

워크플로 템플릿을 "팀 자산"으로 만들려면 저장 위치부터 표준화해야 한다.

다만 여기서 한 가지 주의할 점이 있다. Rules와 Workflows의 저장 경로는 버전과 설정 방식에 따라 달라질 수 있다. 따라서 팀 표준 경로를 정하되, 실제 적용 경로와 우선순위는 최신 Antigravity 문서에서 확인하는 것이 안전하다.³

실무에서는 보통 아래 두 가지를 먼저 정해두면 된다.

워크스페이스 규칙 위치: 프로젝트 공통 규칙 파일을 둘 경로
워크스페이스 워크플로 위치: / 명령으로 호출할 템플릿 파일을 둘 디렉터리
개인 전역 규칙 위치(선택): 개인 습관이나 선호를 담을 전역 설정 파일

중요한 것은 정확한 경로 이름보다도, 팀이 같은 위치를 기준으로 관리하고 리뷰한다는 점이다. 이 구조가 서면 규칙은 상시 적용되고, 워크플로는 필요할 때만 호출되는 체계가 만들어진다.¹²³

워크플로 템플릿 10선

아래 10개 템플릿은 "버그 재현→수정", "리팩터링", "문서화", "릴리즈 노트", "코드베이스 탐색"처럼 반복 빈도가 높은 업무를 대상으로 한다. 각 템플릿은 그대로 복사해 팀의 워크플로 디렉터리에 넣고, 상황에 맞게 '입력 항목'과 '검증 기준'을 조정하면 된다.

템플릿 1) 버그 재현 → 수정 → 회귀 테스트 추가

버그 해결의 출발점은 '추정'이 아니라 '재현'이다. 재현 가능한 버그는 측정 가능한 결함이 되고, 정확한 재현 절차·환경·증거가 있을 때 원인 분석과 회귀 방지가 빨라진다.⁵⁶

워크플로 이름(파일): bugfix-repro-to-regression.md
트리거: /bugfix

입력(요청자가 제공해야 할 것)

버그 요약(한 문장), 발생 빈도(항상/가끔/특정 조건), 환경(브라우저·OS·빌드), 기대 결과 vs 실제 결과, 그리고 가능하면 "확정 실패 아티팩트(스크린샷/로그/영상)" 1개를 받는다. 재현이 어려운 이슈일수록 기록·재생 형태의 증거를 확보하는 게 중요하다.⁵

절차(에이전트가 수행할 것)

재현 단계 최소화: 불필요한 단계를 제거해 "최소 재현 경로"를 만든다.⁶
환경 고정: 동일 버전·데이터·설정을 맞추고, 필요하면 Docker나 샌드박스 기준을 명시한다.⁵
원인 가설 2~3개: 로그, 스택 트레이스, 관련 커밋을 근거로 가설을 세운다.

아티팩트(반드시 남길 것)

artifacts/bug_report.md: 재현 절차, 환경, 기대/실제, 첨부 증거 링크
artifacts/acceptance_criteria.md: "어떤 조건에서 '고쳐졌다'고 말할 수 있는가"
artifacts/regression_test_plan.md: 어떤 테스트를 어디에 추가할지

검증 기준(완료 조건)

수정 PR에는 "버그 재현 테스트(또는 회귀 테스트)"가 포함되어야 하며, 수정 전에는 실패하고 수정 후에는 통과해야 한다. '말로 된 해결'이 아니라 '테스트로 고정된 해결'로 끝낸다.

참고: 다단계로 쪼개고 싶다면 triage→investigate→fix→verify 같은 역할 분리를 적용할 수 있다. 버그 처리 파이프라인을 에이전트 단계로 분리해 입력/출력을 키-값으로 넘기는 방식은 운영 자동화에 유리하다.⁷

템플릿 2) 안전한 리팩터링(행동 동일성 보장)

리팩터링의 실패는 '코드를 바꿈'이 아니라 '행동을 바꿈'에서 온다. 그래서 이 워크플로는 "테스트/동작 증거 먼저 확보 → 작은 단위로 변경 → 성능/동작 회귀 확인" 순서를 강제한다.

워크플로 이름: refactor-safely.md
트리거: /refactor

입력

대상 파일/모듈, 리팩터링 목적(가독성/성능/확장성), 변경 금지 API(호출부 계약), 현재 테스트 실행 방법.

절차

현재 동작을 설명하는 최소 스냅샷을 만든 뒤(테스트, 스냅샷 결과, 로그 등), 변경을 "기계적으로 되돌릴 수 있는 크기"로 쪼갠다. 단계마다 git diff를 리뷰하고, 실패 시 바로 롤백 가능한 커밋 단위를 유지한다.

아티팩트

artifacts/refactor_plan.md: 변경 범위, 리스크, 단계
artifacts/before_after.md: API/동작 비교표(행동 동일성 체크)

검증 기준

기존 테스트 전부 통과 + 새로 추가한 경계 테스트 1~2개 통과. "리팩터링 이유"가 성능이라면 측정 수치(예: 요청 시간, 번들 크기)를 전/후로 남긴다.

템플릿 3) 코드베이스 탐색 & 온보딩 지도 만들기

큰 코드베이스는 '수정'보다 '이해'가 먼저다. 이 워크플로는 신규 합류자나 오랜만에 돌아온 사람이 30분 만에 전체 지도를 잡도록 돕는다.

워크플로 이름: codebase-tour.md
트리거: /tour

입력

내가 하려는 작업(예: 로그인 버그 수정, 결제 플로우 추가), 현재 모르는 것 3가지.

절차

엔트리포인트(실행/빌드), 핵심 도메인 경계, 데이터 흐름, 테스트/배포 경로를 우선순위로 스캔한다. 답을 모르는 부분은 "추정" 대신 "확인해야 할 질문 목록"으로 남긴다.

아티팩트

artifacts/architecture_map.md: 폴더/모듈 책임, 주요 흐름, 의존성
artifacts/where_to_change.md: 특정 요구사항을 구현할 때 바꿔야 할 파일 후보

검증 기준

"작업 1개를 실제로 착수할 수 있는 수준"의 변경 지점이 제시되어야 한다. 예를 들어 함수·컴포넌트·라우트 단위까지 좁혀져 있어야 한다.

템플릿 4) 의존성/프레임워크 업그레이드(깨지지 않게 이동)

업그레이드는 '한 번에 끝내기'가 아니라 '안전한 단계 이동'이다. 이 워크플로는 변경량을 줄이고, 중간 상태에서도 빌드와 테스트가 통과하도록 계획을 쪼갠다.

워크플로 이름: upgrade-deps-migration.md
트리거: /upgrade

입력

현재/목표 버전, 제약(지원 브라우저, Node 버전, 배포 정책), CI 실행 방법.

절차

호환성 이슈를 먼저 조사하고(브레이킹 체인지, deprecated API), 마이그레이션을 2~5단계로 분할한다. 각 단계의 "성공 정의"는 빌드·테스트·린트 통과로 고정한다.

아티팩트

artifacts/migration_plan.md: 단계, 리스크, 롤백 방법
artifacts/compat_matrix.md: 영향받는 패키지, 런타임, 플러그인

검증 기준

각 단계 PR이 독립적으로 병합 가능해야 한다. 즉 중간 단계에서도 프로젝트가 깨지지 않아야 한다.

템플릿 5) 문서화(README/ADR/API 문서) 자동 정비

문서는 '나중에'가 아니라 '같이' 만들어야 쌓인다. 이 워크플로는 코드 변경과 함께 문서를 갱신하고, 팀 합의(결정 기록)까지 남긴다.

워크플로 이름: docs-sync.md
트리거: /docs

입력

문서 대상(README, API 문서, ADR), 문서의 독자(사용자/내부 개발자/운영), 최신 변경사항(커밋/PR 링크).

절차

코드에서 "사용자가 알아야 하는 사실"만 추출해 문서로 변환한다. API 문서라면 요청/응답 예시와 엣지 케이스를 포함하고, 결정이 수반되면 ADR 형식으로 "왜 그렇게 했는지"를 남긴다.

아티팩트

docs/README.md 또는 docs/api.md 업데이트
docs/adr/XXXX-*.md(결정이 있을 때)
artifacts/doc_diff_summary.md: 어떤 변경이 문서에 반영됐는지 요약

검증 기준

문서의 "실행 가능성"을 확인한다. 예를 들어 README의 설치/실행 명령이 실제로 동작해야 한다.

템플릿 6) 릴리즈 노트 작성(사용자 가치 중심 + 기술 추적성)

릴리즈 노트는 개발자가 만든 변경을 이해관계자가 이해할 수 있는 언어로 번역하는 문서다. 좋은 릴리즈 노트는 무엇이 바뀌었는지, 왜 중요한지, 사용자가 해야 할 일이 있는지를 일관된 구조로 전달한다.⁸

워크플로 이름: release-notes.md
트리거: /release-notes

입력

버전/릴리즈 날짜, 이번 릴리즈의 주요 변경 PR 목록(또는 diff 범위), 브레이킹 체인지 여부.

절차

릴리즈 노트를 "고정된 섹션"으로 작성한다. 예를 들어 Upgrade Steps / Breaking Changes / New Features / Bug Fixes / Improvements 같은 구조는 변경 요약과 행동 지시를 동시에 담기 좋다.⁹ 또한 고객 친화 문서라면 기술적 변경 나열이 아니라 '사용자 효익'을 먼저 설명하는 가이드가 유용하다.⁸

아티팩트

docs/release-notes/vX.Y.Z.md: 릴리즈 노트 본문
artifacts/release-traceability.md: PR/이슈 번호 매핑(내부용)

검증 기준

브레이킹 체인지가 있으면 상단에 노출되고, 마이그레이션 단계가 "복사-실행 가능한 수준"으로 구체적이어야 한다.⁸

템플릿 7) 테스트 생성 & CI 안정화('통과'가 아니라 '신뢰')

테스트는 개수보다 "실패가 의미가 있는가"가 중요하다. 이 워크플로는 테스트를 생성하는 것에서 끝내지 않고, flaky 테스트를 줄이고 CI에서 재현 가능하게 만든다.

워크플로 이름: tests-and-ci-hardening.md
트리거: /tests

입력

대상 모듈/기능, 현재 테스트 프레임워크, CI 실행 로그(최근 실패 1회분).

절차

테스트를 함수/경로 단위로 커버하고, 실패 시 원인이 분명한 assertion을 사용한다. 불안정한 테스트는 타임아웃, 비동기 대기, 외부 의존성을 분리해 재현성을 높인다. '재현 불가'에 빠지면 환경, 데이터, 타이밍 변수를 통제하는 방식으로 접근한다.⁵

아티팩트

artifacts/test_matrix.md: 어떤 기능을 어떤 레벨(unit/integration/e2e)로 커버했는지
CI 실패 재현 스크립트(예: scripts/repro-ci.sh)

검증 기준

CI에서 연속 3회 실행해도 같은 결과가 나와야 한다. 성공이든 실패든 결과가 흔들리지 않아야 한다.

템플릿 8) 성능 프로파일링 → 병목 제거 → 회귀 방지

성능 개선은 감이 아니라 측정이다. 이 워크플로는 "어디가 느린지"를 먼저 측정하고, 개선 후 수치를 남겨 회귀를 막는다.

워크플로 이름: perf-profile-optimize.md
트리거: /perf

입력

느린 시나리오(재현 절차), 목표 지표(예: p95 300ms), 측정 도구(Profiler, Tracing, 브라우저 성능 패널 등).

절차

측정 기준을 고정하고(같은 데이터, 같은 환경), 병목 후보를 2~3개로 좁힌 뒤 가장 큰 원인부터 해결한다. 개선이 끝나면 성능 회귀를 잡는 간단한 벤치마크나 스모크를 추가한다.

아티팩트

artifacts/perf_baseline.md: 전/후 지표, 측정 조건
artifacts/perf_changes.md: 변경 요약과 리스크

검증 기준

전/후 지표가 동일 조건에서 개선되었음을 수치로 증명한다.

템플릿 9) 보안 점검(의존성 + 설정 + 코드 경계)

보안은 "한 번 점검"이 아니라 "반복 가능한 루틴"이다. 이 워크플로는 취약점 점검 결과를 코드 변경과 함께 남기고, 프로젝트 규칙에 '보안 경계선'을 반영한다.

워크플로 이름: security-audit.md
트리거: /security

입력

사용 중인 스택, 인증/인가 방식, 최근 변경 중 위험 영역(파일 업로드, 템플릿 렌더링, SQL 등).

절차

의존성 스캔 결과를 정리하고, 위험한 코드 경로를 우선 점검한다. 해결이 필요한 항목은 "우회/완화/근본 수정" 중 무엇인지 분류하고, 팀이 지켜야 할 보안 규칙을 규칙 파일에 추가한다.

아티팩트

artifacts/security_findings.md: 위험도, 근거, 재현/검증 방법
artifacts/security_fixes.md: 수정 내역과 테스트

검증 기준

수정이 필요한 취약점은 재현 절차와 함께 "수정 후 더 이상 재현되지 않음"이 증거로 남아야 한다.

템플릿 10) 핫픽스 운영(롤백 포함) + 사후 분석(Postmortem)

프로덕션 장애는 '고치기'로 끝나지 않는다. 재발 방지와 팀 학습까지 포함해야 다음 사고의 비용이 줄어든다.

워크플로 이름: hotfix-and-postmortem.md
트리거: /hotfix

입력

장애 타임라인(발견 시각, 영향, 임시 조치), 관측된 증거(에러율 그래프/로그), 현재 배포/롤백 절차.

절차

핫픽스는 범위를 최소화하고, 필요하면 즉시 롤백 가능하게 만든다. 복구 후에는 재현 절차를 문서화하고, "탐지(Detection)·대응(Response)·원인(Root cause)·재발 방지(Prevention)" 순서로 사후 분석을 작성한다.

아티팩트

artifacts/hotfix_checklist.md: 배포/롤백 체크리스트
artifacts/postmortem.md: 영향, 원인, 재발 방지 작업(액션 아이템)

검증 기준

재발 방지 항목 중 최소 1개는 자동화(테스트, 모니터링, 알람)로 연결되어야 한다.

팀에서 '템플릿을 자산'으로 운영하는 법

템플릿은 만들어 두는 것으로 끝나지 않는다. 팀 시스템으로 굴리려면, 다음 운영 규칙이 필요하다.

첫째, 템플릿도 코드처럼 리뷰한다. 워크플로는 팀의 행동을 강제하는 도구이므로, 품질 기준과 표현이 일관되어야 한다.

둘째, 산출물을 아티팩트로 고정한다. "완료했습니다" 대신 bug_report.md, migration_plan.md, release-notes/vX.Y.Z.md 같은 파일이 남도록 설계하면, Antigravity가 강조하는 검증 중심 루프가 자연스럽게 굴러간다.³