새벽 2시에 호출되는 대상이 사람이 아니라, 사고를 엄격하게 읽기 전용(read-only)으로 조사하고 근거 있는 보고서를 당신의 편지함에 남겨두는 탐정이라면 어떨까요? Danielle Heberling의 headless-Claude-on-shared-compute 패턴을 기반으로, 사고 대응(incident response)에 초점을 맞추어 TypeScript로 작성되었습니다.

새벽 2시의 호출 (The 2am page)

에러 급증으로 알람이 울립니다. 당신은 잠에서 깨어 빈 터미널을 열고, 항상 하던 일을 시작합니다. 에러 시그니처(error signatures)를 추출하고, 마지막 배포(deploy)를 확인하며, 영향 범위(blast radius)를 산정하고, 추측을 형성합니다. 모든 조사의 첫 30분은 동일한 의식과 같으며, 당신은 반쯤 잠든 상태로 이 일을 수행합니다.

그 의식은 읽기 작업이 많고(read-heavy), 제한적이며, 반복적입니다. 이는 곧 당신 대신 에이전트(agent)가 수행해야 할 바로 그 종류의 작업이라는 말과 같습니다.

그래서 저는 하나를 만들었습니다. 이름은 Poirot입니다.

Poirot란 무엇인가

한마디로 요약하자면: Poirot는 공유 AWS 컴퓨팅(shared AWS compute) 환경에서 헤드리스(headless)로 실행되는 Claude Code입니다. 로그 에러 급증 시 CloudWatch 알람이 울리면, Poirot가 자동으로 파견되어 읽기 전용 잠금(read-only lock) 상태로 사고를 조사하고, 근거 있는 근본 원인(root-cause) 보고서를 당신의 편지함에 작성합니다. Poirot는 진단합니다. 프로덕션(production)에는 절대 손을 대지 않습니다. 보고서가 도착할 때까지 인간의 개입(human in the loop)은 없습니다.

공로를 인정해야 할 부분이 있으며, 먼저 밝혀둡니다: 이것은 Danielle Heberling의 패턴을 정면으로 기반으로 구축되었습니다. 이는 Claude Code가 한 사람의 노트북에서 실행되는 대신, 팀 전체가 트리거할 수 있는 공유 클라우드 컴퓨팅 기반의 헤드리스 코딩 에이전트 패턴입니다. 그녀의 버전인 headless-claude-on-aws는 실패한 CloudFormation 배포를 조사합니다. 저는 그 형태를 빌려와 일반적인 사고 대응(incident response)에 적용하고, CDK를 사용하여 TypeScript로 다시 작성했습니다. DNA는 같지만, 다루는 사건 파일이 다를 뿐입니다.

사건의 개요, 한 장의 그림으로

CloudWatch alarm  (error-spike metric filter)
       │  alarm action
       ▼
...

알람은 조사가 되고, 조사는 보고서가 됩니다. 이것이 전체 흐름입니다.

핵심적인 역할을 수행하는 세 가지 선택지

1. Poirot는 말 그대로 당신의 프로덕션(production)을 망가뜨릴 수 없습니다

Poirot는 실행을 담당하는 역할(role)과는 별개로, 전용 읽기 전용 IAM 역할 (IAM role) 하에서 실행됩니다. 모델이 혼란을 겪거나, 완전히 틀린 답을 내놓거나, 읽고 있는 로그 내의 악의적인 문장에 의해 프롬프트 인젝션 (prompt-injected)을 당하더라도, 그 어떤 것도 생성, 수정, 재시작, 확장 또는 삭제할 수 없습니다. 자격 증명 (credentials)이 이를 허용하지 않기 때문입니다. 여기서의 안전함은 모델이 올바르게 행동하겠다고 약속하는 것이 아닙니다. IAM이 모델의 잘못된 행동을 거부하는 것입니다.

하지만 읽기 전용 (read-only)만으로는 충분하지 않으며, 이 부분이 제가 여러분이 실제로 꼭 기억하길 바라는 대목입니다. Poirot는 신뢰할 수 없는 로그 콘텐츠를 읽으며, 로그 한 줄은 공격자가 제어할 수 있는 문자열입니다. 그런 다음 사람이 읽을 수 있는 어딘가에 보고서를 게시합니다. 이는 데이터 유출 경로 (exfiltration path)가 결합된 프롬프트 인젝션 (prompt-injection) 공격 표면 (surface)입니다. 즉, 정교하게 조작된 로그 한 줄이 에이전트(agent)를 속여 비밀 정보를 읽게 한 뒤 이를 보고서에 쓰도록 유도할 수 있습니다.

따라서 조사관 역할 (investigator role)은 ReadOnlyAccess에서 고가치 읽기 항목인 secrets, SSM parameters, KMS decrypt, S3 object contents, DynamoDB data에 대한 명시적 거부 (explicit deny)를 제외한 형태입니다.

build role        →  오직 다음만 가능: 조사관 역할 수임 (assume the investigator role), 보고서 게시, 
                      Claude 토큰 읽기            (최소 권한 원칙, least privilege)
investigator role →  ReadOnlyAccess, Claude의 AWS CLI가 실제로 실행하는 권한
...

Poirot는 인프라(로그, 메트릭, 배포, 설정)를 조사할 수 있지만, 로그 한 줄이 아무리 정중하게 요청하더라도 당신의 데이터를 읽을 수는 없습니다. 이 사고 모델 (mental model)이 핵심입니다. 당신은 에이전트를 신뢰하는 것이 아니라, 에이전트 주변에 구축한 폭발 반경 벽 (blast-radius wall)을 신뢰하는 것입니다. 프롬프트 (prompts)는 보안 경계 (security boundary)가 아닙니다. IAM이 보안 경계입니다.

2. 토큰당 과금이 아닌 구독 기반으로 비용이 청구됩니다

Claude Code는 토큰당 과금되는 API 키가 아니라, Claude Pro/Max 구독 토큰으로 인증합니다. 조사를 수행할 때 귀하의 플랜에서 비용이 차감되지만 고정된 비용이 적용됩니다. 의존성 플래핑 (flapping dependency)으로 인해 하룻밤 사이에 50개의 알람이 발생하더라도, 귀하는 50번의 조사를 수행하며 월말에 청구되는 금액은 동일합니다. 만약 토큰당 과금 방식을 선호한다면, API 키로 교체하는 것은 한 줄의 시크릿 (secret) 변경만으로 가능합니다.

3. 사고 대응 (Incident response)은 에이전트에게 거의 완벽한 작업입니다

읽기 작업이 많고, 범위가 제한적이며, 반복적인 작업: 이는 온콜 (on-call) 담당 인간을 번아웃시키는 정확한 프로필이자, 에이전트가 제 역할을 다할 수 있는 정확한 프로필입니다. 에러 시그니처 (error signatures)를 추출하고, 마지막 배포 (deploy)와 상관관계를 분석하며, 폭발 반경 (blast radius)을 측정하고, 보고서를 작성합니다. Poirot가 처음 30분간의 작업을 수행함으로써, 인간은 빈 터미널 대신 가설로부터 작업을 시작할 수 있습니다. 이는 엔지니어를 대체하는 것이 아닙니다. 엔지니어가 밤에 겪는 지루한 부분을 삭제하는 것입니다.

탐정이 당신에게 전달하는 것

Poirot은 항상 시스템 프롬프트 (system prompt)에 의해 구조가 고정된 하나의 독립된 보고서로 사건을 종결합니다:

## 사고 요약 (Incident summary)
checkout-api의 5xx 비율이 14:02 UTC에 ~0.1%에서 18%로 급증했으며 현재 진행 중입니다.

...

형식보다 중요한 것은 그 뒤에 숨겨진 규칙입니다: 모든 주장은 Poirot가 실제로 가져온 것, 즉 로그 라인 (log line), 메트릭 (metric), 배포 이벤트 (deploy event)와 연결되어 있습니다. 느낌 (vibes)에 의존하지 않습니다. 증거에 없다면 보고서에 포함되지 않습니다.

그리고 모든 유능한 탐정처럼, Poirot도 "확실하지 않습니다"라고 말할 수 있습니다. 방법론은 고정되어 있습니다: 사실을 확립하고, 실제 에러 라인을 읽고, 최근 배포와 상관관계를 분석하며, 폭발 반경을 측정합니다. 그런 다음 가설을 세우고, 확정하기 전에 이를 반증하려고 시도합니다. 정직한 '아마도'들이 순위가 매겨진 짧은 목록으로 제공되는 것이, 하나의 자신만만한 오답보다 낫습니다. 이는 제가 Danielle의 버전에서 그대로 가져온 원칙입니다.

의도적으로 지루하게 선택한 사항들

일부러 "베스트 프랙티스 (best practice)"를 따르지 않기로 한 몇 가지 결정들입니다:

MCP 서버 대신 AWS CLI 사용. Claude Code의 Bash 도구가 일반 AWS CLI를 실행하도록 했습니다. 구성 요소가 적고, 모든 읽기 작업이 제가 범위를 지정하거나 거부할 수 있는 IAM 액션(action)으로 깔끔하게 매핑됩니다. MCP는 나중에 고려할 만한 좋은 업그레이드 경로이지만, 지금 당장 배선을 구축할 만큼의 가치는 없었습니다.

Lambda 대신 CodeBuild 사용. 조사는 시간이 오래 걸리고 간헐적으로 발생하며, CLI와 Node 툴체인(toolchain)을 갖춘 실제 셸(shell)을 필요로 합니다. CodeBuild는 유휴 비용 없이 이를 제공합니다. Danielle 역시 똑같이 "지루한 것이 좋다"는 이유로 CodeBuild를 선택했습니다.

제로 터치 토큰(zero-touch tokens) 대신 만료 시 교체 방식 사용. 구독 토큰은 몇 달 동안 유지됩니다. Secrets Manager로 완전히 자동 리프레시하는 변형 방식도 존재하지만, 이는 빌드 역할(build role)에 대한 쓰기 권한이 필요하며, 리프레시 토큰 경합(race condition)을 피하기 위해 빌드를 직렬화해야 합니다. 일 년에 두 번 정도만 만지는 자격 증명을 위해 추가적인 폭발 반경(blast radius)을 감수할 가치는 없습니다.

이것은 제가 표현하는 것보다 Danielle이 더 잘 설명한 철학입니다. 우리는 레퍼런스 아키텍처(reference architecture)에 대해 다소 까다로워졌습니다. 깔끔하고, 완전히 관리되며, 완벽하게 범위가 지정된 버전은 아직 존재하지 않거나, 성숙하지 않았거나, 출시하는 데 세 배의 시간이 걸릴 수도 있습니다. 반면, 당신이 실제로 이해하고 스스로 계속 운영할 수 있는 약간은 지저분한 버전이 바로 그곳에 있으며, 오늘날의 실제 문제를 해결하고 있습니다. Poirot가 바로 그것입니다. 의도적으로 지루하게 만들었고, 제가 유지보수할 수 있으며, 지금 바로 작동합니다.

코드는 저렴하니, 스크린샷을 보여주세요

공유 컴퓨팅 위에서의 작은 회색 세포들 (The little grey cells, on shared compute)

제가 계속 돌아오는 핵심은 이것입니다. 온콜(on-call)의 어려운 부분은 명령어를 생성하는 것이 아니었습니다. 그것은 라이브 시스템의 모델을 머릿속에 유지하고 이를 심문하는 것입니다. 이것이 희소한 기술이며, AI는 이 기술을 덜 가치 있게 만드는 것이 아니라 더 가치 있게 만듭니다. 왜냐하면 저렴한 부분, 즉 CLI(Command Line Interface) 호출을 타이핑하는 것은 이제 당신이 위임할 수 있는 정확한 부분이거든요. Poirot가 사건을 종결짓지 않습니다. 그것은 노동을 수행하고, 증거를 테이블 위에 펼쳐놓고, 신뢰도 수준과 함께 용의자를 지목하며, 빈 터미널 대신 시작점을 제공합니다. 여전히 결정하는 것은 당신입니다.

당신은 에이전트(agent)를 믿지 않습니다. 당신은 그 주변을 둘러싼 벽, 그 아래에 깔린 증거, 그리고 그 위에 있는 당신 자신의 판단력을 신뢰합니다. 이것이 전체 요령입니다.

포크(fork)하고 싶다면 레포(Repo)가 여기 있습니다: github.com/wakeupmh/poirot-agent. 그리고 Danielle의 게시물을 읽어보세요. 왜냐하면 Poirot는 그것 없이는 존재할 수 없었기 때문입니다.

Mon ami, may your pages be few and your reports be grounded. 🕵️