에이전트가 탐색하고 실패를 판단할 수 있는 CLI

진행 기간: 2026.10.13–2026.10.24 (이번에 확인한 최근 변경 범위)

Dooray CLI와 NHN Cloud CLI를 개인 프로젝트로 개발했다. 업무에 활용하지만 회사 서비스의 구현 실적으로 합산하지 않는다. 사람이 읽는 화면 외에 에이전트가 명령을 찾고 결과를 판단할 수 있는 출력과 오류 계약을 마련했다.

명령 탐색과 결과 처리를 프로그램에 맞췄다

두 CLI는 --json 출력과 오류 종료 코드를 제공한다. NHN Cloud CLI의 commands --json은 명령 경로와 옵션을 탐색하게 하므로, 에이전트가 명령을 추측하기 전에 지원 여부와 인자를 확인할 수 있다. 종료 코드는 성공 0, API 오류 1, 인증 오류 2, 인자 오류 3, 설정 오류 4로 구분한다. 출력과 종료 코드는 도구 호출 결과를 해석하는 계약이며, 올바른 업무 대상을 선택했다는 보장까지 제공하지 않는다.

HTTP 성공과 API 성공을 구분했다

클라우드 CLI의 최근 변경에서는 HTTP 상태만으로 인증 성공을 판단하지 않고 응답 봉투의 resultCode도 확인했다. 3b56d3f는 봉투의 인증 오류를 종료 코드 2로 분류했고, 159070d는 HTTP 5xx 봉투 안의 401·403을 인증 오류로 오인하지 않게 보완했다(2026.10.19). 인증 실패로 오분류하면 에이전트가 서버 장애에 자격 증명 재설정으로 대응할 수 있어 오류 계층을 나눠야 했다. 커밋 41d274a가 명시하듯 403 응답의 실제 호출 검증은 확인되지 않았으므로, 모든 오류 조합을 운영에서 재현했다고 쓰지 않는다.

경로 값의 인코딩만으로 막히지 않는 입력을 거부했다

Dooray CLI의 src/api/api-path.ts에 있는 apiPath는 경로 인자를 인코딩한다. 그러나 빈 값과 .·..은 URL 정규화로 다른 경로를 가리킬 수 있어 별도로 거부한다(f695232, 2026.10.24). src/api/api-path.test.ts에서 이 입력 경계를 검사한다. 명령 인자가 문자열로 유효하다는 것과 의도한 API 자원을 가리킨다는 것은 다른 조건이었다.

기여와 검증 범위

위 변경은 본인 명의 커밋과 현재 소스에서 확인했다. AI 에이전트를 활용한 개발이며, 커밋 작성자만으로 모든 구현을 수작업하거나 단독 설계했다고 단정하지 않는다. 명령 탐색은 클라우드 CLI의 src/commands/commands.test.ts, 경로 처리는 업무 CLI의 api-path.test.ts에서 테스트 소스를 확인했다. 이번 기록 보강에서는 원본 프로젝트의 테스트나 실제 API 호출을 실행하지 않았다. 도입 팀 수, 업무 시간 절감과 에이전트 성공률은 별도 측정 근거가 없어 성과 수치로 제시하지 않는다.