사람용 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(직접) 중 무엇으로 줘도 동작하게 한다.
• 입력 형식을 까다롭게 받으면 에이전트가 자주 막히고, 너그럽게 받으면 자동화가 매끄러워진다.
• 이름으로 찾을 때는 규칙을 하나로 통일한다. 정확히 일치하는 값을 먼저 찾고, 없으면 부분 일치를 찾고, 후보가 여러 개로 남으면 고르지 않고 에러로 끝낸다. 모호한 입력을 추측해서 처리하면 에이전트가 엉뚱한 대상을 바꾸고도 성공으로 받아들인다.

6. stdout 은 데이터, stderr 는 로그와 에러

에이전트는 stdout 만 파싱하는 경우가 많다. 진행 표시, 경고, 에러 메시지가 같은 스트림에 섞이면 --json 출력도 JSON 으로 읽히지 않는다.

• 결과 데이터는 stdout 으로, 진행 표시와 에러는 stderr 로 보낸다.
• 스피너 같은 진행 표시도 stderr 로 보낸다. dooray-cli 의 스피너는 stderr 스트림에 그린다.
• 에러 메시지는 사람이 읽을 수 있게 쓰되 stdout 에는 한 글자도 쓰지 않는다.

7. 종료 코드를 한 곳에서 정한다

에이전트는 메시지 문장이 아니라 종료 코드로 성공과 실패를 판단한다. 명령마다 process.exit 를 흩어 두면 같은 실패가 명령에 따라 다른 코드로 끝난다.

• 에러 타입을 하나로 두고 메시지와 종료 코드를 함께 담는다. dooray-cli 는 DoorayCliError(message, exitCode) 를 던지고, 진입점의 최상위 핸들러가 한 번만 stderr 에 출력한 뒤 그 코드로 종료한다.
• 명령 코드는 process.exit 를 직접 부르지 않고 에러를 던지기만 한다. 일부만 실패한 파일 일괄 내려받기처럼 끝까지 진행해야 하는 경우에만 process.exitCode 를 설정한다. 종료 방식이 한 곳에 모이므로 코드 체계를 바꿔도 명령을 고칠 필요가 없다.

8. 참조는 앱으로 이동할 수 있는 링크로 출력한다

업무, 문서처럼 다른 시스템의 대상을 가리킬 때는 ID 만 출력하지 않고 그 시스템이 인식하는 표준 링크로 출력한다. dooray-cli 는 업무를 dooray://<조직 ID>/tasks/<업무 ID> 형태의 deeplink(앱 내 특정 화면으로 바로 이동하는 URI)로 출력한다.

• 사람은 링크를 눌러 바로 이동한다.
• 에이전트가 그 링크를 댓글이나 본문에 옮겨 적으면 대상 시스템이 업무로 자동 인식한다.

9. 반복 조회는 캐시하고 변경하면 무효화한다

이름을 ID 로 바꾸는 resolver 는 명령마다 같은 목록 API 를 다시 호출하기 쉽다. 에이전트는 한 세션에서 명령을 수십 번 부르므로 이 낭비가 그대로 쌓인다.

• 이름에서 ID 로 바꾼 결과를 TTL(만료 시간) 캐시에 저장한다. dooray-cli 는 멤버, 프로젝트, 위키, 태그, 템플릿의 변환 결과를 파일로 저장하고 갱신 시각이 TTL 을 넘으면 다시 조회한다.
• 캐시된 엔티티를 바꾸는 mutation(생성, 수정, 삭제)이 성공하면 관련 캐시를 곧바로 무효화한다. 그렇지 않으면 방금 만든 태그를 다음 명령이 찾지 못한다.
• API client 는 순수한 HTTP 래퍼로 두고 캐시 정책을 섞지 않는다. mutation 과 무효화를 같은 service 의 책임으로 묶으면 새 명령을 추가할 때 무효화를 빠뜨리기 어렵다.
• 캐시가 의심될 때 사람이나 에이전트가 직접 지울 수 있는 명령(cache clear)도 함께 둔다.

정리

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

• 기계가 읽는 출력(--json)
• 미리보기(--dry-run)
• 비대화형 모드(--quiet/--no-confirm)
• 되돌리기 어려운 작업의 기본 차단
• 너그러운 입력 해석
• stdout 과 stderr 의 분리
• 한 곳에서 정하는 종료 코드
• 이동할 수 있는 링크 형태의 참조 출력
• TTL 캐시와 변경 후 무효화

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