요약 (TL;DR)

저는 Claude Code를 일상적으로 약 네 달 동안 사용하다가, 실제로 작업 방식을 완전히 바꿔주는 몇 가지 CLI(Command Line Interface) 기능들을 발견했습니다. 이 기능들 중 어느 것도 비밀은 아니며 모두 문서에 나와 있지만, 저는 너무 느린 방식으로 수십 시간을 낭비한 후에야 이를 체득할 수 있었습니다. 가장 큰 변화를 가져온 다섯 가지는 다음과 같습니다: 헤드리스 모드 (headless mode), 사용자 지정 슬래시 명령어 (custom slash commands), 권한 허용 목록 (permission allowlists), 세션 재개 (session resume), 그리고 작업별 모델 선택 (per-task model selection).

문제점 (The Problem)

Claude Code를 처음 사용했을 때, 저는 이를 더 화려해진 자동 완성 기능처럼 여겼습니다. 터미널을 열고 프롬프트를 입력하고, 작동하는 것을 지켜보고, 터미널을 닫고, 다음 날 반복하는 식이었죠. 이는 완전히 합리적인 시작 방식이지만, 많은 가치를 놓치게 만듭니다.

세 가지 특정 고충이 계속 나타났습니다:

1. 반복 프롬프트. 저는 재발행되는 작업(

Claude Code에는 비대화형 (non-interactive) 모드가 있습니다: claude -p "<prompt>". 이 모드는 한 번 실행되어 결과를 출력한 뒤 종료됩니다. REPL이나 주고받는 대화 과정이 없습니다. 덕분에 셸 스크립트 (shell script), Makefile 타겟, 또는 CI 단계에 연결하기가 매우 쉽습니다.

# 마지막 커밋의 diff를 요약하여 일반 텍스트로 출력
claude -p "Summarize the changes in the most recent git commit in 3 bullet points. No preamble."

...

저는 다음과 같은 작업에 이 기능을 사용합니다: 커밋 범위로부터 초안 변경 로그 (changelog) 항목 생성하기, GitHub 이슈 배치를 대략적인 우선순위 그룹으로 분류하기, 또는 제가 직접 diff를 열어보기 전에 "이 PR이 보안에 민감한 부분을 건드리는가"를 확인하는 체크 작업 등입니다. 이 작업들 중 어느 것도 제가 터미널을 지켜보고 있을 필요가 없습니다. 나중에 읽을 수 있는 답변만 있으면 됩니다.

제가 몇 주 동안 놓쳤던 트릭은 이것입니다: 헤드리스 (headless) 모드에 --output-format json을 전달하여 구조화된 출력 (structured output)을 받을 수 있다는 점입니다. 즉, 일반 텍스트를 스크래핑하는 대신 결과를 jq나 다른 스크립트로 바로 파이프 (pipe) 할 수 있습니다.

2. 인간의 개입이 필요한 모든 작업을 위한 커스텀 슬래시 명령어 (slash commands)

제가 _대화형 (interactively)_으로 반복적으로 수행하는 작업의 경우, 프롬프트를 다시 입력하는 대신 슬래시 명령어 (slash commands)로 저장하기 시작했습니다. .claude/commands/ 디렉토리에 마크다운 (markdown) 파일을 넣으면, 어떤 세션 내에서도 호출할 수 있는 /command-name이 됩니다.

<!-- .claude/commands/triage.md -->
Triage the currently open GitHub issues for this repo.

...

이제 /triage는 매번 동일한 구조로 동일한 작업을 수행하며, Slack에서 프롬프트를 다시 설명할 필요 없이 팀원에게 바로 넘겨줄 수 있습니다. 더 큰 돌파구는 이 명령어들이 인자 (arguments)를 받을 수 있다는 점을 깨달은 것이었습니다 (파일 본문의 $ARGUMENTS는 명령어 이름 뒤에 입력하는 내용으로 대체됩니다). 따라서 수십 개의 거의 중복된 명령어 대신, 파일 하나로 관련된 일련의 작업 전체를 처리할 수 있습니다.

3. "예"가 다시 의미를 갖도록 만드는 권한 허용 목록 (Permission allowlists)

이것은 단연코 가장 큰 삶의 질(quality-of-life)을 개선해 준 변화였습니다. .claude/settings.json (또는 사용자 레벨의 ~/.claude/settings.json)에서 특정 도구 호출(tool calls)을 허용 목록(allowlist)에 추가할 수 있으며, 이를 통해 Claude Code가 워크플로우상 명백히 안전한 작업들에 대해 반복해서 묻는 것을 방지할 수 있습니다:

{
  "permissions": {
    "allow": [
...

읽기 전용 명령(Read-only commands)이나 테스트 실행은 매번 확인 대화 상자가 필요하지 않습니다. 이들은 무엇도 파괴할 수 없기 때문입니다. 프롬프트의 양을 "실제로 중요한 것들"(삭제, 강제 푸시(force-push), 저장소 외부 쓰기 등)로 줄이고 나니, 반사적으로 클릭하며 넘기는 대신 모든 확인 사항을 다시 읽기 시작했습니다. 권한 피로(Permission fatigue)는 단순히 짜증 나는 문제가 아니라 실제적인 안전성 퇴보(safety regression)를 초래합니다. 왜냐하면 가장 주의를 기울여야 할 순간에 주의를 기울이지 않도록 훈련시키기 때문입니다.

제가 처음에 실수했던 부분은 이렇습니다. 프롬프트가 지겨워서 Bash(*)와 같은 포괄적인 항목을 사용하여 너무 광범위하게 허용 목록을 설정했습니다. 이는 이 기능에서 얻어야 할 잘못된 교훈입니다. 핵심은 "프롬프트를 없애는 것"이 아니라, 어차피 자동 조종(autopilot) 상태로 승인했을 법한 것들만 침묵시킴으로써 "프롬프트를 다시 의미 있게 만드는 것"입니다. 각 허용 항목의 범위를 와일드카드(wildcard)가 아닌 특정 명령으로 제한하고, 목록을 가끔씩 다시 검토하세요. 일회성 작업을 위해 한 번 허용 목록에 추가해 두고 6개월 뒤에도 여전히 그대로 남아 있는 것을 잊어버리기 쉽습니다.

4. 한 번의 세션 이상 지속되는 모든 작업을 위한 세션 재개 (Session resume)

claude --continue는 현재 디렉토리에서 가장 최근의 대화를 이어갑니다. claude --resume은 며칠 전의 작업으로 다시 돌아가야 할 경우 최근 세션들을 선택할 수 있는 피커(picker)를 제공합니다. 어떤 방식을 사용하든, 무엇을 요청했는지, Claude가 이미 무엇을 시도했는지, 그 과정에서 코드베이스에 대해 무엇을 배웠는지와 같은 전체 컨텍스트(context)가 함께 복구됩니다.

# 어제 중단했던 지점부터 바로 시작하기
claude --continue

...

이 기능을 발견하기 전에는 "작업 도중 노트북을 닫는 것"이 곧 "계획을 잃는 것"을 의미했습니다. 하지만 이제 며칠에 걸친 리팩터링 (refactor)은 그저... 며칠에 걸친 리팩터링일 뿐입니다. 서로 일치하지 않는 다섯 개의 별개 일일 작업으로 쪼개지지 않습니다.

5. 실제 작업에 맞춰 모델과 노력(effort)을 매칭하기

모든 작업이 동일한 양의 추론 (reasoning)을 필요로 하지는 않습니다. 한 줄짜리 린트 (lint) 수정과 "이 모듈의 에러 핸들링 (error handling)을 재설계하라"는 같은 작업이 아니며, 이들을 동일하게 취급하는 것은 시간이나 품질 중 하나를 낭비하는 일입니다. Claude Code는 전체 세션 (session)을 하나의 설정으로 고정하는 대신, 호출 (invocation)마다 모델과 추론 노력을 설정할 수 있게 해줍니다:

# 기계적인 수정을 위한 빠르고 저렴한 패스 (pass)
claude -p "Fix the unused-import lint errors in src/utils/format.ts" --model haiku

...

저는 습관적으로 모든 것을 하나의 모델로 실행하곤 했습니다. 기계적인 작업과 판단이 필요한 작업을 분리하자, 더 어려운 작업의 품질에는 전혀 영향을 주지 않으면서도 평균 대기 시간을 눈에 띄게 줄일 수 있었습니다. 더 어려운 작업에는 여전히 더 깊이 있는 모델이 투입되었기 때문입니다.

배운 점 (Lessons Learned)

1. 대화형 REPL은 Claude Code 제품 전체가 아니라, 자동화하기 가장 어려운 부분일 뿐입니다. "감 잡기" 단계를 지나고 나면, 헤드리스 모드 (Headless mode)에 대부분의 레버리지 (leverage)가 존재합니다.
2. 권한 피로 (Permission fatigue)는 번거로움으로 위장된 보안 문제입니다. 프롬프트 (prompt)를 읽지 않고 "yes"를 클릭하고 있다면, 당신의 확인 단계는 당신을 그 무엇으로부터도 보호해주지 못하고 있습니다.
3. 슬래시 명령어 (Slash commands)는 생각보다 작성하기 쉽고, 두 번째 사용부터는 그 가치를 충분히 합니다. 저는 이것을 "언젠가 있으면 좋겠지"라고 생각하며 미뤄두었지만, 사실은 첫 주에 바로 설정했어야 하는 것이었습니다.
4. 세션 간의 컨텍스트 (context) 손실은 내재적인 것이 아니라 피할 수 있는 것입니다. 저는 "내일 새로 시작하기"가 단순히 비즈니스를 하는 데 따르는 당연한 비용이라고 가정하며 몇 달을 보냈습니다.
5. 모델 선택은 세션 단위가 아니라 작업 단위의 결정입니다. 가장 큰 실수는 "어떤 모델을 쓸 것인가"를 프롬프트마다 조정하는 파라미터 (parameter)가 아니라, 전역 설정 (global setting)처럼 취급한 것이었습니다.

다음 단계 (What's Next)

저는 여전히 훅 (hooks, 특정 도구 호출 전/후에 스크립트를 자동으로 실행하는 기능)을 충분히 활용하지 못하고 있습니다. 문서를 대충 읽고 넘어가는 대신, 제대로 앉아서 설정하는 것이 제 다음 할 일 목록에 있습니다. 또한, 프롬프트를 두 번 다시 입력하며 한숨을 쉬고 나서야 명령어로 저장하는 현재의 습관 대신, 세 번째 필요해지기 전에 슬래시 명령어 (slash commands)를 작성하는 습관을 들여 더 절제된 방식으로 사용하고 싶습니다. 이 중 어느 하나라도 따로 글을 쓸 만한 가치가 있는 내용이 된다면, 다음 포스팅이 될 것입니다.

마무리 (Wrap-up)

만약 현재 Claude Code를 순수하게 대화형 REPL로만 사용하고 있다면, 이번 주에 반복되는 작업 하나에 헤드리스 모드 (headless mode)를 적용해 보세요. 5분 정도의 변화만으로도 지속적인 이득을 얻을 수 있습니다. 그리고 만약 여러분의 시간을 실제로 아껴준 CLI 트릭을 발견했다면, 진심으로 듣고 싶습니다. 댓글로 남겨주세요.

이 글이 유용했다면, 여기 Dev.to에서 저를 팔로우해 주세요. 저는 AI 코딩 에이전트 (AI coding agents)를 구축하고 운영하는 것에 대해 정기적으로 글을 쓰고 있습니다.