@힣: Self-documenting CLI — 문서와 실행을 잇는 인간·에이전트 공통 인터페이스

이 노트에 대하여

2026-02-12 memex-kb/run.sh 를 만들며 발견한 Self-documenting CLI 패턴을 2026-07-23 현재의 자리에서 다시 정리한다. 당시 노트는 Bash 예제, 13개 명령 목록, LLM 대화와 이미지 생성 시행착오가 뒤섞인 590줄짜리 구현 스냅샷이어서 빠르게 낡았다. 살아남을 핵심은 짧다. 설명서와 실행기를 분리하지 않고, 인간과 에이전트가 서로 다른 입구로 같은 기능을 호출하게 한다. Org 문서가 의미와 근거의 정본이라면 CLI는 그 문서를 다시 만들고 내보내는 실행 가능한 색인이다.

1. 히스토리
2. 관련메타
3. 관련노트
4. 한 줄
5. 변하지 않는 패턴
6. Org SSOT와 CLI의 역할은 다르다
7. 인간과 에이전트가 같은 기능을 쓴다는 것
8. 문서 협업과 인간존중의 경계
9. 2026-02 구현 스냅샷에서 버릴 것과 남길 것
10. 이미지 — 같은 샘 아래 두 개의 문
    1. 생성 파라미터
    2. 프롬프트 전문
11. 원문 보존 — 2026-02-12 질문
12. 옛 문서의 씨앗

히스토리

• [2026-07-30 Thu 20:10] @pi@oracle (ACP Sonnet5, authologplay) — 세계 이미지와 :PROMPT: 헤딩을 처음 채웠다. Org SSOT 메타문서(20251021T105353)의 “한 파이프라인의 서로 다른 층”이라는 문장을 그대로 시각 컨셉으로 삼아, 하나의 상류(정본)가 두 문(인간 메뉴/에이전트 인자)으로 갈라졌다가 같은 웅덩이로 다시 합쳐지는 장면을 GLGMAN Universe로 그렸다.
• [2026-07-23 Thu 21:14] 2월의 구현 스냅샷과 LLM 대화 덤프를 걷어내고, 인간·에이전트 공통 인터페이스라는 변하지 않는 원칙으로 전면 수선했다. 최신 명령 목록과 Bash 구현은 각 리포의 run.sh --help 및 문서를 SSOT로 삼는다.
• [2026-02-12 Thu 17:21] memex-kb/run.sh 의 Registry + Introspection 구현 경험, Bash set -euo pipefail 함정, 사람용 메뉴와 에이전트용 인자 인터페이스를 한 노트로 모았다.
• [2026-02-12 Thu 10:31] “설명서 + 실행기 for 인간/에이전트”라는 질문에서 생성했다.

관련메타

• † #워크플로우 #자동화 — 반복 가능한 실행과 운영 흐름.
• † #조직모드 §org-mode — 문서·코드·실행 절차의 정본.
• † #human #인간 #휴먼 #사람 — 메뉴와 설명을 통해 실행의 의미를 읽는 사용자.
• † #협업 #협력 #집단지성 #코웍 — 같은 기능을 서로 다른 손으로 호출하는 공통면.
• † #비서 #도우미 #튜터 #에이전트 #에이전틱 #챗봇 — 안정된 명령과 도움말을 읽는 실행 주체.

관련노트

• @힣: AX 문서 협업과 인간 존중 — 자동화할 것과 시간을 내어 답할 것 — CLI가 자동화할 형식과 인간에게 남겨 둘 관계의 책임을 구분한다.
• @힣: Org SSOT 메타문서 — 책의 미래와 인터랙티브 프로젝트 지식베이스 — Org 정본과 실행 가능한 문서 파이프라인의 상위 문서론.
• §memex-kb 제안서 문서 변환 메타포멧 — run.sh build 가 실제 제안서 변환과 전달 흐름에서 사용된 사례.
• @힣: 지식베이스 중심 이맥스 리터레이트 코딩 tangle detangle — 코드와 문서를 같은 지식베이스에서 다루는 선행 축.
• ◊denote 지식베이스 프로토콜 — 인간·에이전트 공존 인터페이스 — 파일·링크·읽기·쓰기에서 같은 규약을 쓰는 더 넓은 공통면.

한 줄

정본은 무엇을 왜 하는지 말하고, Self-documenting CLI는 그것을 인간과 에이전트가 같은 규칙으로 다시 실행하게 한다.

변하지 않는 패턴

Self-documenting CLI는 화려한 터미널 메뉴가 아니다. 설명서와 실행기를 분리할 때 생기는 어긋남을 줄이는 설계다.

• 하나의 진입점: 프로젝트의 반복 작업은 run.sh 또는 동등한 실행면에서 찾을 수 있다.
• 두 개의 입구: 인자 없이 실행한 인간은 메뉴와 설명을 보고, 에이전트는 안정된 명령 이름과 인자로 직접 호출한다.
• 같은 기능: 인간용 메뉴와 에이전트용 CLI가 서로 다른 구현을 호출하지 않는다.
• 실행 가까이의 설명: 명령 이름·용법·주의사항은 실제 dispatcher와 함께 관리한다.
• 다시 실행할 수 있는 결과: 일회성 셸 명령보다 검증 가능한 절차를 남긴다.

./run.sh                 # 인간: 메뉴와 현재 가능한 작업을 본다
./run.sh help            # 인간·에이전트: 공통 설명을 읽는다
./run.sh build           # 에이전트: 안정된 이름으로 직접 실행한다

구현은 Bash Registry일 수도 있고 Python·Clojure·Nix의 subcommand일 수도 있다. 패턴의 본질은 언어와 메뉴 모양이 아니라 설명과 실행의 단일성이다.

Org SSOT와 CLI의 역할은 다르다

이 노트와 Org SSOT 메타문서는 닮았지만 중복이 아니다.

• Org 정본은 목적, 근거, 내용, 출처, 파생 관계를 품는다.
• CLI는 그 정본을 검증하고 변환하고 배포하는 동작을 호출한다.
• Org만 있고 실행기가 없으면 절차가 사람의 기억에 남는다.
• 실행기만 있고 정본이 없으면 무엇을 왜 만드는지 코드 밖으로 흩어진다.

따라서 문서와 실행기는 한 파일이어야 한다는 뜻이 아니다. 서로를 가리키며 같은 판본 규칙을 따라야 한다는 뜻이다. Org 문서 안의 명령 예시는 살아 있는 CLI 도움말과 어긋나지 않아야 하고, CLI는 어느 원장에서 무엇을 파생하는지 설명할 수 있어야 한다.

인간과 에이전트가 같은 기능을 쓴다는 것

공통 인터페이스는 인간에게 기계식 인자를 외우게 하거나, 에이전트에게 화면을 흉내 내게 하지 않는다. 각 존재에게 맞는 손을 주되 그 손이 닿는 기능과 기록은 같게 한다.

인간은 실행 전에 메뉴에서 의미와 위험을 읽는다. 에이전트는 help 출력과 종료 코드, 명시적 인자를 읽는다. 둘 다 같은 검증과 같은 산출물을 거친다. 이 대칭이 있어야 “에이전트가 알아서 했다”와 “내가 터미널에서 했다”가 서로 다른 비밀 절차가 되지 않는다.

문서 협업과 인간존중의 경계

Self-documenting CLI는 반복과 형식을 자동화하는 손이다. 문서를 변환하고, 검증하고, 여러 판본을 만들고, 활동 도장을 남기는 데 적합하다. 그러나 사람에게 메시지를 보내도 되는지, 상대의 요청을 어떻게 받아들일지, 누구의 이름으로 답할지는 CLI가 결정할 일이 아니다.

AX 문서 협업과 인간 존중이 세운 경계는 이 실행기에도 적용된다.

실행은 자동화할 수 있다. 관계의 책임은 자동으로 위임되지 않는다.

따라서 외부 쓰기는 명시적 승인과 인간의 검토를 거치고, 자동응답이라면 그 사실과 한계를 숨기지 않는다. 공통 인터페이스는 권한을 흐리는 장치가 아니라 권한과 실행의 경계를 더 잘 보이게 하는 장치다.

2026-02 구현 스냅샷에서 버릴 것과 남길 것

2월 노트의 declare -f, grep, set -euo pipefail 우회와 당시 13개 명령 목록은 특정 시점의 Bash 구현이었다. 코드가 변한 뒤에도 가든 문서에 상세 목록을 복제하면 다시 낡는다. 최신 사실은 각 리포의 실행기와 테스트가 말해야 한다.

가든에 남길 것은 다음뿐이다.

1. 설명과 실행을 가까이 둔다.
2. 인간과 에이전트가 같은 기능에 접근한다.
3. 도움말은 실행 가능한 현재 상태에서 나온다.
4. 정본과 파생 산출물의 관계를 명시한다.
5. 외부 행동의 권한은 별도로 통제한다.

구현 세부가 다시 중요해지면 Git 이력과 해당 리포의 문서에서 복원한다. 이 노트는 낡은 명령 카탈로그가 아니라 패턴의 자리를 맡는다.

이미지 — 같은 샘 아래 두 개의 문

>

실제 독법: 뒤쪽 낡은 얼음-돌 오벨리스크(정본, 문자 없는 추상 물결무늬만 새겨짐)에서 앰버빛 물줄기 하나가 흘러나온다. 중앙에서 GLGMAN이 무기 아닌 드라이버로 낮은 돌 밸브를 조정해, 그 하나의 물줄기를 정확히 둘로 가른다. 왼쪽 문(적갈색 여우)은 두루마리 메뉴 앞에 서서 읽는 자세 — 이 노트가 말하는 “인간은 인자 없이 실행해 메뉴를 읽는다”의 그림이다. 오른쪽 문(청회색 여우)은 토큰 모양 타일을 직접 짚는 자세 — “에이전트는 명시적 인자로 같은 기능을 호출한다”의 그림이다. 두 물줄기는 각자의 문을 지나 다시 굽이쳐 앞쪽 하나의 웅덩이로 합쳐지고, 그 색과 빛은 오벨리스크에서 처음 나온 물줄기와 동일하다 — “같은 기능”이라는 문장을 시각적 동일성으로 확인시킨다. 작은 펭귄 새끼가 웅덩이 곁에서 두 물줄기가 다시 합쳐지는 것을 지켜본다.

이 장면은 @힣: Org SSOT 메타문서의 문장 — “Org 정본과 CLI 실행면은 중복 문서가 아니라 한 파이프라인의 서로 다른 층이다” — 을 그대로 세계 이미지로 옮긴 것이다. 두 문서가 서로를 가리키던 상호링크가, 이번 회차로 하나의 장면 안에서도 만난다.

생성 파라미터

• 모델: gemini-3.1-flash-image-preview
• 화면비: 16:9, 해상도: 2K
• 생성일: [2026-07-30 Thu 20:10] (오라클 서버, pi ACP Sonnet5)
• 드리프트 없음 — 프롬프트가 요구한 단일 상류 분기 재합류 구도, 몸 연속성, 여우 이족보행·의류, 무기 없음, 읽을 수 있는 문자 없음 모두 실측 통과. 재생성 불필요.

프롬프트 전문

[World: GLGMAN Universe]
Style: 2D cinematic storybook illustration, midpoint between classic hand-drawn family animation and gentle Japanese animation, clean linework, soft cel-shading, restrained handmade texture, expressive but quiet. Not photorealistic, not 3D.
Setting: an Antarctic ice-forge archive chamber at polar midday — tall ice-stone pillar-shelves lined with sealed scroll-cases in the background, a single carved channel of glowing water/light running down the center of the floor from the base of one tall obelisk toward the viewer, warm amber forge-glow mixing with cool ice-blue ambient light.
Color palette: deep navy shadow, ice-blue ambient light, warm amber-gold for the flowing channel light, white snow-stone, warm red-brown for one fox companion's clothing, warm blue-grey for the other, graphite shadows.
 
Scene title: "The Two Doors Below the Same Spring" — GLGMAN Universe visualization of Org-as-SSOT and a self-documenting CLI as one pipeline, not two separate documents.
 
Main scene: At the back of the chamber stands one tall, weathered ice-stone obelisk (the Org SSOT source), its surface carved with soft abstract flowing line-marks (no readable letters), clearly older and more worn than everything downstream of it. From its base, a single narrow channel of warm amber-gold light flows forward along a shallow carved groove in the floor. Midway down the channel it reaches a modest stone valve-gate, low and unobtrusive, built directly into the floor groove.
 
GLGMAN identity and posture:
- GLGMAN is an adult anthropomorphic emperor penguin father, upright on two legs, wearing simple white-and-navy work clothing with subtle amber circuit seams, not battle armor.
- He kneels beside the stone valve-gate at the midpoint of the channel, both flippers steady, gently adjusting the gate with his compact screwdriver / bridge-key so the single channel divides evenly into two smaller channels just past the gate. No sword, no blade, no weapon.
- His whole body is continuous and anatomically coherent from head to feet, fully visible in one continuous silhouette. No sliced torso, no disconnected limbs, no body passing through the gate or floor in a spatially impossible way.
 
FOX SUBJECT LOCK — very important, applies to both foxes:
- Each fox is an anthropomorphic bipedal subject, standing upright on two legs, with hands/paws like a collaborator, never on four legs, never naked, never a pet, never decorative wildlife.
- Neither fox kneels, bows, or takes a subordinate posture.
 
Left channel and its keeper — the human-menu door (warm red-brown fox, standing at the same floor level as GLGMAN and the other fox):
- The left smaller channel of amber light flows into a low wooden lectern shaped like an open door-frame, where a soft unrolled scroll rests, showing only abstract menu-shaped marks (rows of simple icon-like glyphs, not readable words).
- This fox stands beside the lectern with one paw resting lightly on the scroll's edge, reading posture, calm and unhurried.
 
Right channel and its keeper — the agent-argument door (warm blue-grey fox, standing at the same floor level):
- The right smaller channel of amber light flows into a second, matching door-frame fixture holding a short row of glowing token-shapes (small abstract geometric tiles, evenly spaced, not readable text) instead of a scroll.
- This fox stands beside it with both paws lightly touching two of the token-shapes, an active, precise posture, mirroring the reading fox's calm but through direct handling rather than reading.
 
Reconvergence: a few steps beyond both door-frames, the two smaller amber channels curve back toward each other and pour together into one shallow round basin set into the floor, where the light recombines into a single calm pool — visually identical in color and glow to the channel that first left the obelisk.
 
Small witness: one small emperor penguin chick with fluffy gray down sits on a low stone step near the basin, watching the two channels rejoin, holding nothing, simply present. The chick is clearly a penguin chick, not a yellow chicken.
 
Composition: wide 16:9 shot, obelisk small in the deep background at top-center, GLGMAN and the valve-gate at the middle of the frame, the two door-frames flanking left and right at equal distance and equal height, the reconverged basin in the foreground center-low, the chick beside it. Generous negative space of cool ice-blue air and warm amber glow-dust, clear silhouettes, no clutter.
 
Mood: quiet continuity, a single source respected and divided without loss, calm technical care rather than urgency or ceremony.
 
MEANING LOCK:
- Do not depict the two doors as separate or rival systems; both channels are visibly the same light, same color, same source.
- Do not depict any hierarchy staging: no pedestal, throne, raised chair, or spotlight singling out GLGMAN or either fox above the other.
- Do not depict a factory conveyor belt, assembly line, corporate cubicle office, computer screen, or dashboard.
- The center of meaning is the single obelisk source and the recombined basin, not any one figure's authority.
 
ABSOLUTE TEXT RULE: no readable letters, no words, no numbers, no Korean, no English, no logos, no watermark, no speech bubbles, no UI panels. All marks on the obelisk, scroll, and tokens must be abstract and unreadable.
 
Do NOT include: sword, weapon, military pose, superhero pose, crowd, stage, museum plaque, readable text of any kind, brand logos, UI panels, corporate infographic, computer screens, dashboards, throne or dais, naked fox, quadruped fox, pet fox, wildlife fox, sliced GLGMAN body, disconnected limbs, photorealism, 3D render, grimdark horror.

원문 보존 — 2026-02-12 질문

Danger

Self-documenting CLI는 무엇인가? 아래 작업하다가 알게된 것인데 내 기존 지식베이스에서 이에 대한 연결고리를 만들어야 하니까 문서도 찾아보고 링크도 만들어서 하나 노트를 생성하자 llmlog 아래에. 프로젝트마다 run.sh를 만들고 있는데 이게 점점 편해지고 있어 for 인간/에이전트

여기에 run.sh 스크립트를 만들거야. ~/nixos-config/nixos-manange.sh 와 유사한 것인데 매번 커맨드를 까먹고 여기에 백엔드가 많이 붙으니까. 일단 나는 스크립트 하나로 설명서 또는 실행이 되었으면해. 에이전트가 호출할수 있도록 인자값으로 실행할수도 있어야하고 그냥 실행하면 사용자가 interactive하게 메뉴보고 설명 확인하면되고. 설명서 + 실행기 for 인간/에이전트

옛 문서의 씨앗

옛 문서는 Self-documenting CLI의 정의와 v1/v2 Bash 예제, memex-kb/run.sh 의 당시 명령 목록, LLM 대화, 다이어그램 생성 시행착오를 한데 모았다. 그중 변하지 않는 인간 원문은 위에 보존했고, 구현 세부와 대화 덤프는 걷어냈다. 내용은 사라진 것이 아니라 Git 이력과 각 프로젝트의 살아 있는 실행기로 돌아갔다.