Hooks (훅) — Antigravity 자동화 패턴 가이드

1. 빠른 시작 — Antigravity에서 hooks 효과 5분 만에 만들기 #

"매 대화마다 git 상태를 자동으로 컨텍스트에 알려주는" 효과를 Rules로 구현해 봅니다. 셸 명령을 직접 자동 실행시키는 hooks 방식이 아니라, "git 변경 사항이 있다면 답변 전에 먼저 확인하라"는 행동 규칙을 마크다운으로 정의하는 방식입니다.

Step 1 — Rules 디렉터리 만들기

워크스페이스 루트에 .agent/rules/ 디렉터리를 만듭니다. 이미 있다면 그대로 사용하세요.

프로젝트_루트/
├── .agent/
│   ├── rules/         # 상시 또는 조건부로 적용되는 행동 규칙
│   └── workflows/     # 슬래시 명령으로 호출하는 다단계 절차
└── ...

Step 2 — 첫 Rule 파일 작성

# description: 코드 변경·리뷰·커밋 관련 작업 시 적용되는 git 컨텍스트 규칙
# globs: **/*

## git 컨텍스트 규칙

코드를 수정·리뷰·커밋하는 작업을 시작하기 전에 다음 단계를 따른다.

1. `git status --short`로 현재 워킹 트리 상태를 먼저 확인한다.
2. 변경 파일이 있으면 사용자에게 변경 요약을 한 줄로 보고한다.
3. 새 변경을 만들기 전, 기존 변경과 충돌하는지 점검한다.

git 저장소가 아닌 워크스페이스에서는 위 규칙을 무시한다.

Step 3 — Antigravity에서 결과 확인

Antigravity 에디터를 재시작하거나 워크스페이스를 다시 엽니다. 새 대화에서 "이 파일 좀 고쳐줘" 같은 코드 수정 요청을 보내 보세요. 에이전트가 답변 시작 전에 git status --short를 실행하고 결과를 사용자에게 한 줄로 알려주는 동작을 확인할 수 있습니다.

Step 4 — "응답 후 자동 정리"가 필요하다면 Workflow로

Rules는 매 응답 시작 전에 무엇을 확인할지를 정합니다. 응답이 끝난 뒤 포맷·테스트·정리를 하나의 절차로 묶고 싶다면 Workflow를 만들어 슬래시 명령으로 호출하세요.

# 응답이 끝난 뒤 코드 품질 정리 절차

1. 변경된 Python 파일 목록을 `git diff --name-only --diff-filter=AM`로 추출
2. 각 파일에 `ruff format`을 실행
3. `pytest -x`로 테스트 1회 실행, 실패 시 즉시 보고
4. 모든 단계가 성공하면 "정리 완료" 메시지 출력

이 Workflow는 사용자가 /format-and-test를 입력해 호출합니다. Claude Code의 postTurn 훅처럼 자동 트리거되지는 않지만, 사용자가 한 번 호출하면 등록된 절차가 일관되게 실행됩니다.

다음 절에서 위 패턴이 왜 hooks와 같은 효과를 내는지(개념 비교)와, 더 다양한 활용 패턴을 살펴봅니다.

2. Hooks 개념과 Antigravity의 대응 메커니즘 #

Claude Code 등 일부 에이전트에서 Hooks는 매 턴(turn)마다 자동으로 실행되는 셸 명령으로 정의됩니다. Antigravity는 이를 그대로 제공하지 않지만, 같은 효과를 얻는 메커니즘을 따로 두고 있습니다. 우선 hooks가 푸는 두 가지 문제를 정리하고, 각각을 Antigravity에서 어떻게 푸는지 매핑합니다.

응답 전(pre) vs 응답 후(post) 자동화의 목적

같은 효과를 어떻게 얻는가 — Antigravity vs Claude Code

왜 이런 자동화 패턴이 필요한가

매 대화마다 사용자가 명시적으로 지시하는 방식에는 다음과 같은 문제가 생깁니다.

• ❌ 망각 위험 — "이번엔 ruff 돌리는 거 깜빡했네" 같은 일관성 결핍.
• ❌ 프롬프트 길이 낭비 — 매번 "코드 작성 후 ruff format, mypy, pytest 실행" 같은 반복 지시가 토큰 소모.
• ❌ 컨텍스트 누락 — 에이전트가 "데이터 좀 살펴볼게요" 한 뒤 답변하므로 한 턴이 추가 소모됨.
• ❌ 팀 표준 불일치 — 팀원마다 사용하는 검증 도구·옵션이 달라짐.

Antigravity에서는 위 문제를 Rules + Workflows + 외부 시스템 도구의 조합으로 해결합니다. 한 번 정의하면 워크스페이스를 여는 모든 팀원에게 동일하게 적용됩니다.

Hooks vs Rules vs Skills vs Workflows — 한눈 비교

3. 단계별 등록 가이드 — Rules·Workflows로 hooks 효과 만들기 #

3.1 파일 위치 결정 — 워크스페이스 vs 전역

Antigravity의 자동화 파일은 두 위치 중 하나에 둘 수 있습니다.

두 위치에 같은 항목이 있으면 워크스페이스 정의가 전역을 보강 또는 재정의합니다. 팀 공유가 필요한 자동화는 워크스페이스 디렉터리를 git에 커밋해 모든 팀원이 같은 환경을 얻게 합니다.

3.2 Rule 파일의 표준 골격

# description: 어떤 상황에 적용되는 규칙인지 자연어로 설명 (Model Decision 모드용)
# globs: **/*.py                # 어떤 파일과 관련된 작업에서 활성화할지 (Glob 모드용)

## 규칙 제목

규칙 본문은 평서문으로 명확하게 작성한다. 에이전트가 이를 답변
이전에 자연스럽게 적용한다.

- 항목 1
- 항목 2
- 예외 또는 회피 조건

• frontmatter 주석 (선택) — # description:, # globs:로 활성화 모드를 정합니다. 자세한 내용은 Rules 페이지의 활성화 모드 참조.
• 본문 — 평서·짧은 문장이 가장 잘 동작합니다. 12,000자 이내 권장.
• 여러 파일로 분리 — 주제별로 파일을 나누면 에이전트의 추론 정확도가 높아집니다.

3.3 Workflow 파일의 표준 골격

# 워크플로우 제목 — 한 줄 요약

## 입력
- 사용자가 호출 시 전달할 인자 또는 컨텍스트

## 단계
1. 첫 단계 — 무엇을 확인하고 어떤 도구를 호출할지
2. 두 번째 단계 — 분기 조건 포함 가능
3. ...

## 출력
- 사용자에게 보고할 결과 형식 (표·요약·산출 파일 경로 등)

• 슬래시 명령 이름은 파일명에서 자동 도출됩니다. format-and-test.md는 /format-and-test로 호출.
• 사용자 호출 후 자동 실행되므로, 에이전트가 헷갈리지 않도록 단계마다 도구·결과를 명시합니다.

3.4 가장 자주 쓰는 기본 예시 3가지

# description: 코드 수정·리뷰·커밋 작업을 시작하기 전 git 컨텍스트를 먼저 확인
# globs: **/*

## git 컨텍스트 점검 규칙

코드를 수정하는 답변을 시작하기 전에 다음 단계를 따른다.

1. `git status --short`로 변경 파일을 확인한다.
2. 변경이 있으면 사용자에게 한 줄로 요약 보고한다.
   예: "현재 3개 파일이 미커밋 상태입니다 (src/main.py, tests/test_a.py, README.md)."
3. 새 변경을 만들기 전, 기존 변경과 충돌이 없는지 점검한다.

git 저장소가 아닌 워크스페이스에서는 위 규칙을 무시한다.

# 코드 변경 마무리 — 포맷·린트·테스트

## 단계

1. `git diff --name-only --diff-filter=AM` 실행해 변경된 파일 목록 추출
2. Python 파일이 포함되어 있으면 `ruff format <파일>`을 일괄 실행
3. `ruff check --fix` 실행해 자동 수정 가능한 린트 이슈 처리
4. `pytest -x -q | tail -20` 실행해 빠른 회귀 테스트
5. 모든 단계 결과를 한 줄씩 요약 보고

테스트 실패 시 즉시 중단하고 실패 내역을 사용자에게 보여준다.

호출 방법: 에이전트 채팅에서 /<파일명>을 입력. 위 예시는 /code-cleanup 같은 이름으로 저장하면 그대로 호출됩니다.

# description: CSV·Excel·Parquet 파일을 다루는 데이터 분석 작업 시작 시 적용
# globs: **/*.{csv,xlsx,parquet,ipynb}

## 데이터 윤곽 점검

데이터 분석 답변을 시작하기 전에 다음을 먼저 확인한다.

1. `df.shape`, `df.dtypes`, `df.head(3)` 출력으로 데이터 구조 파악
2. 결측치 비율을 컬럼별로 계산해 5% 이상인 컬럼만 보고
3. 시간·날짜 컬럼이 있으면 자료형이 datetime인지 확인

이 점검을 마친 뒤 사용자 요청을 처리한다.

3.5 등록 후 검증 절차

1. 경로 확인 — 파일이 정확히 .agent/rules/ 또는 .agent/workflows/ 아래에 있는지 확인 (.gemini/가 아닙니다).
2. frontmatter 검증 — Rule 파일은 # description: 또는 # globs: 주석을 추가했는지 확인. Always On 모드라면 둘 다 생략 가능.
3. 워크스페이스 재로드 — Antigravity 에디터에서 워크스페이스를 다시 열거나, 새 대화를 시작합니다.
4. Rule 동작 확인 — 규칙이 적용되는 작업(예: 파이썬 코드 수정 요청)을 보내고, 에이전트가 답변 시작 전에 규칙대로 동작하는지 확인합니다.
5. Workflow 호출 확인 — 슬래시 명령(/<파일명>)을 입력해 절차가 단계대로 실행되는지 확인합니다.

4. 활용 패턴 모음 (참고용 — Claude Code 표기) #

실전에서 자주 쓰이는 자동화 패턴을 카테고리별로 정리했습니다. 자신의 워크플로우에 맞는 항목을 골라 위 변환 규칙대로 Rules·Workflows로 옮겨 사용하세요. 모든 명령은 파일 부재·도구 미설치 시 에러가 나지 않도록 가드 패턴([ -f ... ] && ..., ... || true)을 적용하는 것을 권장합니다.

4.1 코드 품질

4.2 Git 및 버전관리

4.3 테스트 자동화

4.4 데이터 분석 분석가 권장

4.5 보안

4.6 문서 자동화

완성된 통합 예시 — 풀스택 Python 프로젝트

위 패턴들을 조합한 settings.json 예시. 자신의 프로젝트에 맞춰 가감하세요.

{
  "agentSettings": {
    "hooks": {
      "preTurn": [
        {
          "command": "echo '=== Git ===' && git status --short 2>/dev/null && git log --oneline -5 2>/dev/null",
          "description": "변경 파일·최근 커밋 자동 주입"
        },
        {
          "command": "[ -f data/train.csv ] && python -c \"import pandas as pd; df = pd.read_csv('data/train.csv'); print(f'shape={df.shape} null_rate={df.isnull().mean().mean():.2%}')\" || echo 'data/train.csv 없음'",
          "description": "데이터셋 메타 주입 (있을 때만)"
        }
      ],
      "postTurn": [
        {
          "command": "black . --quiet 2>&1 || true",
          "description": "Python 자동 포맷팅"
        },
        {
          "command": "flake8 src/ --max-line-length=88 --statistics 2>&1 | tail -5",
          "description": "린트 검사 (마지막 5줄만)"
        },
        {
          "command": "pytest tests/ -x -q 2>&1 | tail -10",
          "description": "테스트 실행 (실패 즉시 중단)"
        },
        {
          "command": "git add -A && git status --short",
          "description": "변경 사항 자동 스테이징"
        }
      ]
    }
  }
}

5. 프롬프트로 자동화 파일 만들기 #

Rules·Workflow 파일을 직접 작성하는 대신, Antigravity 에이전트에게 자연어로 부탁하면 에이전트가 적절한 위치에 파일을 만들어 줍니다. 사용자는 "원하는 자동화"를 말로 표현하기만 하면 되고, frontmatter·본문 작성은 에이전트가 처리합니다.

5.1 3단계 워크플로우

5.2 시나리오별 프롬프트 템플릿

매 대화가 끝날 때마다 (postTurn) Python 코드를 black으로 자동 포맷팅하고
flake8 린트를 돌려서 마지막 5줄만 보여줘.
실패해도 다음 단계로 넘어가게 가드를 추가해주고,
.gemini/settings.json에 등록해줘.

지금 .gemini/settings.json의 훅 설정을 보고 다음 관점에서 검토해줘:
1. 파일 경로가 하드코딩된 곳이 있는지 (있으면 [ -f ... ] 가드 추가)
2. 출력이 너무 길어 컨텍스트를 낭비하는 곳 (tail -N으로 제한)
3. 실패 시 다음 단계가 막히는 곳 (|| true 또는 || echo 가드)
개선안을 적용한 settings.json을 보여줘.

현재 postTurn 훅 실행이 너무 느려 매 턴이 답답해.
각 명령에 time을 붙여서 실행 시간을 측정하는 임시 settings.json을 만들고,
한 번 돌려본 뒤 가장 느린 명령부터 최적화 방안을 제안해줘.
(예: 캐시, 병렬 실행, 조건부 스킵)

preTurn 훅이 매 대화에서 'data/train.csv: No such file or directory' 에러를
출력해서 컨텍스트를 더럽히고 있어. 현재 settings.json은 다음과 같아:
[settings.json 내용 붙여넣기]
원인을 진단하고, 파일이 없을 때 에러 대신 안내 메시지가 나오도록 수정해줘.

5.3 점진적 정교화 패턴 — 한 번에 완성하지 않기

처음부터 완벽한 훅을 요청하기보다, 가장 단순한 버전 → 동작 확인 → 개선 흐름이 더 안정적입니다.

👤 사용자: postTurn에 black 포맷팅을 추가해줘.

🤖 에이전트: settings.json에 다음 훅을 추가했습니다.
{ "command": "black .", "description": "Python 자동 포맷팅" }

👤 사용자: black 출력이 너무 시끄러워. 변경된 파일 개수만 한 줄로 보여줘.

🤖 에이전트: command를 다음과 같이 수정했습니다.
"command": "black . --quiet 2>&1 | grep -c 'reformatted' | xargs -I {} echo '{} files reformatted'"

👤 사용자: black 미설치 환경에서 에러로 막혀. 미설치면 안내만 하고 넘어가게.

🤖 에이전트: 가드 패턴을 추가했습니다.
"command": "command -v black >/dev/null && black . --quiet || echo 'black 미설치 — pip install black 필요'"

3턴 만에 처음의 단순한 black .이 정량 출력 + 미설치 가드를 갖춘 견고한 훅으로 진화했습니다.

5.4 자주 쓰는 변형 요청 모음

5.5 에이전트와 함께 디버깅하기

훅이 예상대로 동작하지 않을 때, 사용자가 직접 디버깅하는 대신 에이전트와 함께 단계적으로 좁혀가는 방식이 효율적입니다.

6. 트러블슈팅 #

6.1 실행 실패 처리 — 가드 패턴 정리

훅 명령이 실패해도 에이전트 대화는 중단되지 않습니다. 하지만 실패 출력이 컨텍스트를 더럽히면 에이전트의 응답 품질이 떨어집니다. 다음 가드 패턴들을 적절히 조합해 사용하세요.

6.2 디버깅 — stdout/stderr 활용

훅 명령의 stdout과 stderr는 모두 에이전트 컨텍스트에 추가되므로, 진단용 출력을 적극 활용할 수 있습니다.

{
  "command": "echo '=== HOOK START $(date +%T) ===' && pwd && echo SHELL=$SHELL && ls -la .gemini/ && echo '=== HOOK END ==='",
  "description": "훅 실행 환경 진단 (시각·작업 디렉토리·셸·gemini 폴더)"
}

6.3 성능 최적화

• 출력 최소화 — tail -N, --quiet, --silent로 토큰 낭비 줄이기.
• 조건부 실행 — 모든 파일이 아닌 변경된 파일만 처리 (예: git diff --name-only | xargs black).
• 비동기 실행 — 결과를 다음 턴에 봐도 되는 작업은 명령 끝에 &를 붙여 백그라운드로.
• 캐시 활용 — pytest --testmon, mypy --incremental처럼 변경분만 검사하는 모드 사용.
• 훅 개수 관리 — preTurn/postTurn 합쳐 5개 이내 권장. 그 이상이면 헬퍼 스크립트로 통합.

6.4 보안 고려사항

6.5 흔한 실수 모음

7. 더 깊이 학습 #

이 페이지가 훅의 실전 활용에 집중했다면, 다음 자료는 훅의 아키텍처 맥락과 보안적 의미를 다룹니다.

• Harness Engineering — 훅 & 자동화 섹션 — 4-레이어 하네스 구조에서 훅이 차지하는 위치, 보안 레이어와의 상호작용, 데이터 분석 워크플로우 심화 예시.
• Harness Engineering — 설정 레이어 — settings.json 전체 구조와 4가지 정책 축(터미널 실행 모드, 파일 접근, 브라우저 URL, 훅).
• Harness Engineering — 보안 레이어 — allowlist·denylist·샌드박스와 훅 명령의 안전한 결합.
• Rules (규칙) — 자연어 기반 행동 제어. 훅과 상호 보완.
• Workflows (워크플로우) — 다단계 절차 자동화. 단순 훅으로 부족한 복잡한 작업에 사용.
• Antigravity 공식 문서 — 최신 사양과 변경 사항.