DEVOCEAN

얼마 전 X에서 @silvanrec의 에이전트 스레드(스페인어)를 읽었는데,

에이전트를 데모가 아니라 아키텍처로 이해해야 실제 업무 문제를 진단하고 운영할 수 있다는 이야기가 계속 머리에 남았습니다.

마침 지난주에 DEVOCEAN inside 블로그 글쓰기를 Claude Code로 하려고 devocean-mcp를 만들었는데,

스레드에 나온 원칙 상당수를 만들면서 직접 부딪혔던 거 같아서 같이 정리해 봅니다.

원문은 프리랜서·소규모 에이전시가 에이전트로 돈을 버는 방법을 다룬 글입니다.

여기서는 판매·가격 이야기는 덜어내고 아키텍처, 단계적 도입, 운영 원칙 위주로 정리했고, 원문에 없는 사내 도입 관점(거버넌스)을 보강했습니다.

먼저 요점부터 적으면 이렇습니다.

• 에이전트 = LLM + tool calling + 실행 루프 + 메모리/상태. 넷 중 하나라도 없으면 긴 프롬프트를 가진 챗봇입니다.

• 처음부터 완전 자율 에이전트를 만들지 않습니다. 결정론적 자동화에 LLM 판단 지점 하나를 넣는 구조로 시작합니다.

• 성과는 응답 시간, 해결률, 절감된 사람 시간처럼 잴 수 있는 지표로 정의합니다.

• 관측성(로그, 트레이싱, eval)과 프롬프트 버전 관리가 없으면 운영할 수 있는 서비스가 아닙니다.

1. 에이전트의 구성요소

에이전트는 목표를 이루거나 스텝·비용 상한에 닿을 때까지 인식, 추론, 행동, 관찰을 되풀이하는 루프입니다. 한 번 답하고 끝나는 프롬프트와 가장 크게 다른 점이 이 반복입니다.

그림 1. 에이전트 실행 루프와 루프 밖 요소

• 실행 루프: 모델이 도구를 고르고, 도구가 결과를 돌려주면, 모델이 다음 스텝을 정합니다. 이 루프가 없으면 챗봇입니다.

• Tool calling: 이름, 파라미터, 설명으로 된 스키마를 보고 모델이 언제 어떤 도구를 호출할지 판단합니다. API 조회, DB 쓰기, 메일 발송 같은 실제 실행이 여기서 일어납니다.

• MCP: 도구와 데이터 소스를 모델에 상관없이 같은 방식으로 노출하는 개방 표준입니다. 모델이나 공급사를 바꿔도 도구 연동을 다시 짜지 않아도 됩니다.

• 메모리와 상태: 단기(현재 대화 맥락)와 장기(사용자별 과거 상호작용) 메모리를 구분합니다. 장기 메모리가 없으면 매 세션 같은 질문을 반복하게 되고, 사용자 불만 1순위가 됩니다.

• RAG: 문서를 벡터 DB에 인덱싱하고, 질의마다 관련 조각을 찾아 맥락에 넣습니다. 청킹이나 임베딩이 잘못되면 루프가 정상이어도 답이 틀립니다.

devocean-mcp에서는

devocean-mcp는 inside 블로그 임시저장·발행을 Claude Code에서 부를 수 있게 만든 로컬 MCP 서버입니다. 만들고 보니 위 구성요소가 그대로 나뉘어 있었습니다.

특히 마지막 줄이 루프가 왜 필요한지 보여 주는 예였습니다.

오류 메시지를 사람한테 보여 주는 대신 모델이 읽고 다음 행동을 고르게 만들어 두니, 사용자는 뜬 브라우저 창에서 로그인만 하면 됐습니다.

2. 단계별 로드맵

원문은 0~5단계로 나눠서, 더 복잡한 아키텍처로 가기 전에 1단계, 즉 결정론적 플로우에 LLM 판단 지점 하나를 둔 구조로 성과부터 내라고 권합니다.

여기서는 원문 단계 대신 블로그 올리기를 실제로 바꿔 온 순서로 다시 정리해 봤습니다.

돌아보면 단계를 건너뛰지 않은 게 맞았던 거 같습니다.

1단계 스크립트로 글쓰기 화면이 어떤 순서로 움직이는지 이미 알고 있었기 때문에,

2단계에서는 "그 순서 중 어디를 모델에게 맡길까"만 고민하면 됐습니다.

원문은 3단계부터는 사람이 매 실행을 지켜보지 않으니 실패를 먼저 알아차릴 알림 체계가 선행 조건이라고 봅니다.

4단계는 프롬프팅보다 외부 API 문서 해석, 인증(OAuth, API 키, 서명된 웹훅), 부분 장애 처리 역량이 핵심이라고 하는데,

이건 devocean-mcp를 만들며 100% 공감했습니다. 공개 API가 없어서 글쓰기 화면의 자바스크립트를 읽어 요청 형식을 찾는 데 코드 짜는 것보다 시간이 더 들었습니다.

응답은 JSON인데 Content-Type은 text/html로 오고, 임시저장과 발행이 카테고리 필드 이름을 서로 다르게 쓰는 것처럼 문서에 없는 것들이 대부분이었습니다.

3. 자주 하는 기술적 실수

운영 단계에서 가장 비싸게 돌아오는 실수는 상한 없는 루프와 관측성 부재입니다.

저도 표 마지막 줄을 피하려고 애썼습니다. 마크다운 → HTML 변환, 그림 업로드, 썸네일 생성은 추론이 필요 없어서 전부 MCP 안의 일반 코드로 처리했습니다.

모델이 판단하는 곳은 어떤 도구를 부를지, 카테고리를 지정하지 않았을 때 무엇을 고를지 정도입니다.

그것도 카테고리는 처음에 단순한 점수 규칙(제목·태그·본문에 카테고리 이름이 나온 횟수)으로 먼저 만들었습니다.

4. 영역별 기술 스택

원문은 LLM이 판단이 필요한 지점만 맡고, 나머지는 결정론적 도구가 처리하는 계층 구조를 권합니다.

devocean-mcp는 이 표에서 모델은 Claude, 오케스트레이션은 Claude Code, 도구 프로토콜은 MCP, 버전 관리는 git만 쓴 작은 구성입니다.

스킬(절차)과 MCP(도구)를 나눠 둔 덕분에, 원고 쓰는 방식을 바꾸고 싶으면 스킬 문서만 고치고 inside 화면이 바뀌면 MCP 코드만 고치면 됩니다.

5. 엔터프라이즈 관점 보강

원문은 외부 고객에게 납품하는 상황을 전제로 해서, 사내 도입에 필요한 통제 항목은 거의 다루지 않습니다. 사내 에이전트에는 아래 항목을 설계 단계부터 넣어야 합니다.

devocean-mcp를 만들 때 가장 오래 고민한 것도 이 표의 위쪽 항목들이었습니다.

• 권한과 인증: 회사 AI 사용 정책에 비밀번호를 AI 도구에 입력하지 않는다는 항목이 있어서, 아이디·비밀번호 로그인은 처음부터 뺐습니다. 사람이 브라우저에서 직접 로그인하고, MCP는 그 세션 쿠키만 본인만 읽을 수 있는 파일(권한 600)에 저장해 씁니다. 그래서 MCP는 로그인한 사람의 권한을 넘어설 수 없습니다.

• 데이터 거버넌스: inside 응답에는 로그인한 사용자 정보가 섞여 오는데, 카테고리 목록을 받아 보니 항목 123개마다 들어 있었습니다. 그대로 넘기면 대화 기록에 내 정보가 계속 쌓이기 때문에, 응답 전체에서 이 필드를 지운 뒤에 모델에게 넘기게 했습니다.

• 사람 개입: 발행은 실수로 올라가면 사내에 바로 게시되니까 두 단계로 나눴습니다. confirm 값 없이 부르면 제목, 카테고리, 공개 범위만 보여 주고 끝나고, 사람이 확인한 뒤 confirm=true로 다시 불러야 발행됩니다. 공개 범위도 기본은 사내 공개이고, 외부 공개는 명시적으로 요청할 때만 신청합니다.

만들고 나서 보니 "부작용 있는 도구는 사람 승인" 원칙을 코드 기본값으로 박아 둔 게 제일 잘한 결정이었던 거 같습니다.

프롬프트로 "발행 전에 꼭 물어봐"라고 적는 것보다 도구가 기본적으로 발행을 안 하게 만드는 쪽이 훨씬 믿을 만합니다.

6. 정리

원문의 기술 프레임은 표준적이고 대체로 정확해서 사내 입문 교육 자료로 쓸 만합니다. 다만 엔터프라이즈 통제 항목은 따로 보강해야 합니다.

• 바로 쓸 수 있는 부분: 4요소 정의, 결정론적 자동화 우선 원칙, 스텝·비용 상한, 프롬프트 버전 관리, 회귀 eval.

• 확인이 필요한 부분: 원문의 'Gemini Spark가 MCP를 채택했다'는 서술은 출처를 확인하지 못했습니다. 'RAG가 유용성의 80%'는 근거 없는 수사적 수치로 보입니다.

• 직접 해 보고 느낀 점: 작은 도구라도 MCP로 만들어 보면 tool calling, 상태, 인증, 사람 승인이 왜 필요한지 몸으로 알게 됩니다. 에이전트를 공부하신다면 자주 쓰는 사내 화면 하나를 골라 MCP로 붙여 보시는 걸 추천드립니다.

devocean-mcp에도 아직 없는 게 많습니다. 실행 로그나 eval이 없어서, 원문 기준으로 보면 아직 "운영 가능한 서비스"라기보다 개인 도구에 가깝습니다.

다음에는 도구 호출 기록부터 남겨 볼 생각입니다. 사내에서 에이전트를 만들어 보려는 분들께 조금이나마 참고가 되면 좋겠습니다.

devocean-mcp와, 주제만 주면 원고 작성·도식·임시저장까지 해 주는 devocean-blog 스킬의 설치와 사용법은 사용 가이드에 정리해 두었습니다(스킬은 9장).

저장소는 사내 GitLab에 있어서 사내 계정으로 받을 수 있고, 들어가지지 않으면 말씀해 주세요.

출처: X @silvanrec 스레드 (스페인어)