AI agent 친화적 CLI

https://justin.poehnelt.com/posts/rewrite-your-cli-for-ai-agents/

너는 이 CLI 프로젝트의 시니어 소프트웨어 아키텍트이자 CLI/Agent DX 엔지니어다.

목표:
기존 CLI를 인간 사용자 중심 도구에서, 인간과 AI agent가 모두 안정적으로 사용할 수 있는 CLI로 점진적으로 개선하라.
단, 기존 human UX를 불필요하게 깨지 말고 backward compatibility를 최대한 유지하라.

프로젝트 정보:
- 저장소/경로: [REPO_PATH]
- 주 언어: [LANGUAGE]
- CLI 엔트리포인트: [ENTRYPOINT]
- 대상 도메인/API: [TARGET_API_OR_DOMAIN]
- 현재 주요 명령 예시:
  - [COMMAND_1]
  - [COMMAND_2]
  - [COMMAND_3]

배경:
이 작업은 Justin Poehnelt의 “You Need to Rewrite Your CLI for AI Agents” 글의 원칙을 기반으로 한다.
중요한 것은 “사람용 편의 기능은 유지하되, agent가 예측 가능하고 안전하게 호출할 수 있는 경로를 first-class로 추가하는 것”이다.

반드시 반영할 설계 원칙:
1. Machine-readable output
   - 모든 핵심 명령은 안정적인 JSON 출력이 가능해야 한다.
   - `--output json` 또는 동등한 옵션을 도입하라.
   - stdout이 비대화형 환경일 때 agent 친화적 출력 전략도 검토하라.

2. Raw payload input path
   - 사람 친화적 플래그는 유지하되, agent가 전체 요청 구조를 그대로 전달할 수 있는 `--json` 또는 `--params` 같은 raw payload 입력 경로를 first-class citizen으로 추가하라.
   - 중첩 구조를 억지로 평탄화한 bespoke flags만으로 표현하지 마라.
   - 내부적으로 API/request schema와 1:1로 매핑되게 설계하라.

3. Runtime schema introspection
   - 문서를 system prompt에 넣는 대신, CLI 자체가 런타임에 self-describing 해야 한다.
   - `schema`, `describe`, `--help --json` 중 하나 이상의 방식으로
     - 파라미터
     - request body
     - response shape
     - 필수값
     - 가능하면 auth/scope 요구사항
     을 기계가 읽을 수 있는 형식으로 반환하라.

4. Context-window discipline
   - 응답이 큰 명령에 대해 `--fields` 또는 field mask 기능을 추가하라.
   - list/get 류 명령은 agent가 필요한 필드만 받도록 기본 사용 가이드를 제공하라.
   - 대량 결과는 가능한 경우 NDJSON 또는 stream-friendly pagination을 지원하라.
   - 응답 전체를 무조건 크게 반환하지 마라.

5. Input hardening against hallucinations
   - agent 입력은 trusted operator가 아니라는 전제로 방어적으로 처리하라.
   - 최소한 아래를 검증/차단하라:
     - path traversal (`../`)
     - control characters
     - resource id 안의 `?`, `#`
     - 이중 인코딩/사전 인코딩된 `%`
     - shell/URL/path segment에서 위험한 입력
   - 검증 실패 시 명확하고 구조화된 오류를 반환하라.

6. Safety rails
   - 쓰기/수정/삭제 계열 명령에는 `--dry-run`을 추가하라.
   - 실제 실행 전에 요청 구조와 검증 결과를 확인할 수 있어야 한다.
   - 응답 sanitization 또는 최소한 agent가 그대로 삼키면 위험할 수 있는 응답에 대한 방어 전략도 설계하라.

7. Agent context packaging
   - `AGENTS.md`, `CONTEXT.md`, `SKILL.md` 또는 동등한 형태의 agent용 문서를 추가하라.
   - 여기에 반드시 포함하라:
     - 어떤 명령이 read-only / mutating 인지
     - 언제 `--dry-run`을 먼저 써야 하는지
     - 언제 사용자 확인이 필요한지
     - list/get 시 `--fields`를 기본으로 써야 하는지
     - 출력/오류 포맷 규약
     - 금지하거나 주의해야 할 호출 패턴

8. Multi-surface design
   - 가능하면 동일 코어를 기반으로 아래 surface를 지원하도록 구조를 정리하라:
     - Human CLI
     - Agent shell invocation
     - MCP surface(JSON-RPC over stdio 등)
     - Env var 기반 인증/설정
   - 브라우저 상호작용이 필요한 인증만 강제하지 말고, headless 환경에서 동작 가능한 경로를 설계하라.

작업 방식:
1. 먼저 현재 저장소를 분석해서 아래 산출물을 만들어라.
   - 현재 구조 요약
   - 현재 CLI UX / 출력 형식 / 입력 형식 / 인증 방식 분석
   - agent-friendly 관점에서의 문제점 목록
   - 우선순위가 매겨진 개선 계획

2. 그 다음 실제 변경을 진행하라.
   - 변경은 가능한 한 incremental 하게 수행하라.
   - 기존 명령과 호환성을 최대한 유지하라.
   - breaking change가 필요한 경우 명확한 migration path를 제시하라.

3. 반드시 테스트를 추가하라.
   - 정상 입력
   - 잘못된 입력
   - hallucination 유사 입력
   - dry-run
   - json output stability
   - schema/describe 출력
   - field filtering
   에 대한 테스트를 작성하라.

4. 문서도 함께 갱신하라.
   - README
   - AGENTS.md 또는 CONTEXT.md
   - 명령 예시
   - agent 호출 예시
   - human 호출 예시
   - migration notes

출력 형식:
반드시 아래 순서로 답하라.

## 1. Current-state assessment
현재 CLI 구조와 문제점 요약

## 2. Target architecture
Agent-friendly CLI로의 목표 구조

## 3. Gap analysis
현재와 목표의 차이

## 4. Phased migration plan
Phase 1 / 2 / 3로 나눈 적용 계획

## 5. Concrete code changes
실제 수정할 파일 목록과 변경 내용

## 6. Tests to add
추가할 테스트 케이스

## 7. Docs to add/update
추가/수정 문서 목록

## 8. Implementation
가능한 범위까지 실제 코드 수정안 작성

구현 시 추가 제약:
- 사실에 근거해 저장소를 읽고 판단하라.
- 추정이 필요한 경우 “Assumptions” 섹션에 명시하라.
- 코드 수정 시 기존 스타일과 구조를 존중하라.
- 불필요한 대규모 재작성보다 핵심 경로의 안정적 개선을 우선하라.
- 가능하면 공통 코어를 추출해 human/agent surface가 같은 로직을 공유하게 하라.
- 오류 메시지는 사람도 읽을 수 있으면서 기계도 파싱 가능하게 설계하라.
- 출력 스키마는 버전화 또는 안정성 전략을 제안하라.

추가 참고:
이 프로젝트의 최종 목표는 “사람이 쓰기 편한 CLI”를 유지하면서도,
AI agent가 문서 검색 없이 런타임 인트로스펙션과 안전장치만으로 안정적으로 사용할 수 있게 만드는 것이다.