setup-machine

머신 한 대를 작업 가능한 상태로 만든다. 각 항목의 상세 절차는 하위 스킬이 소유하고, 이 스킬은 순서, 충돌, 전제, 검증 집계만 소유한다.

하위 스킬의 내용을 여기에 복사하지 않는다. 복사하는 순간 이중 관리가 되고 원본이 바뀌면 drift한다.

구성 항목

순서	항목	하위 스킬	조건
1	셸·패키지·툴체인 기준선	setup-dotfiles	대화형 머신 (헤드리스는 패키지만)
2	글로벌 에이전트 지침	setup-global-config	항상
3	shell 명령 안전 훅	setup-hooks	python3 필요
4	세션 자동 로그	session-log	jq 필요
5	statusline	statusline	대화형 머신만
6	herdr 설정 이식	setup-herdr	herdr 설치돼 있을 때

dotfiles가 먼저인 이유는 나머지 전부가 그 산출물 위에 서기 때문이다. python3와 jq는 Brewfile이 깔고, herdr도 그렇다 — 순서를 뒤집으면 3·4·6이 전제 미충족으로 잘못 skip된다. 글로벌 지침이 그다음인 이유는 이후 단계의 판단 기준이 그 문서에 있고, 훅이 그다음인 이유는 나머지 작업 중 실수를 이미 막고 있어야 하기 때문이다.

step 0: 하위 스킬 확보

하위 스킬이 없으면 먼저 설치한다. 설치 여부는 스킬 디렉토리 존재로 판정한다.

npx skills add psw7205/skills -g --skill setup-dotfiles setup-global-config setup-hooks session-log statusline setup-herdr -y

--agent를 지정하지 않는다. --agent claude-code를 붙이면 ~/.claude/skills/에 설치되는데, setup-hooks는 Codex 훅 스크립트를 ~/.agents/skills/setup-hooks/scripts/ 절대경로로 참조한다. agent를 지정하지 않으면 agent-중립 위치에 설치되어 그 참조가 성립한다.

검증 목적으로 로컬 레포를 소스로 쓸 때는 psw7205/skills 자리에 그 경로를 넣는다.

node나 skills CLI를 쓸 수 없는 환경이면 이 단계를 skip하고, 리포트에 수동 설치 안내를 남긴 뒤 이미 설치된 항목만으로 진행한다.

프로파일 판정

물어보기 전에 감지한다. 감지로 닫히지 않는 것만 묻는다.

• OS: uname -s (Windows는 herdr config 경로가 다르다 — setup-herdr가 처리)
• 도구 존재: command -v python3 jq herdr codex
• 대화형 머신 여부: 감지 불가. 사용자에게 확인한다. 헤드리스 서버면 statusline과 herdr를 건너뛴다.

도구 감지는 항목 1 이후에 다시 한다. Brewfile이 python3·jq·herdr·codex를 깔기 때문에, 항목 1 이전의 감지 결과로 3·4·6을 판정하면 방금 설치한 도구를 못 보고 skip한다. 항목 1을 건너뛴 경우에만 최초 감지 결과를 그대로 쓴다.

Codex 대상 작업(setup-global-config와 setup-hooks의 Codex 측)은 codex가 감지될 때만 포함한다.

settings.json 단일 패스

setup-hooks, session-log, statusline 세 항목이 모두 ~/.claude/settings.json을 고친다. 서로 다른 키를 건드리므로 키 충돌은 없지만, 순차로 읽고 쓰면 앞 단계의 추가가 뒤 단계의 쓰기에 덮인다.

• 세 하위 스킬이 지시하는 변경을 모아서 한 번에 적용한다. 각 단계마다 read-modify-write하지 않는다.
• 어떤 키를 건드릴지는 하위 스킬의 지시를 따른다. 이 문서에 키 목록을 고정하지 않는다 — 하위 스킬이 새 키를 추가하면 그대로 뒤처진다.
• 이 단일 패스 규칙은 오케스트레이터 실행 중에만 적용된다. 하위 스킬을 단독으로 쓸 때의 개별 쓰기 지침은 그대로 유효하다.
• 재시작 안내는 마지막에 1회만 한다. 세 항목이 각자 "재시작 필요"를 말하지만 재시작은 한 번이면 된다.

skip 판정

두 종류를 구분해서 리포트에 다르게 적는다.

• 전제 미충족: 도구가 없거나 프로파일에 해당하지 않음. 그 항목만 건너뛰고 나머지는 완주한다. 중단하지 않는다.
• 이미 설치됨: 하위 스킬이 각자 명시한 기존 skip 기준을 그대로 쓴다. 판정 기준을 새로 만들지 않는다.

점검 모드

"셋업 점검", "뭐가 빠졌는지 봐줘" 류 요청에서는 아무것도 바꾸지 않고 판정과 리포트만 낸다. 설치 명령과 설정 파일 쓰기를 실행하지 않는다.

리포트

작업 종료 시 항목별로 installed / skipped(이유) / failed(이유)를 낸다. 이어서 사용자가 직접 해야 할 것만 모아서 적는다.

• 에이전트 재시작 (settings.json 변경이 있었을 때 1회)
• herdr 재접속 — remote attach는 클라이언트가 시작 시점에 config를 읽으므로 detach 후 재접속해야 반영된다
• session-log를 설치했으면 로그 기록 위치와 끄는 방법. 자동 기록은 프라이버시 성격이 있으므로 설치 사실을 리포트에서 넘기지 않는다

Gotchas

• 하위 스킬 이름으로 위임하고 절차를 재서술하지 않는다. 재서술은 곧 복제다.
• 한 항목이 실패해도 나머지를 진행한다. 부분 완료 + 정확한 리포트가 중단보다 낫다.
• 대상 파일을 이미 사용자가 손봐둔 경우가 흔하다. 하위 스킬들은 각자 backup과 기존 설정 보존을 지시하므로 그 지시를 우회하지 않는다.