에이전트의 도구는 사람의 터미널이 아니다 — 오래 도는 프로세스와 긴 입력은 도구의 한도 밖으로 빼고, 멈춤은 시간으로 끊는다

Claude Code 같은 코딩 에이전트에게 개발 서버를 띄워 두고 화면을 고치라고 시키면, 한동안은 잘 된다. 그러다 10분쯤 지나 에이전트가 「페이지가 안 열린다」며 코드를 의심하기 시작한다. 실제로는 코드가 아니라 백그라운드로 띄운 개발서버가 죽은 것이다. 그 죽음에는 오류 메시지가 없다. 브라우저 자동화도 비슷하다. 사내 도구의 긴 공지문, 쇼핑몰 상품 설명, 고객 응대 봇의 시스템 프롬프트처럼 천 자 넘는 글을 Playwright 의 fill 로 React textarea 에 넣으라고 하면, 탭이 통째로 멈추고 명령은 끝나지 않는다(playwright fill textarea hang).

에이전트의 도구에는 왜 따로 한도가 있나

에이전트가 쓰는 셸과 브라우저는 사람의 터미널·브라우저가 아니라 한도가 정해진 도구이고, 그 한도에 닿으면 작업은 오류 없이 끊긴다. 한도는 대개 셋이다.

• 시간 상한 — 명령 하나, 백그라운드 작업 하나가 살 수 있는 시간. 넘으면 도구가 프로세스를 내린다
• 세션 수명 — 에이전트 세션이 다시 시작되면 그 세션이 띄운 프로세스도 같이 내려간다. nohup 으로 떼어 놓아도 SIGTERM 을 받는다(종료 코드 143 = 128 + 15, bash 종료 상태)
• 입력 방식 — 브라우저 자동화의 글자 단위 입력은 글자마다 이벤트를 쏜다. 제어 컴포넌트(React 의 controlled textarea)는 그때마다 다시 그리므로, 긴 글에서는 렌더러가 막힌다

셋 다 사람 손에서는 안 생긴다. 사람은 터미널 탭을 몇 시간이고 열어 두고, 긴 글은 붙여넣는다. 그래서 에이전트에게 「사람이 하듯이」 시키면 사람에게 없는 한도에 걸린다.

오래 도는 프로세스는 어디에 둬야 하나

개발 서버·감시 빌드·로컬 DB 처럼 세션보다 오래 살아야 하는 것은 에이전트의 도구가 아니라 사람의 터미널에 둔다. Claude Code 라면 사용자가 ! pnpm dev 로 직접 띄우거나 다른 터미널 창에서 띄워 두고, 에이전트는 주소만 쓴다. 에이전트가 직접 띄워야 한다면 다음을 지킨다.

• 일을 시작할 때마다, 그리고 세션이 바뀐 뒤에는 서버가 살아 있는지 먼저 확인한다(curl -sf localhost:3000 한 줄)
• 「페이지가 안 열린다」를 코드 문제로 읽기 전에 프로세스부터 본다
• 종료 코드 143 이 보이면 코드가 아니라 바깥에서 내려진 것이다

긴 글은 어떻게 넣어야 하나

천 자가 넘는 글은 글자 단위로 치지 말고 한 번에 넣는다. 클립보드 붙여넣기를 쓰거나, Playwright 라면 글자마다 키 이벤트를 쏘지 않고 입력 이벤트 하나만 보내는 keyboard.insertText 를 쓴다(keyboard paste long text playwright). 응답이 없는 탭은 새로 고치지 말고 닫은 뒤 새 탭을 연다 — 멈춘 렌더러에 새로 고침을 보내면 그 명령도 같이 멈춘다.

멈춤은 왜 시간으로 끊어야 하나

이 한도들은 오류를 내지 않으므로, 기다림에는 언제나 끝을 정해 둔다. 끝없이 기다리는 명령은 에이전트 세션 하나를 통째로 먹는다.

• 브라우저 명령·빌드·배포 대기에는 감시 시간(예: 60초)을 둔다. timeout 이나 도구의 시간 제한 옵션으로
• 시간이 다 되면 다시 시도하기 전에 「무엇이 멈췄나」를 한 줄로 남긴다
• 에이전트 브라우저에서 잰 속도·버벅임은 에이전트 도구의 성질일 수 있다 — 같은 계측 페이지를 사람의 브라우저에서도 돌려 맞댄 뒤 판단한다

에이전트 지침에 그대로 넣을 수 있는 문장:

- 개발 서버처럼 오래 사는 프로세스는 사용자에게 띄워 달라고 한다. 직접 띄웠다면 작업 전마다 살아 있는지 확인한다.
- "페이지가 안 열린다"면 코드를 고치기 전에 서버 프로세스부터 확인한다. 종료 코드 143 은 바깥에서 내려진 것이다.
- 1,000자 넘는 글은 글자 단위 입력(fill·type) 대신 붙여넣기나 한 번에 넣는 입력으로 넣는다.
- 모든 대기 명령에는 시간 제한을 둔다. 응답 없는 탭은 새로 고치지 말고 닫고 새로 연다.

우리가 겪은 일

• 백그라운드 개발 서버: Claude Code 세션에서 백그라운드 명령으로 띄운 개발 서버가 도구의 시간 상한(10분)에 걸려 조용히 내려갔다. nohup 으로 떼어 놓자 상한은 피했지만, 세션이 다시 시작되자 SIGTERM(143)을 받고 또 내려갔다. 사용자가 직접 띄우는 쪽으로 바꾸고 나서야 멈췄다.
• 긴 지시문 입력: 1,700자짜리 지시문을 브라우저 자동화의 글자 단위 입력으로 React textarea 에 넣다가 탭 전체가 응답 불능이 됐다. 도구 안내서는 fill·type 과 붙여넣기를 나란히 소개할 뿐 긴 글에서 멈춘다는 말이 없었다. 붙여넣기로 한 번에 넣고, 멈춘 명령은 60초 감시로 끊었다.
• 에이전트 브라우저의 속도: 같은 기계·같은 캔버스에서 에이전트용 Chromium 은 WebGL 프레임이 일반 Chrome 의 두 배 느렸고, WebGL 맥락을 만들 때마다 0.7~1.5초 멈췄다(Chrome 은 10ms). 같은 계측 페이지를 두 브라우저에서 돌려 잰 값이다. 그 버벅임을 코드 회귀로 읽을 뻔했다.

2026-10 기준. 시간 상한 값과 입력 방식은 도구와 버전마다 다르다 — 쓰는 도구의 한도를 한 번 재 두고 지침에 적는다.