Scheduled Tasks (스케줄 태스크) - 오늘코드 Antigravity 튜토리얼

1. 빠른 시작 — 첫 스케줄 태스크 만들기 #

매일 아침 9시에 GitHub 알림을 정리해서 요약 보고하는 스케줄을 5분 만에 만들어 봅니다.

Step 1 — Antigravity 2.0 또는 CLI 준비

다음 중 하나가 설치되어 있어야 합니다.

Antigravity 2.0 데스크톱 앱 — antigravity.google/download에서 다운로드
Antigravity CLI(agy) — 설치 가이드

Step 2 — 스케줄 정의

Antigravity 2.0의 Agent Manager에서 Scheduled Tasks 탭을 열고 새 태스크를 추가합니다. CLI라면 다음 명령:

      터미널
      # 매일 오전 9시(서울 시간)에 실행되는 태스크 추가
agy schedule add \
  --name "daily-github-digest" \
  --cron "0 9 * * *" \
  --tz "Asia/Seoul" \
  --prompt "내 GitHub 알림 중 어제 이후 발생한 PR 리뷰 요청·이슈 멘션을 우선순위별로 정리해서 ~/digest/$(date +%F).md에 저장"
    

Step 3 — 동작 확인

      터미널
      # 등록된 스케줄 목록
agy schedule list

# 다음 실행 시간 미리보기
agy schedule next daily-github-digest

# 지금 즉시 한 번 실행 (테스트)
agy schedule run daily-github-digest
    

방금 무슨 일이 일어났나?

매일 오전 9시(KST)에 에이전트가 자동으로 깨어나 GitHub 알림을 분석합니다.
결과는 ~/digest/2026-05-04.md 같은 일자별 파일로 저장됩니다.
사용자가 Antigravity 앱을 열지 않아도 백그라운드에서 실행됩니다.

2. Scheduled Tasks란? — 개념과 동작 원리 #

Scheduled Tasks는 "사용자가 매번 요청하지 않아도 에이전트가 알아서 깨어나 일하는" 자동화 기제입니다. Unix의 cron이 셸 명령을 자동 실행하는 것처럼, Scheduled Tasks는 에이전트 프롬프트를 자동 실행합니다.

3가지 핵심 구성요소

스케줄(cron 표현식) — 언제 실행할지 정의 (분/시/일/월/요일).
프롬프트(prompt) — 무엇을 할지 자연어로 정의. 매 실행 시 에이전트에게 전달됨.
컨텍스트(context) — 에이전트가 접근할 작업 디렉토리·MCP·스킬·환경변수.

Scheduled Tasks vs Hooks vs Workflows

자동화 도구 3종 비교
기능	실행 시점	사람 개입	전형적 사용
Hooks	대화 매 턴 (사람이 메시지 보낼 때마다)	대화 중	코드 포맷·테스트·git status 자동 주입
Workflows	`/workflow` 명령으로 호출 시	의식적 호출	배포·리뷰 등 다단계 절차
Scheduled Tasks	cron 시간 도래 시 자동	없음 (백그라운드)	일일 리포트·헬스 체크·시계열 모니터링

왜 필요한가?

다음 같은 작업은 사람이 매번 의식적으로 트리거하기 어렵습니다.

매일 아침 같은 시각에 정해진 리포트를 확인·정리
1시간마다 외부 서비스 상태를 점검하고 이상 시 알림
주간 단위로 누적 데이터를 집계·시각화
매월 첫째 주에 의존성 업데이트·취약점 스캔

이런 작업을 Scheduled Tasks에 한 번 등록해두면, 사람이 잊어버리거나 휴가를 가도 자동으로 실행됩니다.

실행 환경: Antigravity 2.0의 Scheduled Tasks는 Google이 관리하는 클라우드 하네스에서 실행됩니다. 사용자의 로컬 PC가 꺼져 있어도 동작합니다. 단, 파일 접근 권한·MCP 서버 설정 등은 사전에 명시해야 합니다.

3. 단계별 등록 가이드 #

3.1 GUI (Antigravity 2.0 앱)에서 등록

Agent Manager 열기 — Antigravity 2.0 앱 좌측 패널의 "Scheduled Tasks" 탭 선택.
"+ New Task" 클릭 — 새 태스크 폼이 열립니다.
이름 입력 — 영문/숫자/하이픈만 사용 권장 (예: daily-pr-review-digest).
Cron 표현식 입력 또는 프리셋 선택 — "매일 9시", "매주 월요일 오후 3시" 같은 프리셋도 제공.
타임존 선택 — 기본은 UTC. 한국이라면 Asia/Seoul 명시.
프롬프트 작성 — 에이전트가 매 실행 시 받을 자연어 지시.
컨텍스트 설정 — 작업 디렉토리, 활성화할 스킬·MCP 서버 선택.
"Test Run" 클릭 — 즉시 한 번 실행해 동작 확인.
"Save & Activate" — 스케줄 활성화.

3.2 CLI(`agy schedule`)로 등록

      기본 사용법
      agy schedule add \
  --name "<고유 이름>" \
  --cron "<cron 표현식>" \
  --tz "<타임존>" \
  --workdir "<작업 디렉토리>" \
  --prompt "<에이전트 지시문>"
    

      전체 옵션 예시
      agy schedule add \
  --name "weekly-dependency-audit" \
  --cron "0 10 * * 1" \
  --tz "Asia/Seoul" \
  --workdir "$HOME/projects/my-app" \
  --skills "package-security,dependency-update" \
  --mcp "github,filesystem" \
  --timeout 600 \
  --notify "stdout,file:$HOME/logs/dep-audit.log" \
  --prompt "package.json과 requirements.txt의 의존성 보안 취약점을 검사하고 patch 또는 minor 업데이트가 가능한 항목 목록을 ~/audit/$(date +%F).md에 작성. 메이저 업데이트는 별도 표시."
    

3.3 주요 옵션 레퍼런스

agy schedule add 명령 옵션
옵션	필수	설명
`--name`	✅	태스크 고유 이름. 영문·숫자·하이픈만 사용 권장
`--cron`	✅	5필드 cron 표현식 (분 시 일 월 요일)
`--prompt`	✅	에이전트가 받을 자연어 지시. 줄바꿈 가능
`--tz`	선택	IANA 타임존 이름 (기본 `UTC`, 권장 `Asia/Seoul`)
`--workdir`	선택	에이전트의 작업 디렉토리. 미지정 시 홈 디렉토리
`--skills`	선택	활성화할 스킬 목록 (쉼표 구분)
`--mcp`	선택	활성화할 MCP 서버 (쉼표 구분, settings.json에 미리 정의)
`--timeout`	선택	최대 실행 시간 (초). 기본 300초
`--notify`	선택	실행 결과 전달 방식: `stdout`, `file:경로`, `email:주소`, `webhook:url`
`--max-concurrent`	선택	동시 실행 인스턴스 수 제한 (기본 1, 멱등성 보호)

3.4 관리 명령

      자주 쓰는 관리 명령
      # 전체 목록
agy schedule list

# 상세 정보
agy schedule show daily-github-digest

# 임시 비활성화
agy schedule disable daily-github-digest

# 재활성화
agy schedule enable daily-github-digest

# 삭제
agy schedule remove daily-github-digest

# 실행 이력 조회
agy schedule history daily-github-digest --limit 10

# 다음 실행 시간 미리보기 (5회)
agy schedule next daily-github-digest --count 5

# 즉시 강제 실행 (테스트용)
agy schedule run daily-github-digest
    

4. Cron 표현식 가이드 #

Antigravity Scheduled Tasks는 표준 Unix cron 5필드 문법을 사용합니다.

      5필드 구조
      ┌─────────────  분 (0-59)
│ ┌───────────  시 (0-23)
│ │ ┌─────────  일 (1-31)
│ │ │ ┌───────  월 (1-12)
│ │ │ │ ┌─────  요일 (0-6, 0 또는 7 = 일요일)
│ │ │ │ │
* * * * *
    

자주 쓰는 cron 표현식

자주 쓰는 cron 표현식
cron 표현식	의미	실제 사용 예시
`/5 * * *`	5분마다	외부 API 상태 폴링
`0 * * * *`	매시 정각	시간별 헬스 체크
`0 9 * * *`	매일 오전 9시	아침 디지스트
`0 18 * * 5`	매주 금요일 오후 6시	주간 회고 자료 자동 정리
`0 9 * * 1`	매주 월요일 오전 9시	주초 PR 리뷰 백로그 점검
`0 0 1 * *`	매월 1일 자정	월간 누적 통계 집계
`30 10 * * 1-5`	평일 10시 30분	업무일 알림 정리
`0 9,18 * * *`	매일 9시·18시	출근·퇴근 시간 상태 점검

특수 표기법

@hourly — 0 * * * * 와 동일
@daily — 0 0 * * * 와 동일 (자정)
@weekly — 0 0 * * 0 와 동일 (일요일 자정)
@monthly — 0 0 1 * * 와 동일
@yearly — 0 0 1 1 * 와 동일

cron 검증 도구: 표현식이 정확한지 확인할 때 crontab.guru 같은 시각화 도구를 사용하면 안전합니다. 또는 agy schedule next <이름> --count 5로 실제 다음 실행 시각 5개를 미리 확인하세요.

5. 활용 패턴 모음 #

패턴 1: 일일 디지스트

      매일 아침 9시 — PR 리뷰 요청 + 이슈 멘션 정리
      agy schedule add \
  --name "daily-pr-digest" \
  --cron "0 9 * * 1-5" \
  --tz "Asia/Seoul" \
  --mcp "github" \
  --notify "file:$HOME/digest/pr-$(date +%F).md" \
  --prompt "내 GitHub 알림 중 어제 18시 이후 발생한 (a) PR 리뷰 요청 (b) 이슈에서 나를 멘션한 것을 우선순위(P0/P1/P2)별로 정리. 각 항목에 한 줄 요약과 링크."
    

패턴 2: 시간별 헬스 체크

      매시 정각 — 프로덕션 API 상태 점검
      agy schedule add \
  --name "hourly-prod-health" \
  --cron "0 * * * *" \
  --timeout 60 \
  --notify "webhook:https://hooks.slack.com/services/..." \
  --prompt "https://api.myapp.com/health 호출하여 응답 시간·상태 코드 확인. 상태 != 200이면 'PROD-DOWN' 형식으로 Slack에 알림. 정상이면 알림 보내지 말 것."
    

패턴 3: 주간 리포트

      매주 금요일 오후 6시 — 이번 주 작업 요약
      agy schedule add \
  --name "weekly-review" \
  --cron "0 18 * * 5" \
  --tz "Asia/Seoul" \
  --workdir "$HOME/projects/my-app" \
  --prompt "이번 주(지난 월요일~오늘) 내 git 커밋, PR 머지, 리뷰 활동을 카테고리(feature/fix/refactor/docs)별로 집계해 ~/reports/week-$(date +%Y-W%V).md에 작성. 다음 주 우선순위로 가져갈 미완 항목도 별도 섹션."
    

패턴 4: 의존성 보안 감사

      매월 1일 오전 10시 — 의존성 취약점 자동 검사
      agy schedule add \
  --name "monthly-dep-audit" \
  --cron "0 10 1 * *" \
  --tz "Asia/Seoul" \
  --workdir "$HOME/projects/my-app" \
  --skills "package-security" \
  --timeout 1800 \
  --prompt "package.json, requirements.txt, pyproject.toml의 모든 의존성을 npm audit / pip-audit / safety 등 적절한 도구로 검사. CVE 우선순위(critical/high/medium/low)별로 정리하고 patch 가능 버전 명시. 결과를 ~/security/dep-audit-$(date +%Y-%m).md에 저장하고 critical/high 발견 시 이메일 발송."
    

패턴 5: 시계열 데이터 집계

      매일 자정 — 어제의 분석 데이터 집계
      agy schedule add \
  --name "daily-metrics-rollup" \
  --cron "0 0 * * *" \
  --tz "Asia/Seoul" \
  --workdir "$HOME/projects/analytics" \
  --prompt "어제의 raw 이벤트 로그를 일자별 집계 테이블로 변환하여 BigQuery analytics.daily_metrics 테이블에 INSERT. 이미 같은 날짜가 있으면 DELETE 후 재삽입 (멱등성 보장). 처리 행 수와 소요 시간을 ~/logs/rollup-$(date +%F).log에 기록."
    

패턴 6: 외부 데이터 동기화

      10분마다 — 외부 카탈로그 변화 감지
      agy schedule add \
  --name "catalog-sync" \
  --cron "*/10 * * * *" \
  --timeout 120 \
  --max-concurrent 1 \
  --prompt "https://partner.example.com/catalog.json 가져와 로컬 ~/data/catalog.json과 비교. SHA256 해시가 달라지면 새 버전을 ~/data/catalog.json에 덮어쓰고 ~/data/catalog-changelog.md에 변경 요약 한 줄 추가. 동일하면 아무 작업 안 함."
    

6. 멱등성 설계 — 같은 작업이 두 번 실행돼도 안전하게 #

⚠️ 가장 중요한 원칙: Scheduled Tasks는 네트워크 지연, 클라우드 재시도, 시간대 전환 등으로 같은 시각에 두 번 이상 실행될 수 있습니다. 모든 스케줄 태스크는 멱등(idempotent)하게 설계해야 합니다 — "두 번 실행돼도 결과가 같아야" 합니다.

멱등성 위반 사례 (피해야 할 패턴)

위험 패턴 vs 안전 패턴

❌ 위험 — 중복 실행 시 데이터 오염

"sales 테이블에 어제 매출 행을 INSERT" — 두 번 실행되면 매출이 두 배로 기록됨
"카운터를 +1 증가" — 두 번 실행되면 +2
"이메일 발송" — 두 번 실행되면 사용자가 같은 메일 두 통 받음
"파일에 새 줄 추가(append)" — 두 번 실행되면 중복 라인

✅ 안전 — 멱등 보장

"날짜 = 어제 행을 DELETE 후 INSERT (UPSERT)" — 몇 번 실행해도 결과 동일
"카운터를 절대값으로 SET (예: SET counter = 42)" — 두 번 실행해도 42
"이메일 보낸 이력 테이블 체크 후 미발송이면 발송" — 한 번만 발송
"파일 전체를 새 내용으로 OVERWRITE" — 항상 같은 최종 상태

멱등성 보장 4가지 기법

① UPSERT (DELETE then INSERT) — 데이터베이스

      프롬프트 예시
      "어제(YYYY-MM-DD) 매출 집계를 sales_daily 테이블에 저장.
DELETE FROM sales_daily WHERE date = '어제';
INSERT INTO sales_daily VALUES (...);
이 두 명령을 트랜잭션으로 묶어 멱등성 보장."
    

② Lock 파일 / 이력 테이블 검사 — 일회성 작업

      프롬프트 예시
      "~/locks/daily-digest-$(date +%F).lock 파일이 이미 존재하면 즉시 종료.
없으면 파일을 생성하고 작업 수행 후 종료. 다음 날 자정에 모든 lock 파일 자동 삭제."
    

③ 외부 상태 비교 후 변경 시에만 동작

      프롬프트 예시
      "외부 카탈로그의 SHA256 해시를 ~/data/catalog.json의 SHA256과 비교.
다르면 새 버전으로 OVERWRITE + 변경 알림.
같으면 아무 작업 안 함 (no-op)."
    

④ 절대값 SET (증분 ❌)

      프롬프트 예시
      "이번 달 1일부터 오늘까지 누적 매출을 계산해
metrics.monthly_revenue = <계산값> 으로 SET.
'+=' 같은 증분 연산자 절대 사용 금지."
    

실용 팁: 프롬프트 마지막에 "이 작업은 멱등하게 설계되어야 하며, 두 번 실행되어도 데이터·외부 상태가 변하지 않아야 함"이라는 문구를 추가하면 에이전트가 자체적으로 멱등성을 검토하고 위험한 패턴을 회피합니다.

동시 실행 방지 — `--max-concurrent 1`

스케줄 실행 시간이 다음 트리거를 지나가는 경우(예: 30분 소요 작업을 10분 간격으로 실행), 동시 실행이 발생할 수 있습니다. 이를 막으려면:

      동시 실행 1개로 제한
      agy schedule add \
  --name "long-running-job" \
  --cron "*/10 * * * *" \
  --max-concurrent 1 \
  --prompt "..."
    

이전 실행이 끝나지 않았으면 새 트리거는 skip됩니다 (실행 이력에 'skipped'로 기록).

7. 트러블슈팅 #

증상별 진단

스케줄 태스크 트러블슈팅
증상	원인	해결
등록은 됐는데 실행 안 됨	타임존이 UTC라서 한국 시간 9시가 UTC 0시	`--tz "Asia/Seoul"` 명시. `agy schedule next`로 다음 실행 시각 확인
같은 시각에 두 번 실행됨	이전 실행이 끝나기 전 새 트리거 발생	`--max-concurrent 1` 추가 + 멱등성 설계 검토
실행 결과를 못 봄	`--notify` 미설정	`--notify "file:~/logs/<name>.log"` 또는 `email:...`, `webhook:...`
`timeout exceeded` 에러	기본 300초 초과	`--timeout` 늘림. 또는 작업을 작은 단위로 쪼개기
특정 MCP 서버 인식 안 됨	settings.json에 MCP가 등록되지 않았거나 인증 만료	`agy mcp list`로 등록 확인. `agy mcp auth <server>` 재인증
로컬 파일 접근 실패	클라우드 하네스는 로컬 PC 파일 시스템과 분리	파일은 클라우드 워크스페이스에 저장하거나 외부 스토리지(GCS/S3) 사용
한밤중에 미국 시각으로 알림 옴	알림 메시지에 타임존 표기 누락	프롬프트에 "한국 시간 기준으로 표기" 명시
실행 이력에 'skipped' 다수	이전 실행이 너무 길어서 다음 트리거가 매번 skip됨	작업을 분할하거나 cron 주기를 늘림. `--timeout` 적정화

디버깅 도구

      디버깅 명령
      # 최근 10회 실행 이력
agy schedule history daily-github-digest --limit 10

# 특정 실행의 전체 로그
agy schedule logs daily-github-digest --run-id <ID>

# 다음 실행 시각 5회 미리보기
agy schedule next daily-github-digest --count 5

# 즉시 강제 실행 (테스트)
agy schedule run daily-github-digest

# dry-run (실제 실행 없이 명령 검증)
agy schedule run daily-github-digest --dry-run
    

성능 최적화

프롬프트 짧게 — 매 실행마다 토큰 소모. 핵심만 작성하고 컨텍스트는 스킬/Rules로 분리.
모델 선택 — Gemini 3.5 Flash 같은 빠른 모델로 명시 (--model gemini-3.5-flash).
출력 제한 — "마지막 10줄만 출력" 같이 결과 크기 제한.
조건부 실행 — 변화 없으면 no-op (외부 해시 비교 등).

8. 관련 자료 #

Antigravity CLI (agy) — Scheduled Tasks는 CLI로 가장 정밀하게 제어 가능
Agent Manager — Antigravity 2.0의 다중 에이전트·스케줄 통합 UI
Hooks — 매 대화 턴 자동 실행 (사람 개입 있는 자동화)
Workflows — 슬래시 명령 기반 다단계 자동화
MCP — 스케줄에서 외부 서비스 호출 시 필요
Harness Engineering — 보안·권한 정책 설계
crontab.guru — cron 표현식 시각 검증 도구
Antigravity 공식 문서

Scheduled Tasks (스케줄 태스크) Antigravity 2.0 신기능

1. 빠른 시작 — 첫 스케줄 태스크 만들기 #

Step 1 — Antigravity 2.0 또는 CLI 준비

Step 2 — 스케줄 정의

Step 3 — 동작 확인

2. Scheduled Tasks란? — 개념과 동작 원리 #

Scheduled Tasks vs Hooks vs Workflows

왜 필요한가?

3. 단계별 등록 가이드 #

3.1 GUI (Antigravity 2.0 앱)에서 등록

3.2 CLI(`agy schedule`)로 등록

3.3 주요 옵션 레퍼런스

3.4 관리 명령

4. Cron 표현식 가이드 #

자주 쓰는 cron 표현식

특수 표기법

5. 활용 패턴 모음 #

패턴 1: 일일 디지스트

패턴 2: 시간별 헬스 체크

패턴 3: 주간 리포트

패턴 4: 의존성 보안 감사

패턴 5: 시계열 데이터 집계

패턴 6: 외부 데이터 동기화

6. 멱등성 설계 — 같은 작업이 두 번 실행돼도 안전하게 #

멱등성 위반 사례 (피해야 할 패턴)

멱등성 보장 4가지 기법

① UPSERT (DELETE then INSERT) — 데이터베이스

② Lock 파일 / 이력 테이블 검사 — 일회성 작업

③ 외부 상태 비교 후 변경 시에만 동작

④ 절대값 SET (증분 ❌)

동시 실행 방지 — `--max-concurrent 1`

7. 트러블슈팅 #

증상별 진단

디버깅 도구

성능 최적화

관련 공식 문서

Scheduled Tasks (스케줄 태스크) Antigravity 2.0 신기능

1. 빠른 시작 — 첫 스케줄 태스크 만들기 #

Step 1 — Antigravity 2.0 또는 CLI 준비

Step 2 — 스케줄 정의

Step 3 — 동작 확인

2. Scheduled Tasks란? — 개념과 동작 원리 #

Scheduled Tasks vs Hooks vs Workflows

왜 필요한가?

3. 단계별 등록 가이드 #

3.1 GUI (Antigravity 2.0 앱)에서 등록

3.2 CLI(agy schedule)로 등록

3.3 주요 옵션 레퍼런스

3.4 관리 명령

4. Cron 표현식 가이드 #

자주 쓰는 cron 표현식

특수 표기법

5. 활용 패턴 모음 #

패턴 1: 일일 디지스트

패턴 2: 시간별 헬스 체크

패턴 3: 주간 리포트

패턴 4: 의존성 보안 감사

패턴 5: 시계열 데이터 집계

패턴 6: 외부 데이터 동기화

6. 멱등성 설계 — 같은 작업이 두 번 실행돼도 안전하게 #

멱등성 위반 사례 (피해야 할 패턴)

멱등성 보장 4가지 기법

① UPSERT (DELETE then INSERT) — 데이터베이스

② Lock 파일 / 이력 테이블 검사 — 일회성 작업

③ 외부 상태 비교 후 변경 시에만 동작

④ 절대값 SET (증분 ❌)

동시 실행 방지 — --max-concurrent 1

7. 트러블슈팅 #

증상별 진단

디버깅 도구

성능 최적화

8. 관련 자료 #

관련 공식 문서

3.2 CLI(`agy schedule`)로 등록

동시 실행 방지 — `--max-concurrent 1`