Antigravity CLI 와 Gemini CLI 실전 - 이전 배경·agy 비대화형·모드와 샌드박스

이 장에서 배우는 것

작은 팀에서 터미널 AI 도구를 함께 쓰려면 설치 명령보다 먼저 맞춰야 할 것이 있다. 어떤 계정으로 접속하는지, 어떤 실행 파일을 쓰는지, 변경과 명령 실행을 어디까지 허용하는지다. 같은 요청문을 공유해도 계정과 실행 환경이 다르면 같은 절차가 되지 않는다. 팀의 재현성은 요청문뿐 아니라 도구 선택과 설정 점검에서 시작한다.

이 장의 제품 기능과 계정 구분은 모두 2026년 10월 기준 예시다. 제공 범위와 동작은 바뀔 수 있으므로 실제 도입 시점에는 공식 문서와 설치된 도구의 도움말을 다시 확인한다. 완성 코드는 외부 도구를 실행하지 않는다. 계정 종류에 따라 도구와 설정 체크리스트를 고르는 Python 프로그램으로 팀의 판단 절차를 표현한다.

• 개인 계정과 기업·API 키 계정을 구분해 사용할 도구를 선택한다.
• 작업 모드와 샌드박스가 서로 다른 통제 수단임을 설명한다.
• 비대화형 요청, JSON 출력, 대화 이어가기를 작업 기록과 연결한다.
• 표준 입력 누락과 크레딧 소진에 대비한 중단·재개 절차를 세운다.
• 선택 도우미의 결과를 실행·테스트·diff 검토로 확인한다.

문제 상황

작은 팀이 Python으로 만든 업무 도구를 관리한다고 하자. 개인 계정으로 기능을 작성하는 사람, 기업 계정으로 변경을 검토하는 사람, API 키로 작업하는 사람이 한 저장소를 사용한다. 팀은 기존 안내문에 적힌 도구 이름만 보고 같은 명령을 실행하려 한다. 그런데 계정에 따라 확인해야 할 도구가 달라 안내문부터 갈라진다.

2026년 10월 기준 예시로, 개인 무료 사용과 Google AI Pro·Ultra 구독 사용은 2026년 6월 18일부터 Gemini CLI에서 Antigravity CLI로 이전했다. Gemini CLI는 Code Assist 표준·기업용과 API 키 사용자 쪽에 남았다. 따라서 예전 개인 계정용 안내를 모든 팀원에게 그대로 적용하면 계정과 도구의 대응부터 어긋날 수 있다.

문제는 실행 단계에서도 이어진다. 한 팀원은 요청 파일을 표준 입력으로 넘기고 실행을 마쳤지만, 실제로는 파일 내용이 요청에 들어가지 않았다. 다른 팀원은 변경을 허용하는 모드를 켰으니 터미널 접근도 제한되었다고 생각했다. 긴 작업 중 크레딧이 소진되자 마지막으로 무엇을 확인했는지 모른 채 처음부터 다시 요청하기도 했다.

팀에 필요한 것은 누구에게나 같은 실행 파일을 강제하는 문서가 아니다. 계정에서 도구를 고르고, 도구에서 설정을 확인하고, 실행 결과를 검증하는 공통 절차다. 앞 장에서 살펴본 계획과 실행의 구분도 이 절차 안에서 이어진다. 도구마다 이름이 다른 부분은 대응표로 관리하고, 검토 기준은 함께 사용한다.

계정에서 도구를 고른다

2026년 10월 기준 예시로, 책 제목의 Gemini는 Google의 Gemini 계열 도구를 가리킨다. 이 장의 개인 사용자 흐름은 Antigravity CLI를 중심으로 설명하며, 기업·API 키 사용자 흐름은 Gemini CLI로 구분한다. 이름이 비슷하다는 이유로 실행 파일과 설정 파일까지 같다고 가정하지 않는다.

2026년 10월 기준 예시: 계정과 도구의 대응

계정 종류	선택할 도구	팀에서 확인할 것
개인 무료	Antigravity CLI, agy	Free 이용 범위와 AI 크레딧 상태
Google AI Pro	Antigravity CLI, agy	구독 계정과 로그인 계정의 일치
기업	Gemini CLI, gemini	조직의 Code Assist 제공 범위
API 키	Gemini CLI, gemini	인증 방법과 비밀값 보관 정책

이 표는 인증 성공을 보장하는 판정표가 아니다. 기업 계정을 선택했다고 조직의 사용 권한까지 확인되는 것은 아니다. 선택 도우미가 할 일은 다음에 확인할 항목을 빠뜨리지 않게 만드는 데 있다. 실제 인증과 사용 가능 여부는 해당 환경에서 별도로 확인한다.

2026년 10월 기준 예시로, Antigravity는 데스크톱 앱, CLI, 편집기 확장으로 구성된다. 데스크톱 앱에는 에이전트 매니저와 로컬·git worktree 실행 흐름이 있다. 개인 플랜은 Free·Pro·Ultra이며 CLI 사용량은 AI 크레딧 방식이다. 이 장에서는 CLI의 실행 경계와 기록 방법을 다룬다. 화면에서 작업을 시작했는지 터미널에서 시작했는지보다, 어떤 폴더를 바꿨고 무엇을 검증했는지가 팀 기록의 중심이 된다.

2026년 10월 기준 예시로, 별도의 gemini-api는 상태 없는 API 명령줄 도구다. 저장소 맥락과 편집 도구를 묶어 코딩 작업을 수행하는 코딩 하네스와 구분해야 한다. API 키를 사용한다는 이유만으로 이번 장의 선택 결과를 gemini-api로 바꾸지 않는다.

팀 문서에는 도구 이름 옆에 확인 날짜와 계정 범주를 함께 적는다. “모두 이 명령을 쓴다”는 안내보다 “개인 계정은 이 흐름을 확인하고 기업 계정은 조직 정책을 확인한다”는 안내가 변경에 대응하기 쉽다. 이전 배경을 길게 외우는 대신, 새 팀원이 자신의 분기를 찾아갈 수 있게 만드는 편이 실용적이다.

이전 사실을 확인하는 출발점은 Gemini CLI 공식 저장소다. 문서의 문장을 팀 규칙으로 복사하기보다는 계정 대응, 확인 날짜, 팀에서 추가로 점검할 내용을 직접 정리한다.

모드와 샌드박스를 따로 점검한다

2026년 10월 기준 예시로, agy의 --mode에는 accept-edits·auto·plan이 있다. --sandbox는 터미널 제한을 위한 옵션이다. 두 설정을 한 덩어리의 “안전 모드”로 취급하면 어떤 통제를 기대하는지 설명하기 어려워진다. 모드는 작업 진행과 승인에 관한 선택으로, 샌드박스는 실행 환경의 제한으로 나누어 확인한다.

2026년 10월 기준 예시: agy 실행 경계의 점검 항목

항목	확인된 이름	팀의 점검 질문
계획 작업	--mode plan	변경 전에 범위와 검증 방법을 정했는가
편집 수용	--mode accept-edits	편집을 허용할 범위와 diff 검토자를 정했는가
자동 진행	--mode auto	설치 버전의 승인 동작을 확인했는가
터미널 제한	--sandbox	현재 환경에서 제한이 어떻게 적용되는가

표의 점검 질문은 팀의 운영 규칙이다. 제품이 그 질문에 자동으로 답해 준다는 뜻은 아니다. 2026년 10월 기준 예시로, 모드별 세부 승인 조건은 설치된 버전의 도움말과 공식 문서에서 확인한다. 특히 auto라는 이름만 보고 모든 명령이 승인된다고 해석하거나, 모든 위험이 차단된다고 해석해서는 안 된다.

2026년 10월 기준 예시로, agy --help에서 이 장에 쓰인 옵션을 확인할 수 있다. 처음에는 계획 모드와 샌드박스를 함께 지정하는 흐름을 검토한다. 다음 명령의 요청은 작업 범위를 설명하는 예시다.

agy --mode plan --sandbox -p "저장소를 살펴보고 수정 대상과 검증 순서를 제안하라. 실제 변경은 하지 말라."

여기서 요청문은 작업 의도를 전달한다. 실제 권한 경계는 도구 설정과 실행 환경에서 확인해야 한다. “변경하지 말라”는 문장을 추가했다고 파일 쓰기 권한이 기술적으로 사라지는 것은 아니다. 반대로 샌드박스를 켰다는 사실만으로 생성된 코드의 논리 오류까지 방지되는 것도 아니다.

2026년 10월 기준 예시로, agy에는 모든 권한을 자동 승인하는 --dangerously-skip-permissions도 있다. 이 장의 기본 절차에는 넣지 않는다. 실행 실패를 해결하려고 이 옵션부터 추가하면 원래 필요했던 권한이 무엇인지 파악하기 어려워진다. 팀은 실패한 작업, 필요한 접근 범위, 허용할 이유를 먼저 구분한다.

2026년 10월 기준 예시로, 추가 작업 폴더를 지정하는 --add-dir와 설정을 지정하는 --settings도 제공된다. 폴더를 추가할 때는 그 폴더가 왜 필요한지 작업 기록에 남긴다. 설정 파일의 구체적인 키와 적용 방식은 공식 문서에서 확인한다. 다른 CLI에서 사용한 설정 키를 이름이 비슷하다는 이유로 옮기지 않는다.

권한을 조정한 뒤에도 검증 순서는 남는다. 변경된 파일을 확인하고, 필요한 테스트를 실행하고, diff를 읽는다. AI의 완료 설명은 검토를 시작할 단서다. 팀이 수용할 근거는 실제 변경과 검증 결과에서 찾아야 한다.

비대화형 실행도 요청과 기록이 필요하다

비대화형 실행(headless execution)은 실행 중 사람과 문답하지 않는 방식이다. 입력이 없다는 뜻은 아니다. 오히려 요청, 작업 폴더, 설정, 결과 저장 위치를 실행 전에 정해야 한다. 대화 중에 부족한 정보를 보충하기 어려우므로 요청 전달 경로부터 확인한다.

2026년 10월 기준 예시로, agy는 -p 또는 --print로 비대화형 실행을 하고 --output-format에 text·json·stream-json을 지정할 수 있다. 이 장에서는 하나의 작업 결과를 확인하기 쉬운 json 예시를 사용한다.

agy -p "이 저장소의 테스트 실행 방법을 찾아 설명하라. 파일은 수정하지 말라." --mode plan --sandbox --output-format json

2026년 10월 기준 예시로, agy의 헤드리스 실행에서 표준 입력으로 전달한 내용을 읽지 않는 실측 함정이 있다. 다음처럼 요청을 파이프로 넘겼다고 요청 내용까지 전달되었다고 판단하면 안 된다.

잘못된 전달 가정: cat request.txt | agy -p "전달한 내용을 검토하라."

이 예에서 짧은 요청 인자는 전달되어도 request.txt 내용까지 읽혔다고 볼 수 없다. 요청은 인자로 전달한다. 파일을 사용하는 자동화라면 먼저 파일 내용을 읽은 다음 실행 인자에 넣는 경로를 명시적으로 만든다. 큰 입력의 크기 제한과 다른 전달 방식은 공식 문서에서 확인한다. 파일 내용을 읽었다는 주장도 결과만 보고 추측하지 말고, 입력에 넣은 식별 문구나 검토 대상 목록으로 점검한다.

2026년 10월 기준 예시로, agy의 --conversation <ID>는 특정 대화를 이어가는 데 사용하고 -c 또는 --continue는 최근 대화를 이어가는 옵션이다. 팀 작업에서는 어떤 대화가 최근인지 실행 순서에 따라 달라질 수 있다. 특정 작업을 재개할 때는 기록한 대화 ID를 사용하는 흐름이 더 명확하다.

agy --conversation <기록한 대화 ID> -p "현재 diff와 테스트 결과를 먼저 확인하고 남은 작업을 정리하라." --mode plan --sandbox --output-format json

대화 ID는 작업 기록의 일부다. 저장소의 브랜치, 커밋, 변경 파일, 실행한 검증과 함께 보관한다. 대화가 이어져도 작업 폴더의 파일은 달라졌을 수 있다. 재개 요청에는 현재 상태를 다시 확인하는 단계를 넣는다. 과거 대화의 설명을 현재 파일 상태로 취급하지 않는 것이 핵심이다.

2026년 10월 기준 예시로, agy에는 --print-timeout이 있다. 정확한 단위와 적용 방식은 공식 문서에서 확인한다. 실행 시간 제한과 AI 크레딧 소진은 다른 문제다. 시간 제한을 바꾼다고 소진된 크레딧이 보충되지는 않는다. 실패 원인을 구분하지 않고 같은 작업을 반복 실행하면 검토해야 할 부분 결과만 늘어날 수 있다.

크레딧 소진으로 작업이 끝나지 않았다면 먼저 자동 재시도를 멈춘다. 현재 diff를 살펴보고, 실행할 수 있는 로컬 테스트를 수행한다. 이어서 완료한 일, 미완료한 일, 확인하지 못한 일을 따로 기록한다. 이용 가능 상태를 확인한 뒤 남은 범위만 다시 요청한다. 중단된 작업을 성공으로 표시하거나, AI의 마지막 문장만으로 완료 여부를 판단하지 않는다.

2026년 10월 기준 예시로, agy에는 mcp·plugin 하위 명령이 있다. MCP(Model Context Protocol)는 외부 도구 연결을 다루며 플러그인은 별도로 제공되는 확장 기능을 확인할 때 살펴볼 대상이다. 둘의 설치·인증 절차가 같다고 가정하지 않는다. 이번 장에서는 연결 여부, 접근 대상, 자격 증명 위치를 체크리스트에 남기는 데 그친다. 구체적인 구성은 공식 문서에서 확인한다.

2026년 10월 기준 예시로, Gemini CLI는 GEMINI.md를 지침 파일로 쓰고 MCP 설정은 ~/.gemini/settings.json에서 다룬다. 비대화형 요청은 gemini -p로 전달하며 JSON 계열 출력에는 --output-format json 또는 stream-json을 사용한다. Antigravity의 규칙 파일 이름은 이 장에서 확정하지 않는다. 공식 문서에서 확인해야 할 항목으로 남긴다.

팀의 공통 검토 기준은 같아도 파일 이름과 설정 방법은 다를 수 있다. GEMINI.md 내용을 그대로 다른 이름의 파일에 복사하기 전에 해당 도구가 무엇을 읽는지 확인한다. 설정 파일에는 비밀값을 그대로 커밋하지 않는다. 연결한 도구가 늘어나면 승인해야 할 접근 범위도 함께 검토한다.

완성 코드

다음 main.py는 Python 3.12 이상 표준 라이브러리만 사용한다. 계정 종류를 문자열로 받아 도구와 점검 항목을 반환한다. 인자 없이 실행하면 네 계정을 고정된 순서로 출력하고, 계정 하나를 인자로 주면 그 계정만 출력한다. 외부 CLI, 인증 정보, 네트워크가 필요하지 않다.

프로그램의 JSON은 선택 도우미 자체의 출력 형식이다. 실제 제품의 JSON 응답 구조를 재현하지 않는다. 도구 선택을 함수로 분리하고 실행 전에 간단한 자체 검사를 수행해, 안내문을 수정하다가 계정 분기를 바꾸는 실수를 확인한다. 고정된 기준일과 계정 순서 덕분에 반복 실행 결과를 비교하기도 쉽다.

import json
import sys

AS_OF = "2026년 10월 기준 예시"
ACCOUNTS = ("개인 무료", "AI Pro", "기업", "API 키")

COMMON = (
    "실행 전 git 상태와 작업 범위 확인",
    "변경 후 실행·테스트·diff 검토",
    "중단 시 변경 파일과 남은 작업 기록",
)

AGY_CHECKS = (
    "로그인 계정과 AI 크레딧 상태 확인",
    "--mode plan과 --sandbox 적용 확인",
    "-p 요청 인자와 --output-format json 확인",
    "요청을 표준 입력에만 넣지 않기",
    "--conversation ID와 현재 파일 상태 함께 기록",
    "규칙 파일 이름과 mcp·plugin은 공식 문서에서 확인",
)

GEMINI_CHECKS = (
    "GEMINI.md의 팀 지침 확인",
    "~/.gemini/settings.json의 MCP 설정 확인",
    "gemini -p와 --output-format json 확인",
    "인증 정보와 비밀값의 저장소 포함 여부 확인",
)


def select_tool(account: str) -> dict[str, object]:
    if account not in ACCOUNTS:
        raise ValueError(f"지원하지 않는 계정: {account}")

    if account in ACCOUNTS[:2]:
        tool = "Antigravity CLI (agy)"
        checks = AGY_CHECKS + COMMON
    else:
        tool = "Gemini CLI (gemini)"
        checks = GEMINI_CHECKS + COMMON

    if account == "AI Pro":
        checks += ("구독 계정과 로그인 계정 일치 확인",)
    elif account == "기업":
        checks += ("조직의 Code Assist 제공 범위 확인",)
    elif account == "API 키":
        checks += ("API 키 인증 방법을 공식 문서에서 확인",)

    return {
        "account": account,
        "tool": tool,
        "checklist": list(checks),
    }


def self_check() -> None:
    for account in ACCOUNTS:
        result = select_tool(account)
        expected = (
            "Antigravity CLI (agy)"
            if account in ("개인 무료", "AI Pro")
            else "Gemini CLI (gemini)"
        )
        if result["tool"] != expected:
            raise RuntimeError("계정과 도구의 대응이 잘못되었다.")

    try:
        select_tool("미등록")
    except ValueError:
        pass
    else:
        raise RuntimeError("미등록 계정을 거부하지 않았다.")

    first = select_tool("개인 무료")
    first["checklist"].append("임시 항목")
    second = select_tool("개인 무료")
    if "임시 항목" in second["checklist"]:
        raise RuntimeError("체크리스트가 호출 사이에 공유되었다.")


def main(argv: list[str]) -> int:
    self_check()
    if len(argv) > 1:
        print("오류: 계정 인자는 하나만 지정한다.", file=sys.stderr)
        return 2

    accounts = tuple(argv) if argv else ACCOUNTS
    try:
        results = [select_tool(account) for account in accounts]
    except ValueError as error:
        print(f"오류: {error}", file=sys.stderr)
        return 2

    document = {"기준": AS_OF, "선택": results}
    print(json.dumps(document, ensure_ascii=False, indent=2))
    return 0


if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1:]))

줄별 해설

import 문 두 줄은 JSON 직렬화와 실행 인자 처리를 준비한다. 외부 패키지를 사용하지 않으므로 별도의 설치 단계가 없다. AS_OF는 출력의 기준 시점을 고정한다. 실제 날짜를 읽지 않기 때문에 같은 입력에는 같은 결과가 나온다.

ACCOUNTS는 지원할 계정의 목록과 기본 출력 순서를 함께 정의한다. 사용자에게 제시할 이름을 코드의 여러 위치에서 제각각 만들지 않도록 한곳에 모았다. 기업은 이 예제의 입력 이름이며, 실제 조직의 계약과 권한을 자동 조회한다는 의미는 아니다.

COMMON은 도구와 무관하게 남겨야 할 검증 항목이다. 실행 전 상태 확인, 변경 후 검증, 중단 시 기록을 포함한다. 특정 도구를 선택했다고 테스트와 diff 검토가 생략되지 않도록 두 분기 모두에 합친다. 제품별 옵션이 바뀌더라도 이 공통 항목의 목적은 유지된다.

AGY_CHECKS와 GEMINI_CHECKS는 2026년 10월 기준 예시의 차이를 담는다. 전자는 요청 인자 전달, 모드, 샌드박스, 대화 기록을 점검한다. 후자는 확인된 지침 파일과 MCP 설정 위치를 점검한다. 확인하지 못한 규칙 파일 이름을 빈칸 대신 추측해서 채우지 않고, 공식 문서에서 확인할 일로 남긴다.

select_tool의 첫 조건문은 입력 검증이다. 알 수 없는 계정을 개인 무료로 처리하면 출력은 그럴듯해 보여도 잘못된 안내가 된다. 지원 목록에 없는 값은 ValueError로 드러낸다. 별칭을 허용하려면 어떤 문자열을 어떤 계정으로 바꿀지 별도 규칙으로 추가해야 한다.

다음 분기는 개인 무료·AI Pro와 기업·API 키를 구분한다. 도구를 고른 다음 계정별 추가 점검을 붙인다. AI Pro는 로그인 계정의 일치, 기업은 조직의 제공 범위, API 키는 인증 방법을 확인한다. 계정 선택만으로 인증 상태까지 확인한 것처럼 표현하지 않는 구조다.

반환값의 list(checks)는 호출마다 새 목록을 만든다. 호출자가 받은 체크리스트를 수정하더라도 다음 호출에 영향을 주지 않게 한다. self_check의 마지막 검사는 바로 이 성질을 확인한다. 도구 대응 검사와 미등록 계정 거부 검사도 포함하므로 정상 분기와 실패 분기를 함께 살펴본다.

main은 인자를 하나까지 허용하고, 인자가 없으면 모든 계정을 사용한다. 오류는 표준 오류로 출력하고 종료값 2를 반환한다. 정상 결과만 표준 출력에 JSON으로 내보내므로 다른 프로그램이 읽을 때 오류 문장과 결과 데이터가 섞이지 않는다. 이는 이 도우미의 설계이며 실제 CLI의 출력 필드를 가정한 것이 아니다.

마지막 두 줄은 파일을 직접 실행할 때 main을 호출한다. 자체 검사가 실패하면 정상 JSON을 출력하기 전에 예외가 발생한다. 검사가 통과해도 제품의 현재 동작까지 검증된 것은 아니다. 프로그램의 분기 정확성과 안내 내용의 최신성은 별도로 확인해야 한다.

실행 결과

다음 명령으로 문법과 경고를 확인한 뒤 프로그램을 실행한다. 컴파일 확인 명령은 성공하면 출력이 없다.

python3 -W error -m py_compile main.py
python3 main.py

{
  "기준": "2026년 10월 기준 예시",
  "선택": [
    {
      "account": "개인 무료",
      "tool": "Antigravity CLI (agy)",
      "checklist": [
        "로그인 계정과 AI 크레딧 상태 확인",
        "--mode plan과 --sandbox 적용 확인",
        "-p 요청 인자와 --output-format json 확인",
        "요청을 표준 입력에만 넣지 않기",
        "--conversation ID와 현재 파일 상태 함께 기록",
        "규칙 파일 이름과 mcp·plugin은 공식 문서에서 확인",
        "실행 전 git 상태와 작업 범위 확인",
        "변경 후 실행·테스트·diff 검토",
        "중단 시 변경 파일과 남은 작업 기록"
      ]
    },
    {
      "account": "AI Pro",
      "tool": "Antigravity CLI (agy)",
      "checklist": [
        "로그인 계정과 AI 크레딧 상태 확인",
        "--mode plan과 --sandbox 적용 확인",
        "-p 요청 인자와 --output-format json 확인",
        "요청을 표준 입력에만 넣지 않기",
        "--conversation ID와 현재 파일 상태 함께 기록",
        "규칙 파일 이름과 mcp·plugin은 공식 문서에서 확인",
        "실행 전 git 상태와 작업 범위 확인",
        "변경 후 실행·테스트·diff 검토",
        "중단 시 변경 파일과 남은 작업 기록",
        "구독 계정과 로그인 계정 일치 확인"
      ]
    },
    {
      "account": "기업",
      "tool": "Gemini CLI (gemini)",
      "checklist": [
        "GEMINI.md의 팀 지침 확인",
        "~/.gemini/settings.json의 MCP 설정 확인",
        "gemini -p와 --output-format json 확인",
        "인증 정보와 비밀값의 저장소 포함 여부 확인",
        "실행 전 git 상태와 작업 범위 확인",
        "변경 후 실행·테스트·diff 검토",
        "중단 시 변경 파일과 남은 작업 기록",
        "조직의 Code Assist 제공 범위 확인"
      ]
    },
    {
      "account": "API 키",
      "tool": "Gemini CLI (gemini)",
      "checklist": [
        "GEMINI.md의 팀 지침 확인",
        "~/.gemini/settings.json의 MCP 설정 확인",
        "gemini -p와 --output-format json 확인",
        "인증 정보와 비밀값의 저장소 포함 여부 확인",
        "실행 전 git 상태와 작업 범위 확인",
        "변경 후 실행·테스트·diff 검토",
        "중단 시 변경 파일과 남은 작업 기록",
        "API 키 인증 방법을 공식 문서에서 확인"
      ]
    }
  ]
}

계정 하나만 확인할 때는 python3 main.py "API 키"처럼 실행한다. 공백이 있는 계정명은 하나의 인자가 되도록 따옴표로 묶는다. 미등록 계정을 넣으면 정상 JSON 대신 오류가 발생해야 한다. 출력의 모양만 확인하지 말고 네 계정의 대응과 공통 검증 항목이 실제로 포함되었는지 읽는다.

팀 저장소에 반영할 때는 main.py의 diff에서 계정 분기, 제품별 항목, 공통 검증 항목을 나누어 살펴본다. 기준일만 바꾸고 안내 내용을 확인하지 않는 변경도 검토 대상이다. 이 장의 실행 결과는 코드에 따른 예상 출력이며, 실제 채택 전에는 위 명령으로 직접 확인한다.

실무에서 자주 틀리는 것

계정 문자열이 비어 있지 않으면 개인 도구를 고른다

다음 코드는 어떤 계정이든 값이 있으면 같은 도구를 고른다. 2026년 10월 기준 예시의 계정 구분을 반영하지 못하므로 기업과 API 키 입력에서도 잘못된 결과를 낸다.

account = "기업"
tool = "Antigravity CLI (agy)" if account else "Gemini CLI (gemini)"
print(tool)

고친 코드는 허용한 계정만 받고 명시적으로 분기한다. 완성 코드에서는 이 규칙을 select_tool에 모아 사용한다.

account = "기업"
allowed = ("개인 무료", "AI Pro", "기업", "API 키")
if account not in allowed:
    raise ValueError("지원하지 않는 계정")
tool = (
    "Antigravity CLI (agy)"
    if account in ("개인 무료", "AI Pro")
    else "Gemini CLI (gemini)"
)
print(tool)

모드 이름으로 샌드박스 상태까지 추정한다

2026년 10월 기준 예시로, --mode와 --sandbox는 구분해 점검한다. 다음 모형은 auto를 선택하면 샌드박스도 켜진 것으로 표시한다. 실제 설정을 확인하지 않고 한 값을 다른 값의 근거로 삼은 오류다.

mode = "auto"
sandbox_enabled = mode == "auto"
print(sandbox_enabled)

고친 모형은 두 값을 따로 받는다. 여기의 참·거짓 값은 교육용 데이터다. 실제 환경에서는 옵션을 지정했는지와 제한이 적용되는지를 별도로 확인한다.

mode = "auto"
sandbox_enabled = False
checks = {
    "선택한 모드": mode,
    "샌드박스 적용 확인": sandbox_enabled,
}
print(checks)

표준 입력을 넣었으니 요청도 전달되었다고 기록한다

2026년 10월 기준 예시로, agy 헤드리스 실행의 표준 입력 함정을 고려해야 한다. 다음 코드는 표준 입력용 문자열이 있다는 사실을 요청 전달의 증거로 취급한다. 실제 실행을 하지 않는 모형이지만 잘못된 기록 기준을 보여 준다.

stdin_text = "테스트 실패 원인을 조사하라."
request_argument = ""
request_ready = bool(stdin_text)
print(request_ready)

고친 코드는 요청 인자를 검증한다. 실제 자동화에서도 요청을 읽는 단계와 실행 인자를 만드는 단계를 구분한다. 요청에 비밀값이 들어 있으면 인자와 실행 기록을 통해 노출될 수 있으므로 전달할 내용 자체도 검토한다.

request_text = "테스트 실패 원인을 조사하라."
request_argument = request_text
if not request_argument.strip():
    raise ValueError("요청 인자가 비어 있다.")
request_ready = True
print(request_ready)

중단된 작업을 성공으로 바꿔 보고한다

크레딧 소진, 실행 실패, 검증 실패를 하나의 성공 상태로 덮으면 다음 작업자가 어디서 이어야 할지 알 수 없다. 다음 코드는 실패를 잡았다는 이유만으로 완료를 선언한다.

try:
    raise RuntimeError("작업이 중단되었다.")
except RuntimeError:
    status = "완료"
print(status)

고친 코드는 중단과 미검증 상태를 보존한다. 재개하기 전에는 현재 파일과 diff를 다시 확인한다. 2026년 10월 기준 예시로, agy의 대화 이어가기 기능을 사용하더라도 이러한 파일 상태 확인은 팀의 절차로 남겨야 한다.

try:
    raise RuntimeError("작업이 중단되었다.")
except RuntimeError:
    status = "중단"
    next_action = "diff와 로컬 테스트를 확인한 뒤 남은 범위 기록"
print(status)
print(next_action)

한눈에 보기

2026년 10월 기준 예시의 도구 차이와 공통 검증 기준

주제	Antigravity CLI	Gemini CLI	공통 기준
계정	개인 무료·AI Pro·Ultra	Code Assist 표준·기업용, API 키	로그인과 이용 권한 확인
비대화형 요청	agy -p	gemini -p	요청 전달 경로 검증
JSON 계열 출력	json·stream-json	json·stream-json	실제 출력 구조를 확인해 해석
지침·설정	규칙 파일 이름은 공식 문서에서 확인	GEMINI.md, MCP는 ~/.gemini/settings.json	팀 지침과 비밀값 분리
실행 경계	--mode와 --sandbox를 각각 점검	설치 버전의 공식 문서에서 확인	필요한 접근 범위만 허용
중단·재개	대화 ID와 크레딧 상태 확인	현재 사용 환경의 재개 절차 확인	파일·테스트·diff로 상태 확인

도구를 고른 결과와 작업이 안전하게 끝났다는 판단은 구분한다. 선택 도우미는 확인할 목록을 제공한다. 그 목록을 실제로 확인했는지, 생성된 코드가 요구사항을 만족하는지는 실행 기록과 검토에서 결정한다. 다음 도구를 사용할 때도 이 검증 기준을 유지하면 팀 절차가 제품 이름에 덜 의존하게 된다.

연습 문제

1. 선택 도우미에 개인 Ultra 입력을 추가하라. 2026년 10월 기준 예시의 계정 대응에 맞게 처리하고, 기존 네 계정의 결과가 바뀌지 않는지 확인하라.
2. 크레딧 소진으로 작업이 중단되었지만 파일 두 개가 수정된 상황을 가정하라. 재개를 위한 기록 항목을 다섯 개 정하고, 완료 여부를 어떻게 표현할지 설명하라.
3. 선택 도우미의 JSON을 받은 프로그램이 account와 tool만 읽고 checklist를 버린다고 하자. 이 처리에서 놓치는 점과 개선 방법을 설명하라.
4. 요청 파일을 표준 입력으로 넘긴 실행에서 AI가 일반적인 검토 의견을 반환했다. 파일을 읽었다고 판단할 수 있는지 설명하고, 다음 실행의 확인 절차를 제안하라.

정답과 해설

1. 2026년 10월 기준 예시로 개인 Ultra는 Antigravity CLI에 대응한다. ACCOUNTS에 계정을 추가하고 개인 계정 집합을 별도로 정의해 분기에 사용한다. 현재 코드의 ACCOUNTS[:2]는 앞의 두 항목만 개인 계정으로 취급하므로 목록에 이름만 추가하면 충분하지 않다. 자체 검사의 기대값도 갱신한다. 기존 계정의 도구와 체크리스트를 변경 전후로 비교한다.
2. 작업 목표, 대화 ID, 현재 브랜치와 커밋, 변경 파일과 diff, 테스트 결과와 남은 작업을 기록할 수 있다. 완료 상태는 “중단, 변경 일부 존재, 검증 미완료”처럼 표현한다. 수정 파일이 있다는 사실과 요구사항을 만족했다는 사실을 구분한다. 이용 가능 상태를 확인한 뒤 현재 파일을 다시 읽고 남은 범위부터 이어간다.
3. 도구 이름만 남기면 계정별 추가 점검과 공통 검증 의무가 사라진다. 체크리스트를 표시하고 각 항목의 확인 여부를 별도 기록으로 관리한다. 목록에 문장이 존재한다는 이유로 확인 완료로 처리해서는 안 된다. 코드에서 생성한 체크리스트와 사람이 확인한 증거를 구분한다.
4. 일반적인 의견만으로 파일을 읽었다고 판단할 수 없다. 2026년 10월 기준 예시의 agy 헤드리스 함정을 고려해 요청 내용을 인자로 전달한다. 다음 실행에서는 검토 대상 목록이나 비밀값이 아닌 식별 문구를 요청에 넣고 결과가 해당 내용을 다루는지 확인한다. 그 뒤에도 제안한 변경은 직접 실행하고 테스트하며 diff로 검토한다.