에이전트 중심 제품 개발을 위한 황금 법칙

에이전트를 개발하는 회사들은 에이전트를 종종 부수적인 기능으로 여긴다. 그러나 이건 크나큰 실수이다.

오늘날 에이전트는 당신의 프로덕트와 유저 사이에서 상호작용하는 하나의 기능이다.

따라서 에이전트를 핵심 인터페이스로 염두에 두고 개발해야 한다.

이를 잘 활용할 수 있다면 업무 자동화와 비동기 흐름처럼 프로덕트의 무궁무진한 가능성을 열어준다. 그러나 반대로 엉성하게 활용한다면 유저의 신뢰를 잃게 만든다. 느리고 버그투성이에, 심지어 정확하지 않은 결과를 제공하기 때문이다.

우리 역시 이런 경험을 해왔기에 지난 1년 동안 AI 아키텍처를 두 번이나 전면 재설계할 수밖에 없었다. 그리고 지금 우리의 에이전트와 MCP는 일간 사용자 수 6,000명을 기록했다.

그 과정에서 우리가 배운 에이전트 중심 제품 개발을 위한 황금 법칙을 공유하려고 한다.

1. 인간이 하면 에이전트도 할 수 있어야 한다

인간이 프로덕트를 통해 할 수 있는 건 에이전트도 할 수 있어야 한다. 즉, 에이전트는 모든 기능에 접근할 수 있어야 한다.

예를 들어 에이전트에게 가격 책정을 위한 A/B 테스트 실행을 명령한다고 가정해보자. 에이전트는 PostHog MCP를 이용해서 피처 플래그와 실험을 생성하고, 둘을 연결한다. 그리고 인사이트와 지표를 설정한다.

그러나 우선순위에 밀려서 실험 생성 기능이 없다고 상상해보자. 에이전트는 플래그와 인사이트까지 만들고, 당신이 직접 PostHog에서 실험을 생성한 뒤 실험 ID를 복사해 붙여넣어 달라고 요청할 것이다. 이는 무척 번거롭고, 에이전트를 사용하는 의미를 없앤다.

에이전트의 장점은 업무를 수행할 때 필요한 시간, 집중, 그리고 전문 지식을 줄여주는 것이다. 만약 에이전트가 실제 유저가 사용하는 것과 동등한 기능에 접근할 수 없다면 결국 중간에 사람의 손을 다시 거쳐야 한다.

물론 인간의 개입이 유용한 순간도 있다. 민감한 정보를 다루는 일처럼 말이다. 그러나 이건 우리가 의도적으로 에이전트를 배제하는 업무이지, 에이전트가 기능상 한계 때문에 수행할 수 없는 업무가 돼서는 안 된다.

실제로는 이런 모습이다

사실상 에이전트는 API의 모든 요소에 접근할 수 있어야 한다.

그렇다고 해서 모든 엔드포인트를 MCP 툴로 바꾸라는 얘기는 아니다. 우리는 v1에서 이와 같은 실수를 했다. 다음 법칙을 설명하면서 이 실수에 대해서 자세하게 설명하겠다.

v2에서 우리는 아래와 같은 방식을 사용했다.

1. 우리 파이프라인은 타입이 지정된 Django 엔드포인트에서 OpenAPI 스펙을 자동으로 생성한다.
2. 그걸 TypeScript 유효성 검사 스키마인 Zod로 변환한다.
3. 동시에 각 제품 팀이 YAML 설정 파일을 통해 엔드포인트를 직접 허용해야 한다. 기본적으로는 아무것도 외부에 노출되지 않는다.
4. 그다음 파이프라인이 Zod 스키마와 YAML 설정을 합쳐서 최종 TypeScript 툴 핸들러를 생성한다.

그 결과 우리는 제품 영역별로 하나씩 파일이 나뉜 툴 핸들러 세트를 얻었다. 이는 MCP 서버에서 바로 쓸 수 있다.

에이전트는 엔드포인트를 100% 정확하게 매치시키지는 않더라도, PostHog API를 통해서 인간이 수행할 수 있는 모든 것들을 할 수 있어야 한다.¹

Subscribe to our newsletter

Product for Engineers

Read by 100,000+ founders and builders

Subscribe

We'll share your email with Substack

2. 에이전트의 추상화 수준에 맞춰라

에이전트 중심의 경험을 구축하기 위해서는 에이전트가 가장 잘 이해하는 언어 수준을 찾고 그걸 활용해야 한다.

이 과정은 수많은 컨텍스트를 절약해준다. 그 장점은 유용한 수준을 넘어 근본적인 차이를 만든다. 프로덕트 에이전트의 인터페이스에 인간의 개입이 적을수록, 그곳엔 더 많은 잠재적 창의성이 존재한다.

생일 선물로 레고 세트를 받은 어린아이를 떠올려보라. 만약 이미 타이어가 조립된 레고라면 아이는 자동차, 트럭, 비행기 같은 상상 가능한 수준의 바퀴 달린 것만 만들 수 있다.

그러나 만약 모든 블록들이 전혀 조립되어 있지 않은 상태라면, 아이는 자유롭게 블록들을 믹스앤매치해서 오토바이, 타이어 그네, 눈썰매처럼 타이어를 자유자재로 활용해서 조립할 수 있다.²

실제로는 이런 모습이다

이전 버전의 MCP에서 "왜 지난주 신규 가입자 수가 떨어졌지?"라는 질문에 에이전트는 projects-get, insight-get, insight-query 두 번까지 총 네 번의 별도 호출을 해야 했다.

사람이 직접 PostHog UI를 탐색한다면 get-insight나 get-funnel 같은 명령어를 놓치지 않겠지만, 에이전트에게는 불필요한 번역 과정일 뿐이다.

그래서 MCP v2에서 우리는 에이전트가 가장 잘 활용할 수 있는 언어인 SQL을 이용해서 PostHog의 데이터를 바로 조회할 수 있게 했다.

프로덕트를 적절한 추상화 수준으로 노출시키자 데이터를 읽고 조회하는 엔드포인트들을 제거할 수 있었다. 그것들은 이미 executeSql.ts에 포함되어 있기 때문이다.

이제 "왜 지난주 신규 가입자 수가 떨어졌지?"에 대한 질문은 하나의 명쾌한 쿼리로 답할 수 있다.

SELECT
    toStartOfWeek(timestamp) AS week,
    countIf(event = 'signed_up') AS signups
FROM events
WHERE timestamp >= now() - INTERVAL 2 WEEK
GROUP BY week
ORDER BY week

3. 컨텍스트를 적게 제공하라

AI가 초기에 등장했을 때, 개발자들은 컨텍스트와 기능 부족의 한계를 만회하기 위해서 모든 것들을 에이전트에게 프론트 로드했다.

그러나 기술은 계속해서 발전하고 있고, 이제는 가능한 한 컨텍스트를 적게 제공하고 모델이 나머지를 스스로 파악하게 만드는 게 하나의 트렌드가 되었다.

이는 유연성에 초점을 맞춘 범용 에이전트에게 효과적이었다. 온 세상 사람들이 어떤 용도로 Claude를 쓸지 예측하는 건 불가능했으니까.

그러나 특정 프로덕트를 위한 에이전트 경험을 개발한다면, 문제의 범위는 훨씬 작다. 당신은 이미 핵심 시나리오와 툴, 그리고 프로덕트가 어떻게 사용될지 알고 있기 때문이다.

따라서 제품 개발자 입장에서는 각각의 세션에서 필요한 것을 프론트 로딩하고, 나머지는 나중에 필요할 때 가져오면서 균형을 잘 유지할 수 있다.

실제로는 이런 모습이다

우리는 처음에는 이런 방식을 생각하지 못했다. 그래서 우리의 v1 프롬프트는 단 네 줄의 코드였고, "PostHog를 사용하는 툴들이니까 한번 잘 써봐요"가 기본적으로 전부였다.

에이전트는 접속할 때마다 같은 걸 매번 새로 파악하느라 시간과 비용을 낭비하곤 했다.

그러나 v2에서 우리는 PostHog MCP에 접속하는 모든 사람들이 그들의 PostHog 데이터를 조회하러 접속했다는 사실을 이용했다. 이게 핵심이었다.

그 이후로 우리는 PostHog MCP 세션의 시작 단계에서 다음과 같이 로드한다.

• PostHog 전용 용어 체계. 피처 플래그, 실험, 세션 리플레이 기타 등등.
• SQL 문법. ClickHouse SQL 위에 얹은 커스텀 번역 레이어 사용법.
• 핵심 쿼리 규칙. 모든 쿼리에 적용되는 필수 제약 조건. 예를 들어 항상 시간 범위로 필터링해야 한다.

나머지는 나중에 불러올 수 있고, 그 시기는 에이전트가 판단하게 했다.

4. 스킬을 효과적으로 작성하라

스킬들은 프로덕트가 할 수 있는 것과 에이전트 툴만으로 할 수 있는 것 사이의 갭을 채워준다.

흔히 저지를 수 있는 실수는 스킬들을 하나하나 일일이 다 일러주는 매뉴얼처럼 작성하는 것이다. 당신이 너무 세세하게 지시한다면 에이전트는 당신의 지시를 너무 철저하게 따르느라 스스로 판단해서 처리할 수 있는 능력을 잃을 것이다. 이에 관해서는 세 번째 규칙에서 설명했다.

대신에 에이전트를 이미 뛰어난 능력을 갖춘 신입사원을 온보딩하는 것처럼 다루자. 능력이 없는 관리자는 모든 과정을 하나하나 지시한다. 이렇게 해라, 다음엔 저렇게 해라, 그건 하지 마라, 항상 이걸 지켜라. 좋은 관리자는 직원을 신뢰하고 그들이 스스로 알아차리지 못하는 것들에 관해서만 개입한다.

그게 좋은 스킬의 모습이다.

좋은 스킬은 오직 인간만이 제공할 수 있는 컨텍스트를 포함해야 한다. 에이전트는 다음과 같은 컨텍스트를 스스로 발견할 수 없기 때문이다.

• 내부 고유 지식. 사내 약어, 네이밍 규칙, 스타일 가이드.
• 엣지 케이스. 가끔 문제가 생기는 특이사항과 처리법.
• 감각과 노하우. 제품을 올바르게 쓰는 법뿐 아니라, 잘 쓰는 법.

실제로는 이런 모습이다

스킬에 어떤 요소가 포함돼야 할지, 스스로에게 한번 질문해보라. 만약 당신이 말해주지 않는다면 에이전트가 프로덕트에 대해 오해할 요소에는 무엇이 있을까?

우리에게는 프로덕트 사이의 연결 고리, 데이터 속에 숨겨져 있는 도메인 지식, 그리고 우리 같은 개발자만의 견해 같은 것들이다. Linear에게는 의견을 포함한 이슈 계층 구조, Figma에게는 디자인 시스템의 일관성이다.

query-retention.md에 추가한 코드 한 줄을 예시로 들자면 다음과 같다.

활성화 및 유지율 이벤트는 기본적으로 $pageview 이벤트를 사용하라. 명시적으로 요청받지 않는 한 signed in처럼 빈도가 낮거나 일관성 없는 이벤트는 피하라. 데이터를 왜곡하기 때문이다.

이러한 가이드 없이, 에이전트는 유저가 언급하는 이벤트를 전부 사용할 것이고 이는 잘못된 결과를 낳을 수 있다. 유지율은 실제보다 더 나쁘게 보일 수 있고, 유저는 직접 분석하지 않는 이상 이를 파악할 수 없을 것이다.

스킬에 이 한 줄을 추가함으로써, 우리는 좋은 지표와 분석이 무엇인지에 관한 PostHog의 공인 의견을 추가했다. 에이전트가 프로덕트를 정확하게 사용하고 유저가 의도치 않게 잘못 이해하는 일을 방지하기 위해서 말이다.

5. 에이전트를 진짜 사용자처럼 대하라

기존 소프트웨어에서, 유저 행동은 예측하기 힘들어도 코드는 예측할 수 있었다. AI 시대에 이제 그 안전성은 존재하지 않는다. 같은 인풋을 투입한다고 해서 언제나 같은 아웃풋이 나오는 것은 아니다.

이는 기존의 테스트 방식들이 놓치는 부분이 존재한다는 뜻이고, 우리는 자동화 테스트가 놓치는 부분을 파악할 수 있는 방법이 필요하다.

그러기 위해선 에이전트를 실제 유저처럼 대해야 한다. 에이전트와 대화를 나누고, 공감대를 만들고, 그들이 무엇을 원하는지에 대한 감각을 발전시켜라.

에이전트를 이해하고, 상호작용 패턴과 에이전트가 지닌 특이점에 익숙해지는 방법들을 아래에 설명하겠다.

실제로는 이런 모습이다

PostHog에서는 이를 위해 다음과 같은 습관과 행동을 실천한다.

• 헤드리스 도그푸딩. 에이전트 기능을 테스트할 때, UI보다 CLI를 먼저 사용한다. 에이전트와 같은 환경에 있게 되고, 에이전트가 경험하는 것과 똑같은 오류, 문법, 마찰을 직접 경험할 수 있다. 내부적으로 MCP 툴 설명이 예상보다 더 많은 토큰을 낭비한다는 문제를 발견했다.

• 수동 추적 리뷰 시간 갖기. 매주 추적 리뷰 시간을 갖고, 사용자 피드백 평점이 달린 실제 사용자 세션을 검토한다. 예를 들어 PostHog AI가 피처 플래그가 예약 출시를 지원하지 않는다고 자신 있게 말했다가 이를 철회한 케이스를 발견했다. 에이전트가 응답했으니 자동화 테스트로는 파악할 수 없었고, 응답이 틀렸을 뿐이다.

• 우리의 직관을 루프에 넣기. 수동 리뷰에서 발견한 것들을 바탕으로 평가 케이스를 만들어서 최대 활용을 할 수 있다. 좋은 점과 나쁜 점을 다 포함시킨다. 한번은 PostHog AI가 사용자가 눈치채지 못한 이상한 데이터 패턴을 스스로 발견하고 개입한 세션을 찾았다. 이걸 평가 케이스로 만들었고, 추후에 모델이나 프롬프트 변경이 있을 시에도 이런 좋은 행동을 유지할 수 있도록 했다.

글쓴이: Jina Yoon(감히 에이전트 신봉자라고 선언할 수 있는).

Subscribe to our newsletter

Product for Engineers

Read by 100,000+ founders and builders

Subscribe

We'll share your email with Substack