주맨의 개발노트

Claude Code Hook으로 작업 완료 알림 받기

JooMan — Tue, 31 Mar 2026 20:08:14 +0900

들어가며

Claude Code로 작업을 맡겨두고 다른 일을 하다 보면 "언제 끝났지?" 하고 화면을 계속 확인하게 됩니다. 특히 여러 프로젝트를 동시에 돌릴 때는 어느 인스턴스가 완료됐는지도 알기 어렵습니다. Android Studio 플러그인, VS Code 터미널, 일반 터미널까지 열어두면 상황은 더 복잡해집니다.

저도 처음에는 그냥 터미널 탭을 왔다 갔다 하면서 확인했습니다. 그런데 이게 생각보다 흐름을 많이 끊었습니다. 아직 안 끝난 작업을 확인하러 들어갔다가 다시 원래 하던 일로 돌아오는 일이 반복됐고, 어떤 때는 Claude Code가 이미 제 응답을 기다리고 있는데도 한참 뒤에 알아차리기도 했습니다.

그래서 Claude Code의 Hook 시스템으로 macOS 네이티브 알림을 붙였습니다. 제가 실제로 쓰고 있는 설정에는 작업 완료와 사용자 응답 요청을 서로 다른 소리로 구분하는 Hook이 들어가 있고, 알림 메시지에는 프로젝트명과 시각도 함께 표시되도록 되어 있습니다. 이 글은 그 실제 설정과, 그 설정을 쓰면서 느낀 사용 흐름의 변화를 함께 정리한 기록입니다.

Hook을 붙이게 된 이유

Claude Code를 백그라운드 작업자처럼 쓰기 시작하면서 가장 먼저 부딪힌 건 완료 시점을 놓치는 문제였습니다. 작업이 30초 걸릴지 5분 걸릴지 매번 다르다 보니, 결국 사람 쪽에서 계속 상태를 확인하게 됩니다. 자동화 도구를 써 놓고 다시 수동 모니터링으로 돌아가는 셈이었습니다.

제가 원한 건 거창한 대시보드가 아니었습니다. 그냥 "끝났다"와 "지금 제가 답해야 한다"를 확실히 구분해서 알려주는 신호면 충분했습니다. Hook은 딱 그 지점에 잘 맞았습니다. Claude Code가 직접 뭔가 복잡한 UI를 제공하는 게 아니라, 특정 이벤트가 발생했을 때 제가 원하는 쉘 명령어를 붙일 수 있기 때문입니다.

Hook이 동작하는 방식

Hook은 Claude Code의 특정 이벤트가 발생할 때 쉘 명령어를 자동으로 실행하는 메커니즘입니다. Claude가 직접 알림을 띄우는 게 아니라, 이벤트가 발생하는 순간 지정해 둔 명령어가 실행되는 구조입니다.

1 — 이벤트 발생 Claude Code가 응답을 마치거나 사용자 입력을 기다림

↓

2 — Hook 트리거 settings.json에 등록된 명령어 실행

↓

3 — 알림 표시 macOS 네이티브 알림 팝업 + 소리 재생

이 구조가 좋았던 이유는 설정을 한 군데만 바꾸면 된다는 점입니다. Hook은 ~/.claude/settings.json에 등록하므로 Android Studio 플러그인, VS Code 터미널, 일반 터미널 등 어디서 Claude Code를 띄우든 동일하게 동작합니다. 한 환경에서만 따로 맞춰야 하는 종류의 설정이 아니라는 점이 꽤 편했습니다.

실제로는 두 이벤트만 있어도 충분했다

Claude Code는 다양한 이벤트에 Hook을 걸 수 있지만, 제 현재 설정 파일에 들어 있는 알림 Hook은 두 가지뿐입니다. 작업이 끝났다는 신호와, 지금 제가 확인해야 한다는 신호입니다. 제 경험상 이 둘만 분리해도 사용 흐름은 꽤 달라졌습니다.

Stop

작업 완료 — Claude가 응답을 마쳤을 때

Claude가 응답 생성을 완전히 끝내고 사용자 입력을 기다리는 상태가 될 때 트리거됩니다. 코드 작성, 파일 수정, 분석 등 모든 작업이 끝난 시점입니다. "이제 확인하러 가도 됩니다"라는 신호로 쓰기 좋습니다.

Noti

응답 요청 — Claude가 사용자 입력을 기다릴 때

Claude가 작업 중 사용자 확인이 필요한 상황에 트리거됩니다. Plan 모드에서 승인 대기, 파일 수정·명령 실행 권한 요청, 선택지 제시 등이 해당됩니다. "지금 당장 확인해야 합니다"라는 신호로 쓰기 좋습니다.

참고로 Hook이 지원하는 전체 이벤트는 Stop, Notification 외에도 PreToolUse, PostToolUse, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, SubagentStop가 있습니다. 저도 처음에는 이것저것 다 붙여볼까 생각했지만, 실제로 계속 유지하게 되는 건 단순한 설정이었습니다. 알림처럼 즉시 체감되는 자동화부터 붙이는 편이 훨씬 낫다고 느꼈습니다.

macOS 알림 명령어

macOS에서 네이티브 알림을 띄우는 가장 간단한 방법은 osascript입니다. 추가 설치가 필요 없다는 점이 좋았습니다. 이 작업을 위해 별도 앱이나 메뉴바 유틸리티를 깔고 싶지는 않았기 때문입니다. 기본 제공 기능만으로 충분했습니다.

기본 형태 Shell

osascript -e "display notification \"메시지\" with title \"제목\" subtitle \"부제목\" sound name \"Glass\""

알림에 표시할 수 있는 필드는 네 가지입니다.

필드	설명	예시
`notification`	알림 본문. 가장 눈에 잘 띄는 텍스트.	`my-android-app 완료`
`title`	앱 이름 위치에 표시되는 굵은 텍스트.	`Claude Code`
`subtitle`	title 아래 작게 표시되는 보조 텍스트.	`14:32`
`sound name`	알림 소리. `/System/Library/Sounds/`의 파일명.	`Glass`, `Ping`

프로젝트명과 시각 자동 삽입

제 현재 설정에서 눈에 띄는 포인트는 프로젝트명을 자동으로 넣는 부분입니다. 실제 명령어에 $(basename $PWD)와 $(date +%H:%M)이 들어가 있어서, 알림에 현재 작업 디렉토리명과 시각이 함께 표시됩니다. 여러 Claude Code 인스턴스를 같이 띄울 때는 알림이 왔다는 사실보다 어느 프로젝트에서 온 알림인지가 더 중요하다고 느꼈는데, 저는 이 방식이 그 문제를 가장 단순하게 풀어준다고 봤습니다.

프로젝트명 + 시각 포함 Shell

osascript -e "display notification \"$(basename $PWD) 완료\" with title \"Claude Code\" subtitle \"$(date +%H:%M)\" sound name \"Glass\""

$PWD는 Hook이 실행되는 시점의 작업 디렉토리를 반환합니다. Claude Code가 실행된 폴더가 곧 $PWD가 되므로, 같은 명령어를 어떤 프로젝트에서든 그대로 쓸 수 있습니다. 따로 프로젝트명을 하드코딩할 필요가 없어서 실제 운용할 때 훨씬 덜 번거롭습니다.

단순 알림

알림이 울려도 화면을 봐야 어느 프로젝트인지 알 수 있습니다. 인스턴스가 많을수록 혼란스러워집니다.

프로젝트명 포함 알림

알림 배너에 my-android-app 완료처럼 프로젝트명이 표시되어 화면을 보지 않아도 파악할 수 있습니다.

두 가지 Hook 설정

제 실제 설정에서는 Stop에 Glass, Notification에 Ping을 연결해 두었습니다. 그 이유는 제 사용 경험 때문입니다. 화면을 보고 있지 않을 때는 텍스트보다 소리가 먼저 들어오는데, 저는 Glass 소리(맑고 길게)를 작업 완료 신호로, Ping 소리(짧고 날카롭게)를 응답 요청 신호로 두는 쪽이 가장 직관적이었습니다.

Stop — 작업 완료 알림

️

Terminal14:32

Claude Code

my-android-app 완료

Glass 사운드 재생

Notification — 응답 요청 알림

️

Terminal14:33

Claude Code ⚠️

my-android-app — 응답이 필요합니다

Ping 사운드 재생

제가 현재 쓰는 settings.json 설정

~/.claude/settings.json에 hooks 키를 추가하면 됩니다. 기존 설정(플러그인, statusLine 등)은 그대로 두고 새 키만 넣으면 됩니다. 아래는 제가 지금 그대로 쓰고 있는 형태입니다.

~/.claude/settings.json JSON

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e \"display notification \\\"$(basename $PWD) 완료\\\" with title \\\"Claude Code\\\" subtitle \\\"$(date +%H:%M)\\\" sound name \\\"Glass\\\"\""
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e \"display notification \\\"$(basename $PWD) — 응답이 필요합니다\\\" with title \\\"Claude Code ⚠️\\\" subtitle \\\"$(date +%H:%M)\\\" sound name \\\"Ping\\\"\""
          }
        ]
      }
    ]
  }
}

설정 파일을 저장한 후 Claude Code를 재시작하면 적용됩니다. Claude Code는 시작 시 settings.json을 읽기 때문에 실행 중 수정해도 재시작이 필요합니다. 처음에는 저장만 하면 바로 반영될 줄 알았는데, 이 부분은 한 번 놓치기 쉬웠습니다.

다만 실제 설정을 그대로 적으면 지금처럼 "command" 한 줄이 길어질 수밖에 없습니다. JSON 문자열 자체는 예쁘게 여러 줄로 나누기 어렵기 때문입니다. 가독성을 더 챙기고 싶다면 알림 명령어를 별도 쉘 스크립트로 빼는 쪽이 낫습니다.

가독성을 우선하면 스크립트로 분리하는 편이 낫다

예를 들어 settings.json에서는 스크립트만 호출하고, 실제 osascript 명령은 별도 파일로 분리할 수 있습니다. 이렇게 하면 설정 파일은 짧아지고, 알림 문구를 나중에 수정할 때도 훨씬 편합니다.

~/.claude/settings.json JSON

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/notify-stop.sh"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/notify-input.sh"
          }
        ]
      }
    ]
  }
}

~/.claude/hooks/notify-stop.sh Shell

osascript -e "display notification \"$(basename $PWD) 완료\" with title \"Claude Code\" subtitle \"$(date +%H:%M)\" sound name \"Glass\""

~/.claude/hooks/notify-input.sh Shell

osascript -e "display notification \"$(basename $PWD) — 응답이 필요합니다\" with title \"Claude Code ⚠️\" subtitle \"$(date +%H:%M)\" sound name \"Ping\""

첫 실행 시 알림 권한 허용

처음 Hook이 실행될 때 macOS가 Terminal(또는 iTerm2)의 알림 권한을 요청합니다. 허용을 눌러야 이후 알림이 표시됩니다. 저는 처음에 "명령어는 맞는데 왜 알림이 안 뜨지?" 하고 잠깐 헷갈렸는데, 원인은 대부분 여기였습니다. 권한을 실수로 거부했거나 나중에 변경하고 싶다면 시스템 설정 → 알림 → Terminal에서 조정할 수 있습니다.

배너

배너 방식 권장

화면 오른쪽 상단에 잠깐 떴다가 자동으로 사라집니다. 알림 센터에도 기록이 남아 나중에 확인할 수 있습니다. 작업에 방해가 적으면서도 눈에 잘 띕니다.

알림
센터

알림 기록 확인

화면 오른쪽 상단 시계를 클릭하면 지나간 알림을 모두 볼 수 있습니다. 여러 인스턴스가 순서대로 완료됐을 때 타임라인을 확인하는 용도로 유용합니다.

사운드는 이렇게 골랐다

/System/Library/Sounds/에 있는 파일이라면 어떤 소리도 쓸 수 있습니다. sound name에는 확장자 없이 파일명만 적으면 됩니다. 실제 제 설정 파일에는 Glass와 Ping이 들어 있습니다. 아래 표의 다른 항목은 선택 가능한 예시들이고, 왜 저는 이 조합을 쓰고 있는지도 함께 정리해봤습니다.

사운드	특징	추천 용도
`Glass`	맑고 길게 울리는 종소리	작업 완료 (Stop)
`Ping`	짧고 날카로운 금속음	응답 요청 (Notification)
`Purr`	부드럽고 낮은 진동음	조용한 환경에서 작업 완료
`Funk`	묵직하고 낮은 타격음	오류나 주의가 필요한 경우
`Tink`	아주 짧고 가벼운 틱 소리	빈번한 이벤트에서 덜 거슬리게

정리하며

이 설정을 붙이고 나서 가장 크게 달라진 건 Claude Code를 덜 감시하게 됐다는 점입니다. 예전에는 일이 끝났는지 확인하려고 제가 먼저 Claude Code를 들여다봤다면, 지금은 정말 필요한 순간에만 알림이 저를 부릅니다. 작은 차이 같지만 집중이 꽤 덜 끊깁니다.

정리하면, 제 실제 설정 파일에는 Stop과 Notification 두 이벤트만 들어 있고, 각각 Glass와 Ping 소리가 연결되어 있습니다. 또 basename $PWD를 써서 프로젝트명이 자동으로 들어가게 해 두었습니다. 여기서부터는 사실 설명이 아니라 제 경험인데, 저는 이 정도만으로도 Claude Code를 한결 덜 감시하게 됐습니다. 특히 여러 작업을 같이 돌릴 때 체감이 더 컸습니다.

핵심 정리

제가 Hook을 붙인 이유는 Claude Code를 덜 감시하고 싶어서였습니다. 완료 여부를 확인하러 직접 들어가는 흐름이 줄어들면 작업 집중이 덜 끊깁니다.
Stop은 작업 완료, Notification은 응답 요청입니다. 두 이벤트만 나눠도 실제 사용성은 꽤 좋아집니다.
basename $PWD로 어느 프로젝트인지 자동 표시합니다. 이 부분은 실제 설정 명령어에도 들어 있고, 여러 인스턴스를 같이 띄울 때 특히 유용했습니다.
소리 구분은 생각보다 효과가 큽니다. 실제 설정은 Glass와 Ping을 쓰고 있고, 저는 이 조합이 가장 직관적이었습니다.
설정은 단순해야 오래 갑니다. 이건 제 결론입니다. 여러 이벤트를 다 붙이기보다, 먼저 체감이 큰 알림 자동화부터 두는 편이 유지하기 쉬웠습니다.

Claude Code Skill 사용 경험 - 왜 user-invocable: false로 설계했나

JooMan — Mon, 30 Mar 2026 14:19:19 +0900

들어가며

Claude Skill을 처음 만들 때는 보통 "이걸 어떻게 호출하지?"부터 생각하게 됩니다. 저도 처음에는 비슷했습니다. 그런데 디자인 시스템 관련 Skill을 정리하면서 방향이 조금 달라졌습니다. 제가 원한 것은 호출 가능한 기능 세트가 아니라, Claude가 언제 물어봐도 같은 기준으로 답하게 만드는 내부 판단 레이어였습니다.

그래서 `design-system-color`, `design-system-spacing`, `design-system-shape`, `design-system-typography` 같은 Skill을 만들면서 일부러 user-invocable: false를 넣었습니다. 이 글은 왜 그렇게 했는지, 그리고 그 선택이 디자인 시스템을 수정하거나 확장할 때 어떤 차이를 만들었는지에 대한 기록입니다.

왜 직접 호출 가능한 Skill로 만들지 않았나

겉으로 보기에는 Skill을 직접 호출할 수 있게 열어두는 편이 더 친절해 보입니다. 하지만 제 목적에는 오히려 반대였습니다. 사용자가 스킬 이름을 기억하고 명령어처럼 불러야 하는 구조보다, 그냥 자연스럽게 질문하면 Claude가 내부 기준을 참고해 답하는 구조가 더 맞았습니다.

특히 디자인 시스템은 단순히 질문에 답하는 주제가 아니라, 시간이 지나면서 계속 변경되고 보완되는 규칙 집합에 가깝습니다. "이 spacing token을 바꿔도 될까?", "새로운 semantic color를 추가할 때 기준이 뭐지?", "radius 규칙을 컴포넌트 전반에 어떻게 반영하지?" 같은 상황에서는 사용자가 스킬 이름을 떠올리는 것보다, Claude가 내부적으로 기준을 안정적으로 참조하는 편이 훨씬 중요했습니다.

직접 호출 중심

사용자가 스킬 이름과 사용법을 알아야 합니다. 결국 기능을 노출하는 쪽에 초점이 맞고, 질의 경험은 오히려 불필요하게 복잡해질 수 있습니다.

내부 기준 중심

사용자는 평소처럼 자연어로 질문하고, Claude만 내부적으로 Skill을 참고합니다. 인터페이스는 단순해지고, 답변 기준은 더 안정적으로 유지됩니다.

`user-invocable: false`에 담았던 의도

이 설정은 단순히 "숨겨두기"가 아니었습니다. 제 경우에는 이 Skill의 역할을 기능이 아니라 기준으로 한정하려는 선언에 가까웠습니다. 사용자가 직접 호출하는 순간, 이 Skill은 운영 문서보다 명령형 도구처럼 인식되기 쉽습니다.

그렇게 되면 문제가 두 가지 생깁니다. 하나는 사용법 자체를 또 학습해야 한다는 점이고, 다른 하나는 "언제 이 스킬을 써야 하지?"라는 메타 질문이 새로 생긴다는 점입니다. 저는 디자인 시스템을 다룰 때 필요한 것이 호출 절차가 아니라, 변경이나 확장 상황에서도 같은 기준을 유지하는 일이라고 봤기 때문에 그 부담을 사용자 쪽에 넘기고 싶지 않았습니다.

.claude/skills/design-system-color/SKILL.md YAML

---
name: design-system-color
description: Nevera 컬러 디자인 시스템 가이드
user-invocable: false
---

당신은 Nevera의 컬러 디자인 시스템 가이드다.
역할은 프로젝트의 시맨틱 토큰 구조를 기준으로
컬러 사용을 일관되게 유지하는 것이다.

내가 원한 사용 방식은 이런 흐름이었다

핵심은 사용자가 Skill의 존재를 몰라도 되는 흐름이었습니다. 개발자는 평범하게 질문하고, Claude는 필요한 순간에만 내부 규칙을 가져와 판단합니다. 이 방식은 디자인 시스템처럼 규칙이 계속 수정되고 확장되는 주제에서 특히 자연스러웠습니다.

Step 1 · 개발자 질문 "이 카드 내부 패딩은 어떤 spacing token이 맞아?" 또는 "새 semantic color를 추가할 때 기준이 뭐야?"처럼 자연어로 그냥 물어봅니다.

↓

Step 2 · Claude 판단 질문이 spacing 검토인지, 컬러 규칙 추가인지 같은 맥락을 파악하고 대응되는 Skill을 내부적으로 선택합니다.

↓

Step 3 · 기준 참조 `NeveraTheme.spacing.*`, 하드코딩 금지, `XxxDimension` 분리 규칙 같은 내용을 기준으로 답변을 구성합니다.

↓

Step 4 · 일관된 응답 사용자는 스킬을 호출하지 않았지만, 결과는 항상 같은 규칙에 기반한 답변을 받습니다.

실제로는 유지보수 측면에서도 이 방식이 더 좋았다

이 구조의 장점은 사용 경험만 단순해지는 데 있지 않았습니다. 유지보수 포인트도 분명해졌습니다. 디자인 시스템 규칙이 바뀌거나 새로운 기준을 추가해야 할 때, 프롬프트 예시를 여러 군데 고치는 대신 Skill 파일만 수정하면 됩니다. 질문 방식은 그대로 두고 내부 기준만 최신화할 수 있다는 점이 컸습니다.

질문 인터페이스와 규칙 저장소를 분리할 수 있다

개발자는 계속 자연어로 묻습니다. 반면 운영자는 Skill 문서에서 판단 기준만 관리하면 됩니다. 이 분리가 되면 "어떻게 물어봐야 좋은 답이 나오는지"를 교육하는 비용도 줄어들고, 규칙 개정이 생겨도 수정 지점이 명확해집니다.

규칙 변경이 생겨도 사용 방식은 바뀌지 않는다

예를 들어 spacing 토큰이나 typography 선택 기준이 조금 바뀌더라도, 사용자는 여전히 같은 방식으로 질문하면 됩니다. 바뀌는 것은 Skill 내부 지식뿐이고, 외부 인터페이스는 고정됩니다. 디자인 시스템처럼 계속 다듬어야 하는 주제에서는 이 고정된 인터페이스가 특히 중요하다고 느꼈습니다.

UX질의

사용자는 자연어만 기억하면 된다

스킬 이름, 호출 문법, 인수 형식을 외울 필요가 없습니다. 그냥 디자인 시스템을 수정하거나 검토할 때 필요한 질문을 던지면 됩니다.

OPS기준

운영자는 Skill 문서만 업데이트하면 된다

규칙이 바뀌거나 새 기준이 추가될 때 수정 대상이 분산되지 않습니다. 지식이 한곳에 모여 있으니 관리가 단순해집니다.

AI응답

Claude는 더 일관된 기준으로 답한다

그때그때 떠올린 설명이 아니라, 명시된 판단 절차와 금지 규칙을 따라가게 됩니다.

결국 이건 숨겨진 기능이 아니라 설계된 제약이었다

AI를 쓸 때는 기능을 더 열어두는 것이 무조건 좋아 보일 때가 많습니다. 하지만 실제로는 무엇을 노출하고 무엇을 내부 규칙으로 남길지 구분하는 일이 더 중요할 수 있습니다. 제 경우 디자인 시스템 Skill은 누군가가 직접 호출하는 도구보다, Claude의 답변을 흔들리지 않게 만드는 기준 문서에 가까웠습니다.

그래서 `user-invocable: false`는 제약이라기보다, 제가 원하는 사용 경험을 만들기 위한 설계 선택이었습니다. 사용자는 더 편하게 질문하고, Claude는 디자인 시스템을 변경하거나 확장하는 상황에서도 더 일관되게 답하게 만드는 방향이었기 때문입니다.

Key Points

직접 호출을 막은 이유는 기능을 숨기기 위해서가 아니라, 자연어 질의를 기본 인터페이스로 유지하기 위해서였습니다.
디자인 시스템 Skill의 역할은 자주 묻는 질문 대응보다, 변경과 확장 상황에서도 내부 판단 기준을 유지하는 데 더 가까웠습니다.
user-invocable: false는 사용성 저하가 아니라 역할 분리를 위한 설정이었습니다.
유지보수 관점에서는 질문 방식은 그대로 두고, Skill 문서만 업데이트하면 된다는 점이 특히 유용했습니다.
결론적으로 이 설계는 Claude를 더 많이 하게 만든 것이 아니라, 더 일관되게 답하게 만든 선택이었습니다.

Claude Code Skill로 커밋 메시지 추천 자동화

JooMan — Fri, 27 Mar 2026 09:48:04 +0900

들어가며

Claude Code를 쓰다 보면 생각보다 자주 반복되는 작업이 있습니다. 그중 하나가 바로 커밋 메시지 정리였습니다. 변경 내용을 보고 Conventional Commits 형식으로 적당한 메시지를 떠올리는 일은 어렵지는 않지만, 맥락을 한 번 더 읽고 정리해야 해서 은근히 흐름을 끊었습니다.

그래서 저는 이 작업을 아예 Claude Code Skill로 분리해 봤습니다. 이번 글은 제가 만든 recommend-commit-message 스킬의 구조를 기준으로, 어떤 문제를 해결하려고 했는지, 어떻게 규칙을 설계했는지, 실제로 어떤 식으로 활용했는지를 공유하는 기록입니다.

참고로 이 스킬은 GitHub에도 공개해뒀습니다. 글을 읽다가 직접 구조를 보고 싶다면 recommend-commit-message Skill 저장소에서 바로 확인할 수 있고, 자신의 프로젝트에 맞게 가져가서 수정해 써도 됩니다.

왜 굳이 Skill로 분리했나

일반 프롬프트로도 “커밋 메시지 추천해줘”는 충분히 할 수 있습니다. 다만 매번 원하는 출력 형식, 언어, 분석 순서, 경고 조건을 다시 설명해야 했고, 결과도 호출할 때마다 조금씩 흔들렸습니다.

반면 Skill로 만들면 반복 규칙을 문서에 고정할 수 있습니다. 한 번 잘 정의해 두면, 그다음부터는 사람이 해야 할 일이 “지금 이 상황에 맞게 호출하기” 정도로 줄어듭니다.

프롬프트로만 처리

매번 조건을 다시 설명해야 하고, 출력 포맷이나 분석 관점이 호출마다 달라질 수 있습니다. 결국 자주 쓰는 작업일수록 손이 더 갑니다.

Skill로 분리

분석 순서, 언어 규칙, 경고 조건, 출력 템플릿을 문서로 고정할 수 있습니다. 호출은 짧아지고 결과는 더 일관됩니다.

제가 만든 스킬의 핵심 구조

이번에 만든 스킬은 staged git 변경사항을 읽고, Conventional Commits 형식의 후보를 2~3개 추천하는 역할에 집중합니다. 중요한 점은 커밋을 직접 실행하지 않는다는 점입니다. 판단은 도와주되 최종 선택은 사람이 하도록 경계를 분명히 뒀습니다.

문서를 보면 단순히 “메시지 추천”만 적은 것이 아니라, 분석 대상과 순서가 꽤 세밀하게 정의되어 있습니다. 저는 이 부분이 Skill의 핵심이라고 생각합니다. 결국 성능 차이는 모델 자체보다도 어떤 문맥을 어떻게 읽히게 설계했는가에서 많이 갈립니다.

1. 출력 언어를 인자로 제어

이 스킬은 $ARGUMENTS로 출력 언어를 바꿀 수 있게 만들었습니다. 기본값은 한국어지만, 영어, 일본어, 중국어, 스페인어, 포르투갈어, 프랑스어, 독일어까지 지정할 수 있게 해뒀습니다.

여기서 재미있는 포인트는 type, scope, Conventional Commits 키워드는 항상 영어로 유지하고, 제목과 본문만 선택한 언어로 쓰도록 분리한 점입니다. 이렇게 해두면 팀 규칙과 읽기 편의성을 동시에 챙길 수 있습니다.

Skill-Recomend-Commit-Message/SKILL.md Markdown

The output language is controlled by $ARGUMENTS:
- No argument or KOR → Korean
- ENG → English
- JPN → Japanese
...

Rule: type, scope, and Conventional Commits keywords
are always in English regardless of language setting.

2. staged/unstaged 상태를 분리해서 다룸

문서의 첫 단계는 git diff --staged 확인입니다. staged 변경사항이 없으면 바로 중단하고, 먼저 git add를 하라고 안내합니다. 반대로 unstaged 변경사항은 git diff로 따로 확인하되, 작업을 멈추지는 않고 마지막에 경고만 붙입니다.

이 구분이 꽤 실용적이었습니다. 실제 커밋 후보를 추천해야 하는 대상은 staged 변경사항이기 때문에 기준은 분명하게 잡고, 동시에 작업 디렉터리에 남아 있는 변경사항도 놓치지 않게 만든 구조입니다.

3. 변경 파일만 보는 게 아니라 프로젝트 맥락까지 읽음

이 스킬에서 제가 특히 신경 쓴 부분은 변경 diff만 읽고 메시지를 짓지 않게 한 것입니다. 프로젝트 스택과 최근 커밋 히스토리도 같이 보도록 넣었습니다.

package.json, build.gradle, Cargo.toml, go.mod, pyproject.toml 같은 파일을 확인해서 기술 스택 힌트를 얻고, git log로 최근 메시지 패턴도 읽습니다. 즉, 지금 바뀐 코드만 보고 추천하는 게 아니라 이 저장소가 원래 어떤 식으로 커밋해왔는지까지 반영하려는 설계입니다.

Step 1 · staged 확인 git diff --staged 결과가 없으면 추천을 중단하고 먼저 stage 하라고 안내합니다.

↓

Step 2 · unstaged 확인 아직 stage 하지 않은 변경이 있으면 마지막에 경고를 붙여 사용자 판단을 돕습니다.

↓

Step 3 · 프로젝트 맥락 분석 빌드 파일, 모듈 구조, 최근 커밋 히스토리를 읽어 scope와 표현 방식을 맞춥니다.

↓

Step 4 · 후보 생성 단일 목적이면 2~3개 후보를, 여러 목적이면 커밋 분리를 제안하며 각각의 후보를 생성합니다.

문서 설계에서 좋았던 부분

이 스킬은 단순히 예시 몇 줄을 적은 문서가 아니라, 모델이 흔들릴 만한 지점을 미리 규칙으로 고정해 둔 문서에 가깝습니다. 특히 좋았던 건 scope 추천 로직, type 선택 가이드, 출력 템플릿을 각각 별도로 정의한 점입니다.

이렇게 분리해 두면 모델이 어느 한 부분에서 애매해져도 다른 규칙이 보정 역할을 해줍니다. 사람이 읽어도 “왜 이런 결과가 나왔는지”를 역추적할 수 있어서, 나중에 스킬을 다듬기도 훨씬 편했습니다.

scope 추천 로직을 단계적으로 정의

문서에는 scope를 정할 때 우선순위가 있습니다. 먼저 Git 히스토리에서 기존 패턴을 확인하고, Android 멀티 모듈이면 모듈 폴더명을 쓰고, 그게 아니면 레이어나 최상위 디렉터리 이름으로 fallback 하도록 했습니다.

이 방식의 장점은 저장소마다 다른 네이밍 문화에 적응할 수 있다는 점입니다. 무조건 파일명만 보고 scope를 짓는 것보다 훨씬 현실적인 결과가 나왔습니다.

1우선

Git 히스토리 우선

이미 팀이나 개인이 쓰고 있는 scope 패턴이 있다면 그 규칙을 먼저 따르게 했습니다. 새 규칙을 발명하기보다 기존 흐름에 붙는 쪽이 안정적입니다.

2구조

모듈/레이어 기반 추론

Android 멀티 모듈이나 Clean Architecture 구조라면 폴더와 파일명에서 feature, layer, service 이름을 읽어 scope 후보로 사용합니다.

3예외

애매하면 생략 가능

scope가 불명확한 프로젝트 전체 변경이라면 억지로 넣지 않도록 했습니다. 없애는 것도 규칙이라는 점이 중요합니다.

type 선택도 파일 경로 패턴으로 힌트를 줌

또 하나 유용했던 부분은 path-based type hint입니다. 테스트 파일이면 test, 문서 파일이면 docs, 워크플로 파일이면 ci처럼 경로 패턴에 따라 기본 힌트를 제공했습니다.

물론 최종 판단은 diff 내용을 봐야 하지만, 이런 힌트가 있으면 모델이 너무 넓은 선택지에서 헤매지 않습니다. 특히 Android 프로젝트처럼 파일 종류가 다양한 경우 체감이 꽤 있었습니다.

판단 기준	문서에서 준 힌트	의도
테스트 파일	`test`, `Spec`, `*Test.kt` → `test`	변경 목적을 빠르게 좁히기 위해
문서 파일	`.md`, `docs/*` → `docs`	코드 수정과 문서 수정을 분리하기 위해
빌드 파일	`package.json`, `.gradle` → `build`, `chore`	의존성/설정 변경을 명확히 드러내기 위해
UI 관련 파일	`screens/`, `components/` → `feat`, `design`	기능 추가와 시각 수정의 경계를 잡기 위해

실제로 써보니 좋았던 점

가장 먼저 느낀 장점은 출력 품질보다 일관성이었습니다. 커밋 메시지는 매번 기막히게 창의적일 필요가 없고, 오히려 저장소 전체에서 톤이 맞는 편이 더 중요합니다. 이 스킬은 바로 그 부분을 잘 해결해줬습니다.

또 하나는 커밋을 나눠야 할 때 도움이 됐다는 점입니다. 문서에 “독립된 목적이 2개 이상이면 split commit을 추천하라”는 규칙을 넣어두니, 단순한 메시지 추천기를 넘어 작업 단위 점검 도구처럼 쓸 수 있었습니다.

Skill를 잘 만들어두면 모델이 더 똑똑해진다기보다, 내가 원하는 작업 기준이 더 분명해집니다. 실제로 체감되는 차이는 대부분 여기서 나옵니다.

이런 식으로 커스텀하는 게 의미 있었던 이유

제가 이번 경험에서 가장 크게 느낀 건 Claude Code Skill의 가치는 “거대한 자동화”보다 “자주 반복되는 작고 애매한 판단을 정리하는 것”에 있다는 점이었습니다. 커밋 메시지 추천은 딱 그런 종류의 작업이었습니다.

개발하면서 반복되지만 매번 설명하기 귀찮은 규칙, 프로젝트마다 조금씩 다른 판단 기준, 팀 혹은 개인의 작업 스타일 같은 것들은 일반 프롬프트보다 Skill 문서에 더 잘 어울립니다. 한번 구조를 잡아두면 이후에는 훨씬 가볍게 재사용할 수 있습니다.

만약 비슷한 고민이 있었다면 글만 읽고 끝내기보다 실제 스킬 문서를 열어보는 편이 더 도움이 됩니다. 제가 사용한 원본은 GitHub의 recommend-commit-message 디렉토리에 올려뒀고, 그대로 참고해도 되고 팀 규칙에 맞게 scope나 type 힌트만 조금 바꿔서 써도 충분합니다.

제가 다음에도 Skill로 빼고 싶은 작업

이번에 해보니 비슷한 결의 작업은 계속 Skill로 분리할 수 있겠다는 확신이 생겼습니다. 예를 들면 PR 설명 생성, 리뷰 체크리스트 정리, 릴리즈 노트 초안 생성 같은 것들이 비슷한 패턴입니다.

공통점은 하나입니다. 정답이 하나로 고정되진 않지만, 좋은 결과를 만드는 판단 기준은 분명히 존재하는 작업이라는 점입니다.

정리하며

이번 recommend-commit-message 스킬은 복잡한 자동화라기보다, 제가 실제로 반복하던 판단 과정을 문서로 외부화한 결과물에 가깝습니다. staged 변경 확인, unstaged 경고, 프로젝트 스택 분석, 히스토리 기반 scope 추천, split commit 제안까지 흐름을 정의해두니 호출이 훨씬 가벼워졌습니다.

Claude Code Skill를 커스텀하게 써본 경험을 한 줄로 정리하면 이렇습니다. 모델에게 일을 잘 시키는 방법은 더 길게 말하는 게 아니라, 반복되는 판단 기준을 구조로 고정하는 것이었습니다.

Summary

이번 스킬의 목적은 staged 변경사항을 읽고 Conventional Commits 형식의 커밋 메시지를 안정적으로 추천하는 것이었습니다.
핵심 설계 포인트는 출력 언어 제어, staged/unstaged 분리, 프로젝트 스택과 Git 히스토리 분석이었습니다.
좋았던 점은 결과가 더 화려해진 것보다, 커밋 메시지 품질과 톤이 일관되게 유지됐다는 점입니다.
Skill의 진짜 장점은 자주 반복되지만 매번 설명하기 귀찮은 판단 기준을 문서로 고정할 수 있다는 데 있습니다.
결론은 Claude Code Skill를 커스텀할수록 모델 활용 경험이 좋아진다기보다, 내가 원하는 작업 방식이 더 선명해진다는 것입니다.

Claude Code Skills 설정 가이드 — SKILL.md 구조부터 Frontmatter까지

JooMan — Fri, 20 Mar 2026 06:43:19 +0900

들어가며

Skills를 만들어보려고 SKILL.md를 처음 열면 바로 질문이 생긴다. frontmatter에는 어떤 필드를 쓸 수 있는가? description은 어떻게 쓰는 게 좋은가? Claude가 Skill을 자동으로 실행하지 않도록 막을 수 있는가? 파일을 어디에 두어야 팀 전체에 공유되는가?

이 글은 그 질문들에 답한다. SKILL.md의 파일 구조, frontmatter 각 필드의 의미와 쓰임새, Skill을 어디에 저장하느냐에 따라 달라지는 적용 범위, 인수를 넘기고 시스템 변수를 활용하는 방법까지 — Skills를 설정하고 제어하는 데 필요한 내용을 정리했다.

Skill이 동작하는 방식

Skill의 핵심은 두 단계 로딩이다. 항상 모든 내용을 메모리에 올리는 게 아니라, 필요할 때만 가져온다. Claude의 컨텍스트 윈도우는 유한하기 때문에 이 구조가 중요하다.

L1메타

항상 컨텍스트에 존재 — `description` 필드

세션이 시작되면 등록된 모든 Skill의 이름과 description이 컨텍스트에 로드된다. Claude는 이걸 보고 "언제 어떤 Skill을 써야 하는지" 파악한다. description이 짧을수록 컨텍스트 절약에 유리하다.

L2본문

호출 시 로드 — `SKILL.md` 본문

Claude가 Skill을 사용하겠다고 판단하거나, 사용자가 /skill-name으로 직접 호출하면 그때 SKILL.md의 전체 내용이 로드된다. 평소에는 컨텍스트를 차지하지 않는다.

L3리소스

선택적 로드 — 보조 파일들

Skill 디렉토리 안에 추가 파일을 둘 수 있다. SKILL.md에서 참조하면 Claude가 필요할 때만 읽는다. 방대한 API 레퍼런스나 예시 컬렉션을 분리할 때 유용하다.

이 구조 덕분에 Skill이 많아도 컨텍스트 부담이 크지 않다. description만 항상 올라오고, 나머지는 실제로 필요한 순간에만 로드된다. Skill이 많아 description 목록이 컨텍스트 한도를 초과하면 일부가 제외될 수 있는데, /context로 확인하거나 SLASH_COMMAND_TOOL_CHAR_BUDGET 환경변수로 한도를 늘릴 수 있다.

SKILL.md 파일 구조와 구성 요소

Skill은 SKILL.md 파일 하나로 시작한다. 이 파일이 있는 디렉토리가 곧 하나의 Skill이다. 구조는 단순하다.

~/.claude/skills/my-skill/ 디렉토리 구조

my-skill/
├── SKILL.md           # 메인 지침 (필수)
├── reference.md       # 상세 레퍼런스 (선택)
├── examples/
│   └── sample.md      # 예시 출력 (선택)
└── scripts/
    └── helper.py      # 실행 스크립트 (선택)

SKILL.md는 YAML frontmatter와 마크다운 본문, 두 부분으로 구성된다. frontmatter가 메타데이터를 정의하고, 본문이 실제 지침이 된다.

~/.claude/skills/explain-code/SKILL.md YAML

---
name: explain-code
description: |
  Explains code with visual diagrams and analogies.
  Use when explaining how code works, teaching about
  a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare to something familiar
2. **Draw a diagram**: Show flow and structure in ASCII art
3. **Walk through the code**: Explain step-by-step
4. **Highlight a gotcha**: What's a common mistake?

이렇게 만들어두면 "이 코드가 어떻게 동작해?"라고 물었을 때 Claude가 description을 보고 자동으로 이 Skill을 적용한다. 또는 /explain-code src/auth/login.ts처럼 직접 호출해도 된다. SKILL.md는 500줄 이하로 유지하고, 상세 레퍼런스는 별도 파일로 분리하는 게 좋다.

Frontmatter — Skill 동작을 제어하는 설정

SKILL.md의 frontmatter에서 Skill의 동작 방식을 세밀하게 제어할 수 있다. 모든 필드가 선택적이지만, description은 꼭 작성하는 게 좋다. Claude가 이 필드를 보고 언제 Skill을 쓸지 판단하기 때문이다.

frontmatter는 반드시 ---로 시작하고 ---로 닫아야 한다. 이 두 줄 사이에 YAML 형식으로 필드를 작성하고, 그 아래에 마크다운 지침 본문이 온다.

SKILL.md 기본 구조 YAML

---
name: ...
description: ...
---

지침 본문...

필드	설명	기본값
`name`	Skill 이름. `/name`으로 직접 호출할 때 사용. 생략 시 디렉토리명으로 대체.	디렉토리명
`description`	Skill이 하는 일과 언제 써야 하는지. Claude가 자동 호출 판단에 사용. 필수에 가까운 권장 필드.	본문 첫 단락
`disable-model-invocation`	`true`로 설정하면 Claude가 자동으로 이 Skill을 로드하지 않음. 사용자가 직접 호출해야 함.	`false`
`user-invocable`	`false`로 설정하면 `/` 메뉴에서 숨겨짐. Claude만 호출 가능한 배경 지식용.	`true`
`allowed-tools`	이 Skill이 활성화될 때 Claude가 허가 없이 사용할 수 있는 도구 목록.	—
`context`	`fork`로 설정하면 별도 서브에이전트 컨텍스트에서 실행.	—
`agent`	`context: fork` 설정 시 사용할 서브에이전트 타입. `Explore`, `Plan`, `general-purpose` 또는 커스텀 에이전트명.	`general-purpose`
`model`	이 Skill이 활성화될 때 사용할 모델 지정.	—
`argument-hint`	자동완성 시 표시되는 인수 힌트. 예: `[issue-number]`	—
`hooks`	이 Skill의 라이프사이클에 스코프된 hooks 설정.	—

description — 자동 호출의 판단 기준

description은 Claude가 "지금 이 Skill을 써야 하나?"를 결정할 때 참고하는 유일한 필드다. 생략하면 본문 첫 단락이 대신 사용되지만, 명시적으로 작성하는 게 좋다. 사용자가 어떤 상황에서 이 Skill을 쓸 것인지를 직접 적어두면 자동 호출 정확도가 높아진다.

review-pr/SKILL.md YAML

---
name: review-pr
description: |
  Review the current pull request for code quality,
  style, and potential bugs. Use when asked to review
  a PR, check code changes, or inspect a diff.
---

disable-model-invocation / user-invocable — 호출 주체 제어

Skill에서 가장 중요한 설계 결정 중 하나가 "이 Skill을 Claude가 알아서 쓰게 할 것인가, 아니면 내가 직접 부를 때만 쓸 것인가"다. disable-model-invocation과 user-invocable, 두 필드로 이를 제어한다.

문제 상황

배포 Skill을 만들었는데, 코드가 완성된 것처럼 보이자 Claude가 알아서 /deploy를 실행해버린다. 사이드 이펙트가 있는 작업이 의도치 않게 트리거된다.

해결책

disable-model-invocation: true를 설정하면 Claude는 절대 이 Skill을 스스로 호출하지 않는다. 사용자가 /deploy를 입력할 때만 실행된다.

반대 상황도 있다. 예를 들어 레거시 시스템의 배경 지식을 담은 Skill이라면, Claude는 관련 작업을 할 때 자동으로 참고해야 하지만 사용자가 /legacy-system-context를 직접 입력하는 건 의미가 없다. 이때는 user-invocable: false를 쓴다.

설정	사용자 호출	Claude 자동 호출	description 컨텍스트 상시 로드
(기본값)	가능	가능	O
`disable-model-invocation: true`	가능	불가	X
`user-invocable: false`	불가	가능	O

allowed-tools — 허가 없이 사용할 도구 지정

기본적으로 Claude는 도구를 사용할 때마다 승인을 요청한다. allowed-tools에 도구를 나열하면 이 Skill이 활성화된 동안 해당 도구는 승인 없이 바로 실행된다. Bash 명령은 Bash(패턴) 형식으로 허용 범위를 좁힐 수 있다.

build/SKILL.md YAML

---
name: build
allowed-tools: Bash(npm *), Bash(git *), Read, Write
---

context와 agent — 서브에이전트에서 실행하기

context: fork를 설정하면 Skill이 현재 대화와 분리된 서브에이전트 컨텍스트에서 실행된다. 긴 탐색 작업이나 현재 대화 맥락을 오염시키고 싶지 않을 때 유용하다. agent로 에이전트 타입을 지정할 수 있으며, 생략하면 general-purpose가 사용된다. 이 두 필드는 함께 써야 의미가 있다.

explore-codebase/SKILL.md YAML

---
name: explore-codebase
context: fork
agent: Explore
---

model — Skill별 모델 지정

특정 작업에 맞는 모델을 고정하고 싶을 때 사용한다. 단순 반복 작업엔 빠른 모델을, 복잡한 분석엔 상위 모델을 배정해 비용과 속도를 조율할 수 있다.

complex-review/SKILL.md YAML

---
name: complex-review
model: claude-opus-4-6
---

지금까지 살펴본 필드들을 실제 배포 Skill에 조합하면 다음과 같다. 각 줄의 역할을 주석으로 표시했다.

deploy/SKILL.md YAML

---
name: deploy                                       # /deploy 로 직접 호출
description: Deploy the application to production.    # 자동 호출 판단 기준
             Use when deploying to staging or production.
disable-model-invocation: true                     # Claude 자동 실행 차단
allowed-tools: Bash(npm *), Bash(git *)             # 허가 없이 쓸 수 있는 도구
context: fork                                        # 서브에이전트 컨텍스트에서 실행
agent: Explore                                       # 사용할 에이전트 타입
---

어디에 저장하는가 — Skill 저장 위치

Skill을 어느 경로에 두느냐에 따라 적용 범위가 달라진다. 개인 작업 스타일 가이드는 ~/.claude/에, 팀 공유 컨벤션은 프로젝트 루트의 .claude/에 두면 된다.

위치	경로	적용 범위
Enterprise	관리형 설정 참조	조직 전체 사용자
Personal	`~/.claude/skills/<skill-name>/SKILL.md`	내 모든 프로젝트
Project	`.claude/skills/<skill-name>/SKILL.md`	현재 프로젝트만
Plugin	`<plugin>/skills/<skill-name>/SKILL.md`	플러그인이 활성화된 곳

같은 이름의 Skill이 여러 위치에 있으면 우선순위가 적용된다: Enterprise > Personal > Project. 프로젝트 Skill을 버전 관리에 포함시키면 팀 전체가 동일한 지침을 공유할 수 있다.

모노레포 환경에서는 중첩 디렉토리 자동 탐색도 지원된다. packages/frontend/ 안의 파일을 편집 중이라면, Claude Code는 packages/frontend/.claude/skills/도 자동으로 찾아본다. 패키지별로 독립된 Skill을 관리할 수 있다는 뜻이다. 또한 --add-dir로 추가한 디렉토리 내 .claude/skills/도 자동 로드되며, 세션 중 수정하면 재시작 없이 즉시 반영된다.

$ARGUMENTS와 시스템 변수 — Skill에 값 전달하기

Skill을 호출할 때 인수를 넘길 수 있다. $ARGUMENTS placeholder가 실제 입력값으로 대체된다. 여러 인수는 $ARGUMENTS[0], $ARGUMENTS[1] (또는 축약형 $0, $1)으로 위치별 접근이 가능하다.

인수 1개 — argument-hint로 힌트 제공하기

인수가 하나일 때는 $ARGUMENTS를 그대로 쓰면 된다. argument-hint 필드를 추가하면 / 메뉴 자동완성에서 어떤 값을 입력해야 하는지 힌트로 표시된다.

fix-issue/SKILL.md YAML

---
name: fix-issue
description: Fix a GitHub issue
argument-hint: "[issue-number]"
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit

사용자는 다음과 같이 호출한다.

터미널 Shell

/fix-issue 42
→ $ARGUMENTS = "42"

argument-hint는 자동완성 UI에 표시되는 힌트일 뿐이며, 실제 값 전달 방식에는 영향을 주지 않는다.

인수 2개 이상 — 위치 인수로 분리하기

공백으로 구분된 여러 인수를 넘기면 $ARGUMENTS[0], $ARGUMENTS[1]로 각각 접근할 수 있다. argument-hint에 위치마다 레이블을 적어두면 사용자가 순서를 기억하기 쉽다.

deploy/SKILL.md YAML

---
name: deploy
description: Deploy to the specified environment
argument-hint: "[env] [version]"
disable-model-invocation: true
---

Deploy version $ARGUMENTS[1] to the $ARGUMENTS[0] environment.

1. Verify $ARGUMENTS[0] is a valid target (staging | production)
2. Check that tag $ARGUMENTS[1] exists in the registry
3. Run the deployment pipeline
4. Confirm health checks pass

사용자는 다음과 같이 호출한다.

터미널 Shell

/deploy staging v1.2.0
→ $ARGUMENTS[0] = "staging"
→ $ARGUMENTS[1] = "v1.2.0"
→ $ARGUMENTS    = "staging v1.2.0"  (전체 문자열)

$ARGUMENTS 외에도 시스템에서 자동으로 제공하는 변수가 있다. ${CLAUDE_SESSION_ID}는 현재 세션 ID로, 세션별 로그 파일 생성이나 작업 추적에 활용할 수 있다. ${CLAUDE_SKILL_DIR}는 해당 Skill의 디렉토리 경로로, 번들된 스크립트를 현재 작업 디렉토리와 무관하게 참조할 때 유용하다.

session-logger/SKILL.md YAML

---
name: session-logger
description: Log activity for this session
allowed-tools: Bash(python *)
---

Run the following script to log this session's activity:

python ${CLAUDE_SKILL_DIR}/scripts/log.py

Log destination: logs/${CLAUDE_SESSION_ID}.log

Activity to log: $ARGUMENTS

트러블슈팅

Skill이 예상대로 동작하지 않을 때 확인할 체크리스트다.

Q1미트리거

Skill이 자동으로 트리거되지 않는다

description에 사용자가 실제로 쓸 법한 키워드가 포함되어 있는지 확인한다. "Skill 목록 보여줘"로 등록 여부를 먼저 체크하고, /skill-name으로 직접 호출해 동작 자체는 정상인지 검증한다. description 문구를 실제 사용 패턴에 맞게 다듬는 게 효과적이다.

Q2과트리거

원치 않는 상황에 Skill이 자꾸 켜진다

description을 더 구체적으로 좁힌다. 그래도 안 되면 disable-model-invocation: true로 수동 호출 전용으로 전환한다.

Q3컨텍스트

일부 Skill이 목록에 보이지 않는다

Skill이 많으면 description 목록이 컨텍스트 예산(기본: 컨텍스트 윈도우의 2%, 최대 16,000자)을 초과해 일부가 제외된다. /context로 경고 메시지를 확인하고, 필요하면 SLASH_COMMAND_TOOL_CHAR_BUDGET 환경변수로 한도를 늘린다.

정리하며

Claude Code Skills는 "반복 설명"의 피로를 해결하는 구조적인 답이다. description만 항상 컨텍스트에 올리고, 실제 내용은 필요할 때만 로드하는 Progressive Disclosure 구조가 컨텍스트 효율을 지킨다. 개인 작업 스타일이든 팀 컨벤션이든, Skill 하나로 Claude를 일관되게 동작시킬 수 있다.

번들 스킬(/batch, /simplify 등)은 당장 쓸 수 있는 강력한 워크플로우를 제공하고, 커스텀 Skill로 팀 특화 지침을 추가하면 된다. 복잡한 워크플로우는 $ARGUMENTS와 동적 컨텍스트 주입, context: fork로 더 강력하게 만들 수 있다. 한 번 잘 만들어두면 반복 작업이 줄고, Claude의 응답 품질도 일정해진다.

핵심 정리

두 단계 로딩이 컨텍스트를 아낀다. description은 항상 로드되고, 본문은 호출 시에만, 보조 파일은 선택적으로 로드된다. Skill이 많아도 컨텍스트 낭비가 없다.
description이 자동 호출의 열쇠다. Claude는 description을 보고 Skill을 써야 할지 판단한다. 어떤 상황에서 이 Skill을 써야 하는지 명시적으로 적어두면 자동 호출 정확도가 높아진다.
disable-model-invocation: true는 사이드이펙트 있는 Skill에 필수. 배포·메시지 전송처럼 타이밍을 직접 제어해야 하는 작업에는 Claude가 알아서 호출하지 못하도록 막아야 한다.
저장 위치가 적용 범위를 결정한다. ~/.claude/는 개인 전체, .claude/는 프로젝트 한정. 프로젝트 Skill을 버전 관리에 포함하면 팀 전체가 동일한 지침을 공유할 수 있다.
$ARGUMENTS로 Skill을 동적으로 만든다. $ARGUMENTS[0], $ARGUMENTS[1]로 위치별 인수를 받고, ${CLAUDE_SKILL_DIR}·${CLAUDE_SESSION_ID} 같은 시스템 변수로 경로와 세션 정보를 처리할 수 있다.

Claude Agent Skills - Skill 이해와 사용법

JooMan — Thu, 19 Mar 2026 06:44:09 +0900

들어가며

Claude API를 처음 사용할 때 대부분의 개발자는 시스템 프롬프트에 배경지식을 쭉 적어 넣습니다. "너는 PDF 전처리 전문가야. 이 라이브러리를 쓰고, 이런 순서로 처리해야 해…" 같은 식으로요. 이 방법은 처음엔 잘 동작하지만, 결국 한계가 옵니다.

지식이 많아질수록 프롬프트는 길어지고, 길어진 프롬프트는 컨텍스트 윈도우를 잠식합니다. 게다가 여러 프로젝트에서 같은 내용을 복붙하다 보면 관리도 엉망이 되죠.

Agent Skills는 이 문제를 해결하기 위해 Anthropic이 설계한 구조입니다. 한 번 만들어두면 Claude가 필요할 때 알아서 꺼내 씁니다.

Agent Skills가 뭔가요?

Agent Skills는 Claude에게 도메인 특화 지식을 제공하는 파일 시스템 기반 모듈입니다. 쉽게 말하면, "이 작업을 할 때는 이 가이드북을 참고해"라고 Claude에게 알려주는 구조예요.

핵심 아이디어: 프롬프트는 그때그때 주어지는 일회성 지시입니다. 반면 Skills는 상시 대기 중인 전문 지식이에요. Claude가 관련 요청을 받으면 그때 꺼내 씁니다.

공식 문서에서는 Skills를 이렇게 설명합니다. "새로 입사한 팀원에게 작성해주는 온보딩 가이드처럼" 구성한다고요. 역할, 절차, 예시, 도구 사용법이 담긴 폴더를 하나 만들어두면 Claude가 그걸 읽고 전문가처럼 동작합니다.

기존 방식과 무엇이 다른가요?

가장 큰 차이는 지식이 로드되는 시점입니다.

기존 방식 — 시스템 프롬프트

모든 지식을 대화 시작부터 컨텍스트에 올립니다. 쓰지 않을 정보도 항상 자리를 차지하죠.

Agent Skills

필요한 순간에만 해당 Skill을 읽어옵니다. 안 쓰는 지식은 컨텍스트를 소비하지 않아요.

이 구조를 공식 문서에서는 Progressive Disclosure(점진적 공개)라고 부릅니다. 3단계로 나눠서 설명할 수 있어요.

Progressive Disclosure — 3단계 구조

L1메타

항상 로드됨 — Skill 이름 + 설명 (~100 토큰)

Claude는 어떤 Skills가 있는지만 미리 알고 있습니다. 내용은 아직 로드하지 않아요.

L2지시

요청이 매칭될 때 로드됨 — SKILL.md 본문 (5,000 토큰 이하)

관련 요청이 들어오면 SKILL.md 파일을 읽어 실제 지식을 컨텍스트에 올립니다.

L3리소스

필요할 때만 로드됨 — 추가 문서 + 스크립트 (사실상 무제한)

추가 마크다운 파일이나 스크립트는 Claude가 직접 필요하다고 판단할 때만 읽습니다.

실제로 어떻게 동작하나요?

Claude가 "이 PDF에서 텍스트 추출해줘"라는 요청을 받았을 때 내부적으로 어떤 일이 일어나는지 따라가봅시다.

Step 1 · 시작 시 시스템 프롬프트에 Skills 목록 로드 (이름 + 설명만, L1)

↓

Step 2 · 요청 수신 "이 PDF에서 텍스트 추출해줘"

↓

Step 3 · Skill 트리거 PDF 관련 Skill 감지 → bash로 SKILL.md 읽기 (L2)

↓

Step 4 · 선택적 로드 폼 작성은 불필요 → FORMS.md는 읽지 않음 (L3 스킵)

↓

Step 5 · 실행 SKILL.md 지시에 따라 작업 완료

중요한 점은, Claude가 가상 머신의 파일 시스템에 접근해서 bash 명령으로 파일을 직접 읽는다는 겁니다. Skills는 단순한 텍스트 설정이 아니라, 실행 가능한 스크립트까지 포함할 수 있는 실제 디렉토리입니다.

SKILL.md 파일은 어떻게 생겼나요?

모든 Skill은 SKILL.md 파일 하나에서 시작합니다. 구조는 생각보다 단순합니다.

SKILL.md Markdown + YAML Frontmatter

---
name: pdf-processing
description: Extract text and tables from PDF files,
  fill forms, merge documents.
  Use when working with PDF files or when the user
  mentions PDFs, forms, or document extraction.
---

# PDF Processing Skill

## 빠른 시작

텍스트 추출에는 pdfplumber를 사용합니다:

```python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## 폼 작성이 필요하다면

자세한 내용은 [FORMS.md](FORMS.md)를 참고하세요.
(복잡한 폼 작성 시에만 이 파일을 읽습니다)

YAML frontmatter의 description 필드가 핵심입니다. Claude는 이 설명을 보고 "이 Skill을 지금 써야 하는가?"를 판단합니다. 언제 써야 하는지를 명확히 적는 것이 가장 중요합니다.

name 필드 규칙

name 필드 규칙 YAML

# ✅ 올바른 예시
name: pdf-processing        # 소문자, 숫자, 하이픈만 허용
name: data-export-tool      # 최대 64자

# ❌ 잘못된 예시
name: PDF_Processing         # 대문자·언더스코어 불가
name: claude-pdf-tool        # 'claude' 예약어
name: anthropic-helper       # 'anthropic' 예약어

Skill 디렉토리 구조

단순한 작업이라면 SKILL.md 하나로 충분합니다. 하지만 복잡한 도메인이라면 파일을 나눠서 관리할 수 있어요.

Skill 폴더 구조 예시 Directory

pdf-skill/
├── SKILL.md          # 핵심 지시 (항상 먼저 읽힘)
├── FORMS.md          # 폼 작성 상세 가이드 (필요할 때만)
├── REFERENCE.md      # API 레퍼런스 (필요할 때만)
└── scripts/
    └── fill_form.py  # 실행 스크립트 (결과만 컨텍스트에 올라옴)

스크립트의 장점: Claude가 fill_form.py를 실행하면, 스크립트 코드 자체는 컨텍스트에 올라오지 않습니다. 실행 결과만 올라와요. 반복적이고 정형화된 로직을 스크립트로 빼면 컨텍스트를 크게 절약할 수 있습니다.

어디서 사용할 수 있나요?

Agent Skills는 Anthropic의 여러 제품에서 사용할 수 있습니다. 각 환경마다 특징이 조금씩 다릅니다.

환경	사용 방법	특이사항
Claude API	`container` 파라미터에 `skill_id` 지정	베타 헤더 3개 필요. 기본 제공 Skills(PDF·Excel·Word 등) 즉시 사용 가능. 커스텀 Skill은 `/v1/skills`로 업로드.
Claude.ai	설정 → Features에서 업로드	Pro·Max·Team·Enterprise 플랜 한정. 현재 개인 단위 공유만 지원.
Claude Code / Agent SDK	`.claude/skills/` 폴더에 배치	파일 시스템 기반 자동 인식. 네트워크 접근 자유로움.

API 요청 예시

api_example.py Python

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[{"role": "user", "content": "이 PDF에서 텍스트를 추출해줘"}],
    container={"type": "auto", "skill_ids": ["pdf-processing"]},
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
        "files-api-2025-04-14",
    ],
)

알아두면 좋은 제약 사항

Cross-surface 동기화 없음: Claude.ai에 업로드한 Skill은 API에서 자동으로 사용할 수 없습니다. 환경마다 별도 관리가 필요해요.

API 환경에서 네트워크 접근 제한: 외부 API 호출이나 인터넷 접근이 막혀 있습니다. 미리 설치된 패키지만 사용할 수 있어요.

Claude.ai 커스텀 Skill은 개인 단위: 팀 전체에 동일한 Skill을 배포하려면 각자 업로드해야 합니다.

정리하며

Agent Skills는 단순한 편의 기능이 아닙니다. 프롬프트를 코드처럼 관리하고, AI의 전문 지식을 모듈화해서 재사용할 수 있는 구조입니다.

팀 단위로 Claude를 활용하거나, 특정 도메인에서 일관된 동작이 필요하다면 시스템 프롬프트 대신 Skills 도입을 진지하게 고려해볼 만 합니다.

핵심 정리

Agent Skills = 재사용 가능한 지식 모듈. 한 번 만들면 여러 대화에서 자동으로 활용됩니다.
Progressive Disclosure로 컨텍스트 절약. 필요한 순간에만 해당 정보를 로드합니다.
SKILL.md의 description 필드가 핵심. Claude가 언제 이 Skill을 써야 하는지 판단하는 기준입니다.
스크립트까지 번들링 가능. 실행 결과만 컨텍스트에 올라와 토큰 효율이 높습니다.
환경마다 별도 관리 필요. API, Claude.ai, Claude Code 간 자동 동기화는 없습니다.

[Jetpack Compose] 테마 간단하게 설정하기

JooMan — Wed, 7 Jan 2026 07:30:23 +0900

Jetpack Compose로 UI를 구성하다 보면 MaterialTheme.colorScheme.primary 같은 코드를 자연스럽게 쓰게 된다.

하지만 막상 이렇게 생각해보면 의문이 든다.

이 테마는 어디서 정의되는 걸까?
색상들은 어떤 기준으로 만들어졌을까?
디자인 시스템이라는 건 정확하게 무엇을 의미할까?

이 글은 Jetpack Compose에서 Material Design 3 테마 구조를 학습하면서 정리한 내용이다.
특히 Material Theme Builder를 활용해 커스텀 테마를 생성하고 Compose에 적용하는 흐름을 중심으로 정리해보려고 한다.

학습 프로젝트 소개: Compose Theming Study

이 글에서 정리한 내용은 아래 학습용 프로젝트를 기반으로 한다.

학습용 프로젝틍 앱 화면

GitHub - JuhyeokLee97/ComposeThemingStudy

Contribute to JuhyeokLee97/ComposeThemingStudy development by creating an account on GitHub.

github.com

이 프로젝트의 목적은 명확하다.
Jetpack Compose에서 디자인 시스템과 테마 구조를 이해하는 것이다
기능 구현보다는, Material Design 3 테마가 어떻게 구성되고 Compose에서 어떻게 사용되는지를 중심으로 살펴보는 데 초점을 맞췄다.

이 글을 통해 Jetpack Compose에서 Theme이 어떤 구조로 구성되고, 어떤 흐름으로 프로젝트에 적용되는지 전체적인 그림을 잡을 수 있기를 바란다.

Jetpack Compose에서 Theme은 무엇을 담당할까?

Compose에서 MaterialTheme는 단순한 색상 묶음이 아니다. 앱 전체 UI의 기준점에 해당한다.

대표적으로 다음 요소들을 포함한다.

ColorScheme
- primary / secondary / tertiary
- background / surface / error
Typography
- body, title, label 계열의 텍스트 스타일
Shape
- 버튼, 카드 등 기본 컴포넌트 형태

Theme의 중요한 점은, UI 코드에서 직접 색상이나 스타일을 결정하지 않도록 유도한다는 것이다.

다시 말해서 Compose에서 Theme는 "디자인 값을 직접 쓰지 않게 만드는 장치"에 가깝다.

테마를 직접 정의하려다 느낀 어려움

Material Design 3 문서를 기준으로 테마를 직접 구성해보려고 하면 생각보다 고려해야 할 요소가 많다.

Light / Dark 테마 각각의 색상
대비 문제
각 Color token의 역할

학습 단계에서는 "이게 맞는 방향인가?"라는 의문이 계속 생기곤 했다.

이 과정에서 사용해본 도구가 Material Theme Builder였다.

Material Theme Builder로 테마 생성하기

Material Theme Builder는 Material Design 3 기준에 맞는 테마를 자동으로 생성해주는 도구다.

핵심 특징은 다음과 같다.

Primary 색상 기준으로 ColorScheme 생성
Light / Dark 테마 자동 구성
Material 3 가이드라인 준수

학습 목적에서 가장 좋았던 점은 완성된 결과물을 먼저 보고 구조를 이해할 수 있다는 점이다.

Compose 프로젝트로 테마 코드 가져오기

Material Theme Builder에서는 Export 옵션으로 Jetpack Compose(Theme)를 선택할 수 있다.

Export된 코드에는 보통 다음과 같은 파일이 포함된다.

Color.kt
Theme.kt
(Typography / Shape 관련 설정)

Material Theme Builder를 통해 Export 된 파일들

학습 프로젝트에서는 이 구조를 그대로 가져와 Compose Theme이 어떻게 정의되고 연결되는지를 중심으로 살펴봤다.

이 과정을 통해 자연스럽게 다음을 이해할 수 있었다.

ColorScheme이 어떻게 분리되는지
Light / Dark 테마가 어떻게 선택되는지

프로젝트에서 Theme 설정 구조

ui/theme/Color.kt

Color.kt 파일은 테마에서 사용할 색상을 정의하고 관리하는 파일이다.
즉, 색상 값 자체보다 "이 색이 어떤 역할을 하는지"에 집중하도록 설계되어 있다.

import androidx.compose.ui.graphics.Color

val primaryLight = Color(0xFF4C662B)
val onPrimaryLight = Color(0xFFFFFFFF)
val primaryContainerLight = Color(0xFFCDEDA3)
val onPrimaryContainerLight = Color(0xFF354E16)
...
val primaryDark = Color(0xFFB1D18A)
val onPrimaryDark = Color(0xFF1F3701)
val primaryContainerDark = Color(0xFF354E16)
val onPrimaryContainerDark = Color(0xFFCDEDA3)

이 구조 덕분에 테마 변경이 필요할 때도 UI 코드에 손대지 않고 색상 정의만 수정할 수 있다.

ui/theme/Type.kt

Type.kt 파일은 테마에서 사용할 TextStyle에 해당하는 typography를 정의하고 관리하는 파일이다.

val provider = GoogleFont.Provider(
    providerAuthority = "com.google.android.gms.fonts",
    providerPackage = "com.google.android.gms",
    certificates = R.array.com_google_android_gms_fonts_certs
)

val bodyFontFamily = FontFamily(
    Font(
        googleFont = GoogleFont("Roboto"),
        fontProvider = provider,
    )
)

val displayFontFamily = FontFamily(
    Font(
        googleFont = GoogleFont("Roboto"),
        fontProvider = provider,
    )
)

val baseline = Typography(
    headlineSmall = TextStyle(
        fontWeight = FontWeight.SemiBold,
        fontSize = 24.sp,
        lineHeight = 32.sp,
        letterSpacing = 0.sp
    ),
    titleLarge = TextStyle(
        fontWeight = FontWeight.Normal,
        fontSize = 18.sp,
        lineHeight = 32.sp,
        letterSpacing = 0.sp
    ),
    ...
)

val typography = Typography(
    displayLarge = baseline.displayLarge.copy(fontFamily = displayFontFamily),
    displayMedium = baseline.displayMedium.copy(fontFamily = displayFontFamily),
    displaySmall = baseline.displaySmall.copy(fontFamily = displayFontFamily),
    ...
)

ui/theme/Theme.kt

Theme.kt 파일은 앱에서 사용할 커스텀한 MaterialTheme을 설정하는 파일이다.
Color.kt에 정의된 값들을 참조해 lightColorScheme, darkColorScheme을 정의하고, Type.kt에 정의된 typography를 함께 설정해 커스텀한 ComposeThemingStudyTheme 내부의 MaterialTheme에 적용한다.

private val LightColorScheme = lightColorScheme(
    primary = primaryLight,
    onPrimary = onPrimaryLight,
    ...
)
private val DarkColorScheme = darkColorScheme(
    primary = primaryDark,
    onPrimary = onPrimaryDark,
    ...
)

@Composable
fun ComposeThemingStudyTheme(
    useDarkTheme: Boolean = isSystemInDarkTheme(),
    content: @Composable () -> Unit
) {
    val colorScheme = when {
        useDarkTheme -> DarkColorScheme
        else -> LightColorScheme
    }
    ...
    MaterialTheme(
        colorScheme = colorScheme,
        typography = typography,
        content = content
    )
}

아래처럼 Theme 레벨에서 colorScheme을 분기함으로써, 개별 Composable에서는 다크 모드 여부를 전혀 신경 쓰지 않아도 된다.

val colorScheme = when {
    useDarkTheme -> DarkColorScheme
    else -> LightColorScheme
}

Theme 사용하기

학습 프로젝트에서는 위와 같은 형태로 Theme을 정의하고, setContent{} 내부에서 Composable 함수 전체를 감싼다.

setContent {
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()

    ComposeThemingStudyTheme {
        Surface(tonalElevation = 5.dp) {
            ReplyApp(
                replyHomeUiState = uiState,
                closeDetailScreen = {
                    viewModel.closeDetailScreen()
                },
                navigateToDetail = { emailId ->
                    viewModel.setSelectedEmail(emailId)
                }
            )
        }
    }
}

이 구조를 기준으로 setContent{} 내부의 모든 Composable은 MaterialTheme.colorScheme과 MaterialTheme.typography를 통해서 ComposeThemingStudyTheme에 정의된 colorScheme과 typography에 접근하도록 구성했다.

이 구조 덕분에 Composable에서는 "어떤 색을 쓸지"가 아니라 "이 UI가 어떤 역할인지"만 표현하면 되도록 구성할 수 있었다.

Theme 적용 전 vs 후 화면

Theme 적용 전 vs 적용 후 화면

마무리

Jetpack Compose에서 Theme을 이해하는 것은 단순히 색상을 바꾸는 법을 배우는 것이 아니다.

Theme은 UI를 예쁘게 만드는 도구가 아니라 일관성을 강제하는 구조다
Material Design 3의 Color token들은 "역할 기반"으로 이해해야 한다
"디자인 시스템이 무엇인지", "UI를 구조적으로 관리한다는 것이 어떤 의미인지"를 함께 이해하는 과정에 가깝다

Material Theme Builder는 그 과정을 시작하기에 좋은 도구였고, 학습 단계에서 "올바른 기준을 가진 결과물"을 빠르게 확인할 수 있게 도와줬다.

Compose Theme 구조가 막연하게 느껴졌다면, 한 번쯤은 테마만을 목적으로 한 작은 학습 프로젝트를 만들어보는 것도 좋은 방법이라고 생각한다.

OkHttp는 왜 사용했을까?

JooMan — Tue, 6 Jan 2026 07:00:18 +0900

Android 공식 배발 가이드에서도 네트워크 통신 라이브러리로 Retrofit 사용을 권장하고 있다.
나 또한 Retrofit을 당연하게 사용해왔지만 왜 Retrofit 사용이 표준이 되었는지 궁금해졌고 글로 설명된 Retrofit 장점을 직접 느껴보기 위해서 Square에서 제공하는 OkHttp가 어떻게 사용되는지 학습하게 됐다.

이 글에서는 OkHttp를 직접 사용해 네트워크 통신을 구현해보며, OkHttp가 어떤 방식으로 동작하는지와 Java의 HttpURLConnection 대비 어떤 점이 개선되었는지를 정리해본다.

OkHttp를 이용한 네트워크 GET 요청 처리

OkHttp에서는 HttpURLConnection과 다르게 사용자가 동기적으로 통신할 수 있고 비동기적으로 통신할 수 있는 선택지를 제공한다.
먼저 동기적으로 유저 정보를 가져오는 GET 방식을 학습했다.

유저 정보를 읽어오는 GET 요청 구현 소스 코드 1 - 동기 방식(`execute`)

val client = OkHttpClient()

fun fetchUserWithOkHttpClient(userId: Int): User? {
    val request = Request.Builder()
        .url("https://jsonplaceholder.typicode.com/users/$userId")
        .build()
    return try {
        val response = client.newCall(request).execute()
        if (response.isSuccessful) {
            val jsonBody = response.body()?.string()
            Gson().fromJson(jsonBody, User::class.java)
        } else {
            null
        }
    } catch(e: Exception) {
        null
    }
}

네트워크 통신 이해 및 소스 코드 분석

1. 네트워크 통신을 수행할 `OkHttpClient()`를 생성한다.

val client = OkHttpClient()

2. 네트워크 통신에 대한 정보를 갖는 Request 객체를 만든다.

Request 객체는 Builder 패턴으로 만든다.
Builder#url() 메서드를 이용해서 서버의 사용자 조회 API URL를 설정한다.
- .url("https://jsonplaceholder.typicode.com/users/$userId")
build()를 통해서 통신 관련된 설정값을 포함한 Request를 만든다.

네트워크 통신 method를 정의하지 않은 이유는 Builder를 통해 생성 시, 기본값이 GET이기 때문에 설정하지 않았다.

3. OkHttpClient를 이용해서 네트워크 통신을 동기적으로 처리하도록 요청한다.

client.newCall(request).execute()
execute(): 동기적으로 처리하는 함수이다.

4. 네트워크 통신이 성공한 경우에 대해 처리한다.

response.isSuccessful: 네트워크 통신 결과값(OkHttp에서 제공하는 Response)을 통해서 성공 여부를 확인한다.
response.body()?.string(): 통신 결과값 중, Body 영역에 해당하는 값을 읽어온다.
Gson().fromJson(jsonBody, User::class.java): Json 형식의 문자열로 반환된 Body 값을 미리 정의해둔 User 데이터 클래스 형태로 변환한다.

유저 정보를 읽어오는 GET 요청 구현 소스 코드 2 - 비동기 방식(`enqueue`)

val client = OkHttpClient()

private fun fetchUserWithOkHttpClient(
    userId: Int,
    onSuccess: (User) -> Unit,
    onError: (String) -> Unit
) {
    val request = Request.Builder()
        .url("https://jsonplaceholder.typicode.com/users/$userId")
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onResponse(response: Response) {
            if (response.isSuccessful) {
                val jsonBody = response.body().string()
                val user = Gson().fromJson(jsonBody, User::class.java)
                onSuccess(user)
            }
        }

        override fun onFailure(request: Request, e: IOException) {
            onError(e.toString())
        }
    })
}

네트워크 통신 이해 및 소스 코드 분석

1. 네트워크 통신을 수행할 `OkHttpClient()`를 생성한다.

val client = OkHttpClient()

2. 네트워크 통신에 대한 정보를 갖는 Request 객체를 만든다.

Request 객체는 Builder 패턴으로 만든다.
Builder#url() 메서드를 이용해서 서버의 사용자 조회 API URL를 설정한다.
- .url("https://jsonplaceholder.typicode.com/users/$userId")
build()를 통해서 통신 관련된 설정값을 포함한 Request를 만든다.

네트워크 통신 method를 정의하지 않은 이유는 Builder를 통해 생성 시, 기본값이 GET이기 때문에 설정하지 않았다.

3. OkHttpClient 이용해서 네트워크 통신을 비동기적으로 처리하도록 요청한다.

client.newCall(request).enqueue(object: Callback{ ... })
enqueue(): 비동기적으로 처리하는 함수이다.
object: Callback{ ... }: 비동기적으로 처리하기 위해서 네트워크 통신 성공과 실패를 처리할 콜백을 선언해준다.
- onResponse(response: Response): 네트워크 통신이 성공한 경우, 해달 콜백이 호출된다.
  - onFailure(request: Request, e: IOException): 네트워크 통신이 실패한 경우, 해당 콜백이 호출된다.

Callback#onResponse 콜백이 호출된다는 것은 클라이언트에서 원하는 성공의 의미와는 다르다.
네트워크 통신이 실패하지 않고 성공했다는 의미로 서버에서 에러를 정상적으로 내려주는 경우도 네트워크 통신 성공으로 취급된다.
그러기 때문에 내부에서 response 값을 이용해서 클라이언트 기준에서 성공/실패 여부를 관리해서 처리해야한다.

HttpURLConnection보다 OkHttp가 나은 점

이전에 HttpURLConnection을 직접 사용해 네트워크 통신을 구현해보며 Low-level API가 어떤 식으로 동작하는지 확인했다.
이를 통해서 HTTP 통신의 기본 구조를 이해할 수 있었지만, 동시에 왜 이 방식이 실무에서 잘 사용되지 않는지도 자연스럽게 체감하게 됐다.

같은 GET 요청을 OkHttp로 구현해보며 HttpURLConnection과 비교했을 때, 개발자 입장에서 어떤 점이 개선되었는지를 정리해보면 다음과 같다.

1. 요청과 연결 개념의 분리

HttpURLConnection에서는 연결 객체 자체가 요청의 역할을 한다.

val connection = url.openConnection() as HttpURLConnection
connection.requestMethod = "GET"
connection.setRequestProperty(...)

요청 정보가 mutable한 connection 객체에 흩어져서 설정된다.
"이것이 하나의 요청이다"라는 개념적 경계가 불명확하다.
설정 순서에 따라 실수가 발생하기 쉽다.

반면 OkHttp는 Request라는 명확한 요청 모델을 제공한다.

val request = Request.Builder()
    .url("https://example.com")
    .get()
    .build()

URL, Method, Header, Body가 하나의 불변 객체(Request)로 묶인다.
요청 자체가 값처럼 취급된다.
요청 정의와 실행(Call)이 명확히 분리된다.

Request 모델 덕분에 요청을 '연결 설정 과정'이 아니라 '명세'로 다룰 수 있게 됐다.

2. 동기/비동기 처리 모델의 명확한 분리

HttpURLConnection은 비동기 처리를 직접 제공하지 않는다. 개발자가 직접 Thread/Executor를 만들어야 하고 동기/비동기 처리 경계가 코등상에 명확하지 않다.

반면 OkHttp는 명확한 선택지를 제공한다.

// 동기
client.newCall(request).execute()

// 비동기
client.newCall(request).enqueue(callback)

execute(): 호출한 스레드를 block
enqueue(): OkHttp 내부 스레드에서 비동기 실행 후 콜백 전달

3. Response 구조의 명확화

HttpUrlConnection에서는 응답을 다루기 위해서 여러 API를 조합해야 한다.

responseCode
getHeaderField()
inputStream/errorStream

OkHttp는 HTTP 응답을 하나의 Response 객체로 구조화된다.

response.code
response.headers
response.body

Status/Header/Body의 역할이 명확하다.
onResponse가 호출되더라도 HTTP 에러일 수 있음을 명시적으로 인지할 수 있다.
응답 처리 흐름이 코드로 자연스럽게 드러난다.

HTTP 프로토콜 구조가 API 설계에 그대로 반영되어 있는 것 같다.

4. 확장성과 공통 관심사 분리

HttpURLConnection은 공통 로직을 넣기 어렵다.

로깅, 인증 헤더 추가, 재시도, 캐싱 등 모든 요청마다 중복 코드가 생기기 쉽다.

OkHttp는 Interceptor를 통해 이를 구조적으로 해결한다.

// 인증 헤더 추가 관련 Interceptor 구현
class AuthInterceptor(
    private val tokenProvider: TokenProvider
) : Interceptor {

    override fun intercept(chain: Interceptor.Chain): Response {
        val original = chain.request()

        val newRequest = original.newBuilder()
            .addHeader("Authorization", "Bearer ${tokenProvider.token}")
            .build()

        return chain.proceed(newRequest)
    }
}

// OkHttpClient에 추가
val client = OkHttpClient.Builder()
    .addInterceptor(AuthInterceptor(tokenProvider))
    .build()

네트워크 요청 흐름에 공통 로직을 레이어로 삽입 가능하다.
요청/응답을 가로채되, 구조를 깨지 않는다.

OkHttp는 네트워크 계층을 확장 가능한 파이프라인으로 다룰 수 있는 큰 장점이 있는 것 같다.

Retrofit 이전에는 Android에서 네트워크 통신을 어떻게 했을까?

JooMan — Mon, 5 Jan 2026 17:54:10 +0900

Android 개발에서 Retrofit은 사실상 표준처럼 사용되지만, "왜 Retrofit이 필요한가?"에 대해서는 깊이 고민해보지 않았다.
High-level의 Retrofit을 사용하는 장점을 글로써 이해하는 것이 아니라 직접 경험하기 위해서는 Low-level에서의 네트워크 통신이 어떻게 동작하는지 알 필요가 있다고 느껴졌다. 그래서 Java에서 제공하는 HttpURLConnection을 이용한 네트워크 통신 방법을 학습하기로 했다.

HttpURLConnection GET 사용법

먼저 Low-level의 HttpURLConnection에서 기본적인 REST API - GET 요청을 하는 소스 코드는 다음과 같다.

소스 코드

fun fetchUserWithHttpUrlConnection(userId: Int): User? {
    var connection: HttpURLConnection? = null
    try {
        val url = URL("https://jsonplaceholder.typicode.com/users/$userId")
        connection = url.openConnection() as HttpURLConnection
        connection.requestMethod = "GET"
        connection.connectTimeout = 5000
        connection.readTimeout = 5000

        val responseCode = connection.responseCode
        if (responseCode == HttpURLConnection.HTTP_OK) {
            val inputStream = connection.getInputStream()
            val reader = BufferedReader(InputStreamReader(inputStream))
            val response = reader.readText()
            reader.close()

            val gson = Gson()
            return gson.fromJson(response, User::class.java)
        }
        return null
    } catch (e: Exception) {
        e.printStackTrace()
        return null
    } finally {
        connection?.disconnect()
    }
}

HttpURLConnection을 통한 네트워크 통신 이해 및 소스 코드 분석

1. 네트워크 통신 요청을 위해서는 HttpURLConnection 객체 생성이 필요하고, 요청에 대한 정보를 담아야한다.

HttpURLConnection은 URL.openConnection()를 통해서 객체를 생성한다.
- openConnection()은 연결 객체를 준비하는 단계이며, 실제 네트워크 연결은 lazy 하게 이후 시점에서 시작된다.
HttpURLConnection의 속성값(method, connectionTimeout, readTimeout)들을 설정한다.

2. 네트워크 연결/요청 전송은 `responseCode` 또는 `inputStream/outputStream` 접근 시점에 트리거된다.

val responseCode = connection.responseCode를 통해서 트리거된다.

3. 네트워크 통신 요청 결과값을 읽을 수 있도록, 즉 처리할 수 있도록 셋팅한다.

val inputStream = connection.getInputStream(): 서버로부터 수신된 데이터를 OS의 소켓 버퍼를 통해 읽어올 수 있는 스트림이다.
val reader = BufferedReader(InputStreamReader(inputStream)): 바잍 단위로 전달되는 데이터를 문자로 처리하기 위해 InputStreamReader를 사용한다. 그리고 효율적으로 데이터를 읽어오기 위해서 BufferedReader로 변환한다.
val response = reader.readText(): 내부적으로 read()를 반복 호출해서 스트림의 끝까지 읽어 하나의 문자열을 만든다. 이 과정에서 데이터 전달이 완료되지 않으면 read()에서 Block 될 수 있다.

서버 응답 값은 한 번에 완성되어 전달되는 것이 아니라 네트워크 특성상 조각 단위로 전달된다.
InputStream/BufferedReader는 데이터를 미리 다 받아두는 것이 아니라, 스트림에서 read()가 호출될 때마다 전달된 만큼 읽고(없으면 block) 문자로 디코딩, 버퍼링하도록 준비하는 Wrapper다.
따라서 서버/네트워크가 늦으면 reader.readText() 내부의 read 과정에서 스레드가 block 될 수 있고, 이를 메인 스레드에서 수행하면 UI 정지(ANR) 위험이 생길 수 있다.

4. 네트워크 스트림 및 소켓과 같은 OS 리소스 해제를 위해 BufferedReader를 종료한다.

reader.close()

5. 전달받은 Json 타입의 문자열 데이터를 User 클래스 타입으로 변환한다.

생각 정리

Square에서 OkHttp와 Retrofit을 제공하기 전에는 Java에서 제공하는 HttpURLConnection을 사용한 것 같다.

HttpURLConnection을 사용해서 네트워크 통신을 할 수는 있지만, 개발하고 유지보수하는 입장에서 네트워크 통신을 위한 객체 connection을 생성하고 Builder 패턴이나 DSL 패턴 없이 요청에 대한 정보를 설정하는데 있어서 자유도가 높은 대신, 관리 포인트가 많아 유지보수 비용이 컸을 것으로 보인다.
OkHttp를 이용하면 Request를 이용해서 Builder 패턴으로 네트워크 통신을 위한 규칙을 강제해서 관리하기 쉽고,
Retrofit을 이용하면 주석 기반으로 관리하기 용이한데 말이다.

몇 개 안되는 네트워크 통신에서는 사용할 수 있겠지만 실제 프로덕트에서는 수 많은 통신이 이루어지고 각 통신에서 변경사항이 발생한다면 유지보수하기가 상당히 어려웠을 것으로 예상된다.

Foreground Service Short Service로 게시글 업로드 구현하기

JooMan — Wed, 24 Dec 2025 23:25:53 +0900

안드로이드에서 백그라운드 작업을 안정적으로 처리하면서도,

사용자에게 현재 작업이 진행 중임을 명확하게 알려야 하는 경우 어떤 선택이 적절할까?

단순한 네트워크 요청이라면 WorkManager가 좋은 선택이 될 수 있다.
하지만 다음 조건을 모두 만족하는 작업이라면 이야기가 달라진다.

사용자가 명확히 트리거한 작업이고
즉시 실행되어야 하며
앱이 백그라운드로 전환되더라도 중단되면 안 되고
수행 시간이 길지 않은 작업

이 글에서는 이러한 조건을 만족하는 게시글 업로드(이미지 + 텍스트) 시나리를 예시로, Foreground Service 중에서 Short Service를 어떻게 사용하면 좋을지 정리해본다.

참고). Android 14(API 34)에서 강화된 정책까지 함께 다룬다.

샘플 전체 코드가 궁금한 경우, 제일 하단에 위치한 예제 코드부터 확인하면 된다.

Foreground Service란?

Foreground Service는 사용자가 인지해야 하는 작업을 수행하기 위해 사용하는 Service다.

핵심 특징은 다음과 같다.

반드시 Notification을 통해 사용자에게 작업 수행 중임을 알려야 한다
백그라운드 상태에서도 비교적 높은 실행 우선순위를 가진다
시스템 리소스를 지속적으로 사용하므로 남용하면 안 된다

즉, Foreground Service는 단훈시 "백그라운드에서 오래 돌리기 위한 도구"가 아니라,
사용자가 지금 이 작업이 실행 중이라는 사실을 알아야 하는 경우에만 사용하는 것이 전제다.

언제 Foreground Service를 사용해야 할까?

다음 질문에 모두 Yes라면 Foreground Service를 고려해볼 수 있다.

이 작업은 사용자 액션으로 직접 시작되었는가?
작업이 진행 중임을 사용자가 인지해야 하는가?
앱이 백그라운드로 가도 작업이 중단되면 안 되는가?

게시글 업로드는 보통 이 조건을 만족한다.
사용자가 업로드 버튼을 눌렀고, 업로드 중이라는 사실을 알고 싶어 하며,
업로드 도중 앱을 나가더라도 작업이 계속되기를 기대한다.

이런 맥락에서 Foreground Service는 자연스러운 선택이다.

Foreground Service, short Service란?

Short Service는 짧은 시간 안에 반드시 종료되는 작업을 위한 Foreground Service 타입이다.

공식 문서 기준 핵심 제약은 다음과 같다.

약 3분 이내에 작업이 종료되어야 한다
STICKY 재시작을 지원하지 않는다
Android 14(API 34)부터는 타임아웃이 강제되며, 무시 시 ANR이 발생한다

즉, Short Service는 "지금 당장 끝내야 하는 작업을 빠르게 처리하고 즉시 정리하는 Service를 의미한다.

Foreground Service 사용 방법

1. Foreground Service 선언 및 권한

Foreground Service 권한 및 Service 선언

Short Service를 사용하기 위해서는 FOREGROUND_SERVICE 권한과 사용할 Service를 Manifest에 선언해 한다.

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

<application>
    <service
        android:name=".service.PostService"
        android:foregroundServiceType="shortService" />
</application>

Notification 권한에 대한 이해

공식 문서에서는 Foreground Service 실행 자체에는 POST_NOTIFICATION 권한이 필수는 아니라고 명시한다.

Apps don't need to request the POST_NOTIFICATIONS permission in order to launch a foreground service.

다만 Foreground Service의 목적은 사용자에게 작업 수행 사실을 알리는 것이므로, 실제 사용자 경험 관점에서는 Notification을 정상적으로 노출하기 위해 POST_NOTIFICATIONS 권한을 함께 사용하는 것이 바람직하다.

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <application>
        <service
            android:name=".service.PostService"
            android:foregroundServiceType="shortService" />
    </application>
</manifest>

2. Foreground Service 실행

Foreground Service는 onStartCommand() 내부에서 startForeground()를 호출함으로써 시작된다.

Foreground Service의 Short Service를 사용할 때 반드시 기억해야 할 두 가지 포인트가 있다.

1. START_NOT_STICKY 사용

Short Service는 재시작을 전제로 하지 않는다.
따라서 onStartCommand()의 반환값으로는 START_NOT_STICKY를 사용하는 것이 적절하다.

2. startForegound() 호출 시 OS 버전 분기

ForegroundServiceType 개념은 Android 10(API 29)에서 도입되었다.
따라서 Short Service를 의도대로 동작시키기 위해서는 OS 버전 분기가 필요하다.

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
    startForeground(id, notification, ServiceInfo.FOREGROUND_SERVICE_TYPE_SHORT_SERVICE)
} else {
    startForeground(id, notification)
}

3. Foreground Service 종료 (중요)

Android 14부터 Foreground Service의 Short Service에는 3분 타임아웃이 강제된다.

타임아웃이 발생하면 Service.onTimeout() 콜백이 호출되며, 이를 처리하지 않으면 *ANR이 발생한다.

따라서 반드시 다음 처리가 필요하다.

stopForeground(): Foreground 상태 해제
stopSelf(): Service 종료

override fun onTimeout(startId: Int) {
    stopForeground(STOP_FOREGROUND_REMOVE)
    stopSelf(startId)
}

게시글 업로드를 Foreground Service Short Service로 구현하기

게시글 업로드 예제에서는 다음과 같은 설계 기준을 사용했다.

업로드 성공 여부는 서버 응답 기준으로 판단한다
Short Service 타임아웃은 실패로 간주하지 않는다
비즈니스 실패에 대해서만 실패 Notification을 노출한다

이는 Short Service의 타임아웃이 네트워크 통신 실패가 아니라 Service 수명 정책 이벤트라는 점을 고려한 선택이다.

아래는 전체 예제 코드다.

@AndroidEntryPoint
class PostService : LifecycleService() {

    @Inject
    lateinit var postBoardUseCase: PostBoardUseCase

    @Inject
    lateinit var notificationHelper: NotificationHelper

    @Inject
    lateinit var postEventBus: PostEventBus

    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        super.onStartCommand(intent, flags, startId)
        val boardParcel = intent?.getParcelableExtra(EXTRA_BOARD, BoardParcel::class.java)
        if (boardParcel == null) {
            stopSelf(startId)
            return START_NOT_STICKY
        }
        startForegroundService()
        lifecycleScope.launch(Dispatchers.IO) {
            postBoard(startId, boardParcel)
        }
        return START_NOT_STICKY
    }

    private fun startForegroundService() {
        val notification = notificationHelper.createPostBoardUploadNotification()

        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
            startForeground(
                NotificationHelper.POST_UPLOAD_NOTIFICATION_ID,
                notification,
                ServiceInfo.FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
            )
        } else {
            startForeground(
                NotificationHelper.POST_UPLOAD_NOTIFICATION_ID,
                notification
            )
        }
    }

    private suspend fun postBoard(startId: Int, boardParcel: BoardParcel) {
        try {
            postBoardUseCase(
                title = boardParcel.title,
                content = boardParcel.content,
                images = boardParcel.images
            ).fold(
                onSuccess = { boardId ->
                    postEventBus.emit(PostEvent.Success(boardId))
                },
                onFailure = { exception ->
                    val errorMessage = when (exception) {
                        is PostException -> exception.userMessage
                        else -> exception.message ?: "업로드에 실패했습니다."
                    }
                    postEventBus.emit(PostEvent.Failure(errorMessage))
                    throw exception
                }
            )
        } catch (e: Exception) {
            showFailedNotification()
        } finally {
            stopForeground(STOP_FOREGROUND_REMOVE)
            stopSelf(startId)
        }
    }

    private fun showFailedNotification() = with(notificationHelper) {
        val notification = createPostBoardUploadFailedNotification()
        notify(NotificationHelper.POST_UPLOAD_NOTIFICATION_ID, notification)
    }

    override fun onTimeout(startId: Int) {
        super.onTimeout(startId)
        stopForeground(STOP_FOREGROUND_REMOVE)
        stopSelf(startId)
    }

    companion object {
        const val EXTRA_BOARD = "extra_board"
    }
}

[Jetpack Compose] Compose에서 Navigation 사용

JooMan — Wed, 26 Nov 2025 16:40:32 +0900

Compose에서의 Navigation

Navigation Component는 Jetpack Compose 앱에서도 사용할 수 있다.
이를 통해 Composable 간 화면 이동을 구현하면서 Navigation Component가 제공하는 인프라와 기능을 그대로 활용할 수 있다.

프로젝트 설정

Compose에서 Navigation을 사용하려면, app 모듈의 build.gradle 파일에 아래 Navigation 관련 의존성을 추가해야 한다.

dependencies {
    val nav_version = "2.9.6"

    implementation("androidx.navigation:navigation-compose:$nav_version")
}

시작하기

Navigation을 사용할 때, navigation host, graph 그리고 controller를 구현해야 한다.

참고. Navigation에 대한 자세한 내용은 [Jetpack Compose] Navigation 개요 글에서 확인할 수 있다.

NavController 만들기

Navigation Controller는 내비게이션의 핵심 개념 중 하나다. NavController는 내비게이션 그래프(NavGraph)를 사용해 그래프에 정의된 destination 간 이동을 담당한다.

Navigation Component를 사용할 때는 NavController 클래스를 통해 Navigation Controller를 생성한다. 그리고 NavController는 사용자가 방문한 destination을 추적하고, destination 간 이동을 관리하는 핵심 API다.

Compose에서의 NavController

Jetpack Compose에서 NavController를 만들기 위해서는 rememberNavController() 함수를 사용하면 된다.

val navController = rememberNavController()

NavController는 Composable 계층 구조에서 가능한 상위 계층에서 생성해야 한다.그렇게 해야 NavController에 접근해야 하는 모든 Composable이 이를 참조할 수 있다.

이렇게 NavController를 상위에 두면, 화면 내부뿐 아니라 화면 외부 Composable들을 업데이트할 때도 NavController를 SSOT(Single Source of Truth)에 따라 사용할 수 있게 된다. 이는 상태 호이스팅(state hoisting)의 원칙을 따르는 방식이다.

NavHost 만들기

NavHost는 현재 내비게이션 대상(destination)을 담는 UI 요소다. 사용자가 앱 안에서 화면을 이동할 때, 앱은 이 NavHost 안에서 다른 destination을 교체하며 화면을 전환한다.

1. NavHost 생성과 동시에 Graph 구성하기

Route는 특정 destination으로 이동하기 위해 필요한 정보를 포함하며, destination을 식별하는 역할을 한다.

@Serializable 어노테이션을 사용하면, 해당 Route 타입에 필요한 직렬화/역직렬화 로직이 자동으로 생성된다. 이 어노테이션은 Kotlin Serialization 플러그인이 제공하므로, 먼저 플러그인을 설정해야 한다.

Route를 정의한 뒤에는 NavHost Composable을 사용해 Navigation Graph를 구성한다.

아래 예시 코드를 보자.

@Serializable
object Profile

@Serializable
object FriendsList

val navController = rememberNavController()

NavHost(navController = navController, startDestination = Profile) {
    composable<Profile> { ProfileScreen() }
    composable<FriendsList> { FriendsListScreen() }
}

Profile과 FriendsList는 각각 하나의 Route를 표현하는 직렬화 가능한 객체다.
NavHost는 NavController와 첫 시작인 destination에 해당하는 Route 타입을 받는다.
NavHost 람다는 내부적으로 NavController.createGraph()를 호출하여 NavGraph를 생성한다.
각 composable<T>() 호출은 해당 Route 타입을 그래프에 destination으로 추가한다.
각 composable<> 블록 내부에서 선언된 Composable이 NavHost가 해당 destination에 렌더링할 UI를 정의한다.

2. NavController.createGraph()로 그래프 생성 후 NavHost에 전달하기

NavHost 내부에서 바로 그래프를 구성하는 방식이 Compose에서 일반적인 패턴이지만, 경우에 따라 Navigation Graph를 외부에서 먼저 생성한 뒤 NavHost에 전달해야 하는 상황도 있다.

이런 경우 NavController의 createGraph() 함수를 사용해 NavGraph를 직접 구성할 수 있다.

아래 코드는 앞선 예제와 동일한 그래프를 NavHost 외부에서 생성한 뒤, NavHost에 전달하는 방식이다.

val navGraph by remember(navController) {
  navController.createGraph(startDestination = Profile) {
    composable<Profile> { ProfileScreen() }
    composable<FriendsList> { FriendsListScreen() }
  }
}

NavHost(navController = navController, graph = navGraph)

Composable로 이동하기

Composable로 이동하려면 NavController.navigate<T>()를 사용해야 한다. 이 overload 버전의 navigate()는 하나의 route 인자(타입)만 받으며, 이 타입 자체가 destination을 식별하는 키 역할을 한다.

@Serializable
object FriendsList

navController.navigate(route = FriendsList)

Navigation Graph에서 Composable로 이동하려면, 먼저 각 destination을 하나의 타입으로 대응되도록 NavGraph를 정의해야 한다. Composable destination은 composable<T>() 함수를 사용해 등록한다.

Composable에서 이벤트를 외부로 전달하기

Composable 함수가 다른 화면으로 이동해야 한다고 해서 해당 Composable을 NavController를 직접 넘겨 navigate()를 호출하게 하면 안 된다. UDF(Unidirectional Data Flow) 원칙에 따르면, Composable은 내비게이션 로직을 직접 다루지 않고 이벤트만 외부로 전달해야 한다.

구체적인 예시는 아래 섹션에서 설명한다.

예시

@Serializable
object Profile
@Serializable
object FriendsList

@Composable
fun MyAppNavHost(
    modifier: Modifier = Modifier,
    navController: NavHostController = rememberNavController(),
) {
    NavHost(
        modifier = modifier,
        navController = navController,
        startDestination = Profile
    ) {
        composable<Profile> {
            ProfileScreen(
                onNavigateToFriends = { navController.navigate(route = FriendsList) },
                /* ... */
            )
        }
        composable<FriendsList> { FriendsListScreen(/* ... */) }
    }
}

@Composable
fun ProfileScreen(
    onNavigateToFriends: () -> Unit,
    /* ... */
) {
    /* ... */
    Button(onClick = onNavigateToFriends) {
        Text(text = "See friends list")
    }
}

Navigation Graph의 각 destination은 route를 통해 생성된다. 이 route는 destination에 필요한 정보를 나타내거나 직렬화 가능한 객체 또는 클래스다.
MyAppNavHost Composable은 NavController 객체를 갖고 있다.
navigate() 호출은 MyAppNavHost 내부에서 이루어져야 하며, ProfileScreen처럼 UI를 선언하는 Composable에서 직접 호출하면 안 된다.
ProfileScreen에는 사용자를 FriendsList로 이동시키는 버튼이 있지만, 이 버튼은 직접 navigate()를 호출하지 않는다.
대신 버튼은 onNavigateToFriends 파라미터로 전달된 람다 함수를 호출한다.
MyAppNavHost는 ProfileScreen을 NavGraph에 등록할 때 onNavigateToFriends에 navController.navigate(route = FriendsList)를 호출하는 람다를 전달한다.
이를 통해 사용자가 ProfileScreen의 버튼을 눌렀을 때 올바르게 FriendsListScreen으로 이동하게 된다.

인자와 함께 이동하기

인자를 갖는 Route 만들기

Destination에 특정 데이터를 전달할 필요가 있는 경우, route를 파라미터를 갖는 클래스로 정의해야 한다. 아래 예시처럼 Profile route는 name 파라미터를 갖는 data class이다.

@Serializable
data class Profile(val name: String)

Destination에 인자를 전달할 때는 route 클래스를 인스턴스화하면서 생성자에 값을 전달하면 된다.

Note: 인자를 전달할 때는 data class를 사용해야 한다. 인자가 없는 경우에는 object 또는 data object를 사용해야 한다.

그리고 Nullable 한 인자를 전달해야 하는 경우에는 default 값을 설정해야 한다.

@Serializable
data class Profile(val nickname: String? = null)

Destination에서 type-safe한 인자 이용하기

Route 객체는 NavBackStackEntry.toRoute() 또는 SavedStateHandle.toRoute()를 통해서도 얻을 수 있다. composable<T>()를 사용해 destination을 정의하면 해당 블록에서 NavBackStackEntry를 파라미터로 받을 수 있다.

@Serializable
data class Profile(val name: String)

val navController = rememberNavController()

NavHost(navController = navController, startDestination = Profile(name="John Smith")) {
    composable<Profile> { backStackEntry ->
        val profile: Profile = backStackEntry.toRoute()
        ProfileScreen(name = profile.name)
    }
}

Navigation Graph의 startDestination이 "John Smith" 값을 갖는 Profile route로 설정되어 있다.
Destination은 composable<Profile>{}의 블록 자체다.
ProfileScreen Composable은 name의 값으로 profile.name을 사용한다.
그러므로 "John Smith" 값이 ProfileScreen으로 전달된다.

NavController와 NavHost를 함께 사용한 예시 코드

@Serializable
data class Profile(val name: String)

@Serializable
object FriendsList

// Define the ProfileScreen composable
@Composable
fun ProfileScreen(
    profile: Profile,
    onNavigateToFriendsList: () -> Unit,
) {
    Text("Profile for ${profile.name}")
    Button(onClick = { onNavigateToFriendsList() }) {
        Text("Go To Friends List")
    }
}

// Define the FriendsListScreen composable
@Composable
fun FriendsListScreen(onNavigateToProfile: () -> Unit) {
    Text("Friends List")
    Button(onClick = { onNavigateToProfile() }) {
        Text("Go to Profile")
    }
}

// Define the MyApp composable, including the `NavController` and `NavHost`.
@Composable
fun MyApp() {
    val navController = rememberNavController()
    NavHost(navController, startDestination = Profile(name = "John Smith")) {
        composable<Profile> { backStackEntry ->
            val profile: Profile = backStackEntry.toRoute()
            ProfileScreen(
                profile = profile,
                onNavigateToFriendsList = {
                    navController.navigate(route = FriendsList)
                }
            )
        }
        composable<FriendsList> {
            FriendsListScreen(
                onNavigateToProfile = {
                    navController.navigate(
                        route = Profile(name = "Aisha Devi")
                    )
                }
            )
        }
    }
}

위 코드에서는 Composable은 NavController를 직접 전달받는 대신, NavHost가 처리할 수 있도록 이벤트(콜백)를 외부로 노출한다. 즉, Composable은 () -> Unit 형태의 파라미터를 갖고 있고, 이 파라미터에는 NavHost로부터 NavController.navigate()를 호출하는 람다가 전달된다.

복잡한 데이터 사용하기

Navigation에서 복잡한 객체(ex. UserInfo, Product 등 전체 모델)를 직접 전달하는 것은 지양해야 한다. 대신 화면 이동 시에는 필수적인 최소 정보, 예를 들면 고유 식별자(ID)와 같은 값만 전달하는 것이 좋다.

// Pass only the user ID when navigating to a new destination as argument
navController.navigate(Profile(id = "user1234"))

복잡한 객체는 별도의 Data Layer에서 관리하며, 이를 통해 SSOT(Single Source of Truth) 원칙을 따를 수 있다. Destination으로 이동한 뒤에는 전달된 ID를 이용해 Data Layer에서 필요한 데이터를 조회하면 된다.

추가로 ViewModel에서 Route에 담긴 인자 값을 참조하기 위해서는 SavedStateHandle을 사용하면 된다.

class UserViewModel(
    savedStateHandle: SavedStateHandle,
    private val userInfoRepository: UserInfoRepository
) : ViewModel() {

    private val profile = savedStateHandle.toRoute<Profile>()

    // Fetch the relevant user information from the data layer,
    // ie. userInfoRepository, based on the passed userId argument
    private val userInfo: Flow<UserInfo> = userInfoRepository.getUserInfo(profile.id)
}

이런 접근 방식은 Configuration Changes가 발생했을 때 데이터가 유실되는 것을 막아주고, 해당 객체가 업데이트 되거나 변경(mutation)되는 과정에서 발생할 수 있는 불일치 문제도 방지해준다.

주맨의 개발노트

Claude Code Hook으로 작업 완료 알림 받기

들어가며

Hook을 붙이게 된 이유

Hook이 동작하는 방식

실제로는 두 이벤트만 있어도 충분했다

작업 완료 — Claude가 응답을 마쳤을 때

응답 요청 — Claude가 사용자 입력을 기다릴 때

macOS 알림 명령어

프로젝트명과 시각 자동 삽입

두 가지 Hook 설정

Stop — 작업 완료 알림

Notification — 응답 요청 알림

제가 현재 쓰는 settings.json 설정

가독성을 우선하면 스크립트로 분리하는 편이 낫다

첫 실행 시 알림 권한 허용

배너 방식 권장

알림 기록 확인

사운드는 이렇게 골랐다

정리하며

Claude Code Skill 사용 경험 - 왜 user-invocable: false로 설계했나

들어가며

왜 직접 호출 가능한 Skill로 만들지 않았나

user-invocable: false에 담았던 의도

내가 원한 사용 방식은 이런 흐름이었다

실제로는 유지보수 측면에서도 이 방식이 더 좋았다

질문 인터페이스와 규칙 저장소를 분리할 수 있다

규칙 변경이 생겨도 사용 방식은 바뀌지 않는다

사용자는 자연어만 기억하면 된다

운영자는 Skill 문서만 업데이트하면 된다

Claude는 더 일관된 기준으로 답한다

결국 이건 숨겨진 기능이 아니라 설계된 제약이었다

Claude Code Skill로 커밋 메시지 추천 자동화

들어가며

왜 굳이 Skill로 분리했나

제가 만든 스킬의 핵심 구조

1. 출력 언어를 인자로 제어

2. staged/unstaged 상태를 분리해서 다룸

3. 변경 파일만 보는 게 아니라 프로젝트 맥락까지 읽음

문서 설계에서 좋았던 부분

scope 추천 로직을 단계적으로 정의

Git 히스토리 우선

모듈/레이어 기반 추론

애매하면 생략 가능

type 선택도 파일 경로 패턴으로 힌트를 줌

실제로 써보니 좋았던 점

이런 식으로 커스텀하는 게 의미 있었던 이유

제가 다음에도 Skill로 빼고 싶은 작업

정리하며

Claude Code Skills 설정 가이드 — SKILL.md 구조부터 Frontmatter까지

들어가며

Skill이 동작하는 방식

항상 컨텍스트에 존재 — description 필드

호출 시 로드 — SKILL.md 본문

선택적 로드 — 보조 파일들

SKILL.md 파일 구조와 구성 요소

Frontmatter — Skill 동작을 제어하는 설정

description — 자동 호출의 판단 기준

disable-model-invocation / user-invocable — 호출 주체 제어

allowed-tools — 허가 없이 사용할 도구 지정

context와 agent — 서브에이전트에서 실행하기

model — Skill별 모델 지정

어디에 저장하는가 — Skill 저장 위치

$ARGUMENTS와 시스템 변수 — Skill에 값 전달하기

인수 1개 — argument-hint로 힌트 제공하기

인수 2개 이상 — 위치 인수로 분리하기

트러블슈팅

Skill이 자동으로 트리거되지 않는다

원치 않는 상황에 Skill이 자꾸 켜진다

일부 Skill이 목록에 보이지 않는다

정리하며

Claude Agent Skills - Skill 이해와 사용법

들어가며

Agent Skills가 뭔가요?

기존 방식과 무엇이 다른가요?

Progressive Disclosure — 3단계 구조

항상 로드됨 — Skill 이름 + 설명 (~100 토큰)

요청이 매칭될 때 로드됨 — SKILL.md 본문 (5,000 토큰 이하)

필요할 때만 로드됨 — 추가 문서 + 스크립트 (사실상 무제한)

실제로 어떻게 동작하나요?

`user-invocable: false`에 담았던 의도

항상 컨텍스트에 존재 — `description` 필드

호출 시 로드 — `SKILL.md` 본문

유저 정보를 읽어오는 GET 요청 구현 소스 코드 1 - 동기 방식(`execute`)

1. 네트워크 통신을 수행할 `OkHttpClient()`를 생성한다.

유저 정보를 읽어오는 GET 요청 구현 소스 코드 2 - 비동기 방식(`enqueue`)

1. 네트워크 통신을 수행할 `OkHttpClient()`를 생성한다.

2. 네트워크 연결/요청 전송은 `responseCode` 또는 `inputStream/outputStream` 접근 시점에 트리거된다.