준비: 활용 팁

왜 미리 갖추는가

본 실습 11단계 동안 상태줄·핸드오프·이미지 첨부·파일 참조·에이전트 뷰·라이브 아티팩트를 계속 쓰게 됩니다. 처음 등장하는 단계에서 새로 배우면 그 단계의 판단에 집중할 수 없으므로 여섯 가지를 미리 한 번씩 손에 익힙니다.

이 단계에서 하는 것

아래 여섯 절을 순서대로 한 번씩 해 봅니다. 각 절 끝에 본 실습 어느 단계에서 쓰는지 적어 두었습니다.

따라하기

상태줄

계측값을 확인하는 수단입니다. /statusline에 자연어로 시킵니다.

/statusline 모델 이름, 컨텍스트 사용률, 세션 비용을 한 줄로 표시해 주세요

스크립트를 직접 쓰려면 ~/.claude/settings.json에 다음을 둡니다. 이 방법은 jq가 필요합니다. jq가 없으면 위의 /statusline 경로를 씁니다.

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] ctx \\(.context_window.used_percentage // 0)%  $\\(.cost.total_cost_usd // 0)\"'"
  }
}

context_window.used_percentage는 입력 토큰(input_tokens + 캐시 생성·읽기 토큰)만으로 계산되고 출력 토큰은 포함하지 않습니다. cost.total_cost_usd는 세션 누적값이며 /clear로 새 세션이 시작되면 0으로 돌아갑니다. 그래서 기록표에는 단계 시작 비용과 끝 비용을 따로 적고, 끝 비용은 그 단계의 커밋 직전에 읽습니다. 비용을 표시하지 않는 환경은 N/A로 적습니다. 이 두 값은 매 단계 시작과 끝에 읽습니다.

상태줄 스크립트는 표준 입력으로 세션 JSON을 받고, 표준 출력에 찍은 문자열을 그대로 보여줍니다. 본 실습에 필요한 필드는 두 개이고, 한도 사용률은 참고용입니다.

필드	무엇인가
`context_window.used_percentage`	컨텍스트 사용률. 기록표의 사용률 열
`cost.total_cost_usd`	세션 누적 비용. 기록표의 시작·끝 비용 열
`rate_limits.five_hour.used_percentage`, `rate_limits.seven_day.used_percentage`	5시간·7일 한도 사용률. Pro·Max 구독에서 첫 응답 후에만 채워집니다. 기록표에는 적지 않습니다

스크립트를 고친 뒤에는 세션을 다시 열지 않고 가짜 입력으로 확인할 수 있습니다. /statusline이 만든 스크립트의 경로는 ~/.claude/settings.json의 statusLine.command 값에 있습니다. 그 경로를 아래 명령의 <스크립트 경로> 자리에 넣습니다. 위의 jq 한 줄을 그대로 쓴 경우에는 sh <스크립트 경로> 자리에 그 jq 명령을 넣습니다.

echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":25},"cost":{"total_cost_usd":1.5}}' | sh <스크립트 경로>

나머지 필드, padding·refreshInterval 같은 옵션, 갱신 시점, 예제 스크립트는 공식 문서 Customize your status line에 있습니다.

핸드오프

세션을 넘길 때는 판단을 남깁니다. 파일 목록은 git이 갖고 있습니다. 템플릿은 /clear와 /compact가 소유합니다. 프롬프트는 다음과 같습니다.

지금까지의 작업을 docs/handoff/<날짜>.md 에 다음 네 절로 써 주세요.
## 하려던 것
## 지금까지 확인한 사실 (근거와 함께)
## 시도했다가 접은 접근과 그 이유
## 다음에 할 것
파일 목록과 변경 내역은 git이 갖고 있으니 쓰지 마세요.

공개 마켓플레이스에 같은 일을 하는 스킬이 있으면 그것을 써도 됩니다. 핸드오프는 11단계에서 씁니다.

이미지 첨부

세 가지 방법이 있습니다. 이미지 파일을 Claude Code 창으로 드래그 앤 드롭하기, 클립보드에 복사한 이미지를 Ctrl+V(Windows·WSL은 Alt+V)로 붙여넣기, 프롬프트에 이미지 경로를 직접 쓰기(예: “이 이미지를 분석해 주세요: /path/to/image.png”). 붙여넣거나 드롭한 이미지는 [Image #N]처럼 번호가 붙어 프롬프트에서 위치를 참조할 수 있습니다. 스크린샷은 판단 재료이지 증거가 아니라는 점은 Visual Verification이 다룹니다. 이미지 첨부는 9단계에서 씁니다.

macOS에서 이미지를 클립보드에 넣는 방법입니다. 붙여넣기는 기본이 Ctrl+V이고, iTerm2에서는 Cmd+V도 됩니다.

화면을 캡처하면서 바로 클립보드로 보내려면 스크린샷 단축키에 Ctrl을 더합니다. 영역은 Ctrl+Shift+Cmd+4, 전체 화면은 Ctrl+Shift+Cmd+3입니다. 이미 찍은 캡처는 구석에 뜨는 축소판을 Control 클릭해 “클립보드에 저장”을 고릅니다.
Shift+Cmd+5의 옵션에서 저장 위치를 클립보드로 두면 이후 캡처가 모두 클립보드로 갑니다.
브라우저의 이미지는 오른쪽 클릭 뒤 “이미지 복사”를 고릅니다. 파일로 있는 이미지는 미리보기로 열어 Cmd+A, Cmd+C를 칩니다.
터미널에서 파일을 클립보드에 넣을 때는 다음을 씁니다. pbcopy는 텍스트만 다루므로 이미지에는 쓸 수 없습니다.

osascript -e 'set the clipboard to (read (POSIX file "/path/to/image.png") as «class PNGf»)'

파일 참조

@src/counter.ts처럼 @로 파일을, @src/로 디렉터리를 프롬프트에 올립니다. 파일 참조는 내용 전체를, 디렉터리 참조는 파일 목록만 컨텍스트에 올립니다. 큰 파일을 반복해서 @로 올리면 매 호출 비용이 됩니다. 그 이유는 Context Window에 있습니다. 파일 참조는 4단계에서 씁니다.

에이전트 뷰

여러 세션을 한 화면에서 봅니다.

claude agents             # 대시보드
claude --bg "<프롬프트>"   # 백그라운드로 새 세션 시작
claude attach <id>
claude logs <id>
claude stop <id>          # claude kill도 같은 뜻

세션 안에서는 /bg(/background의 별칭)로 현재 세션을 백그라운드로 돌립니다. 백그라운드 세션은 파일을 편집하기 전에 .claude/worktrees/ 아래 격리된 worktree로 옮겨 간다는 점은 Worktrees가 설명합니다. 에이전트 뷰는 7단계에서 씁니다. 자세한 내용은 공식 문서 Agent view에 있습니다.

라이브 아티팩트

세션 산출물을 claude.ai의 공유 가능한 페이지로 publish합니다. 프롬프트는 다음과 같습니다.

docs/tutorial-log.md 를 표로 보여 주는 아티팩트를 만들어 주세요.

새 아티팩트는 처음에는 게시한 사람에게만 보입니다. Manual·Accept edits 모드에서는 게시 전에 승인을 묻습니다. Auto 모드에서는 승인 없이 게시될 수 있습니다. 그래서 공개 여부는 사람이 별도로 확인합니다. 에이전트가 만든 결과물을 공개할지는 사람이 판단한다는 원칙은 보안에 있습니다. 라이브 아티팩트는 11단계에서 선택으로 씁니다. 자세한 내용은 공식 문서 Artifacts에 있습니다.

완료 확인

상태줄에 컨텍스트 사용률이 표시됩니다. claude agents에 진입하고 나올 수 있습니다.

계측 기록

상태줄의 두 값이 기록표의 어느 열에 가는지 확인해 둡니다. 사용률은 “단계 끝 컨텍스트 사용률” 열에, 비용은 단계 시작에 읽은 값을 “시작 비용” 열에, 단계 커밋 직전에 읽은 값을 “끝 비용” 열에 적습니다.

어긋났을 때

상태줄이 비어 있으면 첫 API 응답 전인지 봅니다. 첫 응답 전에는 used_percentage가 null일 수 있습니다. 프롬프트를 한 번 친 뒤 다시 봅니다.
백그라운드 세션이 편집을 거부하면 병렬 작업이 막힐 때를 확인합니다.