fablize 딥다이브
— "검증·완료·조사"를 운(運)이 아닌 절차로 강제하는 Claude Code 플러그인

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

제작자가 발견한 핵심은 이렇다. Fable 5와 Opus 4.8을 비교했더니, 닫힌(정답이 있는) 작업에서는 두 모델이 사실상 동등했다. 차이는 열린(open-ended) 작업에서만 났고, 그 본질은 "암시 하나를 한 발 더 따라가는 깊이"였다. 그런데 이 깊이는 모델의 능력이라 지시로 옮길 수 없었다(주입 실험에서 반박됨). 반면 "실제로 돌려본다 · 끝까지 본다 · 체계적으로 조사한다" 같은 좋은 작업의 절차는 전이됐다. fablize는 바로 이 전이 가능한 절차만 골라 담은 것이다.

2왜 주목받는가

왜 지금 TrendShift에 오르는가.

"AI 코딩 에이전트가 작업을 다 했다고 말해 놓고 실제로는 안 했다"는 문제는 모든 사용자가 겪는 고질병이다. fablize가 주목받는 이유는, 이 문제를 정신론(더 잘하라는 프롬프트)이 아니라 결정론적 메커니즘(후크·검증 게이트)으로 막으려 하기 때문이다. 게다가 그 설계가 실측 비교 실험에 근거한다는 점이 차별점이다.

3기술 스택 전체 지도

의외로 단순하다 — Bash + Python(stdlib) + Markdown + Claude Code 플러그인 규약.

fablize에는 무거운 런타임이 없다. 외부 의존성 0이 설계 철학이다. 모든 게 Bash 후크, 표준 라이브러리만 쓰는 Python 한 개, Markdown 규약 문서로 이뤄진다. "하네스는 가벼워야 한다"는 원칙의 구현이다.

왜 "Python stdlib only"인가

goals.py는 argparse·json·datetime·pathlib만 import한다. pip 설치가 필요 없다는 뜻이다. 상태는 ./.fablize/goals.json과 ledger.jsonl에 파일로 저장돼 세션이 죽어도(대화가 끊겨도) 살아남는다. 외부 골 관리 시스템 없이 자기완결적으로 동작하는 게 핵심 설계다.

4아키텍처 심화 — 검증 절차를 강제하는 흐름

사용자 프롬프트 한 번이 어떤 게이트를 거쳐 "증거 없는 완료"를 막는가.

fablize의 본질은 "두 개의 후크가 작업의 입구와 출구를 지킨다"는 것이다. 입구에서는 router.sh가 작업 종류를 보고 맞는 규율을 주입하고, 출구에서는 finish-the-work.sh가 "약속만 하고 끝낸" 종료를 되돌린다. 그 사이를 goals.py의 검증 게이트가 받친다.

핵심 설계 패턴 4가지

5디렉토리 구조 해부

파일 하나하나가 곧 메커니즘 하나다.

주목할 구조: 실행 로직(hooks·scripts)과 지침 텍스트(skills·packs)가 분리돼 있다. 후크/엔진은 결정론적 코드, 팩/스킬은 모델에게 읽히는 절차 문서다. 같은 절차(예: 조사 프로토콜)가 router가 주입하는 한 줄 요약과 packs의 전문(全文) 두 층으로 존재해, 필요할 때만 전문을 읽게 한다(컨텍스트 절약).

6학습 포인트 (기술별)

이 작은 레포가 가르쳐 주는, 실무에 곧장 쓰는 것들.

Claude Code Hooks — 에이전트 행동을 외부에서 통제하기

fablize의 가장 큰 학습 가치는 hooks의 실전 패턴이다. 입구(UserPromptSubmit)에서 맥락을 주입하고, 출구(Stop)에서 종료를 검문하는 두 후크가 핵심이다. 후크는 stdin으로 JSON을 받아 처리하고, stdout/JSON 결정으로 응답한다. 출구 후크의 차단 패턴은 이렇게 생겼다.

# finish-the-work.sh — 약속만 한 종료를 감지해 차단(개념 발췌)
# 1) 무한루프 가드: 이미 한 번 막았으면 통과
active=$(... .get('stop_hook_active', False) ...)
if [ "$active" = "True" ]; then exit 0; fi

# 2) 마지막 단락(끝 400자)만 검사 — 보고서 전체가 아니라 "맺음말"
tail = last_text[-400:]

# 3) 미래/의도 표현만 매칭(과거형 제외). 영어+한국어
promise = re.search(r"\b(I'?ll|I will|let me)\b...\b(now|implement|run|fix)\b", tail)
asks_user = re.search(r"(\?|shall i|would you like|let me know)", tail)

# 4) 약속 O + 질문 X → 턴을 막고 "지금 실제로 하라" 재주입
if promise and not asks_user:
    print('{"decision":"block","reason":"...do that work now with tool calls..."}')

배울 핵심: (1) 무한루프 가드(stop_hook_active), (2) 범위 한정 검사(끝 400자만 — 본문 전체를 정규식 돌리면 오탐), (3) 의도 vs 완료 구분(과거형 제외), (4) 예외 통로(질문으로 끝나면 정당한 종료로 통과). "규율을 결정론으로 강제하되 정당한 경우는 빠져나가게 한다"는 균형 감각이 그대로 들어 있다.

입구 라우터 — 키워드로 "최소 규율"만 주입

# router.sh — 작업 신호별 정밀 주입(개념 발췌)
case "$low" in
  *debug*|*bug*|*error*|*crash*|*"not working"*)
    add "[fablize:investigation] ... investigation-protocol.txt 따르라 ..." ;;
esac
case "$low" in
  *html*|*svg*|*game*|*canvas*|*chart*|*render*)
    add "[fablize:grounding] ... verification-grounding-pack.txt 그라운딩 루프 ..." ;;
esac
[ -n "$emit" ] && printf '%s\n' "$emit"
exit 0   # 매칭 없으면 조용히 통과 — 작업 절대 안 막음

여기서 배울 것: "모든 규칙을 항상 주입"하면 컨텍스트가 오염되고 모델이 산만해진다. 그래서 작업 신호별로 필요한 한 줄만 주입하고, 전문은 팩 파일로 미뤄둔다. 프롬프트 엔지니어링의 "관련성 있는 컨텍스트만"을 후크 레벨에서 구현한 사례.

검증 게이트 상태머신 — goals.py

goals.py는 작은 상태머신이다. 스토리는 pending → in_progress → complete/failed/blocked로만 전이하고, 활성화(next)되지 않은 스토리는 체크포인트 불가, 완료엔 증거 필수, 마지막 스토리엔 검증 명령+결과 필수라는 불변식(invariant)을 코드로 박았다. 상태는 JSON 파일로 영속화돼 세션을 넘어 재개된다. "에이전트에게 책무성(accountability)을 부여하는 최소 설계"의 좋은 예다.

7시스템 요구사항

"무엇이 깔려 있어야 도는가" — 매우 가볍다.

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

"플러그인을 쓰기"에서 "메커니즘을 이해하기"로.

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

fablize를 발판으로 "에이전트 하네스 설계"까지 가는 4주 코스.

10핵심 키워드 사전

fablize를 읽다 막히는 용어 빠른 참조.

11참고 링크

• GitHub: fivetaku/fablize (README에 실험 근거 + 전이 가능/불가능 표)
• 한국어 README: README.ko.md
• Claude Code 플러그인/스킬 문서: Claude Code Docs
• Claude Code Hooks 가이드: Hooks 문서
• 설치: /plugin marketplace add fivetaku/fablize → /plugin install fablize
• always-on 설치: bash ${CLAUDE_PLUGIN_ROOT}/setup/setup.sh (local 권장)