AI 가이드

세션이 지나는 시간

1. 도구와 설정을 갖출 때

   팁 1

   • 오래 가는 지침은 AGENTS.md에 두고 system_instruction에는 호출마다 바뀌는 것만 적는다.

     둘은 더해져서 함께 적용되므로 같은 내용을 양쪽에 적으면 매 호출마다 두 벌이 들어간다. 페르소나·긴 가이드라인은 코드와 함께 버전 관리되는 AGENTS.md로 내리고, 호출별 조정만 인라인으로 넘긴다. Gemini API — Building managed agents

2. 모델과 추론 강도를 고를 때

   팁 2

   • 출력이 긴 작업에서는 모델에게 덜 생각하라고 명시한다.

     긴 글을 뽑는 일은 사고 토큰이 아니라 출력 토큰이 일한다. 사고를 줄이라고 적어 두면 같은 결과에 토큰이 덜 든다. max_output_tokens를 조이는 것으로 대신하면 사고와 출력이 함께 잘려 답이 끊긴다. Gemini API — Thinking

   • Gemini 3으로 옮길 때는 chain-of-thought 프롬프트를 걷어내고 thinking_level: "high"로 대신한다.

     2.5에서 추론을 끌어내려고 붙여 둔 단계별 지시 문단이 3에서는 중복이다. 프롬프트를 단순하게 줄이면 매 호출의 입력이 그만큼 줄고 모델이 헤매지도 않는다. Gemini API — Gemini 3 developer guide

3. 자료를 넣거나 일을 나눌 때

   팁 4

   • 크고 여러 요청에 공통인 내용은 프롬프트 맨 앞에 몰아 둔다.

     암묵 캐싱은 접두사가 같을 때 걸린다. 공통 자료를 뒤에 두거나 요청마다 순서를 바꾸면 접두사가 깨져 캐시가 안 붙는다. 캐싱에는 모델마다 정한 최소 입력 토큰 수가 있어, 그보다 짧은 요청은 캐시가 안 걸린다. Gemini API — Context caching

   • 같은 자료를 두고 물을 것이 여럿이면 짧은 시간 안에 몰아서 보낸다.

     캐시는 시간이 지나면 식는다. 같은 접두사를 쓰는 질문을 하루에 흩어 보내면 매번 전액을 내고, 붙여서 보내면 뒤의 요청들이 캐시 적중으로 깎인다. Gemini API — Context caching

   • 컨텍스트가 길면 질문은 자료 앞이 아니라 맨 뒤에 붙인다.

     긴 컨텍스트에서 질문을 앞에 두면 답 품질이 떨어져 되묻게 되고, 되묻는 한 번이 그 긴 컨텍스트를 통째로 다시 태운다. 캐시 접두사 규칙과도 같은 방향이다 — 공통 자료가 앞, 그날의 질문이 뒤다. Gemini API — Long context

   • PDF·영상으로 컨텍스트 창이 넘치면 media_resolution을 명시적으로 낮춘다.

     Gemini 3은 기본 해상도가 올라가 같은 PDF가 2.5보다 토큰을 더 먹을 수 있다. Gemini API — Gemini 3 developer guide

4. 대화가 길어지거나 일이 바뀔 때

   팁 1

   • 작업 파일은 살리고 대화만 비울 때는 previous_interaction_id를 빼고 environment만 넘긴다.

     대화 컨텍스트와 샌드박스 상태는 서로 다른 축이다. 컨텍스트가 지저분해졌다고 통째로 새로 시작하면 설치한 패키지와 만든 파일까지 날아가 다시 만드는 토큰이 든다. Gemini API — Managed Agents Quickstart

고치는 값이 커지는 순서

1. 같은 말을 되풀이하게 될 때

   팁 1

   • 지침을 스킬로 묶을 때는 SKILL.md의 description에 무엇을 하는지와 언제 쓰는지를 구체적으로 적는다.

     에이전트는 대화가 열릴 때 스킬의 이름과 설명만 보고, 관련 있어 보일 때에야 SKILL.md 본문을 읽는다. 그 스킬을 쓸지는 설명으로 정해진다. Antigravity Docs — Agent Skills

2. 결과가 어긋났을 때

   팁 2

   • 계획이 어긋나면 프롬프트를 새로 쓰지 말고 구현 계획 아티팩트에 코멘트를 달아 고치게 한다.

     새 프롬프트로 다시 설명하면 어디가 틀렸는지를 모델이 다시 추측해야 한다. 코멘트는 그 줄에 붙어 있어 범위를 줄이라는 말인지 스택을 바꾸라는 말인지가 자리로 드러나고, 파일이 하나도 안 바뀐 때에 붙는다. Antigravity Docs — Implementation Plan

   • 안정된 지점에서 /fork로 갈라 다른 설계를 시험하고, 실패하면 /resume으로 원래 대화에 돌아온다.

     진행해 둔 것을 잃지 않고 다른 설계를 시험할 수 있다. 다만 복제되는 것은 대화뿐이고 작업 디렉터리는 그대로라, 파일까지 가르려면 git 브랜치나 stash를 따로 잡아야 한다. Antigravity Docs — Managing conversations

3. 완료를 확인하게 할 때

   팁 1

   • 코드를 고치라고 시킬 때 돌려 볼 테스트·빌드 명령을 같은 프롬프트에 함께 적는다(테스트가 없으면 테스트부터 쓰게 한다).

     믿을 만하고 맞는 수정을 받는 가장 효과적인 방법이 에이전트에게 로컬 확인 수단을 주는 것이다. 명령이 있으면 에이전트가 제 결과를 돌려 보고 테스트 출력을 읽어 스스로 고치기를 되풀이한다. Antigravity Docs — CLI Best Practices