인간과 에이전트를 위해 구축된 Spaces CLI

TL;DR

Mistral AI는 단 세 개의 명령어로 멀티 서비스 프로젝트를 생성, 실행 및 배포할 수 있는 명령줄 인터페이스인 Spaces를 출시했습니다. 이 도구는 모든 대화형 프롬프트에 플래그나 설정 파일에 상응하는 옵션을 갖추도록 설계되어, 자율적인 AI 에이전트가 수동 개입 없이 도구를 사용할 수 있습니다.

훌륭한 개발자 경험이란 무엇인가

Spaces는 반복적인 설정 작업을 제거하는 데 집중합니다. 합리적인 디렉토리 레이아웃을 선택하고, 설정 파일을 자동 생성하며, 서비스를 서로 연결하여 다음과 같이 실행한 후에는 핫 리로드(hot-reload), 데이터베이스, Dockerfile을 갖춘 새로운 프로젝트를 즉시 실행할 수 있게 합니다:

$ spaces init my-project
$ cd my-project
$ spaces dev

CLI는 명령어를 세 가지 기능적 범주로 그룹화합니다:

  • Scaffolding – 프로젝트 구조를 생성하고, 질문을 던지며, 옵션을 보여줍니다.
  • Development – 단일 spaces dev 명령어로 내부 개발 루프를 실행합니다.
  • Operations – 명시적인 확인이 필요한 프로덕션 수준의 작업을 수행합니다.

두 번째 사용자를 위한 설계: AI 에이전트

AI 코딩 에이전트가 init을 위한 대화형 TUI 피커를 사용하려고 시도했을 때, 가공되지 않은 ANSI 이스케이프 코드를 마주하며 UI를 탐색할 수 없었습니다. 간단한 해결책은 --components 플래그를 노출하는 것이었지만, 더 깊은 통찰은 CLI에서 요청하는 모든 정보는 비대화형 표현 방식이 있어야 한다는 것이었습니다.

플래그를 통한 보편적 계약

각 대화형 질문은 하나의 계약을 나타냅니다: CLI는 계속 진행하기 위해 값이 필요합니다. 플래그, 설정 파일 또는 기본값을 제공함으로써, 입력 방식에 관계없이 동일한 비즈니스 로직이 실행됩니다. 구현 예시:

def init_command(
    components: str | None = Option(None),
    yes: bool = Option(False, "-y"),
):
    if components:
        selected = components.split(",")
    elif yes:
        selected = get_defaults()
    else:
        selected = show_picker()
    create_project(selected)

-y 플래그는 호출자가 프로그래밍 방식으로 필요한 모든 데이터를 제공함을 의미하며, 이로 인해 CLI는 stdin에서 멈추는 대신 필요한 입력이 누락되었을 경우 명확하게 오류를 발생시킵니다.

엔드 투 엔드 에이전트 워크플로우

에이전트는 이제 다음과 같이 할 수 있습니다:

  1. spaces --help를 실행하여 명령어 시그니처를 발견합니다.
  2. config.yaml 및 context.json을 자동으로 생성합니다.
  3. Dockerfile, 레지스트리 설정 및 CI 파이프라인을 사람의 개입 없이 연결합니다.
  4. 10분 이내에 Koyeb에서 프로젝트를 Space로 배포합니다.

각 대화형 프롬프트에 플래그에 상응하는 옵션이 있기 때문에, 에이전트는 시작부터 배포까지 자율적으로 작동합니다.

구조화된 데이터를 인터페이스 레이어로 사용

Spaces는 각 모듈이 하드코딩된 로직이 아닌 데이터 모델에 의해 설명되는 플러그인 시스템을 사용합니다:

class ModulePlugin(BaseModel):
    type_id: str
    category: str
    default_port: int
    def get_env_vars(self) -> list[EnvVarDef]: ...
    def get_dev_command(self, port: int) -> str: ...

플러그인은 내부를 들여다볼 수 있고(introspectable), JSON으로 직렬화할 수 있으며, 차이점을 비교(diff)할 수 있습니다. 인간은 TUI 피커를 통해 상호작용하고, 에이전트는 레지스트리를 조회하여 JSON을 받습니다. 이제 새로운 모듈을 추가하는 데는 새로운 플러그인 클래스만 필요하며, 이를 통해 피커, Dockerfile 생성기, compose 템플릿 전반에 걸친 중복 업데이트를를 방지할 수 있습니다.

에이전트를 위한 컨텍스트 제공

Spaces는 모든 init 시에 두 개의 파일을 생성합니다:

  • context.json – 프로젝트의 모듈, 포트, 명령어 및 환경 변수의 스냅샷.
  • AGENTS.md – LLM을 위한 명시적인 절차적 지침, 예: "database 변경 사항을 테스트하기 전에 mycli dev --migrate를 실행하세요."

이러한 아티팩트는 에이전트에게 신뢰할 수 있는 진실의 원천(source of truth)을 제공하여, 잘못된 포트를 사용하거나 중복된 의존성을 설치하는 것과 같은 추측을 통한 실수를를 방지합니다.

컨텍스트 파일은 캐시 버스터(cache-buster) 역할도 합니다. 프로젝트 설정이 변경될 때마다 자동으로 업데이트됩니다.

암묵적 상태 제거

암묵적 가정(예: 현재 작업 디렉토리(CWD)에 의존하는 것)은 에이전트 자동화를 방해합니다. 해결책은 모든 상태를 명시시킴으로써 합리적인 폴백(fallback)을 활용하는 것입니다:

# Before
config = load_config(Path.cwd() / "config.yaml")
# After
config = load_config(
    path or find_config_in_parents(Path.cwd())
)

CWD, 환경 변수, 그리고 dot-file 위치를 명시적으로 만드는 것은 에이전트의 신뢰성을 높이고 인간의 스크립팅 능력을 향상시킵니다.

에이전트 친화적 관행 Checklist

  • 모든 대화형 입력에는 상응하는 플래그가 있습니다.
  • 플래그는 헤드리스(headless) 실행을 위한 스마트한 기본값을 제공합니다.
  • 모든 상태(경로, 환경 변수, 설정)는 명시적으로 전달됩니다.
  • 플러그인은 순수 데이터 모델이며, 자동으로 내부를 들여다볼 수 있습니다.
  • context.json과 AGENTS.md는 에이전트에게 구조화된 프로젝트 설명서를 제공합니다.

왜 이것이 모두에게 더 나은 도구를 위한 데 도움이 되는가

에이전트 지향적 설계가 추가되었다고 해서 인간의 경험이 저하되지는 않습니다. TUI 피커, 스피너, 확인 대화창은 그대로 유지됩니다. 대신, 에이전트를 위해 요구되는 제약 조건(명시적 입력, 플래그 기반 계약, 구조화된 메타데이터)은 개발자에게 CLI를 더 조합 가능하고, 스크립트 작성이 가능하며, 테스트 가능하게 만듭니다.

Mistral AI는 모든 개발자 도구 제작자에게 모든 input() 호출, CWD 가정, 그리고 인간 전용 출력에 대해 검토하고, 비인간 프로세스가 동일한 인터페이스를를 사용할 수 있는지 질문해 볼 것을 권장합니다.

Spaces CLI는 Mistral AI의 Lorenzo Signoretti, Riwa Hoteit, Sam Fenwick이 구축하였으며, Applied AI 팀의 피드백을 받았습니다.

Sources