AI 에이전트용 CLI 구축: Google의 gws CLI에서 배운 설계 원칙

에이전트 우선 CLI 설계가 중요한 이유

인간 개발자 경험(DX)은 발견 가능성과 용인성을 최적화하는 반면, 에이전트 DX는 예측 가능성과 심층 방어가 필요합니다. 이 글은 인간 우선 CLI를 에이전트용으로 개조하는 것은 효과적이지 않다고 주장하며, Google Workspace용 gws CLI를 통해 이를 입증합니다. 이 CLI는 처음부터 AI 에이전트를 주요 사용자로 설계되었습니다.

주요 설계 원칙

맞춤형 플래그보다 원시 JSON 페이로드: 인간은 --title "My Doc"과 같은 간단한 플래그를 선호하지만, 에이전트는 번역 손실 없이 API 스키마에 직접 매핑되는 직접적인 JSON 페이로드에서 더 잘 작동합니다.

예시 비교:

인간 우선 (10개 플래그, 평평한 네임스페이스):
my-cli spreadsheet create --title "Q1 Budget" --locale "en_US" --timezone "America/Denver" --sheet-title "January" --sheet-type GRID --frozen-rows 1 --frozen-cols 2 --row-count 100 --col-count 10 --hidden false

에이전트 우선 (하나의 JSON 플래그):
gws sheets spreadsheets create --json '
{
  "properties": {"title": "Q1 Budget", "locale": "en_US", "timeZone": "America/Denver"},
  "sheets": [{"properties": {"title": "January", "sheetType": "GRID", "gridProperties": {"frozenRowCount": 1, "frozenColumnCount": 2, "rowCount": 100, "columnCount": 10}, "hidden": false}}]
}'

gws CLI는 모든 입력에 대해 --params와 --json 플래그를 사용하여 전체 API 페이로드를 직접 수락합니다. 권장 접근 방식은 별도의 도구를 유지하는 대신 동일한 바이너리에서 두 경로를 모두 지원하는 것입니다.

추가 고려사항

이 글은 에이전트 우선 CLI를 위한 몇 가지 다른 설계 고려사항을 설명합니다:

• 스키마 인트로스펙션: 에이전트가 런타임에 검사할 수 있는 자체 설명 스키마
• 컨텍스트 창 규율: 에이전트 컨텍스트 제한 내에 맞도록 출력 관리
• 입력 강화: 에이전트 환각 현상에 대한 보호
• 에이전트 스킬: 단순 명령어가 아닌 기능 제공
• 다중 표면 지원: MCP, 확장 프로그램 및 환경 변수와의 작업
• 안전 장치: 시험 실행 모드 및 응답 정제

CLI는 AI 에이전트가 외부 시스템과 상호작용하는 가장 낮은 마찰 인터페이스가 되어가고 있으며, 인간 지향적 인터페이스보다 결정적이고 기계 가독 가능한 출력이 필요합니다.