AI 에이전트를 위한 CLI 디자인 패턴: 오해와 실용적 접근법

CLI 인터페이스 프로토콜 명확화

1부에서 가장 큰 오해는 'CLI'가 LLM에 리눅스 터미널을 제공하는 것을 의미한다는 것이었습니다. CLI는 실제로 인터페이스 프로토콜입니다: 텍스트 명령어 입력 → 텍스트 결과 출력. 구현은 두 가지 방식으로 이루어질 수 있습니다:

• 셸의 PATH에 있는 바이너리나 스크립트로 — 실제 셸에서 실행되는 CLI 도구가 됨
• 코드 내부의 명령어 파서로 — LLM이 run(command="weather --city Tokyo")를 출력할 때, 문자열을 파싱하여 셸 없이 애플리케이션 코드에서 직접 실행함

핵심은 LLM이 CLI를 사용하는 것처럼 느끼게 만드는 것입니다. 저자의 시스템에서는 대부분의 명령어가 OS에 닿지 않습니다 — 명령어 라우터가 디스패치하는 Go 함수입니다. 실제 OS가 진정으로 필요한 명령어(스크립트 실행, 패키지 설치)만 격리된 마이크로-VM으로 전달됩니다. 에이전트는 어떤 계층이 자신의 명령어를 처리하는지 알지 못하며 신경 쓰지 않습니다.

에이전트 친화적 CLI 설계 원칙

두 가지 핵심 철학

철학 1: 유닉스 스타일 도움말 설계

• tool --help → 최상위 명령어 목록
• tool <command> --help → 해당 하위 명령어의 구체적인 매개변수와 사용법

이를 통해 에이전트가 사전에 모든 문서를 컨텍스트에 넣지 않고도 필요에 따라 기능을 발견할 수 있습니다.

철학 2: 팁 사고방식

모든 응답 — 특히 오류 — 은 불필요한 탐색을 줄이는 지침을 포함해야 합니다.

나쁜 예:

> cat photo.png [error] binary file

좋은 예:

> cat photo.png [error] cat: binary file detected (image/png, 182KB). Use: see photo.png (view image) Or: cat -b photo.png (base64 encode)

중요한 이유: 유효하지 않은 탐색은 토큰을 낭비합니다. 다중 터너 대화에서 이 낭비는 누적됩니다 — 모든 실패한 시도는 컨텍스트에 남아, 이후 모든 터너에 대한 주의와 추론 자원을 소비합니다. 단 하나의 유용한 힌트가 대화의 나머지 부분에서 상당한 토큰을 절약할 수 있습니다.

안전한 CLI 설계

CLI 명령어가 위험하거나 되돌릴 수 없는 작업을 포함할 때, 도구 자체가 안전 메커니즘을 제공해야 합니다.

드라이런 / 변경 미리보기 — 실수 방지

에이전트의 권한 내에서 이루어지지만 되돌리기 어려운 결과를 초래하는 작업을 위해. 목표는 에이전트(또는 인간)가 실행하기 전에 무슨 일이 일어날지 볼 수 있게 하는 것입니다.

> dns update --zone example.com --record A --value 1.2.3.4 ⚠ DRY RUN: A record for example.com: 5.6.7.8 → 1.2.3.4 Propagation: ~300s. Not instantly reversible. To execute: add --confirm

미리보기는 현재 상태가 무엇이고 무엇으로 변경될지 명확히 보여줘야 합니다. 에이전트는 --confirm으로 확인합니다.

인간 승인 — 에이전트의 자율성을 넘어서는 작업

인간의 판단이나 승인이 필요한 작업을 위해 — 에이전트가 얼마나 확신하든, 이것들을 스스로 완료할 수 없습니다.

접근법 1: 차단형 푸시 승인

> pay --amount 500 --to vendor --reason "office supplies for Q2" ⏳ Approval required. Notification sent to your device. Waiting for response... ✓ Approved. Payment of $500 completed. [exit:0 | 7.2s]

애플의 기기 로그인 확인과 유사합니다 — CLI는 전체 컨텍스트(금액, 수신자, 사유)와 함께 인간의 기기에 직접 푸시 알림을 보냅니다. CLI는 인간이 승인하거나 거부할 때까지 차단된 후, 결과를 에이전트에 반환합니다.

접근법 2: 확인 코드 / 2FA

> transfer --from savings --to checking --amount 10000 ⚠ This operation requires 2FA verification. Reason: transferring $10,000 between accounts. A code has been sent to your authenticator. Re-run with: --otp <code>