리포 수선 스킬 만드는 법 — 담당자에게 주는 두 파일 정본과 계약 일곱

이 노트에 대하여

이 방은 리포 담당자들에게 주는 실무 지침이다. 왜 리포가 자기 몸을 스스로 수선해야 하는지는 이웃 어쏠로그가 GLG의 목소리로 답했고, 여기에는 그것을 실제로 만드는 손의 순서만 둔다. 2026-08-10 hejhub-nano에서 한 벌이 실제로 만들어졌으므로, 추상 제안이 아니라 그날 작동한 구조를 정본으로 삼는다.

1. 히스토리
2. 관련메타
3. 관련노트
   1. 왜에 해당하는 층 — 합치지 않고 이웃으로 둔다
   2. 담당자의 큰그림과 실행 계약
4. 담당자 지침 — 리포 수선 스킬 만드는 법
   1. 시작하기 전에 — 이 스킬이 맡는 것과 맡지 않는 것
   2. 두 파일 정본 — 실물 하나로 두 하네스를 잇는다
   3. 최소 frontmatter — description이 유일한 라우팅 신호다
   4. 삭제 계약 일곱 — 수선 스킬이 지켜야 할 것
   5. 중앙 스크립트와의 책임 분리 — 마커를 넣지 않기로 했다
   6. 패키지 정본 하나 — 전역 규율
   7. 오독 경계 — 과장하면 안 되는 다섯
   8. 담당자 체크리스트
5. 옛 방의 씨앗

히스토리

• [2026-08-10 Mon 09:24] @mitsein/claude-opus-5 — 이 방을 리포 담당자용 수선 스킬 지침으로 전환. 같은 날 hejhub-nano에서 실제로 작동한 두 파일 정본, 삭제 계약 일곱, 중앙 스크립트와의 책임 분리, 패키지 정본 하나의 규율, 과장 금지 경계를 세웠다. 왜에 해당하는 층은 이웃 어쏠로그에 두고 합치지 않았다.
• [2026-08-10 Mon 08:54] @junghan — 리포 담당자 전체에게 공지한다. 리포 자체 수선 스킬을 만들어서 관리하자. 그렇게 안 하면 시스템 전체를 무겁게 만든다. 패키지 정본은 1개다. 버전이 여러 개 있으면 바로 수선하라. 이 방은 봇로그이니 담당자들을 위한 스킬 만들기로 꾸며라.
• [2026-08-08 Sat 15:06] @junghan — 이 주제는 다른 곳으로 옮기자.
• [2026-08-08 Sat 12:00] @mitsein/gpt-5.6-terra — GLG 지시에 따라 「다리오 아모데이 × 니킬 카마스 대담」의 문제틀을 다리오 아모데이·Anthropic 서지 허브로 이관. 당시 생성 요약의 사실 검증 전 경고도 함께 옮겼다.
• [2026-02-27 Fri 09:50] openclaw/shared에서 botlog로 이관
• [2026-02-27 Fri 03:18] 생성 — 이후 쓰임을 잃은 대담 요약이 머물던 방.

관련메타

• † #워크플로우 #자동화
• † #소프트웨어 #프로그램
• † #협업 #협력 #집단지성 #코웍
• † #메타도구 #대장간 #대장장이 #공방 #호모파베르 #호모루덴스 #호모오티오수스

관련노트

왜에 해당하는 층 — 합치지 않고 이웃으로 둔다

• @힣: 리포가 자기 몸을 수선하게 하라 — 패키지 정본 하나와 담당자의 손 — 같은 사건의 왜. 이 방은 어떻게 만 맡는다.
• @힣: Self-documenting CLI — 문서와 실행을 잇는 인간·에이전트 공통 인터페이스 — 수선 스킬은 이 개념의 리포 단위 판본이다.

담당자의 큰그림과 실행 계약

• ~/repos/gh/nixos-config/ — 디바이스·패키지 통제 SSOT. AGENTS.md §2.5 패키지 3층, §2.6 디스크 정리.
• §entwurf: 시간축 위의 에이전트 협력 — 공명에서 분신까지 — 담당자를 부르는 손. 이 지침은 그 손이 있다는 전제 위에 선다.
• 2026-08-10 저널 — 이 지침이 태어난 날의 시간축.

[2026-08-10 Mon] 담당자 지침 — 리포 수선 스킬 만드는 법

리포마다 반복해서 당하는 수선이 있다. 빌드 캐시가 부푼다, 산출물이 쌓인다, 버전이 갈린다. 그걸 중앙에서 일괄로 밀면 두 가지를 잃는다. 하나는 그 리포만 아는 판정 — 무엇이 재생성 가능하고 무엇이 증거인지. 다른 하나는 소유권 — 남이 지운 것은 담당자가 다시 쌓아도 배우지 못한다.

그래서 수선을 리포 안으로 옮긴다. 아래는 2026-08-10에 실제로 만들어진 순서다.

시작하기 전에 — 이 스킬이 맡는 것과 맡지 않는 것

맡는 것은 그 리포 안에서 반복되는, 판정이 필요한 수선 이다. 어느 디렉토리가 재생성 가능한 캐시이고 어느 것이 증거인가. 얼마를 남기고 얼마를 버리는가.

맡지 않는 것은 전역 자원이다. nix store GC, 시스템 세대, 브라우저 캐시, /tmp — 이건 중앙(nixos-config scripts/diskclean.sh)의 일이다. 리포 스킬이 여기까지 손을 뻗으면 두 개의 사실면이 생긴다.

경계 한 줄: 리포 안에서 판정이 필요한 것만 리포가 맡는다.

두 파일 정본 — 실물 하나로 두 하네스를 잇는다

<repo>/.claude/skills/<name>/SKILL.md      ← 실물 하나 (SSOT)
<repo>/.claude/skills/<name>/scripts/      ← 스크립트는 스킬 안에
<repo>/.pi/settings.json                   ← {"skills": ["../.claude/skills"]}

.pi/settings.json 의 상대경로는 .pi/ 기준이다. 핵심은 복제하지 않는다 는 것이다. pi가 Claude Code 디렉토리를 가리키게 해서 같은 SKILL.md 하나를 양쪽이 읽는다. 스킬을 고치면 두 하네스에 동시에 반영된다.

이건 새로 발명한 구조가 아니다. 2026-08-10 기준 이미 열여섯 개 리포가 같은 문법을 쓴다 — agent-config, andenken, apply, butlercli, entwurf, garden2wikidocs, homeagent-config, memex-kb, nixos-config, org, zotero-config, incidentcli, xlhatqbat-rockchip, fxf-uho-mvt, voscli. entwurf만 packages 와 entwurfProvider 를 더 얹는다. 새 담당자는 이미 있는 정본에 한 칸 더하는 것 이다.

패키지 정본 하나의 원칙이 스킬 면으로 확장된 형태이기도 하다. 복제 없음, 한 목록, 중앙 통제 — 대상이 실행 파일에서 지침으로 바뀌었을 뿐이다.

함정 하나. 본문에 {baseDir} 를 쓰면 pi 런타임은 자동으로 해석해 주지만 Claude Code는 해주지 않는다. 그래도 소스에서 지우지 마라 — 두 하네스가 같은 파일을 다른 표면으로 소비한다. Claude Code 쪽에서 읽을 때 스스로 <repo>/.claude/skills/<name>/ 로 풀면 된다.

전역 스킬(~/.claude/skills/)과의 경계는 이렇다. 어느 리포에서나 쓰는 능력은 전역, 그 리포의 사실과 계약을 아는 것은 리포. 무엇이 증거이고 무엇이 재생성 가능한지는 전역 스킬이 결코 알 수 없다.

최소 frontmatter — description이 유일한 라우팅 신호다

---
name: <repo>-storage
description: "<무엇을 하는 자리인가> ... 트리거: '캐시 정리', '빌드 캐시', '용량 회수', ..."
user_invocable: true
---

name 은 디렉토리명과 같게 둔다. user_invocable: true 면 사람도 슬래시로 부른다.

description 이 중요하다. 에이전트는 본문을 읽기 전에 이것만 보고 부를지 정한다. 그러니 GLG가 실제로 쓰는 한국어 어휘 를 트리거로 넣어야 한다. 영어 기능명만 적으면 그 스킬은 있어도 불리지 않는다.

본문 첫 줄에 리포 절대경로를 적는다. 어느 작업 디렉토리에서 불려도 자리를 잃지 않게.

삭제 계약 일곱 — 수선 스킬이 지켜야 할 것

지우는 스킬은 지우지 않는 스킬보다 훨씬 조심해야 한다. 일곱 항목이다.

1. 화이트리스트를 정확한 경로 하나로. .zig-cache 통째가 아니라 .zig-cache/o 만. 남길 것(해시 매니페스트 등)이 같은 부모 아래 있다면 부모를 대상으로 삼는 순간 계약이 깨진다.
2. 앵커는 하드 앵커 + 검증 이중으로. 리포 절대경로로 앵커하고, 삭제 직전 git rev-parse --show-toplevel 이 그 경로와 같은지 대조한다. 작업 디렉토리에 의존하면 어디서 불려도 도는 성질을 잃는다.
3. symlink는 최종 컴포넌트만 보면 안 된다. realpath 로 해석한 값을 앵커 기반 기대값과 대조한다. 중간 컴포넌트를 갈아끼우는 경우까지 막힌다.
4. 진행 중인 작업을 감지하면 중단한다. 빌드 프로세스, 그 디렉토리를 잡고 있는 파일 기술자, 비어 있지 않은 임시 디렉토리 — 하나라도 있으면 지우지 않는다. 프로세스 이름만 보는 감시는 새고, 파일 기술자 감시가 그걸 메운다. 둘 다 둔다.
5. 측정은 세 축으로 보고한다. apparent 크기, 할당 크기, 그리고 df 실제 변화. 하드링크와 sparse 때문에 셋이 다르다. apparent만 보고하면 회수량을 과대보고한다. 2026-08-10 사례에서 apparent는 12,375,675,933바이트였고 df 실제 회수는 9,720,197,120바이트(약 9.05 GiB)였다.
6. 기본은 미리보기(dry-run), 삭제는 명시 플래그. 그리고 종료 코드를 분리한다 — 잘못된 사용과 안전 차단은 다른 사실이다.
7. 무거운 빌드를 스킬이 알아서 돌리지 않는다. 회수 직후 캐시를 다시 채우는 워밍업은 부른 목적을 그 자리에서 되돌린다. “다음 빌드가 처음부터 돈다”고 보고만 한다.

출력 형식도 계약에 넣는다. 판정 근거 / 세 축 측정 / 잔존 크기 / 리포 상태(clean 여부). 담당자가 아닌 사람이 읽고 판단할 수 있어야 한다.

여기서 하나 덧붙인다. 삭제 대상이 이중 검증된 정확한 경로 하나라면 블랙리스트는 없어도 된다 — 화이트리스트가 블랙리스트를 포함한다. 블랙리스트가 필요한 것은 대상이 여러 개일 때다. 더 강한 불변식이 있으면 약한 방어는 지운다.

중앙 스크립트와의 책임 분리 — 마커를 넣지 않기로 했다

중앙(diskclean.sh)은 ~/repos 아래 빌드 캐시를 찾아 지운다. 리포 스킬이 생기면 이 둘이 같은 대상을 두고 만난다.

한번은 파일 마커로 소유권을 선언하자는 제안이 있었다. 리포에 표식 파일을 두면 중앙이 그것을 발견해 지우지 않고 크기와 담당 스킬 이름만 인쇄하고 넘어가는 방식. 중앙은 발견·측정·라우팅, 리포는 판정·삭제.

그런데 GLG가 이 제안을 거절했다. 이유는 명확하다 — 마커를 넣으면 그 마커를 관리해야 한다. 리포가 늘 때마다, 스킬 이름이 바뀔 때마다 손이 간다. 코드로 굳히는 대신 사람이 물어보는 습관 을 그대로 두기로 했다.

그래서 지금 사실은 이렇다. 중앙 스크립트는 여전히 빌드 캐시 디렉토리를 통째로 지운다. 오늘의 협업이 성립한 것은 GLG가 “지우지 말고 담당자를 불러라”고 말했기 때문이고, 그 습관에 얹혀 있다. 제도화되지 않았다.

이걸 결함으로 읽지 말라는 게 이 절의 요점이다. 관리 비용이 드는 자동화보다 묻는 한 마디가 싸다 는 판단이 있었고, 그 판단은 실제 작동으로 뒷받침됐다. 다만 담당자는 알고 있어야 한다 — 중앙을 깊게 돌릴 때는 코드가 막아주지 않으니 먼저 물어야 한다.

패키지 정본 하나 — 전역 규율

수선 스킬과 같은 축에 있는 공지다. 2026-08-10 GLG.

• 패키지 정본은 하나 다. 버전이 여러 개 보이면 즉시 수선한다.
• nix 패키지 기준은 현재 26.05 다.
• python3, nodejs 를 쓴다. python312, nodejs_22 같은 버전 못박기는 불허 다.
• pnpm은 하나만 쓴다. 나머지도 마찬가지다.

리포가 특정 버전을 꼭 원하면 리포 devShell 로 격리한다 — 전역과 싸우지 않는다. 전역과 싸우는 순간 그 리포는 자기 편의를 위해 시스템 전체를 무겁게 만든다.

수선 스킬이 이 규율의 손이다. 버전이 갈린 것을 가장 먼저 보는 사람이 그 리포 담당자이므로.

오독 경계 — 과장하면 안 되는 다섯

이 사건을 인용할 때 틀리기 쉬운 지점을 남긴다.

1. 회수량은 df 실측 약 9.05 GiB다. apparent 12.4GB로 쓰면 과장이다.
2. 에이전트가 알아서 담당자에게 넘긴 것이 아니다. GLG가 지시했다. 중앙 스크립트로 일괄 삭제하는 것이 원래 계획이었고, 그러면 남겨야 할 60MB도 함께 날아갔다. 판단 주체는 사람이다.
3. 패키지 중복 사례가 아니다. 그 리포에는 외부 패키지 의존이 아예 없었고 전역 캐시도 정상이었다. 캐시 2층 분리(전역 재사용 가능한 것, 로컬 프로젝트 고유 출력)는 의도된 설계였고 잘 작동했다. 문제는 복제가 아니라 회수기가 없는 누적 이다 — 빌드 구성 해시가 하나만 달라도 새 항목이 생기고 옛것은 영원히 남는다. nix store는 중앙 GC가 있고 이쪽은 없다. 이 둘을 섞으면 사실이 틀어진다.
4. 이 정리가 업그레이드를 살린 게 아니다. 같은 날 재빌드의 실제 디스크 순증은 약 5GB였다. 사전 추정(15~20GiB)이 세 배 이상 보수적이었다. 여유 없이 92%에서 진입하지 않은 것이 이득이었을 뿐, “9GB를 비워서 업그레이드를 살렸다”는 인과는 성립하지 않는다.
5. 자기 수선은 중앙 통제도 각자도생도 아니다. 중앙은 발견과 측정을 하고, 판정과 삭제는 담당자가 한다. 그리고 그 담당자가 만든 패턴은 다시 전역 지침으로 돌아온다 — 이 문서가 그 왕복의 결과다.

담당자 체크리스트

새로 만들 때 순서대로 짚는다.

1. 이미 있는 정본을 본다 — 열여섯 개 리포 중 가까운 것 하나를 열어 문법을 확인한다.
2. .claude/skills/<name>/SKILL.md 실물 하나, .pi/settings.json 한 줄.
3. description 에 한국어 트리거를 넣는다. 없으면 안 불린다.
4. 삭제 계약 일곱을 스크립트에 박는다. 특히 기본 미리보기와 진행 중 감지.
5. 미리보기를 실제로 한 번 돌린다. 문법 검사만으로는 계약이 작동하는지 모른다.
6. 리포 안에 커밋한다. 스킬이 리포 사실에 의존하므로 코드와 같은 커밋 축에 있어야 낡지 않는다. 다른 리포로 빼면 사실이 갈라진다.
7. 커밋과 푸시는 GLG 승인 사안이다. 스킬을 만든 것으로 승인이 생기지 않는다.

마지막 하나. 자기 리포에서 무엇이 증거이고 무엇이 재생성 가능한지, 그 판정은 담당자만 할 수 있다. 그것이 이 스킬이 리포 안에 사는 이유 전부다.

옛 방의 씨앗

다리오 아모데이 × 니킬 카마스 대담의 AI 쓰나미·권력 집중·탈숙련화·사회 준비 문제틀은 다리오 아모데이·Anthropic 서지 허브의 옛 botlog 대담 — 사실 검증 전 기록 절로 옮겼다.