관련메타
-
- 리터레이트 프로그래밍 계보
- †조직모드 §org-mode - Org-babel, 코드 블록 실행
- †워크플로우자동화 - 프로젝트별 스크립트 관리
-
- AI 에이전트 접근성
- †ai프롬프트 - 에이전트가 호출하는 명령어 구조
- † 비서-도우미-튜터 에이전트 - CLI를 통한 자동화
- †-바이브코딩-vibecoding - 인간과 AI의 협업 워크플로우
-
- 자동화 생태계
- †#자동#자동완성#따라#자동화 - 스크립트 자동화 메타
-
- 셀프 트래킹과 메타 시스템
- † 메멕스 셀프트레킹 - 자기 문서화의 철학적 기반
- †-어쏠로그__autholog - 자신의 사고/작업을 기록
태그 변경 사항 파일 경로가 llmlog/20260212T103100--self-documenting-cli... 형식으로 자동 변경되었습니다. Denote 링크는 identifier 기반이라 경로 변경에도 안전합니다.
📊 Tokens: 33,856 in, 609 out
@user 좋다
관련노트
히스토리
- memex-kb/run.sh 구현 경험 반영 (v2 Registry + Introspection 패턴, Bash 함정 등)
- 생성
Self-documenting CLI란?
Self-documenting CLI(Self-documenting Command-Line Interface)는 스크립트 자체가 문서이자 실행기 역할을 하는 디자인 패턴입니다. 사용자 매뉴얼과 실행 도구를 분리하지 않고, 하나의 스크립트로 통합합니다.
핵심 특징
- 이중 인터페이스: 인간은 interactive 메뉴로, 에이전트는 CLI 인자값으로 동일한 기능에 접근
- 자기 설명적: 스크립트를 실행하면 사용 가능한 명령어와 설명을 바로 확인 가능
- 단일 진입점: 프로젝트당 하나의
run.sh또는manage.sh스크립트로 모든 작업 수행 - 일관성: 프로젝트마다 동일한 패턴을 적용하여 학습 비용 감소
왜 필요한가?
인간의 관점
- 복잡한 명령어를 매번 기억할 필요 없음
- 메뉴 기반 인터페이스로 직관적 작업
- 실행 전 설명 확인 가능
에이전트의 관점
- 표준화된 CLI 인자로 자동화 가능
- 스크립트 자체가 API 문서 역할
- 일관된 패턴으로 학습 용이
유지보수 관점
- 문서와 코드의 동기화 문제 해소
- 하나의 파일만 관리하면 됨
- 프로젝트 온보딩 시간 단축
구조 패턴: v1 (Simple Case) vs v2 (Registry + Introspection)
두 가지 구현 수준이 있다. 프로젝트 복잡도에 따라 선택한다.
v1: Simple Case (nixos-manage.sh)
v2: Registry + Introspection (memex-kb/run.sh)
핵심 기술: 소스 파일 Introspection
Bash 함정: set -e 환경에서의 주의사항
실전 적용: memex-kb/run.sh
v1 vs v2 비교
장점
단점
- 복잡한 로직은 별도 스크립트로 분리 필요 (run.sh는 래퍼 역할)
- 대규모 프로젝트에서는 메뉴가 길어질 수 있음 (카테고리 구분선으로 완화)
- Bash 숙련도가 필요 (특히 v2의
set -e함정 이해) - v2의 소스 파일 파싱은
declare -f의 한계를 우회하는 workaround
관련 개념
- †ai프롬프트 - 에이전트가 이해하기 쉬운 인터페이스
- †튜토리얼 매뉴얼 가이드 활용법 - 사용자 가이드
- † 터미널 - CLI 환경
- † 리눅스 유닉스 운영체제 - Bash 스크립팅
- † #리눅스 #유닉스 #운영체제
실제 사용 사례
참고 자료
핵심 교훈
- Bash의
declare -f는 주석을 제거한다. “코드가 곧 문서”가 되려면 소스 파일 직접 파싱이 필요하다.set -euo pipefail환경에서grep과[[ ]] && ...패턴은 예상치 못한 종료를 유발한다.- Self-documenting CLI는 단순한 스크립트가 아니라, 인간과 AI가 함께 사용할 수 있는 인터페이스 디자인 철학이다. “설명서 + 실행기”라는 개념으로, for 인간/에이전트 모두를 위한 도구다.
Comments