사람과 에이전트를 위한 CLI, Spaces

Spaces는 내부 플랫폼용 CLI를 만들며 사람과 에이전트 모두에 맞는 설계를 찾았다. spaces init my-project와 spaces dev만으로 프로젝트 생성, 개발 환경 구동, 설정 생성, 스테이징 배포까지 이어지는 흐름을 만들었고, 이 CLI는 결국 인간뿐 아니라 코딩 에이전트의 도구가 됐다.

사람에게 좋은 CLI의 기준은 분명했다. Scaffolding은 구조를 만들고 선택지를 보여주며, Development는 바로 실행되고, Operations는 신중하게 다뤄져야 한다. TUI 기반 선택기는 보기에는 좋았지만, 에이전트는 ANSI 코드와 키보드 입력을 처리할 수 없어 막혔다.

핵심 해법은 모든 인터랙션을 플래그로 환원하는 것이었다. 입력 방식보다 필요한 정보를 먼저 생각하고, 그 정보를 플래그·기본값·설정 파일로 공급할 수 있게 만들었다. -y는 단순히 확인을 건너뛰는 옵션이 아니라, stdin에 멈추지 말고 필요한 값을 전부 프로그램적으로 해결하라는 계약이 됐다.

구체적으로는 다음과 같은 방향으로 바뀌었다.

• --components처럼 인터랙티브 질문의 비대화형 대안을 제공
• -y 모드에서는 모든 프롬프트가 플래그 값이나 스마트 기본값으로 해결되도록 설계
• 실행 로직은 입력 경로와 분리해 한 번만 테스트 가능하게 구성

두 번째 축은 구조화된 데이터였다. 모듈 타입을 하드코딩하지 않고, 각 컴포넌트가 자신의 속성과 동작을 선언하는 플러그인 시스템을 만들었다. 사람은 TUI에서 고르고, 에이전트는 레지스트리를 질의해 JSON으로 받는다. 같은 데이터지만 렌더링만 달라진다.

이 변화는 유지보수도 단순화했다. 새 모듈을 추가할 때 예전에는 picker, Dockerfile 생성기, env 파일 writer, compose 템플릿을 모두 고쳐야 했지만, 이제는 플러그인 클래스 하나를 추가하면 된다. 레지스트리가 단일 진실 공급원이 됐다.

에이전트가 프로젝트를 더 잘 이해하도록 **context.json**과 **AGENTS.md**도 init 때 생성한다. 전자는 모듈, 포트, 실행 명령, env var를 담은 구조화된 스냅샷이고, 후자는 LLM용 실행 규칙이다. 에이전트는 이를 먼저 읽고 나서야 작업하므로 포트 추측, 잘못된 테스트 명령 실행, 이미 관리되는 의존성 재설치 같은 실수를 크게 줄인다.

마지막 문제는 암묵적 상태였다. config.yaml을 현재 작업 디렉터리에서 찾는 방식은 사람에겐 자연스럽지만, 워크스페이스 루트에서 실행하는 에이전트에겐 함정이다. 그래서 CWD 의존을 줄이고, 명시적 경로와 부모 디렉터리 탐색을 조합한 방식으로 바꿨다.

정리하면, 효과가 컸던 원칙은 이렇다.

• 모든 인터랙티브 입력에는 플래그 대응값이 있어야 한다
• 모든 플래그에는 헤드리스 모드용 스마트 기본값이 있어야 한다
• CWD, env var, dotfile 같은 숨은 상태는 입력으로 드러내야 한다
• 플러그인은 코드 조각이 아니라 데이터 모델이어야 한다
• context.json 같은 컨텍스트 파일이 에이전트와 CI, 스크립트 모두를 돕는다

결과적으로 CLI는 사람에게도 더 나아졌다. TUI와 스피너, 확인 대화상자는 그대로 유지하면서, 에이전트가 들어올 수 있는 두 번째 문을 열었다. 사람과 에이전트의 제약은 결국 같은 문제를 가리키며, 그 제약을 만족시키는 설계가 곧 더 컴포저블하고 스크립트 가능하며 테스트 가능한 도구를 만든다.