한 커맨드를 세 곳에서 부른다 — JD 5필드에서 하루가 도는 데까지

첫 편이 착수 이전을 정했다. 무엇을 자동화 대상으로 고를지, 무엇을 만들면 끝난 것인지, 조직 규칙을 어디에 얼마나 적을지까지다.

이 글은 그 대상을 실제로 굴러가는 것으로 옮긴다. 순서는 조직을 세우는 순서와 같다 — 어떤 부서부터 만들지 정하고, 사람 하나의 할 일을 명세로 적고, 쓸 수 있는 권한을 배급하고, 보고 라인을 잇는다. 그리고 그렇게 만든 것이 사람이 손대지 않아도 하루가 돌아가는 상태까지 가야 한다.

이 글의 마지막 세 절이 그 「하루」다. 아침에 할 일을 확인하고 저녁에 한 일을 정리하는 사이클, 로컬에서 잘 돌던 것을 운영에 올릴 때 추가로 붙여야 하는 것, 그리고 자리에 없을 때 지시를 보내는 경로다.

이 글이 옮긴 원 자료의 작성 기준일은 2026-07-26이다. 파일 경로·명령 이름·임계값·기능 제약은 그 시점의 것이며 버전에 따라 바뀐다.

이 글의 예시 시각(09:00 체크인 등)·timeout·재시도 횟수는 원 자료의 실습 예제이자 제시 기준선이며 특정 조직의 실제 운영 사례가 아니다.

그리고 아래 표들에서 이 글이 어휘를 바꿔 실은 자리는 둘이다 — JD 표의 에이전트명 예시 한 칸(「고객CS담당」)과, 라우팅 표 여섯 행 중 둘째 행 하나(「인사 심사 에이전트」로 보내는 행의 키워드와 대상 이름)다. 원 자료의 것을 같은 업무 도메인의 다른 표현으로 옮긴 것이며, 그 두 자리를 뺀 나머지 칸은 원 자료의 표기 그대로다. 이 절들의 요점은 이름이나 단어 선택이 아니라 JD의 필드 구성과 분기 구조이므로 어휘를 바꿔도 논지가 달라지지 않는다.

용어 정리

첫 편의 용어표에서 이 글이 쓰는 행만 추렸다.

조직도 → JD → 도구 배급 → 보고 라인

설계 사고 구조는 CEO가 회사를 세우는 4단계에 대응된다.

네 단계의 순서가 뒤집히면 안 되는 이유는 각 단계가 앞 단계의 산출물을 입력으로 받기 때문이다. 무슨 일을 시킬지 모르면 어떤 권한이 필요한지 정할 수 없고, 권한이 정해지지 않으면 어디까지 연결할지도 정할 수 없다.

에이전트 하나를 5필드로 정의한다

에이전트 하나는 5필드 JD로 정의한다. 이 5줄이면 구현 가능한 최소 단위라는 것이 원 자료의 주장이다.

다섯 필드 중 가운데 셋(역할·입력·출력)이 경계를 정하는 필드다. 입력에 없는 것을 보지 않고 출력에 없는 것을 만들지 않는다는 계약이며, 이 계약이 흐려지면 뒤에 나오는 라우팅이 그대로 무너진다.

어느 부서부터 — 3단계 절차

부서 선택은 통증 확인 → ROI 추정 → 연동 난이도 확인 순이며, 외부 연동(PG사·ERP·전자세금계산서)이 복잡하면 두 번째 타자로 미룬다. 일반 원칙은 수익 엔진 부서(마케팅·영업)부터인데, 첫 성공 사례가 나머지 예산을 열어주기 때문이다.

세 단계의 순서가 곧 탈락 필터의 순서다. 통증이 없으면 ROI를 따질 것도 없고, ROI가 나와도 연동이 막히면 착수 자체가 안 된다.

외부 API를 붙이기 전 세 가지 점검

원 자료는 이 세 가지가 필수로 제시된다고만 적었다. 왜 필수인지는 「위반 시 위험」 열에서 읽어낼 수 있다 — 세 결과가 전부 사후에 되돌리기 어려운 것이다. 노출된 키는 회수해도 이미 쓰인 뒤이고, 차단된 계정은 코드를 고쳐도 바로 풀리지 않으며, 로그에 남은 개인정보는 지워도 그때까지 성립한 「개인정보보호법 위반」이 없던 일이 되지는 않는다. 이렇게 이유를 붙여 읽는 것은 이 글의 정리다.

재시도는 **최대 5회 + 지연 2배 증가(exponential backoff)**가 기준선으로 제시된다. 무한 재시도는 계정 차단으로 직결된다.

이 「5회」는 외부 API 호출의 백오프 상한이다. 원 자료가 이 값을 놓은 자리는 외부 API 연동 절이고, 첫 편이 든 **「최대 3회」**는 완성 합격선의 안정성 축 자리다. 두 값이 서로 다른 대상을 잰다고 읽는 것은 이 글의 정리다 — 원 자료에서 두 값은 각각 자기 절에 한 번씩 나올 뿐이고, 한 문장 안에서 서로를 언급하며 견주는 대목은 찾지 못했다. 그 유추대로면 이쪽은 호출 한도(429)를 건드리지 않고 버티는 횟수이고, 저쪽은 재시도 정책이 존재하는지를 등급 요건으로 볼 때의 상한이다. 두 값을 같은 선으로 읽으면 모순처럼 보이지만, 하나는 외부 서비스와의 관계에서, 하나는 산출물 판정 기준에서 나온다.

최대 5회·지연 2배는 원 자료가 제시한 기준선이며 이 글이 측정한 값이 아니다. 실제 상한은 연동하는 서비스의 플랜별 한도에 따라 달라진다. 원 자료 작성 기준일은 2026-07-26이다.

데이터는 세 곳으로 나눈다

이 분할이 뒤섞이면 권한 설계와 백업 정책이 동시에 무너진다. 세 행의 「이유」 열이 서로 다른 축을 든다는 점이 그 이유다 — 하나는 이력, 하나는 접근 제어, 하나는 용량이다. 한 곳에 몰아넣으면 세 축 중 둘은 반드시 포기하게 된다.

외부 연동은 필요할 때만

판단 기준은 "언제 체크하는가"로 정리된다. 여섯 행 중 선행 조건이 붙은 것은 둘이다 — 이메일은 「발송은 한도 검증 후」, 팀 메신저는 「운영 안정화 후」다. 둘 다 잘못 붙였을 때 밖으로 새어 나가는 연동이라는 공통점이 있다. 아직 조용히 실패하는 자동화를 알림으로 팀 채널에 뿌리면 신뢰를 먼저 잃는다.

네 가지 연결 패턴

에이전트를 어떻게 엮을지는 네 가지 패턴 중에서 고른다. 이건 분산 시스템 통신 패턴과 그대로 대응된다.

네 패턴의 「약점」 열이 전부 다른 종류라는 점이 선택을 가능하게 만든다. 가용성·비용·병목·관측성 중 무엇을 먼저 포기할 수 있는지가 곧 답이다.

에이전트 수가 늘면 결국 허브 앤 스포크로 수렴한다. 오케스트레이터만 전체 컨텍스트를 갖고 하위에는 필요한 것만 전달하는 구조가 비용과 라우팅을 동시에 잡기 때문이다.

팀 구성과 라우팅 — 키워드 교집합을 비운다

여러 에이전트를 묶는 순간 문제는 "누가 처리할 것인가"로 옮겨간다. 원 자료의 라우팅 규칙은 오케스트레이터가 키워드 표를 보고 분기하는 구조다.

위 표에서 이 글이 바꿔 실은 것은 둘째 행 하나다 — 키워드 「채용·지원서·전형·스크리닝」과 대상 「인사 심사 에이전트」를 원 자료의 것에서 같은 업무 도메인의 다른 표현으로 옮겼다. 나머지 다섯 행은 원 자료의 표기 그대로다. 분기가 어떤 구조로 이뤄지는지가 요점이고 단어 자체는 아니다.

여섯 행을 하나씩 배정하면 이렇다. 위의 네 행은 키워드 하나가 에이전트 하나로 배정되는 규칙이고, 다섯째 행은 배정 후보가 둘 이상일 때(「2개 이상 키워드 동시」 → 병렬 호출 후 결과 통합), 여섯째 행은 배정이 정해지지 않을 때(「분류 불명확」 → 사용자에게 선택지 제시 후 재분기)의 규칙이다 — 넷 + 하나 + 하나로 여섯 행이 전부 배정된다. 뒤의 두 행이 없으면 키워드에 두 번 걸린 요청과 어디에도 걸리지 않은 요청이 갈 곳을 잃고, 오케스트레이터가 아무 데나 보낸다. 이렇게 갈라 읽는 것은 이 글의 정리다.

라우팅 설계의 황금 규칙은 두 개다.

• 구체적 키워드를 명시적으로 나열한다. "학교 업무", "뭐든 잘 합니다" 같은 모호한 설명이 최악의 반패턴이다.
• 에이전트 간 키워드 교집합은 공집합이어야 한다. 등록 담당이 채점·출석 단어를 쓰지 않는 식으로 어휘를 분리한다.

둘째 규칙이 위 표의 실제 설계 조건이다. 네 개의 키워드 묶음 사이에 겹치는 단어가 하나라도 있으면 그 단어가 들어온 순간 분기가 결정되지 않는다.

오케스트레이터는 직접 산출물을 만들지 않는다. 분기 → 호출 → 결과 종합이 전부이고, 상위 도구(하위 에이전트 호출 권한)는 오케스트레이터 한 명만 갖는다. 공유 상태는 단일 파일을 source of truth로 두고, 동시 쓰기 충돌을 피하기 위해 에이전트별로 자기 키만 쓴다.

팀의 구성요소 넷

위의 둘이 일하는 주체이고 아래 둘이 주체들이 공유하는 상태다. 아래 둘을 빼면 팀은 그냥 여러 개의 에이전트이지 팀이 아니다.

운영 제약 셋

원 자료가 남긴 운영 제약 세 가지도 기록해 둔다. 프리뷰 단계 기능을 실무에 얹을 때의 전형적인 리스크다.

• 메시지 전달은 비동기다. 응답이 즉시 오지 않으므로 공유 상태 파일을 폴링하거나 메일박스를 확인해야 한다.
• 세션 복구가 지원되지 않을 수 있다. 따라서 모든 상태는 파일로 영속화하는 것을 전제로 설계한다.
• 실험 기능은 환경 플래그로 켜진다. 플래그를 프로젝트 설정에 박아두면 팀원마다 다르게 동작하는 사고를 막을 수 있다.

세 항목이 같은 결론으로 모인다. 메모리에 있는 것은 없다고 가정한다. 응답도 세션도 플래그도 휘발할 수 있으므로 파일에 적힌 것만 상태로 친다.

한 커맨드, 세 트리거

파이프라인 설계의 핵심 패턴은 하나의 커맨드를 세 경로에서 동일하게 호출하는 것이다.

유지보수 원칙은 명확하다. 로직이 바뀌면 커맨드 파일 한 개만 고치면 세 방향이 동시에 갱신된다. 트리거별로 로직을 복제하면 곧 세 벌이 서로 달라진다.

세 행의 「주의점」이 전부 기동 경로 때문에 생기는 제약이라는 점이 요점이다. 로직은 같은데 Hook은 세션 안에서 돌아 세션을 막을 수 있고, Cron은 세션 밖 최소 환경에서 돌아 경로가 깨지며, 수동은 사람이 실수로 실제 발송을 걸 수 있다.

원 자료가 강조한 세부 규칙 몇 가지를 표로 남긴다.

여섯 행 중 넷(Hook 종료 코드 · Hook timeout · 실행 파일 경로 · dry-run)은 값 하나가 틀려도 에러 없이 지나가는 항목이다. 종료 코드를 잘못 쓰면 세션이 막히고, 경로가 축약형이면 스케줄러에서만 안 찾히며, dry-run을 건너뛰면 실제 발송이 나간 뒤에 안다.

5초·15~30초 같은 timeout 값은 원 자료가 제시한 기준선이며 이 글이 측정한 값이 아니다. 원 자료 작성 기준일은 2026-07-26이고, 종료 코드 규약과 설정 반영 절차는 그 시점 도구 사양이다.

하루의 형태 — 체크인 / 업무 / 체크아웃

운영 비유는 "좋은 직원의 하루"다. 출근하면 할 일을 확인하고, 퇴근하면 한 일을 정리하며, 금요일엔 주간 보고서를 낸다. 이 세 가지를 스케줄러 세 줄로 자동화한다.

여섯 행 중 위의 넷이 업무를 돌리는 사이클이고 아래 둘이 시스템 자체를 점검하는 사이클이다. 아래 둘의 목적 열이 산출물이 아니라 「예방」·「부채 관리」인 것이 그 차이를 드러낸다. 이 두 행의 점검 항목은 세 번째 편이 주기별 체크리스트로 펼친다.

스케줄 등록 시 반드시 지켜야 할 것 두 가지가 반복 강조된다. 절대 경로와 로그 리다이렉션이다. 스케줄러는 사용자 셸 설정을 읽지 않는 최소 환경에서 돌기 때문에, 개발 환경에서 잘 되던 것이 여기서만 조용히 실패한다.

위 시각(09:00·18:00·금 17:00)과 점검 소요 시간(15분·30분)은 원 자료가 제시한 예시 스케줄이며 관측된 값이 아니다. 원 자료 작성 기준일은 2026-07-26이다.

로컬에서 운영으로 — 전환 시 붙여야 할 것

로컬에서 돌던 것을 운영에 올릴 때 추가로 필요한 것은 기능이 아니라 관측과 통제 수단이다.

일곱 행의 「빠뜨리면」 열을 성격별로 배정하면 이렇다. 넷은 알아차리는 시점이 늦어지는 것을 말하고(경로 — 조용히 실패한다 / 로그 — 알 수 없다 / 알림 — 며칠 뒤에 발견한다 / 비용 — 청구서로 처음 알게 된다), 둘은 피해의 크기를 말하며(권한 — 되돌릴 수 없는 조작 / 실패 처리 — 그날 전체 중단), 나머지 하나(실행 방식)만 성격이 다르다 — 자동화가 아예 성립하지 않는다는 뜻이다. 운영 전환의 본질이 기능 추가가 아니라 관측 추가라는 것이 첫 묶음에서 드러난다.

비용 행이 특히 그렇다. **"자동화 코드를 짜기 전에 비용 모니터링부터 설정한다"**는 원칙이 여기서 나온다. 자동화가 열심히 돌수록 비용도 자동으로 늘어나기 때문이다.

이 글이 비용에 대해 담은 것은 위 표의 한 행과 이 원칙 한 줄이 전부다. 비용 구조를 축별로 분해하는 본체는 마지막 편에 있다 — 모델을 난이도별로 3분할하는 방법, 프롬프트 캐싱의 히트율별 비용 시나리오, 에이전트 개수가 늘 때 비용이 개수보다 빨리 오르는 이유가 거기 있다.

Dispatch — 자리에 없을 때 지시하는 세 경로

정기 사이클 밖에서 즉시 대응이 필요한 상황을 위해 원격 지시 경로를 만든다. 카페에서 문의를 받았을 때, 이동 중 에러 알림을 받았을 때가 상정된 시나리오다.

세 방식의 제약이 각각 운영 부담·보안 부담·표현력 제한으로 갈린다. 셋 중 무엇을 감당할 수 있는지가 선택 기준이다.

핵심 구조는 30줄 수준으로 단순하다. 메시지 수신 → 발신자 화이트리스트 검증 → CLI 서브프로세스 실행(타임아웃 지정) → 결과 문자열 회신. 복잡한 건 인프라가 아니라 보안이다.

다섯 원칙은 누가 들어오는가(1·4) / 무엇으로 들어오는가(2) / 무엇을 했는가(3) / 무엇까지 할 수 있는가(5) 네 층을 덮는다. 원격 경로는 방화벽 안쪽에 난 구멍이라 층마다 막지 않으면 한 겹만 뚫려도 끝까지 열린다.

긴급 대응 워크플로우

네 단계를 합쳐 알림 수신부터 초기 대응까지를 5분 안에 끝내는 것이 목표다. 하지만 중요한 것은 속도 자체가 아니라 원격에서 할 수 있는 일의 범위를 미리 정해두는 것이다. 맨 오른쪽 열이 그 목록이며, 위험 명령을 원격 경로에서 차단해 두면 급한 순간에 되돌릴 수 없는 조작을 하는 사고를 구조적으로 막을 수 있다.

위 목표 시간(1·2·1·1분, 합계 5분)은 원 자료가 제시한 목표치이며 관측된 대응 시간이 아니다. 「30줄 수준」이라는 구현 규모도 원 자료의 서술이다. 원 자료 작성 기준일은 2026-07-26이다.

다음 편으로

이 글은 만들고 굴리는 데까지를 다뤘다. 한 명을 5필드 JD로 정의하고(경계), 여럿을 키워드 교집합이 공집합이 되게 묶고(라우팅), 세 트리거가 커맨드 하나를 부르게 하고(파이프라인), 그 위에 하루 사이클과 운영 전환 항목, 원격 지시 경로를 얹었다.

이 절들을 관통하는 것은 하나다. 경로를 늘리되 로직은 늘리지 않는다. 트리거가 셋이어도 커맨드는 하나이고, 에이전트가 넷이어도 상위 도구를 가진 것은 오케스트레이터 하나이며, 원격 경로가 셋이어도 통과할 수 있는 명령의 범위는 한 벌로 정의된다. 늘어난 경로마다 로직을 복제하는 순간 서로 달라지기 시작한다.

그런데 이렇게 잘 짜 두어도 장애는 난다. 이어지는 다음 편은 장애가 났을 때 어디부터 보는가를 다룬다 — 모든 장애를 증상·원인·해결·예방 4단으로 분해하고, 깨진 곳을 3계층으로 좁히고, 가장 자주 나오는 문제 10선과 실제 장애 5건을 같은 틀에 넣는다.