break-time은(는) 무엇을 하나요?
너무 오랫동안 집중해서 코딩(또는 바이브코딩)하고 있을 때 휴식을 취하도록 부드럽게 알려주는 앰비언트 스킬입니다. Claude 자체는 응답 간의 실제 시간을 추적할 수 없습니다. Claude는 대화만 볼 뿐입니다. 후크는 Claude 외부의 하네스에서 실행되며, Claude가 알 수 없는 컨텍스트를 주입할 수 있습니다. 이것이 바로 이 스킬의 작동 원리입니다.
한 번도 후크를 작성해 본 적이 없다면 먼저 HOOKS-101.md를 읽어보세요. 독립형 튜토리얼이며, 복사하여 붙여넣기만 하면 됩니다. 읽는 데 약 15분 정도 걸리며, 나중에 구축할 모든 앰비언트 스킬의 기초가 됩니다.
기능
- 현재 "활성 세션"의 시작 시간을 추적합니다(10분 동안 유휴 상태이면 재설정).
- 사용자가 프롬프트를 제출할 때마다 활발하게 작업한 시간을 계산합니다.
- 설정 가능한 임계값(기본값 45, 90, 120분)을 초과하면 Claude의 컨텍스트에 일회성 알림을 주입합니다. 그러면 Claude는 사용자의 질문에 답변하기 전에 자신의 스타일로 간략하게 휴식을 언급합니다.
/snooze [N](기본 60분) 또는/break-reset명령어로 알림을 관리할 수 있습니다.- 각 임계값은 활성 세션당 한 번만 실행됩니다. 반복 알림이 없습니다.
호출
이 스킬은 패시브 후크(설치 후 자동 실행)와 몇 가지 액티브 명령어(관리용)로 구성됩니다.
| 트리거 | 동작 |
|---|---|
| (자동) | 후크는 모든 프롬프트에서 실행됩니다. 설치 후 별도 호출 불필요 |
/break 또는 /break-time | 현재 상태 표시: 활성 세션 실행 시간, 다음 임계값, 스누즈 상태 |
/snooze [N] | N분 동안 알림 스누즈 (기본값 60) |
/break-reset | 활성 세션 타이머 재설정 (지금을 세션 시작으로 간주) |
/break-time configure | 사용자에게 ~/.claude/break-time.conf에서 임계값 편집 안내 |
| 자연어: "break-time 스누즈", "지금 휴식 중이야", "타이머 중지" | 동일 |
비활성화
~/.claude/settings.json에서 후크 블록을 제거하세요. 스킬 파일은 그대로 둬도 됩니다. 후크가 연결되지 않으면 비활성화됩니다.
설치
break-time/폴더를~/.claude/skills/break-time/에 복사합니다.example-settings.json의 후크 블록을~/.claude/settings.json에 추가합니다(이미 존재하는 파일이므로 병합하고 덮어쓰지 마세요).- Claude Code를 다시 시작하여 하네스가 새 후크를 인식하도록 합니다.
- 끝입니다. 이제 모든 프롬프트에서 후크가 실행됩니다.
초보자용 전체 가이드는 HOOKS-101.md에 있습니다.
후크 작동 방식 (기계적 관점)
- 사용자가 프롬프트를 제출합니다.
- Claude가 프롬프트를 보기 전에 하네스가
bash ~/.claude/skills/break-time/scripts/check_break.sh를 호출합니다. - 후크는
~/.claude/break-time.state(플랫 키-값 파일)를 읽고, 경과 시간을 계산한 후, 임계값을 초과했는지 확인합니다. - 임계값이 발동하면 후크는
<system-reminder>블록을 표준 출력으로 출력합니다. 하네스는 표준 출력을 캡처하여 Claude의 다음 턴에 추가 컨텍스트로 추가합니다. - Claude는 알림을 보고 응답에 자연스럽게 녹여냅니다: "그런데, 지금 90분째 집중하고 계시네요. 계속 가기 전에 5분 정도 일어나서 걸어보시는 게 좋겠어요. 자, 질문에 답변드리자면..."
- 발동된 각 임계값은 상태 파일에 기록되어 활성 세션이 재설정될 때까지 다시 발동되지 않습니다.
설정
상태 및 설정은 ~/.claude/에 저장됩니다:
break-time.state— 런타임 상태(session_start, 발동된 임계값, snooze)break-time.conf— 선택적 사용자 설정(thresholds, idle_gap, message style)
break-time.conf가 없으면 기본값이 사용됩니다:
THRESHOLDS="45 90 120" # 분 단위 — 알림 시점
IDLE_GAP=10 # 유휴 시간(분) = 새 세션 간주
STYLE=friendly # friendly | aggressive | poetic
STYLE=poetic으로 설정하면 알림이 하이쿠 형식이 됩니다(poet-commit 스킬을 향한 크로스-스킬 러브레터입니다).
안전 장치
- 프롬프트를 절대 차단하지 않습니다. 후크는 항상 0으로 종료됩니다. 실패해도 사용자 작업에 영향을 미치지 않습니다.
- 항상 파일에 로그를 기록합니다(
~/.claude/break-time.log). 오류를 대역 내에서 표시하지 않고 디버깅이 가능합니다. - 출력이 제한적입니다. 알림은 짧은 단락 하나입니다. 컨텍스트 창을 넘치게 하지 않습니다.
- 스누즈는 항상 존중됩니다. 사용자가 스누즈 상태이면 후크는 계속 시간을 추적하지만 아무것도 출력하지 않습니다.
- 네트워크 호출이 없습니다. 순수 로컬 파일 I/O만 사용합니다. 프롬프트를 지연시키지 않습니다.
이 스킬의 파일
SKILL.md— 이 파일HOOKS-101.md— 후크 작성에 대한 독립형 튜토리얼 (배포 가능)example-settings.json—~/.claude/settings.json용 복사-붙여넣기 후크 설정scripts/check_break.sh— 후크 자체scripts/snooze.sh— N분 동안 알림 스누즈scripts/reset.sh— 활성 세션 타이머 재설정scripts/state.sh— 현재 상태 출력 (/break명령어에서 사용)README.md— 간단한 설치 지침