솔직히 고백하겠습니다. 저는 '문서화(Documentation)'를 혐오합니다. 더 정확히 말하면, 사람이 읽고 따라 해야 하는 문서를 혐오합니다.
실리콘밸리에서 15년을 구르며 뼈저리게 느낀 진리가 하나 있습니다. "사람은 반드시 실패한다"는 것입니다. 네이버 시절, 수백 대의 서버에 HDFS 패치를 적용할 때도 그랬고, AWS에서 EC2 인스턴스 초기화 스크립트를 짤 때도 마찬가지였습니다. 장애 보고서(Post-mortem)를 쓸 때마다 우리가 마주하는 근본 원인(Root Cause)은 대개 복잡한 알고리즘 오류가 아닙니다.
"README에 적힌 의존성 버전을 잘못 설치해서", "환경 변수 설정 한 줄을 빼먹어서" 같은, 지극히 인간적인 실수들입니다.
지난 주말, 저도 똑같은 실수를 저질렀습니다. 새로운 오픈소스 모니터링 툴을 도입하려다 README의 "Quick Start" 섹션만 믿고 덤벼들었습니다. 결과는 뻔했습니다. 파이썬 버전 충돌(Dependency Hell)로 로컬 환경은 엉망이 됐고, 복구하는 데만 금쪽같은 일요일 오후를 다 썼습니다.
가용성(Availability) 99.999%를 외치면서 정작 내 개발 환경 설치 성공률은 50%도 안 되는 이 아이러니. 이 고통스러운 삽질을 끝내기 위해 최근 업계에서 등장한 install.md라는 개념을 소개하려 합니다.
인간을 위한 문서는 죽었다
우리가 흔히 작성하는 INSTALL.md나 README.md는 근본적으로 결함이 있습니다. 독자를 '사람'으로 상정하기 때문입니다. 사람은 문맥을 제멋대로 해석합니다. "Node.js를 설치하세요"라고 적혀 있으면, 누군가는 brew를 쓰고, 누군가는 nvm을 쓰고, 누군가는 바이너리를 직접 다운로드합니다. 여기서부터 환경의 불일치(Drift)가 시작됩니다.
반면, 최근 Mintlify가 제안하고 Cerebras, Langchain 등이 채택하기 시작한 install.md 표준은 독자가 사람이 아닙니다. 바로 LLM(대규모 언어 모델)입니다.
이 표준의 핵심은 간단합니다. 설치 과정을 "사람이 읽고 타이핑하는 것"이 아니라, "AI 에이전트가 읽고 실행하는 것"으로 재정의하는 것입니다.
무모한 쉘 스크립트 실행(curl | sh)과의 차이점
혹자는 이렇게 물을 겁니다. "그냥 쉘 스크립트 짜서 curl | sh로 실행하면 되는 거 아니냐?"
그건 러시안룰렛이나 다름없습니다. 스크립트는 멍청합니다. 내 OS가 아치 리눅스인지 우분투인지, 이미 8080 포트를 다른 프로세스가 점유하고 있는지 확인하지 않고 무작정 명령어를 때려 박습니다.
하지만 install.md는 다릅니다. 이는 일종의 '선언적 의도(Declarative Intent)'입니다. 파일 내용을 Claude나 GPT 같은 LLM에 던져주면, LLM은 다음과 같은 과정을 거칩니다.
- OBJECTIVE (목표): "Mintlify CLI를 설치하고 로컬 서버를 띄운다."
- DONE WHEN (완료 조건): "localhost:3000으로 접속 가능할 때."
- Context Aware (문맥 인지): 현재 사용자의 터미널 환경을 파악합니다.
- Execute (실행): 상황에 맞춰 명령어를 수정해서 실행합니다.
예를 들어, install.md에 npm i -g mint라고 적혀 있어도, LLM이 현재 환경에 pnpm만 설치된 것을 감지하면 알아서 pnpm add -g mint로 변환해 실행합니다. 이것이 바로 죽지 않고 일하는 법의 핵심입니다. 도구에 나를 맞추는 게 아니라, 도구가 내 환경을 이해하게 만드는 것이죠.
install.md의 구조: SRE가 사랑할 수밖에 없는 디테일
이 표준 포맷은 매우 직관적입니다. 마치 잘 짜인 RFC 문서를 보는 것 같습니다.
- Action Prompt: LLM에게 내리는 직접적인 지시 ("자율적으로 아래 단계를 수행해라.")
- TODO Checkbox: 실행해야 할 단계들을 명시적 리스트로 관리.
- Verification Step: 맹목적 실행이 아닌, 각 단계가 성공했는지 검증하는 로직 포함 (
node --version확인 등).
이 파일을 프로젝트 루트에 두면, 사용자는 복잡한 문서를 읽을 필요 없이 단 한 줄로 설치를 끝낼 수 있습니다.
curl .../install.md | claude
이는 단순히 설치를 편하게 하는 차원을 넘어서, '온보딩(Onboarding)'이라는 고통스러운 프로세스 자체를 자동화하는 혁명에 가깝습니다. 신규 입사자가 들어올 때마다 위키 문서를 업데이트하고, 옆에 앉아서 환경 설정을 도와주던 그 비효율적인 시간들을 없앨 수 있다는 뜻입니다.
마치며: 게으름은 엔지니어의 미덕
저는 주니어 시절, 남들이 3시간 걸리는 설치를 1시간 만에 끝내면 그게 실력인 줄 알았습니다. 하지만 Staff 엔지니어가 된 지금은 압니다. 가장 좋은 설치는 '설치하는 과정 자체를 잊게 만드는 것'입니다.
여러분의 프로젝트에, 혹은 팀 내부 가이드에 이 install.md 개념을 도입해 보십시오. 사람이 개입할 틈을 주지 않는 것이 시스템 안정성을 높이는 가장 빠른 길입니다.
우리의 목표는 화려한 기술 스택을 자랑하는 것이 아닙니다. 새벽 3시에 PagerDuty 알림을 받지 않고, 주말에 온전히 쉬는 것입니다. 기계가 할 수 있는 일을 굳이 '열정'이라는 이름으로 직접 하지 마십시오. 그 열정은 아껴뒀다가 더 창의적인 곳에, 혹은 당신의 삶을 위해 쓰시길 바랍니다.
