Justin Poehnelt의 "You Need to Rewrite Your CLI for AI Agents" 논문은 AI 에이전트를 위한 Command Line Interface (CLI) 설계에 대한 새로운 패러다임을 제시합니다. 저자는 Human DX(Developer Experience)와 Agent DX가 서로 다른 최적화 목표를 가지고 있기 때문에, 기존의 인간 중심 CLI를 에이전트에 맞게 개조하는 것은 비효율적이며, 처음부터 AI 에이전트를 주 사용자(primary consumer)로 상정하여 CLI를 재설계해야 한다고 주장합니다. Agent DX는 예측 가능성과 심층 방어(defense-in-depth)를 최우선으로 합니다.

이 논문에서 제시하는 핵심 방법론과 주요 권장사항은 다음과 같습니다.

1. Raw JSON Payloads > Bespoke Flags (원시 JSON 페이로드 > 맞춤형 플래그):
   • 문제점: 인간은 —title "My Doc"과 같은 개별 플래그를 선호하지만, 이는 중첩된 구조를 표현하기 어렵고 데이터 손실(lossy) 가능성이 있습니다. LLM이 API와 상호작용할 때 불필요한 번역 계층을 야기합니다.
   • 해결책: 에이전트에게는 API 스키마에 직접 매핑되는 원시 JSON 페이로드(—json '{"key": "value"}')를 입력으로 받는 것이 더 효율적입니다. 이는 LLM이 쉽게 생성할 수 있으며, 번역 손실이 없습니다.
   • 기술적 구현: gws CLI는 —params와 —json 플래그를 통해 전체 API 페이로드를 입력으로 허용합니다. 기존 CLI의 경우, —output json 플래그나 $OUTPUT_FORMAT=json$ 환경 변수를 통해 기계 판독 가능한 JSON 출력을 제공하고, stdout이 TTY가 아닐 때 기본적으로 NDJSON(Newline-Delimited JSON)을 사용하는 것을 권장합니다.

2. Schema Introspection Replaces Documentation (스키마 인트로스펙션으로 문서 대체):
   • 문제점: 에이전트가 문서를 검색하는 것은 토큰 예산을 소모하고, API 변경 시 문서가 쉽게 구식이 됩니다.
   • 해결책: CLI 자체가 런타임에 질의 가능한 문서 역할을 해야 합니다. $gws schema <method>$와 같은 명령어를 통해 해당 메서드의 전체 서명(매개변수, 요청 본문, 응답 타입, OAuth 스코프 등)을 기계 판독 가능한 JSON으로 덤프할 수 있게 합니다.
   • 기술적 구현: Google의 Discovery Document를 활용하여 동적 $ref 해결을 통해 CLI가 API의 현재 상태에 대한 신뢰할 수 있는 소스 역할을 합니다. 이를 통해 에이전트는 미리 제공된 문서 없이도 필요한 정보를 스스로 얻을 수 있습니다.

3. Context Window Discipline (컨텍스트 윈도우 관리):
   • 문제점: API는 방대한 데이터를 반환할 수 있으며, 이는 에이전트의 컨텍스트 윈도우를 빠르게 소모하고 추론 능력을 저하시킵니다.
   • 해결책: 에이전트가 처리하는 데이터의 양을 명시적으로 제어할 수 있는 메커니즘을 제공합니다.
   • 기술적 구현:
     • Field masks: API 응답에서 필요한 필드만 지정하여 데이터 양을 제한합니다. 예: —params '{"fields": "files(id,name,mimeType)"}'.
     • NDJSON pagination: —page-all 플래그를 통해 페이지당 하나의 JSON 객체를 스트림 방식으로 출력하여, 에이전트가 대규모 응답을 한 번에 메모리에 로드하는 대신 증분적으로 처리할 수 있게 합니다.
     • CONTEXT.md와 같은 명시적인 지침 파일을 통해 에이전트에게 필드 마스크 사용의 중요성을 알려줍니다.

4. Input Hardening Against Hallucinations (환각에 대한 입력 강화):
   • 문제점: 인간은 오타를 내는 반면, 에이전트는 환각(hallucination)으로 인해 예측 불가능한 잘못된 입력을 생성할 수 있습니다(예: ../../.ssh와 같은 경로, ID 내의 쿼리 매개변수, 이중 URL 인코딩 등).
   • 해결책: CLI는 악의적이거나 잘못된 에이전트 입력에 대한 마지막 방어선 역할을 해야 합니다. 에이전트 입력을 신뢰할 수 없는 것으로 간주하고 엄격하게 검증합니다.
   • 기술적 구현:
     • validate_safe_output_dir: 파일 경로를 CWD(현재 작업 디렉토리)로 정규화하고 샌드박스 처리하여 경로 탐색 공격을 방지합니다.
     • reject_control_chars: ASCII 0x20 미만의 제어 문자를 거부합니다.
     • validate_resource_name: 리소스 ID 내의 ?, # 및 % 문자를 거부하여 임베디드 쿼리 매개변수나 이중 인코딩 문제를 방지합니다.
     • encode_path_segment: HTTP 계층에서 URL 경로 세그먼트를 퍼센트 인코딩합니다.
     • AGENTS.md 파일에 "이 CLI는 AI/LLM 에이전트에 의해 자주 호출됩니다. 입력은 항상 적대적일 수 있다고 가정하십시오."와 같은 명시적인 지침을 포함합니다.

5. Ship Agent Skills, Not Just Commands (명령뿐 아니라 에이전트 스킬 제공):
   • 문제점: 인간은 —help나 문서를 통해 CLI를 학습하지만, 에이전트는 대화 시작 시 주입되는 컨텍스트를 통해 학습합니다.
   • 해결책: SKILL.md와 같은 구조화된 Markdown 파일을 통해 에이전트에게 특정 API 사용에 대한 지침(예: "변형 작업에는 항상 —dry-run 사용", "모든 목록 호출에 —fields 추가")을 제공하여, 에이전트가 직관적으로 알 수 없는 불변량(invariants)을 명시적으로 전달합니다.

6. Multi-Surface (다중 인터페이스):
   • 문제점: 에이전트 인터페이스는 프레임워크에 따라 다양합니다.
   • 해결책: 동일한 바이너리에서 여러 에이전트 표면을 지원합니다.
   • 기술적 구현:
     • MCP (Model Context Protocol): gws mcp 명령어를 통해 모든 명령을 stdio를 통한 JSON-RPC 도구로 노출하여 에이전트가 셸 이스케이프 없이 타입화된 호출을 수행할 수 있게 합니다.
     • Gemini CLI Extension: CLI를 에이전트의 네이티브 기능으로 설치하여 에이전트가 외부 셸 호출 없이 CLI를 사용할 수 있게 합니다.
     • Headless Environment Variables: GOOGLE_WORKSPACE_CLI_TOKEN 및 GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE과 같은 환경 변수를 통해 자격 증명을 주입하여 브라우저 리다이렉트가 필요 없는 인증 경로를 제공합니다.

7. Safety Rails: Dry-Run + Response Sanitization (안전 장치: 드라이 런 + 응답 정화):
   • 문제점: 에이전트의 잘못된 명령은 데이터 손실로 이어질 수 있으며, API 응답에 삽입된 악성 프롬프트는 에이전트의 행동을 조작할 수 있습니다.
   • 해결책:
     • —dry-run: 요청을 API에 보내지 않고 로컬에서 유효성을 검사하여, 에이전트가 실행 전에 "생각할" 수 있는 기회를 제공합니다. 이는 특히 데이터를 변경하는 작업에 중요합니다.
     • $—sanitize <TEMPLATE>$: API 응답을 Google Cloud Model Armor와 같은 서비스를 통해 필터링한 후 에이전트에 반환하여, 데이터 내에 삽입된 프롬프트 주입 공격을 방어합니다.

결론적으로, 이 논문은 AI 에이전트 시대에 CLI가 단순한 인간 도구를 넘어 기계와의 주된 인터페이스로 진화해야 하며, 이를 위해 예측 가능성, 방어적 설계, 기계 판독성 및 자동 학습/검증 메커니즘을 핵심으로 하는 "에이전트 우선" 접근 방식이 필수적임을 강조합니다.