예상 독자는 Claude Code를 업무나 개인 개발에서 사용하고 있는(또는 도입을 검토 중인) Web 엔지니어이다. 빌드나 테스트용 서버 등 '끝날 때까지 기다릴 수밖에 없는 커맨드'를 Claude Code에 던질 때마다, 에이전트가 sleep 5 && ls와 같은 폴링 (Polling)을 반복하며 무의미하게 대화 (Turn)를 소비했던 경험이 있는 사람을 위해 작성한다.

전제 환경은 macOS (Darwin), Claude Code CLI (2026년 7월 시점의 환경에서 동작 확인), 셸 (Shell)은 zsh이다.

• Claude Code의 Bash 툴에는 run_in_background: true라는 인수가 있어, 커맨드를 백그라운드에서 실행한 채로 다음 작업으로 넘어갈 수 있다. 출력 확인이나 정지는 전용 툴 (BashOutput / KillBash 상당)로 수행한다. 수동 sleep 폴링보다 빠르며, 무의미한 턴 소비도 없다.
• 단, "세션이 끝나도 프로세스는 계속 살아있다", "대화형 입력을 기다리는 커맨드는 멈춘다", "로그 차분(diff) 취득 누락"이라는 3가지 함정이 있다.

구체적인 예로, npm run dev와 같이 종료되지 않는 개발 서버를 기동하면서 다른 작업을 병행하고 싶은 케이스를 생각해보자.

Claude Code에게는 다음과 같은 지시를 내리는 것만으로 충분하다.

개발 서버를 백그라운드에서 기동하고, 기동 로그에 error가 나타나지 않는지 확인한 뒤 다음 태스크로 진행해줘

이때 에이전트 측에서는 대체로 다음과 같은 Bash 툴 호출이 발생한다 (트랜스크립트 표시로 내용을 확인할 수 있다).

{
"command": "npm run dev",
"run_in_background": true,
...

응답에는 백그라운드 프로세스를 가리키는 ID (shell_id 상당)가 반환된다. 에이전트는 이 ID를 사용하여 필요한 타이밍에 차분 로그(diff log)만 가져온다.

{
"bash_id": "abc123",
"filter": "error|Error"
...

로그가 안정되었거나 작업이 끝난 타이밍에 명시적으로 프로세스를 정지시킨다.

{ "bash_id": "abc123" }

내 환경에서는 이것을 사용하게 된 이후로 "빌드가 끝날 때까지 대화가 멈추는" 상태가 사라졌고, 체감 응답 속도가 상당히 좋아졌다. 특히 watch 모드의 빌드나 로컬 서버 기동은 포그라운드 (Foreground)에서 기다리게 할 의미가 거의 없다.

흐름을 정리하면 다음과 같다.

1. 세션 종료 후에도 살아있는 프로세스
백그라운드로 기동한 프로세스 (특히 npm run dev와 같은 개발 서버)는 Claude Code의 대화 세션을 닫아도 OS 상에서는 계속 동작한다. 다음 날 다시 같은 포트로 기동하려고 시도하다가 EADDRINUSE가 발생하여, "어라, 누가 이 포트를 쓰고 있지?"라며 lsof -i :3000으로 범인 찾기를 하게 된 적이 있다. 백그라운드 실행을 사용한다면, 작업의 마지막에 명시적으로 정지시키는 것까지를 하나의 세트로 취급하는 것이 안전하다.

2. 대화형 입력 대기 문제
npm init처럼 프롬프트 입력을 기다리는 커맨드를 백그라운드로 던지면, 출력이 전혀 진행되지 않은 채 대기 상태로 남는다. 포그라운드 실행이라면 "입력을 기다리고 있구나"라고 즉시 알 수 있지만, 백그라운드에서는 단순히 "반응이 없다"라고만 보이기 때문에 원인 파악에 시간이 걸렸다. 백그라운드 실행은 서버 기동, 빌드, 테스트 실행과 같은 비대화형 (Non-interactive) 커맨드로 한정하는 것이 안전한 운용 방법이다.

3. 로그 차분 취득의 어려움
오래 실행되는 커맨드일수록 로그 양이 많아지기 때문에, 차분 로그를 가져가는 타이밍이 길어지면 대량의 출력이 한꺼번에 돌아와 에러 메시지가 묻히는 경우가 있었다. 에러만 골라내고 싶을 때는 정규 표현식 필터 (Regular Expression Filter)로 좁혀서 가져오도록 하면 누락을 상당히 줄일 수 있다. 모든 건을 매번 읽으려 하지 말고, 필터를 전제로 설계하는 것이 요령이다.

애초에 왜 이 기능이 고마운가 하면, AI 에이전트가 sleep 5를 반복하는 식의 폴링은 그만큼 대화 주고받기 (토큰)를 소비해 버리기 때문이다. 종료를 기다리기만 하는 단순 루프는 특히 낭비가 크다.

백그라운드 실행 + 완료 통지 (또는 차분 로그 취득)의 조합을 통해, 에이전트는 "던져두고 다른 일을 진행하다가, 끝나는 타이밍에 보고를 받는" 인간의 비동기적인 업무 방식에 가까운 거동을 할 수 있게 된다. 빌드나 서버 기동 때마다 기다려야 했던 스트레스가 미미하지만 확실하게 줄어들었다.

• Claude Code의 Bash 도구는 run_in_background: true 설정을 통해 백그라운드 실행이 가능하며, 전용 도구로 모니터링 및 중지가 가능하다. 이는 에이전트에게 sleep 폴링 (sleep polling)을 시키는 것보다 빠르고 확실하며, 토큰 (token) 낭비도 방지할 수 있다.
• "프로세스가 살아남는 문제", "대화형 명령어가 멈추는 문제", "로그 차분(diff) 취득 누락"의 3가지는 운영상 주의해야 한다.
• 개발 서버나 워치 모드 (watch mode) 빌드와 같이 종료되지 않는 명령어를 다룰 때 특히 효과를 발휘한다.