README 에 체크리스트가 없으면, 그 시스템은 예측 불가능하다.

누군가 내 레포를 클론했다. docs를 읽는다. 그리고 — 멈춘다. “다음에 뭐 하지?”

이건 문서의 문제가 아니라 예측 가능성의 문제다. Manufacturing Bridge 작업 중 이걸 깨달았다: README의 “git clone → opencode”는 두 줄이지만, 그 사이에 6개의 갭이 있었다.

문제

공개 템플릿(opencode-drewgent)을 누군가 클론하면 어떤 일이 일어나는가?

Python 의존성? 설치하라고 말한 적 없음 .env 파일? 직접 만들어야 아는 수준 launchd 데몬? 매뉴얼 참조 or 복사-붙여넣기 cron이 왜 안 돌지? 아무도 알려주지 않음 DISCORD_BOT_TOKEN이 뭔지? .env.example에 없었음 gbrain은 어떻게 설치하지? 언급조차 없었음

예측 가능성 = 6/10. Manufacturing Bridge의 6대 패턴 중 하나가 “템플릿 갭”이었다. 점검 결과: launchd plist 없음, .env.example 불완전, 첫 실행 원스톱 없음, README 체크리스트 없음.

결정: “클론 → 실행”을 6단계로 좁힌다

설계 원칙: 처음 실행하는 사람이 0에서 production까지 6개 명령어 안에 도달하게.

달성한 것:

bash scripts/setup.sh 하나로 환경 설정 완료 3개의 launchd plist 템플릿 (opencode serve, cron, discord-bot) .env.example에 DISCORD_BOT_TOKEN + OPENAI_API_KEY 섹션 추가 README에 6단계 first-run 체크리스트 표 추가

What This Build Delivers

setup.sh — Python 확인 → pip install → .env 생성 → launchd 안내 → 검증. 102줄, 의존성 0 (bash only). launchd 템플릿 3종 — opencode serve (headless 없는 n dispatcher (60초), discord-bot. 모두 KeepAlive + 10초 ThrottleInterval 적용. .env.example 보강 — DISCORD_BOT_TOKEN, OPENAI_API_KEY, gbrain 섹션 추가. 주석으로 용도와 획득 경로 명시. README 체크리스트 — 6단계 표. 필수/선택 구분. “안 되나요?” fallback 포함.

왜 예측 가능성이 우선순위인가

Drewgent의 핵심 철학 중 하나: 시스템은 모르는 사람이 봐도 작동할 수 있어야 한다.

이건 친절함이 아니라 구조적 불가능의 적용이다. “실수하지 마”가 아니라 “실수할 수 있는 갭을 없애는 것.”

README 체크리스트가 없는 레포는, 사용자에게 “너가 직접 알아내” 라고 말하는 것과 같다. 그리고 그건 예측 가능성 점수를 6/10으로 만든다. Manufacturing Bridge는 이걸 9/10으로 올리는 작업이었다.

Slice 1: setup.sh

102줄. bash-only. 의존성 0. 하는 일:

Python 3.11+ 확인 pip install -r requirements.txt .env가 없으면 .env.example에서 복사 + API 키 안내 launchd 템플릿 발견 → 설치 명령어 안내 croniter / pyyaml / kanban.db 검증

핵심 결정: setup.sh는 안내지 실행이 아니다. launchd plist를 강제로 복사하지 않고 “이렇게 하세요”를 보여준다. 이유: 사용자가 plist의 {{PLACEHOLDERS}}를 자신의 값으로 바꿔야 하기 때문. 자동화할 수 없는 단계는 자동화하지 않는다 — 이것도 Tiered Autonomy의 적용이다.

Slice 2: launchd 템플릿

3개 데몬, 모두 동일한 패턴:

KeepAlive { SuccessfulExit: false, ThrottleInterval: 10 } — 크래시 시 10초 후 자동 재시작 RunAtLoad — 재부팅 후 로그인 시 자동 실행 WaitForNetworkInterface (discord-bot) — 네트워크 준비 후 시작 StandardOutPath / StandardErrorPath — 로그는 logs/ 디렉토리

핵심 결정: 템플릿은 ai.yourgent. 라벨 사용. setup.sh가 rename-drewgent 스킬과 연동되어 사용자 이름으로 치환된다. 하드코딩된 ai.drewgent. 라벨을 박지 않은 이유: push-template.sh로 공개 템플릿에 올릴 때 개인 정보가 새지 않도록.

Slice 3: .env.example 보강

기존 .env.example에는 DISCORD나 gbrain 관련 키가 전혀 없었다. Lombok Agent Fork 때 DISCORD_BOT_TOKEN을 추가했지만, 그게 .env.example에는 반영되지 않았다.

추가한 섹션:

DISCORD_BOT_TOKEN — Discord ↔ opencode 게이트웨이. 봇 생성 URL과 용도 명시. OPENAI_API_KEY — gbrain 하이브리드 검색. 획득처와 설치 명령어 포함.

핵심 결정: API 키 주석에 “Get at: https://…” URL을 포함. 사용자가 “이게 뭐지?”에서 “아, 여기서 발급받으면 되는구나”까지 0초에 도달하게.

Slice 4: README 체크리스트

Quick Start 섹션에 6단계 표 추가:

셋업 — bash scripts/setup.sh API 키 입력 — .env 편집 (OPENCODE_API_KEY 필수) 이름 변경 (선택) — skill(“rename-drewgent”) 검증 — bash scripts/bridge-lint.sh launchd 설치 (macOS) — 템플릿 복사 + launchctl load opencode 실행

각 단계에 필수/선택 표시. “안 되나요?” fallback으로 트러블슈팅 링크.

핵심 결정: 체크리스트는 코드 덩어리가 아니라 의사결정 트리다. 각 단계는 “이걸 왜 해야 하는가?”에 답할 수 있어야 한다. setup.sh가 “무엇을” 담당한다면, 체크리스트는 “왜”와 “언제”를 담당한다.

예측 가능성 6 → 9

변경 전:

README: “git clone → opencode” 2줄. 중간 갭 6개. launchd: 사용자가 직접 plist 작성. .env: DISCORD_TOKEN? OPENAI_KEY? 모름. 예측 가능성: 6/10

변경 후:

README: 6단계 체크리스트. 각 단계가 다음 단계를 명확히 가리킴. setup.sh: 실행하면 “이제 뭐 하지?”가 사라짐. launchd: 템플릿 3개 + 설치 명령어 1줄. .env.example: 모든 API 키가 주석과 함께 존재. 예측 가능성: 9/10 (완벽은 없다 — rename 스킬은 선택사항으로 남겨둠)

결론: 갭을 메우는 게 기능을 추가하는 것보다 중요하다

이 PR은 새로운 기능을 0개 추가했다. 단지 문서와 템플릿의 갭을 메웠을 뿐이다. 그런데 이게 Drewgent의 pull request 중 가장 영향력 있는 작업 중 하나일 수 있다.

왜? 처음 클론하는 사람의 경험을 6단계로 좁혔기 때문. “너가 직접 알아내”에서 “이 순서대로 따라와”로 바꿨다. 그리고 그게 Manufacturing Bridge가 가르쳐준 가장 중요한 교훈이다: 갭을 메우는 게 기능을 추가하는 것보다 예측 가능성을 더 높인다.

공개 템플릿: github.com/humanerd-drew/opencode-drewgent

Built with opencode-drewgent