unlazy 딥다이브
— AI에게 “다 했어요”를 증명하게 만드는 법

1프로젝트 한줄 요약

unlazy는 Claude Code와 Codex CLI에 설치하는 “완료 규율” 스킬입니다. 한 문장으로 줄이면 이렇습니다 — 에이전트가 “끝냈습니다”라고 말하는 것과, 끝났다는 사실이 실제로 참인 것은 다른 일이라는 전제 위에 만들어진 도구입니다.

작동 방식은 의외로 단순합니다. 작업을 시작할 때 GATES.md라는 파일에 “이 일이 끝났다면 이 명령이 이렇게 나와야 한다”를 미리 적어 둡니다. 그리고 에이전트가 완료를 선언하려 할 때, gate-check.mjs라는 CLI가 그 명령을 진짜로 실행합니다. 종료 코드가 0이고 출력이 기대한 패턴과 맞아야만 그 항목이 “met(충족)”으로 바뀝니다.

실제 사용은 이렇게 생겼습니다.

# 1) 스킬 설치
npx skills add Leonxlnx/unlazy

# 2) 에이전트에게 지시 (트리 깊이 5로 분해해서 하라는 뜻)
/unlazy tree 5 결제 모듈을 리팩터링하고 모든 마이그레이션 경로를 검증해줘

# 3) 게이트 상태만 확인 — 아무것도 실행하지 않음
node scripts/gate-check.mjs --status GATES.md

# 4) 사람이 검토한 뒤 승인 + 실제 실행
node scripts/gate-check.mjs --approve GATES.md

--status와 --approve가 나뉘어 있다는 점이 중요합니다. --status는 원장을 읽기만 하고 어떤 명령도 실행하지 않습니다. 실행은 사람이 명시적으로 승인한 뒤에만 일어납니다. 왜 이렇게 나눴는지는 4장에서 다룹니다.

2왜 주목받는가

이 저장소는 2026년 8월 9일에 만들어졌습니다. 이 글을 쓰는 8월 24일 기준 15일 만에 ⭐1,875 · 포크 110개입니다. 코드는 스크립트 5개, 총 1,570줄 남짓입니다. 무엇이 이 속도를 만들었을까요.

배경: “에이전트 게으름”은 실재하는 문제다

AI 코딩 에이전트를 써 본 사람이면 익숙한 장면이 있습니다. 파일 10개를 고쳐야 하는데 3개만 고치고 “주요 변경을 완료했습니다”라고 하거나, 테스트를 돌리지도 않고 “통과할 것으로 예상됩니다”라고 하거나, 어려운 부분에 // TODO: 나중에 구현을 남기고 끝내는 경우입니다.

기존 해법들과의 차이

핵심 차이는 증거의 출처입니다. 앞의 세 가지는 모두 최종 판단을 언어 모델에게 맡깁니다. unlazy는 판단을 운영체제에게 맡깁니다. npm test가 exit 1을 내면 그건 협상의 여지가 없는 사실입니다.

Stop hook — 프롬프트를 무시해도 막히는 층

더 흥미로운 건 선택 기능인 Stop hook입니다. Claude Code에는 세션이 끝나려 할 때 외부 프로그램에게 물어보는 훅이 있는데, unlazy는 여기에 scripts/stop-hook.mjs를 꽂습니다. 게이트가 아직 안 끝났으면 {"decision":"block"}을 돌려줘서 세션 종료 자체를 플랫폼 레벨에서 거부합니다 — 모델이 지침을 무시하기로 결심해도 소용이 없다는 뜻입니다.

이례적인 정직함

이 저장소가 개발자들 사이에서 화제가 된 또 하나의 이유는 문서 태도입니다. 초기 버전의 README에는 “6회 비교 실험으로 효과를 입증했다”는 주장이 있었는데, 저자가 스스로 그 주장을 철회했습니다. 원자료가 남아 있지 않아 재현할 수 없다는 이유였습니다.

커뮤니티 반응도 실제로 코드에 반영됐습니다. 외부 기여자 최소 5명의 PR이 머지됐고, 총 커밋 31개 중 상당수가 Windows 호환성·타임아웃 처리 같은 실사용 버그 수정입니다.

3기술 스택 전체 지도

이 저장소의 package.json에는 dependencies 필드 자체가 없습니다. 실수가 아니라 설계입니다.

{
  "name": "unlazy-skill",
  "version": "2.1.0",
  "private": true,
  "type": "module",
  "engines": { "node": ">=16" }
  // dependencies · devDependencies 둘 다 없음
}

3-1. 런타임 · 언어

3-2. 배포 · 설치 경로

npm이 아니라 npx skills add로 배포됩니다. 이건 vercel-labs가 만든 “AI 에이전트 스킬” 설치 CLI로, GitHub 저장소를 에이전트의 스킬 디렉토리에 직접 심어 줍니다.

npx skills add Leonxlnx/unlazy          # 현재 프로젝트에 설치
npx skills add Leonxlnx/unlazy -g       # 사용자 전역
npx skills add Leonxlnx/unlazy --all    # 감지된 모든 에이전트에

# 수동 설치 시 위치
~/.claude/skills/unlazy   # Claude Code
~/.codex/skills/unlazy    # Codex CLI

3-3. CI · 테스트

.github/workflows/test.yml이 3(OS) × 3(Node 버전) = 9개 조합을 돌립니다. Windows를 진지하게 지원한다는 신호이고, 실제로 코드 곳곳에 Windows 전용 분기가 있습니다.

테스트 프레임워크도 안 씁니다. Jest도 Mocha도 없이 tests/ 아래 .mjs 러너 4개가 child_process.execFile로 실제 CLI를 서브프로세스로 띄워 검증합니다.

3-4. 저장소는 어디에?

데이터베이스가 없습니다. 상태는 전부 파일시스템에 있습니다.

4아키텍처 심화 분석

4-0. 전체 흐름도

4-1. 관대하지 않은 파서 — fail-closed Markdown DSL

scripts/lib/gates.mjs의 parseGates()가 GATES.md를 읽습니다. 여기서 저자는 흔한 유혹을 거절했습니다 — 정규식으로 CHECK:를 찾아 긁어오지 않습니다.

거부 규칙도 엄격합니다. 다음 중 하나라도 걸리면 파싱 에러로 전체를 거부합니다.

• ID가 없는 게이트
• 중복된 ID
• 들여쓰기가 없는 속성 줄
• 게이트가 0개인 원장

4-2. 승인을 “전체 조건의 해시”에 묶기

여기가 이 저장소에서 가장 배울 게 많은 부분입니다. 사용자가 게이트 하나를 승인하면, 그 승인은 명령 문자열이 아니라 실행 조건 전체의 SHA-256 해시에 묶입니다.

// scripts/gate-check.mjs
function oracle(file, gate) {
  const cwd = resolvedGateCwd(gate, file);
  return { schema: 1, check: gate.check, expect: gate.expect, cwd, shell,
    timeoutMs: timeoutSeconds * 1000, maxOutputBytes: MAX_OUTPUT_BYTES,
    regexTimeoutMs: REGEX_TIMEOUT_MS, platform: process.platform, path: pathValue };
}
function signature(file, gate) { return sha256(JSON.stringify(oracle(file, gate))); }

해시에 들어가는 항목을 보세요. 명령(check)과 기대값(expect)뿐 아니라 작업 디렉토리, 셸, 타임아웃, 플랫폼, 그리고 PATH 환경변수까지 들어갑니다. 하나라도 바뀌면 서명이 달라지고, 이전 승인은 자동으로 무효가 됩니다.

4-3. 정규식을 죽일 수 있는 스레드에 가두기

EXPECT:에는 /pattern/flags 형태의 임의 정규식을 쓸 수 있습니다. 편리하지만 위험합니다 — 어떤 정규식은 특정 입력에서 사실상 영원히 안 끝납니다.

해법은 우아합니다. 매 검사마다 워커 스레드를 새로 하나 띄우고, 250ms 타이머와 경쟁시킵니다. 타이머가 이기면 worker.terminate()로 스레드를 통째로 죽입니다. 워커 코드는 전부 9줄입니다.

// scripts/lib/regex-worker.mjs — 파일 전체
import { parentPort } from "node:worker_threads";
parentPort.once("message", ({ source, flags, output }) => {
  try { parentPort.postMessage({ matched: new RegExp(source, flags).test(output) }); }
  catch (error) { parentPort.postMessage({ error: error.message }); }
});

4-4. DB 없이 만드는 분산 잠금 — 리스(lease) 파일

병렬 서브에이전트 여러 개가 같은 파일을 동시에 고치면 서로 덮어씁니다. unlazy는 게이트에 OWNS: glob(파일 패턴)을 붙여 소유권을 선언하게 하고, .unlazy/locks/*.lease 파일로 조율합니다.

겹침 판정도 보수적입니다. globsOverlap()은 두 패턴이 확실히 서로소임을 증명할 수 있을 때만 통과시킵니다. 소스 주석이 태도를 그대로 보여줍니다.

// scripts/lib/gates.mjs
// Prove disjointness only when literal path segments disagree. Everything else
// conflicts, including mid-segment pairs such as a* and ab*.
export function globsOverlap(left, right) { ... }

a*와 ab*는 사실 겹치지만, 겹치는지 아닌지 판정이 복잡합니다. 애매하면 충돌로 본다 — 잘못된 병렬 실행보다 불필요한 대기가 낫다는 판단입니다.

4-5. 자기 자신을 풀어주는 서킷브레이커

Stop hook은 강력한 만큼 위험합니다. 게이트가 영원히 충족되지 않으면 사용자는 세션을 끝낼 수 없게 됩니다. scripts/stop-hook.mjs는 이걸 원장 내용 해시로 감지합니다.

// scripts/stop-hook.mjs
const MAX_BLOCKS = 6;
// ...
if (sessionState.blocks > MAX_BLOCKS) {
  allow("unlazy: releasing after " + MAX_BLOCKS + " blocks without gate progress" + where + "...");
}

차단할 때마다 원장의 해시를 기록해 두고, 6번 연속 해시가 그대로면 “진행이 없다”고 판단해 스스로 차단을 풉니다. 강제 장치가 사용자를 인질로 잡지 않게 하는 안전핀입니다.

5디렉토리 구조 해부

5-1. 읽는 순서 추천

1. README.md → 무엇을 주장하고 무엇을 주장하지 않는지
2. references/gates.md → 원장 포맷. 이걸 알아야 코드가 읽힘
3. scripts/lib/regex-worker.mjs → 9줄. 몸풀기
4. scripts/stop-hook.mjs → 132줄. 훅 계약이 어떻게 생겼는지
5. scripts/lib/gates.mjs → 575줄. 파서와 잠금의 본체
6. scripts/gate-check.mjs → 690줄. 마지막에
7. SECURITY.md → 코드를 본 뒤에 읽으면 “아 그래서 그렇게 짰구나”가 됨

5-2. references/ 를 따로 뺀 이유

SKILL.md는 에이전트가 매번 컨텍스트에 싣는 파일입니다. 여기에 모든 규칙을 다 넣으면 토큰을 크게 잡아먹습니다. 그래서 핵심 지침만 SKILL.md에 두고, 상세 규칙은 references/로 빼서 필요할 때만 읽게 합니다.

6학습 포인트 (기술별)

// scripts/gate-check.mjs
const stopChild = () => {
  try {
    if (process.platform === "win32") child.kill("SIGKILL");
    else process.kill(-child.pid, "SIGKILL");  // 음수 PID = 프로세스 그룹 전체
  } catch { try { child.kill("SIGKILL"); } catch {} }
};

7하드웨어 / 시스템 요구사항

내부 상한값

8직접 해볼 수 있는 실습 과제

# GATES.md
- ID: tests
  CHECK: npm test
  EXPECT: /(\d+) passing/

- ID: redos
  CHECK: node -e "console.log('a'.repeat(40))"
  EXPECT: /(a+)+b/

9관련 기술 심화 학습 로드맵

함께 보면 좋은 것

• 구조 비교 — 같은 “에이전트 규율” 문제를 프롬프트로 푸는 저장소(예: CLAUDE.md 모음집류)와 코드로 푸는 unlazy를 나란히 놓고, 각각 어떤 상황에서 깨지는지 표로 정리
• 훅 생태계 — Claude Code의 hook 문서를 읽고, Stop 외의 훅으로 같은 강제를 구현할 수 있는지 검토
• 검증 가능성 — 본인 팀의 “완료 정의(DoD)”를 실행 가능한 명령으로 바꿔 쓰는 연습. 대부분의 DoD는 실행 불가능하게 쓰여 있습니다

10핵심 키워드 사전

11참고 링크

저장소

• Leonxlnx/unlazy — 본체 (MIT)
• SKILL.md — 에이전트가 읽는 지침
• SECURITY.md — 위협 모델. 이 저장소에서 가장 잘 쓰인 문서
• research/validation-protocol.md — 자기 주장 철회와 재현 프로토콜
• references/gates.md — 원장 포맷 명세

배경 지식

• Claude Code Hooks 문서 — Stop hook 계약의 공식 명세
• Node.js worker_threads — 4-3절의 격리 기법
• Node.js child_process — 프로세스 실행과 종료
• CommonMark — Fenced code blocks — 파서가 직접 구현한 규칙
• OWASP — ReDoS
• vercel-labs/skills — npx skills add의 정체

현재 상태 (2026-08-24 확인)