oh-my-fable

Anthropic 프롬프팅 가이드(Opus 5.5, Fable 5.1)의 작업 규칙을 Claude Code에 상시 적용하는 법. 설치만 하면 알아서: 터미널이든 헤드리스든 서브에이전트든, 세션마다 맞는 규칙이 들어갑니다.

Opus 5.5(지금 Claude Code의 기본 모델)와 Fable 5.1 기준이며, Sonnet 5.5(Claude Code 기본 effort가 Opus 5.5처럼 medium)·Opus 5·Sonnet 5에서도 그대로 씁니다.

한국어 · English · 中文

대충 한 줄로 시켜도, 제대로 된 요청으로 바뀌어 실행됩니다.

👤 당신이 치는 것

/fable-prompt 로그인 버튼 눌러도 아무 반응 없어 고쳐줘

🤖 Claude가 실제로 받는 요청 (대화 맥락에서 자동으로 채워짐)

목표: 로그인 버튼을 누르면 /api/login 이 호출되고, 성공하면 /dashboard 로 이동하게 한다
맥락: src/components/LoginButton.tsx, 콘솔 오류 "TypeError: onSubmit is not a function", 어제 인증 방식을 바꾼 커밋 이후 발생
범위: 이 버튼과 그 핸들러만. 옆의 회원가입 폼이나 다른 오류는 고치지 말고 후속 과제로 보고
완료 기준: 실제 클릭을 재현해 /dashboard 이동 확인, 콘솔 오류 0, 변경 파일 목록 첨부

설치만 하면, 나머지는 자동입니다.

• 사용 형태를 세션마다 알아서 판정 · 터미널·IDE면 대화형, claude -p·Agent SDK·에이전트 하네스면 무인으로 감지해 "사용자가 지켜보고 있지 않다" 문단과 "중간 보고로 멈추지 말라" 문단을 그때만 넣습니다. 섞어 써도 바꿀 것이 없습니다.
• 서브에이전트까지 자동 · Agent 도구로 띄운 서브에이전트(규칙 파일을 안 읽는 Explore·Plan 포함)에 짧은 판을 따로 넣습니다.
• 파일을 만들지 않습니다 · CLAUDE.md도 규칙 파일도 건드리지 않고, 훅이 세션마다 넣습니다. 그래서 갱신은 플러그인만 올리면 되고 제거하면 흔적이 없습니다.
• 질문 없음 · 설정은 선택 사항입니다. 확인할 것은 설치 승인 하나뿐입니다. 한 번은 /fable-setup rules-file을 권합니다. 기본 규칙을 규칙 파일로 두는 방식이고, Claude Code 훅 문서도 바뀌지 않는 규칙은 훅 텍스트보다 파일에 두라고 합니다.

Anthropic 공식 문서 Prompting Claude Fable 5.1, Prompting Claude Opus 5.5, 그리고 Opus 5.5 가이드가 출발점으로 지정한 Prompting Claude Opus 5의 처방을 훅 하나와 스킬 네 개에 담았습니다. 문구는 원문을 거의 그대로 씁니다.

어느 모델용인가요? Opus 5.5(지금 Claude Code의 기본 모델)와 Fable 5.1 둘 다입니다. 끝까지 하기·범위 제한·진행 보고 규칙은 두 모델의 공식 가이드가 같은 말을 하고, 무인 세션에만 붙는 "중간 보고로 멈추지 말라" 문단은 Opus 5.5 가이드에서 왔습니다. 부분 편집·도구 일괄 호출·서식 규칙은 Fable 5.1 가이드에만 있는 처방이지만 다른 모델에 있어도 해가 되지 않습니다. 네 칸 요청 틀(목표·맥락·범위·완료 기준)은 모델이 무엇이든 되묻기와 빗나간 결과를 줄입니다. Sonnet 5.5(Claude Code 기본 effort medium, Opus 5.5와 같음), Opus 5, Sonnet 5에서도 그대로 씁니다. 세션이 xhigh나 max effort로 시작하면 훅이 Sonnet 5.5 가이드의 블록 N도 넣습니다.

목차

• 무엇을 하나
• 설치: 한마디
• 사용법: 평소처럼
• 초보자 흐름
• 작동 원리: 세 층
• 1층 · 매번 요청에
• 2층 · 상시 규칙
• 3층 · 설정값
• 증상별 처방
• FAQ
• 구성
• 기여와 라이선스

무엇을 하나

Fable 5.1은 긴 작업을 혼자 끝까지 해내는 능력이 커진 대신 버릇이 바뀌었습니다. 작업 중 말수가 줄고, 한 번에 도구 하나씩만 부르고, 작은 수정에도 파일을 통째로 다시 쓰고, low effort에서는 검색 대신 기억으로 답합니다. Opus 5.5는 긴 무인 작업 중간에 진행 보고만 하고 턴을 끝내 작업이 거기서 멈추는 버릇이 있습니다(공식 가이드 "Unattended agentic runs"). 공식 가이드는 이런 변화에 대한 증상별 처방이고, 이 플러그인은 그 처방을 자동으로 적용합니다.

설치: 한마디

Claude Code에 이렇게만 말하세요.

https://github.com/Junhan2/oh-my-fable 설치해줘

Claude가 설치하면 끝입니다. 질문도, 설정 파일도 없습니다. 다음에 Claude Code를 열면 자동으로 적용됩니다. 지금 이 세션에서 바로 쓰고 싶으면 /reload-plugins(방금 설치한 플러그인 로드) 다음 /clear(규칙 주입) 를 한 줄씩.

claude plugin marketplace add Junhan2/oh-my-fable
claude plugin install oh-my-fable@oh-my-fable

60초 경로: 내 환경에서는?

사용법: 평소처럼

그냥 평소처럼 요청하면 됩니다. 상시 규칙은 이미 켜져 있습니다. 요청이 짧거나 막연하면 앞에 /fable-prompt를 붙이세요.

/fable-prompt 이거 좀 고쳐줘

목표·맥락·범위·완료 기준·effort를 채운 요청을 보여 주고 바로 실행합니다. 보기만 하려면 뒤에 프롬프트만.

초보자 흐름

작동 원리: 세 층

가이드의 처방은 적용 방법이 다른 세 층으로 나뉩니다.

1층 · 매번 요청에

좋은 요청은 네 칸입니다.

요청에 따라 덧붙이는 것:

• 문제를 설명만 할 때 · "진단만 하고 고치지 마". 가이드의 명시적 예외.
• 최신 정보가 필요할 때 · effort를 high 이상으로 두거나 "사용자가 쓴 이름 그대로 한 번은 검색해" (블록 H).
• effort · Opus 5.5와 Sonnet 5.5는 medium이 기본이자 가이드의 출발점, Fable 5.1은 high가 기본. 어려운 작업만 그 세션에서 올리기(/effort high 다음 s). low는 검색을 건너뛸 수 있음. xhigh/max는 생각이 길어지고(Opus 5.5는 같은 단계에서 Opus 5보다 더 오래 생각함) 긴 문서는 초안을 두 번 써서 느려지니 장문 안내문(블록 G)을 붙이고 max_tokens를 넉넉히.
• 글이 빽빽할 때 · Please remove all mannered prose.
• 자료 요약 · 올바른 답 예시 1건(블록 J)을 같이 줌.

2층 · 상시 규칙

플러그인의 SessionStart 훅이 세션마다 아래 블록을 영어 원문 그대로 불러옵니다(파일 hooks/always-on.md). CLAUDE.md는 수정하지 않으며, 사용자 언어와 무관하게 영어입니다. 블록 A의 첫 문단("사용자가 지켜보고 있지 않다")과 블록 M("중간 보고로 멈추지 말라")은 헤드리스·SDK 세션에서만 자동으로 들어가고 터미널·IDE에서는 빠집니다. 항상 넣으려면 /fable-setup unattended. 블록 N은 세션이 xhigh나 max effort로 시작할 때만 들어갑니다(claude -p에서는 훅이 모델을 전달받지 못해 CLAUDE_CODE_EFFORT_LEVEL만 기준이 됩니다). 훅이 넣는 각 부분은 사실을 말하는 한 줄로 시작합니다(예: "This session was started headless (entrypoint sdk-cli); the user's standing rules for such sessions follow."). Claude Code 훅 문서가 훅 텍스트를 시스템 명령이 아닌 사실 문장으로 쓰라고 하기 때문입니다.

3층 · 설정값

• 모드 · ~/.claude/oh-my-fable.json 의 {"enabled": true, "mode": "interactive" | "unattended"}. 프로젝트의 .claude/oh-my-fable.json 이 있으면 그것이 우선. /fable-setup 이 대신 써 줍니다.
• effort · /effort <단계> 후 Enter가 settings.json의 modelSettings.<모델>.effortLevel에 모델별로 저장합니다. 옛 전역 effortLevel은 Opus 5.5와 Sonnet 5.5에는 적용되지 않습니다. 환경 변수 CLAUDE_CODE_EFFORT_LEVEL이 있으면 그것이 이기니 모델별 값을 쓰려면 환경 변수를 비울 것. maxEffortLevel(전역 또는 모델별)이 있으면 어느 값이든 그 상한으로 깎이고, /fable-status가 깎인 값을 보여 줍니다. 기본값은 Opus 5.5·Sonnet 5.5 medium, 그 밖의 모델 high(Opus 4.7은 xhigh). 모델마다 단계의 실제 사고량이 달라 다른 모델의 값을 그대로 옮기지 말 것.
• API 직접 연동 · thinking.display: "updates"를 켜야 진행 메모가 화면에 옴. 대화 이력은 덧붙이기만(thinking 블록 포함), 턴마다 넣는 알림은 turn-scoped system message로. 압축은 서버 압축 또는 블록 K.
• 서브에이전트 · 시작 도구는 즉시 반환, 결과는 나중 메시지로. Claude Code 서브에이전트는 세션의 effort를 그대로 물려받으니, 고정하려면 에이전트 파일 머리말(frontmatter)에 effort:.
• 비전 · 차트·표는 crop-and-zoom 도구를 붙이면 대부분의 이득.
• 거절(stop_reason: "refusal") 처리 · "컴파일 되나요?" 대신 "버그 있나요?"로 묻기.

증상별 처방

블록 원문 전체: skills/fable-prompt/references/prompt-blocks.md

FAQ

CLAUDE.md에 이미 비슷한 규칙이 있으면? /fable-setup이 표로 짚어 줍니다. 같은 뜻이면 "이미 있음", 반대 뜻(서식 금지, 마지막에 한꺼번에 보고)이면 바꿔 넣을 문장을 제안합니다. 실제 수정은 사용자가 합니다. Claude Code가 AI의 CLAUDE.md 자기 수정을 막기 때문입니다.

규칙을 CLAUDE.md 말고 다른 곳에 두고 싶어요. 기본값에서는 규칙이 플러그인 안에만 있고 훅이 세션마다 넣으므로 CLAUDE.md도 규칙 파일도 만들지 않습니다. 권장하는 설정은 규칙 파일(/fable-setup rules-file)입니다. Claude Code 훅 문서가 바뀌지 않는 규칙은 훅 텍스트보다 파일에 두라고 하고, 에이전트 팀도 이 파일을 읽습니다. CLAUDE.md 구간은 세 번째 선택지입니다. 비교표는 초보자 흐름의 "선택 사항"에 있습니다.

Opus 5.5에서도 되나요? 됩니다. 지금 Claude Code의 기본 모델이 Opus 5.5라 2.2.0부터 두 모델을 함께 기준으로 삼습니다. 끝까지 하기·범위 제한·진행 보고는 두 가이드가 같은 말을 하고, 무인 세션의 "중간 보고로 멈추지 말라" 문단(블록 M)은 Opus 5.5 가이드에서 왔습니다. 서식 규칙·부분 편집·도구 일괄 호출은 Fable 5.1 가이드에서 온 것이라 Opus 5.5에서는 효과가 작을 수 있지만 해는 없습니다. Sonnet 5.5, Opus 5, Sonnet 5도 마찬가지입니다. Sonnet 5.5도 Claude Code에서 medium effort로 시작하고 사용자 설정의 전역 effortLevel을 무시하며, 상태 줄이 그 사실을 보여 줍니다.

왜 지금 바로 쓰려면 /reload-plugins 다음 /clear 인가요? 공식 문서 기준 두 명령은 하는 일이 다릅니다. /reload-plugins는 "플러그인, 스킬, 에이전트, 훅, MCP 서버를 재시작 없이 다시 로드"합니다(Plugins). 규칙을 넣는 SessionStart 훅은 "새 세션(startup), 재개(resume), /clear, 압축(compact), 분기(fork)" 때만 실행됩니다(Hooks). 즉 reload는 훅을 등록만 하고 실행하지 않으므로, 설치한 세션에서는 /clear로 한 번 실행시켜야 합니다. 새 세션을 열면 둘 다 필요 없습니다.

지금 뭐가 켜져 있는지 보려면? /fable-status. 플러그인 버전, 규칙 위치, 이 세션의 모드(자동 감지 근거 포함), effort, 규칙 파일 버전, CLAUDE.md 충돌을 표 하나로 보여 주고 아무것도 바꾸지 않습니다. 새 세션을 열 때도 같은 내용이 한 줄로 화면에 뜹니다(Claude의 문맥에는 들어가지 않음).

되돌리려면? /fable-setup remove 가 설정 파일, 규칙 파일, CLAUDE.md 구간을 지웁니다. 그다음 claude plugin uninstall oh-my-fable@oh-my-fable. 잠시 끄기만 하려면 ~/.claude/oh-my-fable.json 에 {"enabled": false}.

플러그인을 못 까는 헤드리스 전용 환경(별도 CLAUDE_CONFIG_DIR, CI)은? hooks/rules-file-unattended.md를 그 환경의 rules/oh-my-fable.md로 복사(또는 이 저장소 체크아웃에 심링크)하면 플러그인 없이 무인 규칙 전체가 실립니다. 훅은 이 파일을 사용자 관리 파일로 보고 조용합니다.

/fable-audit와 /doctor prompt-audit는 뭐가 다른가요? 묻는 방향이 반대입니다. /fable-audit는 내 규칙에 프롬프팅 가이드의 어떤 절이 빠졌는지(더할 것)를 찾고, Claude Code의 /doctor prompt-audit(2.1.283 이상)는 내 규칙에서 낡았거나 틀렸거나 서로 부딪히는 문구(지울 것)를 찾습니다. 둘 다 스스로 고치지 않으니, 설정을 정리할 때는 둘 다 돌리세요.

omitClaudeMd: true인 서브에이전트도 규칙을 받나요? 규칙 파일이나 CLAUDE.md로는 받지 못합니다. Claude Code 2.1.284에서 재 보니 omitClaudeMd: true인 사용자 정의 서브에이전트는 ~/.claude/rules/*.md, 프로젝트의 .claude/rules/*.md, CLAUDE.md를 하나도 보지 못했고, 같은 에이전트에서 이 설정만 뺀 쪽은 셋 다 봤습니다. 훅은 이런 에이전트를 구별할 수 없어서(SubagentStart 입력에는 에이전트 종류만 옴) 훅만 방식이면 다른 서브에이전트처럼 짧은 판을 받고, 다른 방식이면 이 플러그인에서 아무것도 받지 않습니다. 가벼운 문맥이라는 이 설정의 취지와 맞으니, 꼭 닿아야 하는 규칙은 그 에이전트의 프롬프트에 넣으세요.

API나 Agent SDK로 직접 붙이는 경우는? /fable-setup은 질문 도구가 필요해 SDK에서는 auto 인자만 됩니다. 가장 간단한 방법은 hooks/always-on.md 내용을 시스템 프롬프트에 그대로 붙이는 것입니다. 3층의 API 항목(thinking.display 등)은 그쪽 설정입니다.

구성

oh-my-fable/
├── .claude-plugin/
│   ├── plugin.json            플러그인 매니페스트
│   └── marketplace.json       이 저장소를 마켓플레이스로 등록
├── hooks/
│   ├── hooks.json             SessionStart · SubagentStart 훅 등록
│   ├── session-start.sh       훅 본체 (세션 시작: 규칙 파일이 있으면 무인 문단만, 없으면 전체 · 서브에이전트: 짧은 판 · --status)
│   ├── subagent.md            서브에이전트에 넣는 짧은 판
│   ├── always-on.md           블록 원문 (영어)
│   ├── rules-file.md          /fable-setup이 ~/.claude/rules/oh-my-fable.md 로 복사하는 기본 규칙
│   ├── rules-file-unattended.md 플러그인 없는 헤드리스 전용 환경용 정적 규칙(무인 문단 둘 포함)
│   ├── effort-high.md         블록 N, 세션이 xhigh·max effort로 시작할 때만 추가
│   └── autonomy-unattended.md 무인 모드에서만 추가되는 문단 둘
├── skills/
│   ├── fable-setup/SKILL.md   충돌 점검·모드 전환·설정 점검 (2층·3층)
│   ├── fable-status/SKILL.md  지금 적용 중인 것 한 표로 (읽기 전용)
│   ├── fable-audit/
│   │   ├── SKILL.md           내 규칙을 가이드와 대조 (읽기 전용)
│   │   └── references/        가이드 절별 점검표와 모델별 주의점
│   └── fable-prompt/
│       ├── SKILL.md           매번 요청 개선 (1층)
│       └── references/        블록 원문(A~N)과 전후 예시
├── evals/                     `claude plugin eval` 평가 묶음: 사례 5개, 모델 판정 없이 규칙으로 채점
├── README.md · README.en.md · README.zh.md
└── LICENSE

기여와 라이선스

이슈와 PR을 환영합니다. 가이드가 갱신되면 hooks/always-on.md(주입 원문), hooks/autonomy-unattended.md(무인 문단), hooks/rules-file.md(마커 버전을 올릴 것), hooks/rules-file-unattended.md, hooks/effort-high.md, skills/fable-prompt/references/prompt-blocks.md(전체 블록 목록)를 같이 고칩니다. 플러그인이 실제로 무엇을 보태는지 재려면 claude plugin eval . --scaffold --allow-tools Edit Write를 돌립니다(사례마다 플러그인 없는 쪽도 함께 돌려 비교합니다).

MIT © Junhan2. 가이드 원문의 저작권은 Anthropic에 있습니다.