AI 에이전트를 위한 CLI 설계

이전 글에서 AI 에이전트에게 가장 적합한 도구는 CLI라고 강조한 적이 있다. GUI보다는 텍스트 기반의 명령어가 기계와 기계, 혹은 인간과 기계 사이의 소통에서 훨씬 명확하기 때문이다. 하지만 단순히 CLI를 제공하는 것만으로는 부족하다. 최근 AI 에이전트의 특성에 맞춰 CLI를 어떻게 설계해야 하는지에 대해 다룬 훌륭한 글을 발견했다. 이 글을 바탕으로 AI 친화적인 CLI가 갖춰야 할 구체적인 요소들을 정리해 보려 한다.

AI 에이전트가 소프트웨어를 조작하는 방식은 우리가 생각하는 것보다 훨씬 정교하면서도 동시에 투박하다. 인간 사용자는 터미널에 출력되는 텍스트의 배치를 보고 직관적으로 상황을 파악하지만, LLM 기반의 AI 에이전트는 텍스트 덩어리를 토큰 단위로 쪼개어 분석한다. 이 과정에서 불필요한 장식이나 가독성을 위해 넣은 공백들은 오히려 AI에게 노이즈로 작용할 수 있다. 따라서 AI 에이전트를 위한 CLI 설계의 첫 번째 원칙은 데이터의 구조화와 예측 가능성이다. 단순히 텍스트를 뿌려주는 것이 아니라, 기계가 이해할 수 있는 명확한 규격이 필요하다.

가장 효과적인 방법은 역시 JSON 출력을 기본으로 지원하는 것이다. 많은 현대적인 CLI 도구들이 이미 --output json 같은 옵션을 제공하고 있지만, 이를 단순히 부가 기능으로 여겨서는 안 된다. AI 에이전트가 CLI를 호출했을 때 반환되는 JSON 데이터는 별도의 파싱 로직 없이도 다음 체인의 입력값으로 즉시 활용될 수 있다. 이는 AI의 추론 비용을 낮추고 결과의 정확도를 비약적으로 높여준다. 만약 JSON 출력이 표준화되어 있다면, AI는 별도의 정규 표현식을 작성하거나 텍스트에서 숫자를 찾아내려 애쓸 필요가 없어진다.

두 번째로 중요한 점은 상호작용의 완전한 배제다. 우리는 습관적으로 파괴적인 작업을 수행하기 전에 'Are you sure? (y/n)'와 같은 프롬프트를 띄우도록 설계한다. 하지만 AI 에이전트 환경에서 이러한 대화형 프롬프트는 치명적인 장애물이다. AI가 백그라운드에서 작업을 수행하다가 입력을 기다리며 멈춰버리면 전체 워크플로우가 중단된다. 이를 방지하기 위해 모든 명령어는 비대화형 모드를 지원해야 하며, --yes나 --force 같은 플래그를 통해 모든 결정을 명령 시점에 확정할 수 있도록 해야 한다. 환경 변수를 통해 인터랙티브 모드를 강제로 끄는 설정도 좋은 대안이 된다.

에러 메시지 설계 또한 AI 에이전트 시대에는 새로운 관점이 필요하다. 기존의 에러 메시지가 '무엇이 실패했는가’에 집중했다면, AI를 위한 에러 메시지는 '어떻게 해결할 수 있는가’를 포함해야 한다. AI 에이전트는 실행 결과로 돌아온 에러 텍스트를 읽고 스스로 수정을 시도할 수 있는 능력이 있다. 예를 들어 단순히 'Invalid argument’라고 출력하기보다 'The --timeout value must be an integer between 1 and 60’처럼 구체적인 제약 조건을 명시해 주면, AI는 즉시 값을 수정하여 재시도한다. 이러한 셀프 힐링 구조는 자동화의 완성도를 한 단계 끌어올린다.

마지막으로 명령어의 도움말(help) 자체가 AI를 위한 매뉴얼이라는 사실을 잊지 말아야 한다. AI 에이전트는 새로운 도구를 접하면 가장 먼저 --help를 입력하여 사용 가능한 옵션과 인자를 탐색한다. 이때 제공되는 설명이 모호하거나 예시가 부족하면 AI는 잘못된 가정을 바탕으로 명령을 생성하게 된다. 각 옵션의 기본값, 가능한 값의 범위, 그리고 실제 활용 예시를 도움말에 상세히 기술하는 것만으로도 AI의 도구 활용 능력을 극적으로 향상시킬 수 있다. 이제 문서화는 인간 개발자뿐만 아니라 AI 에이전트를 위한 교육 자료로서 기능해야 한다.

결론적으로 우리가 만드는 CLI는 이제 인간과 AI라는 두 종류의 사용자를 동시에 만족시켜야 한다. 사용자 경험(UX)이라는 용어가 오랫동안 인터페이스 설계의 중심이었다면, 이제는 에이전트 경험(AX)이라는 새로운 기준을 도입해야 할 때다. 기계가 읽기 좋은 코드를 짜는 것이 클린 코드의 기본이듯, 기계가 다루기 좋은 인터페이스를 설계하는 것이 현대 소프트웨어 엔지니어링의 핵심 역량이 될 것이다. CLI는 그 변화의 최전선에 있는 가장 강력한 도구다.