덕삼
블로그

agy 실전 가이드 1편 — 설치와 지침 파일(AGENTS.md·rules)

agy 실전 가이드 1편입니다. agy 는 Google Antigravity 의 터미널 클라이언트입니다. 이 연재는 같은 사이트의 「Claude Code 실전 가이드」 5부작과 짝을 이룹니다. 독자가 Claude Code 를 써 봤다고 보고, agy 에서 다르게 움직이는 지점을 중심으로 씁니다. 버전은 2026-11-18 기준 1.5.10 입니다.

이번 편의 질문은 agy 는 어떤 지침 파일을 실제로 읽는가입니다. 답부터 적습니다. 저장소 루트의 AGENTS.md 는 그대로 읽고, 전역 지침은 ~/.gemini/config/rules/ 에서 읽습니다. 다만 경로가 Gemini CLI 시절 파일과 섞여 있습니다. 파일 패턴으로 켜지는 규칙은 버전에 따라 동작하지 않았습니다. 그래서 꼭 지켜야 할 지침은 항상 읽히는 자리에 둡니다.

설치는 한 줄이고, 버전은 스스로 바뀝니다

공식 문서 기준 설치 명령은 다음과 같습니다(macOS·Linux).

curl -fsSL https://antigravity.google/cli/install.sh | bash
~/.local/bin/agy --version   # 1.5.10 (2026-11-18)

실행 파일은 ~/.local/bin/agy 에 놓입니다. 제 맥에서는 225MB 짜리 단일 바이너리였습니다.

agy 는 스스로 업데이트합니다. 버전을 고정하는 방법은 찾지 못했습니다. 2026-11-04 에는 측정하는 도중에 1.4.12 가 1.5.0 으로 바뀌었습니다. agy changelog 로 세어 보았습니다. 1.2.16(2026-10-04 측정) 다음부터 1.5.10(2026-11-18)까지 32개 버전이 나왔습니다. 45일에 32번입니다. 그래서 이 연재의 동작과 수치에는 측정한 버전과 날짜를 붙입니다. 여러분의 agy 는 이미 다른 버전일 수 있습니다.

첫 세션 전에 agy models 를 한 번 돌려 보길 권합니다. 제 계정에서는 18개 모델이 나왔습니다. Gemini 4 와 Gemini 3.8 Flash 계열이 중심입니다. Claude Opus 5.5·Sonnet 5.5 와 GPT-OSS 120B 도 있었습니다. 확인한 계정은 제 것 하나라, 다른 요금제에서는 목록이 다를 수 있습니다.

~/.gemini 폴더에는 세 가지가 섞여 있습니다

agy 는 Gemini CLI 의 뒤를 잇는 도구라 설정 폴더 ~/.gemini 를 함께 씁니다. 처음 열어 보면 비슷한 이름이 여럿이라 헷갈립니다. 제 맥의 폴더를 역할별로 나누면 다음과 같습니다.

경로쓰는 쪽들어 있는 것
~/.gemini/settings.json옛 Gemini CLI예전에 등록한 MCP 서버 4개. agy mcp list 에는 나오지 않습니다
~/.gemini/config/agy 사용자 정의rules/, skills/, plugins/, hooks.json, mcp_config.json
~/.gemini/antigravity-cli/agy CLI 자체settings.json(모델·권한 규칙), 대화 기록, 로그

흔한 실수는 옛 settings.json 을 고치고 agy 에 반영되길 기다리는 것입니다. 공식 이전 안내도 전역 MCP 설정이 ~/.gemini/config/mcp_config.json 으로 옮겨졌다고 적습니다. CLI 설정은 antigravity-cli/settings.json, 지침·스킬·훅은 config/ 아래라고 기억하면 됩니다.

AGENTS.md 하나로 세 에이전트를 묶습니다

agy 는 저장소 루트의 AGENTS.md 와 GEMINI.md 를 둘 다 읽습니다. 공식 문서는 .agents/AGENTS.md 와 .agents/rules/*.md 도 워크스페이스 규칙으로 꼽습니다. AGENTS.md 에는 머리말(frontmatter)이 없고, 내용 전체가 늘 켜진 규칙으로 들어갑니다.

로드 여부는 직접 쟀습니다. 빈 git 폴더의 AGENTS.md 에 암호어 하나를 적었습니다. 그리고 도구를 쓰지 말라고 한 뒤 암호어를 물었습니다. 2026-10-04 에 1.2.16 을 비대화형(headless)으로 실행하니 정답을 말했습니다. 파일을 두지 않은 대조군에서는 모른다고 답했습니다. 1.4.2 와 1.5.0 에서도 결과가 같았습니다. 그보다 앞선 1.1.17·1.2.7 의 비대화형 실행은 두 파일을 모두 읽지 못했습니다. 원인은 밝히지 못했습니다.

그래서 저는 저장소마다 AGENTS.md 하나만 둡니다. Claude Code·Codex·agy 가 같은 파일을 읽습니다. 함정은 Claude Code 쪽에 있습니다. Claude Code 는 CLAUDE.md 가 있으면 AGENTS.md 를 읽지 않습니다. 두 파일을 합치지 않고 하나만 고릅니다. CLAUDE.md 를 꼭 둬야 하면 첫 줄에 @AGENTS.md 를 넣어 가져옵니다.

규칙 파일은 트리거 네 가지로 켜집니다

AGENTS.md 가 저장소 전체 지침이라면 .agents/rules/*.md 는 쪼갠 규칙입니다. 이 파일들은 머리말에 trigger 를 반드시 적어야 합니다. 공식 문서 기준으로 값은 네 가지입니다.

trigger켜지는 때
always_on매 턴 시스템 프롬프트에 전문이 들어갑니다
model_decision경로와 description 만 먼저 넣고, 모델이 필요할 때 읽습니다
globglobs 패턴에 맞는 파일을 다룰 때 켜집니다
manual자동으로는 켜지지 않습니다

머리말이 틀리면 그 규칙은 조용히 버려집니다. 화면에 오류가 나오지 않습니다. 새 규칙을 넣었으면 한 번은 실제로 읽히는지 물어봅니다.

전역 규칙은 ~/.gemini/config/rules/*.md 나 ~/.gemini/AGENTS.md 에 둡니다. 제 전역 지침은 rules/global.md 한 파일이고 10,956바이트입니다. 크기 제한도 있습니다. 공식 문서는 규칙 파일 하나가 24,000바이트를 넘으면 뒤를 잘라 낸다고 적습니다. 전역 규칙과 always_on 규칙은 합쳐서 20,000토큰 예산을 나눠 씁니다. 예산을 넘으면 큰 파일부터 본문 대신 경로만 남긴다고 합니다.

파일 패턴 규칙은 믿지 않습니다

trigger: glob 은 Claude Code 의 paths: 규칙과 같은 역할입니다. 그런데 실측에서 함정이 셋 나왔습니다.

첫째, 패턴 여러 개를 쉼표로 이을 때 공백을 넣으면 안 됩니다. 공식 문서 예시는 "*.py, *_test.py" 처럼 쉼표 뒤에 공백이 있습니다. 1.2.16 에서 이렇게 쓰면 두 번째 패턴이 맞지 않았습니다. "*.py,*_test.py" 로 붙여 써야 했습니다.

둘째, 슬래시가 든 패턴은 앞에 **/ 를 붙여야 했습니다. sub2/** 는 맞지 않았고 **/sub2/** 는 맞았습니다.

셋째, 1.5.0(2026-11-04)에서는 glob 규칙이 아예 켜지지 않았습니다. 맞는 파일을 읽게 한 뒤에도 규칙에 적은 암호어를 답하지 못했습니다. 다섯 번 시도해 다섯 번 모두 그랬습니다. 같은 조건의 always_on 규칙은 정답이었습니다. changelog 에는 이 변화가 적혀 있지 않고, 1.5.10 에서 고쳐졌는지는 아직 확인하지 못했습니다.

그래서 제 기준은 단순합니다. 어기면 사고가 나는 규칙은 AGENTS.md 나 always_on 에 둡니다. glob 규칙에는 놓쳐도 괜찮은 스타일 안내만 둡니다.

하위 폴더의 AGENTS.md 는 읽히지 않습니다

모노레포라면 하위 폴더마다 AGENTS.md 를 두고 싶어집니다. agy 는 이 파일을 읽지 않습니다. 공식 문서도 같은 내용을 적습니다. 에이전트가 하위 폴더 파일을 읽거나 고쳐도 그 폴더의 규칙은 로드하지 않습니다. 실측도 같았습니다. 실행한 폴더 기준으로만 읽었고, 하위 폴더 파일을 고친 다음 턴에도 읽지 않았습니다. 하위 폴더 지침이 필요하면 그 폴더에서 agy 를 실행하거나 루트 AGENTS.md 의 한 절로 옮깁니다.

Claude Code 와 다른 점

항목Claude Codeagy
기본 지침 파일CLAUDE.md (없을 때만 AGENTS.md)AGENTS.md·GEMINI.md 둘 다
쪼갠 규칙.claude/rules/*.md, paths:.agents/rules/*.md, trigger 필수
전역 지침~/.claude/CLAUDE.md~/.gemini/config/rules/*.md, ~/.gemini/AGENTS.md
설정 폴더~/.claude/ 하나~/.gemini/ 안에 Gemini CLI 와 agy 가 함께

가장 큰 차이는 지침 파일 이름입니다. Claude Code 에서 CLAUDE.md 에 적던 내용을 agy 에 주려고 GEMINI.md 를 따로 만들 필요는 없습니다. AGENTS.md 하나에 쓰고, Claude Code 쪽에서 그 파일을 가져오게 하는 편이 관리할 파일이 적습니다.

실사례 — “확인하라"는 건너뛰고 “반드시 확인하라"는 지켰습니다

제 에이전트 설정 저장소에는 사람마다 다른 개인 지침을 얹는 장치가 있습니다. 루트에 AGENTS.<이름>.md 를 두고 스크립트를 돌립니다. 그러면 하네스(에이전트 실행 도구)마다 그 파일을 읽게 하는 생성물이 생깁니다. Claude Code 에는 CLAUDE.local.md 를, agy 에는 .agents/rules/personal-<이름>.md 를 만듭니다. agy 생성물의 머리말은 trigger: always_on 입니다. 위에서 본 이유로 glob 은 쓰지 않았습니다.

이 장치에는 규칙이 하나 붙어 있습니다. 세션의 첫 응답에서 사용자가 누구인지 묻고, 답을 듣기 전에는 개인 지침을 따르지 않는다는 규칙입니다. 처음 문구는 “루트의 AGENTS.*.md 를 확인한다"였습니다. agy 1.5.0 은 간단한 질문을 받자 이 단계를 건너뛰고 바로 답했습니다(한 번 시도). 문구를 “반드시 툴로 확인한다 — 간단해도 건너뛰지 않는다"로 바꾸자 두 번 모두 먼저 물었습니다. 같은 실험에서 Claude Code 는 두 문구 모두에서 먼저 물었습니다.

표본이 세 번뿐이라 일반화하기는 이릅니다. 제 해석은 이렇습니다. agy 는 지침의 “해야 한다"와 “하면 좋다"를 Claude Code 보다 느슨하게 가릅니다. 꼭 밟아야 할 단계는 조건 없이 쓰고, 건너뛰지 말라는 말까지 붙여야 했습니다. 다음 버전에서 처음 문구로도 단계를 지킨다면 이 해석은 틀린 것입니다.

정리

1편의 답은 이렇습니다. agy 는 루트 AGENTS.md·GEMINI.md 와 ~/.gemini/config/rules/ 를 읽습니다. 파일 패턴 규칙은 버전에 따라 켜지지 않았으니, 지켜야 할 규칙은 항상 읽히는 자리에 둡니다.

agy 를 새로 올렸다면 해 볼 일이 하나 있습니다. 빈 폴더에 암호어를 적은 AGENTS.md 를 두고 agy -p 로 물어보십시오. 2편은 agy 에게 어디까지 맡길지 정하는 실행 모드와 권한을 다룹니다. 질문 하나에도 드는 컨텍스트 비용도 함께 잽니다.