AI 에이전트가 CLI를 사용할 때 어떤 실수를 할까요? 오타? 아닙니다. 에이전트는 ../../.ssh 같은 경로를 멀쩡히 생성하거나, 리소스 ID 안에 ?fields=name을 슬쩍 끼워 넣습니다. 인간은 절대 이런 실수를 하지 않죠.

Google Workspace CLI를 처음부터 에이전트 우선으로 설계한 엔지니어 Justin Poehnelt가 그 경험을 정리해 공개했습니다. 핵심 주장은 단순합니다. “Human DX(개발자 경험)와 Agent DX는 목표 자체가 다르다. 인간용 CLI를 에이전트에게 그냥 쥐어주는 건 지는 싸움이다.”

출처: You Need to Rewrite Your CLI for AI Agents – justin.poehnelt.com

에이전트는 ‘새로운 방식’으로 틀린다

인간이 CLI를 쓸 때 흔한 실수는 오타, 플래그 순서 혼동, 잘못된 파일명 정도입니다. 에이전트의 실수 패턴은 완전히 다릅니다.

• 파일 경로에 ../../.ssh 같은 경로 순회를 넣는다
• 리소스 ID 뒤에 ?fields=name을 붙여 쿼리 파라미터를 ID처럼 사용한다
• 이미 URL 인코딩된 문자열을 다시 인코딩해 %2e%2e 같은 이중 인코딩을 만든다
• 눈에 보이지 않는 제어 문자를 문자열 출력에 끼워 넣는다

이건 단순한 버그가 아닙니다. LLM이 hallucination을 일으키는 방식이 바로 이렇습니다. 글에서는 이를 “에이전트는 신뢰할 수 없는 오퍼레이터다”라고 표현합니다. 웹 API가 사용자 입력을 검증하듯, CLI도 에이전트 입력을 방어적으로 처리해야 한다는 뜻입니다.

인간이 싫어하는 것을 에이전트는 좋아한다

가장 흥미로운 역전이 있습니다. 인간은 터미널에서 중첩된 JSON을 직접 쓰는 걸 싫어합니다. 에이전트는 오히려 선호합니다.

--title "My Doc" 같은 편의 플래그는 사람이 쓰기엔 편하지만, 중첩 구조를 표현할 수 없습니다. 반면 --json '{...전체 API 페이로드...}' 형식은 LLM이 손쉽게 생성할 수 있고, API 스키마와 1:1로 대응되니 번역 손실도 없습니다.

문서를 미리 시스템 프롬프트에 넣어두는 것도 에이전트에게 비효율적입니다. API 버전이 바뀌는 순간 문서가 낡아버리고, 토큰도 낭비됩니다. 대신 gws schema sheets.spreadsheets.create 같은 명령으로 에이전트가 런타임에 직접 스키마를 조회하도록 하면, CLI 자체가 살아있는 문서가 됩니다.

에이전트에게 ‘직관’을 주입하는 스킬 파일

에이전트는 --help를 읽고 스스로 노하우를 쌓지 않습니다. 인간이라면 경험으로 터득할 “리스트 조회할 때는 항상 필드 마스크를 쓰세요”, “변경 작업 전엔 dry-run 먼저 하세요” 같은 규칙을 명시적으로 알려줘야 합니다.

Justin이 만든 gws CLI는 API 서피스별로 100개 이상의 SKILL.md 파일을 포함합니다. 에이전트가 대화 시작 시 이 파일을 컨텍스트로 주입받아, 직관 없이도 올바른 사용 패턴을 따를 수 있도록 설계했습니다.

이 접근은 MCP(Model Context Protocol)와도 자연스럽게 연결됩니다. 같은 바이너리를 CLI, MCP 서버, Gemini Extension 등 여러 인터페이스로 동시에 노출할 수 있고, 모두 동일한 Discovery Document를 단일 소스로 참조합니다.

에이전트가 외부 시스템을 다루는 도구를 만들 때 어떤 철학이 필요한지를 잘 보여주는 사례입니다. 구체적인 구현 패턴과 코드 예시, 그리고 후속 글 The MCP Abstraction Tax도 원문에서 확인할 수 있습니다.