시스템 프롬프트보다 기술: Antigravity SDK를 활용한 Anki 튜터 만들기

AI는 저를 조금 게으르게 만들었습니다.

극단적으로 게으른 것은 아닙니다. "로봇이 모든 것을 다 할 거야" 식의 게으름도 아닙니다. 그보다는, 에이전트(Agent)에게 지루한 일을 시키는 것에 익숙해지면, 모든 작은 수동 워크플로우(Manual workflow)가 의심스럽게 보이기 시작한다는 것에 가깝습니다.

Anki가 완벽한 예시입니다.

Anki는 훌륭합니다. 저는 공부하는 내용, 작업 중인 주제, 그리고 코드베이스(Codebases) 안에 숨겨진 기묘하고 작은 결정 사항들을 기억하기 위해 Anki를 사용합니다. 간격 반복(Spaced repetition)은 효과적입니다. 문제는 Anki가 아닙니다.

문제는 바로 저입니다.

이미 부패가 시작되는 것이 보입니다. 복잡한 카드들을 볼 때, 제 뇌는 스스로와 협상을 하기 시작합니다. "그래, 기본적으로 이건 알고 있었어." "거의 맞았어." "문맥 속에서라면 기억했을 거야." 그러고는 'Good'을 누르고 넘어가 버립니다.

그것은 공부가 아닙니다. 그것은 스스로 인증한 '느낌(Vibes)'일 뿐입니다.

제가 실제로 원했던 것은 제 실제 Anki 컬렉션 위에 앉아 있는 학습 파트너(Study buddy)였습니다. 카드에 질문을 던지고, 제 답변을 기다리고, 실제 정답을 공개하고, 정직하게 비교하며, 차이점을 설명한 뒤에야 비로소 이것이 'Again', 'Hard', 'Good', 또는 'Easy'인지 결정하도록 도와주는 존재 말입니다.

AI는 그런 용도로 짜증 날 정도로 뛰어납니다.

새로운 프로젝트를 맡을 때도 유용합니다. 저장소(Repo)에 들어갔을 때, 저는 단순히 요약본만을 원하는 것이 아닙니다. 나중에 주요 결정 사항, 아키텍처(Architecture), 주의 사항(Gotchas), 그리고 "왜 이렇게 되어 있는가?"와 같은 부분들에 대해 퀴즈를 받고 싶습니다. Anki는 그런 용도로도 훌륭합니다.

하지만 저는 여전히 게으릅니다.

저는 모든 카드를 수동으로 작성하지 않을 것입니다. 모든 덱(Deck)을 일일이 손으로 업데이트하지도 않을 것입니다. 그리고 휴대폰으로 공부할 때, 에이전트가 채점해 줄 수 있도록 채팅창에 긴 답변을 직접 타이핑하지는 않을 것입니다. 음성(Voice) 기능도 작동해야 합니다.

그래서 이 프로젝트는 빠르게 "Gemini를 Anki에 연결하기"에서 벗어났습니다.

그것은 하나의 작은 에이전트 시스템(Agent system)이 되었습니다:

• 집중적인 복습 세션을 위한 터미널(Terminal) 튜터
• 음성 답변을 포함하여 휴대폰으로 공부할 수 있는 Telegram 튜터
• 웹 조사나 로컬 코드베이스로부터 카드를 생성하는 덱 빌더(Deck builder)
• 코드 변경을 감지하고 작업하는 동안 카드를 생성할 수 있는 워치 모드(Watch mode)

이것은 매우 많은 동작(Behavior)을 포함합니다.

저의 첫 번째 본능은 평소와 같았습니다. 더 큰 시스템 프롬프트 (System Prompt)를 작성하는 것이었죠. 에이전트 (Agent)에게 학습 세션을 어떻게 진행할지 알려줍니다. 좋은 플래시카드 (Flashcards)를 어떻게 작성할지 알려줍니다. 코드베이스 (Codebase)를 어떻게 조사하고 아키텍처 (Architecture)를 카드로 변환할지 알려줍니다. Telegram에서 어떻게 다르게 행동할지 알려줍니다. 제가 승인할 때까지 스케줄링 (Scheduling)을 건드리지 말라고 알려줍니다.

이 방법은 약 10분 정도만 작동합니다.

그러면 시스템 프롬프트는 잡동사니 서랍이 되어버립니다.

어려운 점은 에이전트에게 도구 (Tools)를 주지 않는 것이 아니었습니다.

어려운 점은 에이전트에게 습관 (Habits)을 주는 것이었습니다.

그 지점에서 Google Antigravity SDK가 정말 잘 들어맞았습니다. 이 SDK는 에이전트 런타임 (Agent Runtime)을 Python 라이브러리로 제공합니다. 커스텀 도구 (Custom tools), 재사용 가능한 기술 (Reusable skills), 라이프사이클 훅 (Lifecycle hooks), 안전 정책 (Safety policies), 스트리밍 (Streaming), 트리거 (Triggers), 그리고 서로 다른 인터페이스 (Surfaces)에서 동일한 에이전트 로직을 실행할 수 있는 다양한 방법들을 제공합니다.

Antigravity SDK가 제공하는 것

Antigravity SDK는 단순히 채팅 모델 (Chat model)을 감싸는 래퍼 (Wrapper)가 아닙니다.

이것은 Google Antigravity 2.0과 Antigravity CLI 뒤에 있는 것과 동일한 에이전트 런타임에 대한 프로그래밍 방식의 접근 권한을 Python을 통해 제공합니다.

이것이 중요한 이유는 실제 에이전트가 단순히 모델 호출 (Model call)만으로 이루어지지 않기 때문입니다. 실제 에이전트에게는 다음과 같은 것들이 필요합니다:

• 도구 (Tools)
• 턴 간의 메모리 (Memory across turns)
• 권한 (Permissions)
• 훅 (Hooks)
• 기술 (Skills)
• 스트리밍 (Streaming)
• 트리거 (Triggers)
• 부작용 (Side effects)에 대한 안전 장치

SDK는 이 모든 것을 하나의 주요 추상화 (Abstraction)인 Agent 뒤에 배치합니다.

가장 작고 유용한 버전은 정말 미미한 수준입니다:

import asyncio
from google.antigravity import Agent, LocalAgentConfig

...

다음 명령어로 설치하세요:

pip install google-antigravity

그 다음 Google AI Studio에서 Gemini API 키를 설정하세요:

export GEMINI_API_KEY="your-key-here"

이것이 헬로 월드 (Hello world)입니다.

유용한 버전은 실제 워크플로 (Workflow)를 중심으로 런타임 기능들을 구성할 때 시작됩니다.

이 프로젝트에서 Antigravity SDK의 구성 요소들은 다음과 같이 매핑되었습니다:

Antigravity SDK 기능	사용 사례
Agent / LocalAgentConfig	터미널 튜터, Telegram 튜터, 덱 빌더가 모두 동일한 에이전트 런타임 (agent runtime)에서 실행됨
...

이 목록이 바로 이 프로젝트가 모델 호출 주변에 거대한 프롬프트를 두는 방식보다 SDK 프로젝트로서 더 잘 작동했던 이유입니다.

이제, 첫 번째 유용한 단계: 에이전트에게 '손'을 부여합니다.

에이전트에게 손을 부여하기: Python 도구로서의 Anki

Anki는 이미 AnkiConnect 애드온을 통해 HTTP API를 가지고 있습니다. 전체 브릿지(bridge)는 기본적으로 localhost:8765로 보내는 하나의 POST 요청과 같습니다.

def invoke(action: str, **params):
    response = requests.post(
        "http://localhost:8765",
...

그 지점부터 에이전트 도구(agent tools)는 그저 일반적인 Python 함수일 뿐입니다.

단순화된 버전:

def list_decks() -> str:
    """복습 예정 개수와 함께 모든 Anki 덱을 나열합니다."""
    decks = invoke("deckNames")
...

그런 다음 SDK에 이들을 등록합니다:

from google.antigravity import LocalAgentConfig

config = LocalAgentConfig(
...

이것이 SDK의 가장 멋진 부분 중 하나입니다. 커스텀 도구 (custom tools)를 위해 별도의 서버가 필요하지 않습니다. 이번 버전에서는 MCP, 프레임워크, 스키마 생성기(schema generator), 또는 두 번째 프로세스가 필요하지 않았습니다.

에이전트는 일반 Python을 호출할 수 있습니다.

실제 프로젝트에서 저는 더 많은 도구를 갖게 되었습니다:

• list_decks
• get_due_cards
• show_answer
• rate_card
• find_notes
• add_note
• add_notes
• update_note
• suspend_card
• unsuspend_card
• undo
• get_stats
• sync

이것만으로도 튜터를 유용하게 만들기에는 충분했습니다.

이것이 첫 번째 패턴입니다:

기능을 도구(tools)에 담으세요.

도구는 에이전트의 손입니다. 하지만 손이 곧 행동(behavior)은 아닙니다.

행동을 위해, 저는 기술(skills)을 사용했습니다.

거대한 시스템 프롬프트의 문제점

처음에는 에이전트의 시스템 지침 (system instructions)에 모든 것을 설명하려고 시도했습니다.

튜터는 복습 세션을 어떻게 진행해야 하는지 알아야 합니다:

1. 질문을 보여준다
2. 내 답변을 기다린다
3. 정답을 공개한다
4. 내 답변과 비교한다
5. 평가를 제안한다
6. 확인을 기다린다
7. 그제서야 Anki 스케줄링을 업데이트한다

또한 좋은 카드를 작성하는 방법도 알아야 합니다:

• 카드당 하나의 사실 (one fact per card)
• 정답이 먼저 나오는 뒷면 (answer-first backs)
• 불필요한 잡학 지식 배제 (no trivia padding)
• 모호한 질문 금지 (no vague questions)
• 거대한 에세이형 카드 금지 (no giant essay cards)

그다음 덱 빌더 (deck builder)에는 또 다른 워크플로우 (workflow)가 필요합니다:

• 주제 조사
• 중요한 사실 추출
• 카드 생성
• Anki에 존재하는지 확인

그다음 코드베이스 덱 빌더 (codebase deck builder)에는 다른 워크플로우가 필요합니다:

• 저장소 (repo)를 너비 우선 (breadth-first)으로 조사
• 핵심 추상화 (abstractions) 찾기
• 책임과 데이터 흐름 (data flow) 설명
• 무작위 구문 (syntax)에 대한 카드 생성 방지

그다음 Telegram은 더 짧은 답변을 보내야 합니다. 휴대폰에서 Markdown 벽을 보고 싶어 하는 사람은 아무도 없기 때문입니다.

이 모든 것을 하나의 시스템 프롬프트 (system prompt)에 넣을 수 있습니다.

하지만 그렇게 해서는 안 됩니다.

거대한 시스템 프롬프트에는 세 가지 문제가 있습니다:

1. 모든 작업을 오염시킵니다. 당신이 스페인어 동사를 검토하고 있는 동안 에이전트 (agent)는 코드베이스 탐색을 생각하고 있습니다.
2. 재사용하기 어렵습니다. 동일한 카드 작성 규칙이 터미널 튜터, Telegram 튜터, 그리고 덱 빌더 모두에 나타나야 합니다.
3. 부패합니다. 새로운 동작이 생길 때마다 아무도 어떤 규칙이 무엇을 제어하는지 모를 때까지 동일한 덩어리에 계속 붙여넣게 됩니다.

이것이 바로 스킬 (skills)이 해결하는 문제입니다.

구조가 다음과 같이 변했습니다:

system prompt = 튜터 규칙
              + 카드 작성 규칙
              + 코드베이스 탐색 규칙
...

다음과 같이 변했습니다:

system prompt  = 정체성 + 엄격한 안전 가이드라인 (hard safety floor)
review-buddy   = 학습 세션 동작
plain-cards    = 카드 작성 동작
...

이것이 제목 뒤에 숨겨진 진짜 패턴입니다.

"프롬프트를 더 좋게 만드세요"가 아닙니다.

프롬프트를 더 작게 만드세요.

시스템 프롬프트보다 스킬 (Skills over System Prompts)

스킬 (skill)은 내부에 SKILL.md 파일이 들어 있는 폴더입니다.

제 프로젝트에는 세 개가 있습니다:

.agents/skills/
  plain-cards/
    SKILL.md
...

각 스킬은 아주 작은 양의 프런트매터 (frontmatter)로 시작합니다.

예를 들어, 리뷰 (review) 스킬은 다음과 같이 시작합니다:

---
name: review-buddy
description: 대화형 Anki 리뷰 세션을 실행하기 위한 플레이북 (Playbook) — 한 번에 카드 하나씩 퀴즈를 내고, 함께 회상 (recall) 정도를 채점하며, 등급을 제출하고, 노이즈가 있거나 깨진 카드를 수정합니다.
...

해당 description은 단순히 사람을 위한 문서가 아닙니다. 이는 경량화된 탐색 계층 (discovery layer)입니다. 에이전트는 어떤 기술 (skills)이 존재하는지 확인할 수 있으며, 작업이 필요할 때만 전체 지침 (instructions)을 로드할 수 있습니다.

기술 (skill)은 서비스가 아닙니다. MCP 서버도 아닙니다. 배포 (deployment)도 아닙니다. 그것은 디스크에 위치하여 필요할 때 에이전트로 불러올 준비가 되어 있는 행동 패키지 (behavior package)입니다.

그다음 SDK는 기술 디렉토리를 로드합니다:

config = LocalAgentConfig(
    system_instructions=SYSTEM_INSTRUCTIONS,
    tools=ALL_TOOLS,
...

핵심 아이디어는 간단합니다:

시스템 프롬프트 (system prompt)는 에이전트가 누구인지를 말해줍니다. 기술 (skills)은 에이전트가 현재 어떤 일을 하고 있는지를 말해줍니다.

이 프로젝트에서 시스템 프롬프트는 작게 유지됩니다. 에이전트가 실제 Anki 컬렉션과 함께 작업하는 친절한 플래시카드 튜터라고 명시할 뿐입니다.

세부 사항은 기술 (skills)에 담겨 있습니다.

review-buddy: 학습 세션 플레이북 (playbook)

이 기술은 복습 세션을 어떻게 운영할지를 설명합니다.

다음과 같은 리듬을 다룹니다:

• 한 번에 카드 하나씩 질문하기
• 사용자가 시도할 때까지 정답 숨기기
• 정답을 공개하고 짧게 설명하기
• 등급 (rating) 제안하기
• 확인 대기하기
• 노이즈가 있거나 깨진 카드 처리하기
• 요약과 함께 종료하기

이것은 코드가 아닙니다. 행동 프로토콜 (behavioral protocol)입니다.

이 차이는 중요합니다. 복습 흐름은 터미널 I/O, Telegram 메시지, 또는 AnkiConnect에 종속되지 않습니다. 그것은 단지 좋은 튜터가 어떻게 행동해야 하는지에 대한 방식일 뿐입니다.

plain-cards: 카드 작성 스타일 가이드

이 기술은 카드의 품질을 관리합니다.

에이전트에게 다음과 같은 카드를 작성하도록 지시합니다:

• 원자적 (atomic)인
• 정답 우선 (answer-first) 방식의
• 간결한 (lean)
• 검증된 (verified)
• 불필요한 내용이 없는 (free of filler)
• 몇 달 뒤에도 복습하기 쉬운

잘못된 플래시카드는 카드가 없는 것보다 나쁩니다. 그것은 가짜 진전 (fake progress)을 만들어냅니다. 모델은 몇 초 만에 10개의 카드를 생성할 수 있지만, 스타일 가이드가 없다면 미래의 내가 싫어할 모호한 카드 10개를 기꺼이 생성해낼 것입니다.

그래서 카드 작성이 하나의 기술 (skill)이 되었습니다.

codebase-cards: 리포지토리 탐색 프로토콜

이 기술은 소스 코드를 Anki 카드로 변환하기 위한 것입니다.

에이전트는 저장소(repo)를 너비 우선 탐색(breadth-first) 방식으로 조사하고, 아키텍처, 데이터 흐름(data flow), 책임(responsibilities), 그리고 주의사항(gotchas)을 식별한 다음, 유용한 발견 사항만을 카드로 변환하도록 지시받습니다.

이 기술은 덱 빌더(deck builder)의 코드 모드(code mode)를 구동합니다:

python deck_builder.py "overall architecture" --path ~/my/project --count 6

포커스 힌트(focus hint)는 바뀌지만, 탐색 프로토콜(exploration protocol)은 동일하게 유지됩니다.

이것이 두 번째 패턴입니다:

재사용 가능한 동작을 스킬(skills)에 담으세요.

시스템 프롬프트(system prompt)에 넣지 마세요. 엔트리포인트(entrypoints)마다 중복시키지 마세요. 파이썬 조건문(Python conditionals) 속에 묻어두지 마세요.

스킬은 단지 하나의 파일일 뿐이지만, 프로젝트 전체의 형태를 변화시킵니다.

하나의 동작 계층, 세 가지 인터페이스

동작이 스킬에 거주하게 되면서, 새로운 인터페이스(surfaces)를 추가하는 것이 훨씬 쉬워졌습니다.

아키텍처는 다음과 같았습니다:

                         .agents/skills/
                  ┌──────────┼──────────┐
                  │          │          │
...

터미널 튜터(terminal tutor)는 가장 단순한 인터페이스입니다:

async with Agent(config) as agent:
    await run_interactive_loop(agent)

텔레그램(Telegram) 튜터는 동일한 에이전트를 다르게 사용합니다:

async def chat_response(agent: Agent, prompt: str) -> str:
    response = await agent.chat(prompt)
    return "".join([token async for token in response])

덱 빌더(deck builder)는 작업하는 동안 출력을 스트리밍(stream)합니다:

response = await agent.chat(message)
async for token in response:
    print(token, end="", flush=True)

서로 다른 인터페이스. 동일한 런타임(runtime). 동일한 스킬.

이것이 제가 가장 좋아했던 부분입니다. 텔레그램은 복사된 리뷰 프롬프트(review prompt)가 필요하지 않았습니다. 덱 빌더는 자체적인 카드 작성 선언문(card-writing manifesto)이 필요하지 않았습니다. 코드베이스 모드(codebase mode)는 별도의 앱 전용 교리(app-specific doctrine)가 필요하지 않았습니다.

그들은 모두 동일한 스킬 디렉터리(skill directory)를 로드했습니다.

터미널 튜터

터미널 버전은 기준점(baseline)입니다.

Anki를 시작하고, 튜터를 실행한 뒤, 자연스럽게 질문하세요:

python tutor.py

그다음:

XYZ에 대해 퀴즈를 내줘

튜터는 복습할 카드를 나열하고, 질문을 하나 던진 뒤, 제 답변을 기다리고, 실제 Anki 정답을 공개하며, 답변을 비교하고, 가르침을 준 뒤, 평가를 제안합니다.

중요한 점은, 모델이 제가 정답을 맞혔다고 생각한다는 이유만으로 스케줄링 (scheduling)을 업데이트하지 않는다는 것입니다.

이 복습 루프는 설계 단계부터 인간 참여형 (human-in-the-loop) 방식입니다:

Agent: 이 답변은 'Good (3)'으로 평가하겠습니다. 핵심 개념은 파악했지만 날짜를 놓치셨네요.
User: 맞아요
Agent: 3점으로 평가되었습니다. 다음 카드로 넘어갑니다...

또는 제가 직접 수정할 수도 있습니다:

Agent: 이 답변은 'Hard (2)'로 평가하겠습니다.
User: 사실 1점이에요
Agent: 'Again (1)'으로 평가되었습니다. 다시 학습해 봅시다.