사람용 CLI와 AI 에이전트용 CLI는 설계가 다르다

예전에는 CLI를 사람만 썼다. 지금은 Claude Code 같은 AI 에이전트가 CLI를 호출해 업무를 자동화한다. 같은 도구라도 "에이전트가 쓰기 좋게" 설계하면 자동화가 훨씬 매끄럽고, 그러지 않으면 자동화가 자주 깨진다.

여러 업무 자동화 CLI를 직접 만들어 에이전트로 호출해 보면서 정리한 설계 원칙을 공유한다. (예시는 공개한 개인 도구 dooray-cli·nhncloud-cli에서 가져왔다.)

왜 다른가

사람은 출력을 눈으로 읽고, 모호하면 다시 입력하고, 위험한 작업은 알아서 조심한다. 에이전트는 그렇지 못하다. 출력을 기계적으로 파싱해야 하고, 입력 형식이 어긋나면 멈추며, 위험한 작업도 시키면 그냥 한다. 그래서 에이전트가 쓸 CLI는 출력·확인·안전을 사람용과 다르게 설계해야 한다.

1. 기계가 읽을 수 있는 출력 (--json)

사람용 표 출력은 에이전트가 파싱하기 어렵다.

• --json 플래그로 구조화된 결과를 내보내면, 에이전트가 결과를 받아 다음 단계로 바로 넘길 수 있다.
• 사람용 표 출력과 기계용 JSON 출력을 분리해 둔다 — 둘 다 필요하다.

2. 미리보기 (--dry-run)

에이전트는 위험한 작업도 망설임 없이 실행한다.

• --dry-run으로 "실행하면 무엇이 일어나는지"만 보여주고 실제로는 바꾸지 않는 모드를 둔다.
• 에이전트(또는 사람)가 미리보기로 확인한 뒤 실제 실행을 결정할 수 있다.
• 파일을 만들거나 외부에 전송하는 명령일수록 미리보기의 가치가 크다.

3. 비대화형 모드 (--quiet, --no-confirm)

대화형 프롬프트("정말 진행할까요? y/n")는 사람에겐 친절하지만 에이전트·자동화 환경에선 멈춤의 원인이다.

• --no-confirm으로 확인 단계를 건너뛰고, --quiet으로 진행 로그를 줄여 결과만 깔끔하게 남긴다.
• CI 파이프라인이나 에이전트 호출에서 사람이 끼어들지 않아도 끝까지 돈다.

4. 안전장치는 기본값으로

비대화형으로 만들수록 안전장치를 도구 안에 내장해야 한다.

• 같은 파일을 덮어쓰거나 중복 생성하려 하면 경고하거나 막는다.
• 외부 제출·삭제·게시처럼 되돌리기 어려운 작업은 기본적으로 막고, 명시적 플래그가 있을 때만 수행한다.
• "에이전트가 시키는 대로 다 한다"는 전제 위에서 위험한 기본 동작을 없앤다.

5. 입력을 너그럽게 해석한다

에이전트는 정확한 입력 형식을 항상 알지는 못한다.

• 같은 대상을 URL·ID·코드·이름 등 여러 형식으로 받아 자동으로 분기해 처리한다.
• 예를 들어 사람 지정은 이름(부분 일치)·이메일(정확히)·내부 ID(직접) 중 무엇으로 줘도 동작하게 한다.
• 입력 형식을 까다롭게 받으면 에이전트가 자주 막히고, 너그럽게 받으면 자동화가 매끄러워진다.

정리

에이전트가 호출할 도구는 다음을 갖추면 자동화가 잘 깨지지 않는다.

• 기계가 읽는 출력(--json)
• 미리보기(--dry-run)
• 비대화형 모드(--quiet/--no-confirm)
• 되돌리기 어려운 작업의 기본 차단
• 너그러운 입력 해석

이렇게 만든 CLI를, 반복 작업을 절차로 고정한 skill이 호출하면 업무 자동화가 한 단계 더 매끄러워진다. skill로 절차를 고정하는 쪽은 Claude Code의 Skill 시스템에서 다룬다.