AI 도구를 쓰는 방법은 두 가지로 나뉜다. 그냥 실행하는 것과, 내 워크플로우에 녹여 통제하며 쓰는 것. 전자는 데모에서 빛나고, 후자는 실무에서 살아남는다. 최근 두 가지 사례가 이 차이를 선명하게 드러냈다. 하나는 Claude Desktop·Cursor에서 자연어 한 마디로 벨로그에 글을 발행하는 MCP 서버 개발기이고, 다른 하나는 병렬로 돌아가는 코딩 에이전트를 어떻게 리뷰 큐로 관리하느냐를 다룬 방법론이다.
자연어 명령 한 줄이 워크플로우가 되기까지
벨로그에 글을 발행하는 흐름을 생각해보자. 에디터에서 쓰고, 복사하고, 붙여넣고, 오타를 발견하면 다시 반복한다. 몇 번 반복하면 임시저장 목록에 비슷한 글이 세 개쯤 쌓인다. 로컬 파일과 벨로그 중 어느 쪽이 원본인지 헷갈리기 시작한다. Velog의 @dodledog은 이 문제를 MCP 서버로 풀었다. "이 문서 벨로그에 올려줘"라고 말하면 Cursor나 Claude Desktop이 로컬 마크다운 파일을 그대로 발행하고, 같은 파일을 다시 올리면 새 글이 아니라 기존 글을 수정하는 방식이다.
핵심 설계는 멱등성(idempotency)이다. 처음 발행 시 프런트매터에 velog_post_id를 기록해두고, 이후 실행 때는 그 ID를 분기 조건으로 삼아 create 대신 update를 호출한다. 파일이 유일한 원본이고, 몇 번을 실행해도 결과가 같다. 이 두 줄의 목표가 전체 구조를 결정했다. AI 도구를 통해 자연어로 트리거하는 것은 겉모습이고, 진짜 설계는 재실행 안전성을 보장하는 상태 추적에 있다.
조용한 실패가 설계를 무너뜨린다
개발 과정에서 가장 오래 붙잡힌 지점은 인증도, API 구조도 아니었다. GraphQL errors는 비어 있는데 data.writePost만 null로 돌아오는 조용한 실패였다. 처음에는 토큰 만료로 단정하고 에러 메시지도 그렇게 써뒀다. 그 한 줄이 실제 원인 추적을 엉뚱한 방향으로 끌고 갔다.
진짜 원인은 두 가지였다. 첫째는 필수 인자를 빈 객체로 보냈을 때 검증 에러 없이 null이 반환되는 것이었고, 둘째는 short_description 필드를 요청하면 벨로그 서버 리졸버가 터지면서 errors와 data가 동시에 내려오는 부분 실패였다. 문제는 클라이언트가 errors를 감지하면 무조건 예외를 던지도록 설계되어 있었다는 점이다. 글은 실제로 저장됐는데 id를 못 받아서 파일에 기록이 안 됐고, 다음 실행이 또 새 글을 만들었다. 중복 글을 막으려고 만든 도구가 정확히 그 지점에서 중복을 만들고 있었다.
해결책은 두 겹이었다. 문제가 되는 필드를 쓰기 응답에서 아예 빼고, errors가 있어도 data에 유효한 결과가 남아 있으면 경고만 남기고 결과를 수용하는 것. 그리고 에러 메시지에서 원인을 단정하는 대신 가능한 후보를 나열하는 방식으로 바꿨다. 이 두 가지 수정이 멱등성 보장의 진짜 마지막 퍼즐이었다. 조용한 실패에 원인을 단정하는 메시지를 붙이면 진단이 틀린 방향으로 고정된다. 이건 MCP 서버 개발에만 국한된 교훈이 아니다.
에이전트가 많아지면, 리뷰가 병목이 된다
단일 MCP 서버 하나를 통제하는 것도 이 정도 설계가 필요하다면, 병렬로 돌아가는 코딩 에이전트 여러 개를 동시에 다루는 상황은 어떨까. dev.to의 Agentis는 이 문제를 명쾌하게 진단한다. 병렬 에이전트의 병목은 터미널을 하나 더 여는 것이 아니라, 어떤 세션이 지금 주의를 요구하는지, 누가 각 변경의 오너인지, 결과를 수용하기에 충분한 근거가 있는지를 판단하는 것이다.
핵심 프레임은 세션 단위가 아니라 검토 가능한 아티팩트 단위로 조율하는 것이다. 모든 태스크는 오너 한 명, 요청된 아티팩트 하나, 쓰기 범위 하나를 가져야 한다. 두 세션이 같은 파일을 수정할 수 있다면 통합 담당자를 미리 정하거나 작업을 직렬화한다. 병렬 실행이 소유권 없이 진행되면 충돌 해결이 리뷰 단계로 밀려날 뿐이다.
세션 상태도 우선순위로 정렬한다. 인간 결정 없이 진행 불가 → 검증 실패 → 리뷰 대기 → 실행 중 → 유휴 순으로 줄을 세운다. 이렇게 하면 오래 돌아가는 노이즈 세션이 결정을 기다리는 작은 태스크를 가리는 일을 막는다.
리뷰 패킷 개념도 중요하다. 에이전트의 마지막 메시지는 주장일 뿐이다. 그 주장을 뒷받침하는 근거—diff 범위, 진단 결과, 빌드·테스트 결과, 실제 사용 확인—가 패킷으로 함께 와야 한다. 리드는 트랜스크립트 전체를 다시 열지 않고도 "무엇이 바뀌었나", "작동한다는 근거가 있나", "여전히 잘못될 수 있는 게 뭔가" 세 가지에 답할 수 있어야 한다. 패킷이 이 세 가지를 답하지 못하면 리뷰 준비가 된 것이 아니다.
에이전트를 도구로 만드는 설계 공통 원칙
두 사례는 서로 다른 문제를 다루지만 같은 방향을 가리킨다. AI 에이전트를 실행하는 것은 쉽다. 그 결과물을 신뢰 가능한 방식으로 워크플로우에 녹이는 것은 설계의 문제다.
첫째, 상태를 파일이나 태스크 카드에 명시적으로 기록하라. 벨로그 MCP 서버의 velog_post_id 프런트매터 기록이나, 병렬 에이전트의 세션-아티팩트 분리가 모두 같은 원리다. 에이전트가 닫히거나 세션이 끊겨도 상태가 보존되어야 재실행이 안전하다.
둘째, 실패를 조용히 삼키지 마라. 부분 실패를 일괄 예외로 처리하거나, 원인을 단정하는 에러 메시지를 쓰는 것 모두 진단을 망가뜨린다. 에이전트가 "성공"을 외쳐도 그것이 결과의 끝이 아니라 리뷰의 시작임을 설계에 반영해야 한다.
셋째, 관찰과 실행을 분리하라. 병렬 에이전트 대시보드는 오너십·긴급도·근거를 보여주는 관찰 도구여야 하며, 승인·병합·배포는 해당 권한과 감사 이력이 있는 시스템에 남겨야 한다. 벨로그 MCP 서버도 인증 자동화를 포기하고 "처음 한 번만 사람에게 맡기는" 구조로 통제권을 명확히 했다.
전망: 내 도구로 만든다는 것의 의미
MCP 프로토콜이 확산되면서 자연어로 외부 서비스를 조작하는 진입장벽은 계속 낮아지고 있다. 하지만 진입장벽이 낮아진다고 통제 복잡도까지 낮아지지는 않는다. 오히려 실행이 쉬워질수록 설계 없이 에이전트를 돌리는 유혹도 커진다.
"이 문서 벨로그에 올려줘"라는 한 마디 뒤에 멱등성 추적, 부분 실패 처리, 토큰 로테이션 흡수, 조용한 실패 진단이라는 설계가 숨어 있다. 병렬 에이전트 리뷰 뒤에는 오너십 분리, 리뷰 패킷 요구, 위험 우선 정렬이라는 구조가 있다. AI 워크플로우를 진짜 내 도구로 만든다는 것은, 그 자연어 명령 한 마디가 신뢰할 수 있는 결과로 이어지도록 그 사이의 모든 경로를 설계한다는 뜻이다.