AI는 코드가 아닙니다

함수(Function)에 같은 질문을 두 번 던지면, 당신은 같은 답변을 얻습니다. 그것이 계약(Contract)입니다. LLM에 같은 질문을 두 번 던지면, 서로 다른 두 가지 답변을 얻을 수도 있습니다. 둘 다 정답일 수 있지만, 표현 방식은 다를 것입니다.

AI 보조 도구를 사용하여 개발할 때 발생하는 대부분의 좌절감은, 두 번째 방식(LLM)으로 작업하면서 첫 번째 방식(함수)의 계약을 기대하는 데서 비롯됩니다. 해결책은 프롬프트(Prompting)를 더 강하게 하는 것이 아닙니다. 더 나은 브리핑(Briefing)을 하는 것입니다: AI = 컨텍스트 (Context).

구체적인 문제점

WebsitePublisher.ai는 AI 어시스턴트가 MCP 도구(59개)와 REST API를 통해 완전한 웹사이트를 구축하는 플랫폼입니다. 웹숍(Webshop)을 구축하는 작업은 제품 카탈로그, 장바구니, 결제 오케스트레이션(Checkout orchestration), 결제(Mollie/Stripe), 재고, 인보이스(Invoicing), 이메일, 검색, 할인, 리뷰, 위시리스트, 장바구니 이탈 복구, 분석(Analytics), 배송 등 14가지의 통합(Integration) 과정을 거칩니다.

14가지 통합 과정을 넘나들며 즉흥적으로 행동하는 AI는 예측 가능한 실수를 저지릅니다: 클라이언트 측(Client-side)에서 주문 총액을 계산하거나, 엔드포인트(Endpoint) 이름을 추측하거나, 두 개의 별개 인증(Auth) 시스템(방문자 세션 vs 관리자 토큰)을 혼동하거나, 브라우저에서 데이터 API로 직접 쓰기를 시도하는 등의 실수입니다.

우리는 이를 알고 있습니다. 왜냐하면 우리 스스로가 그 모든 실수를 먼저 저질러 보았기 때문입니다.

해결책: 컨텍스트로서의 쿡북(Cookbook)

그래서 우리는 그것들을 기록했습니다. 단 한 번 말이죠. '이커머스 쿡북(E-commerce Cookbook)'은 약 1,900줄의 마크다운(Markdown)으로 구성되어 있으며, CDN을 통해 제공되고, 빈 프로젝트에서 작동하는 상점에 이르기까지 12단계로 구조화되어 있습니다. 여기에는 다음 내용이 인코딩되어 있습니다:

• 두 가지 황금률 (Two golden rules). 브라우저 JS는 데이터 API에 직접 쓰지 않으며, 돈/재고/포인트 로직은 항상 서버 측 (server-side)에서 처리됩니다. 각각의 규칙에 대해 서비스 출시 전 발견한 실제 취약점(exploits)을 ❌/✅ 표로 정리했습니다.
• 분리된 두 가지 인증 시스템 (Two auth systems, kept apart). 스토어프론트(storefront)를 위한 방문자 세션 (매직 링크, magic link)과 상점 소유자를 위한 별도의 비밀번호 기반 관리자 토큰 (admin tokens)이 있습니다. 쿡북은 어떤 엔드포인트(endpoint)가 어디에 속하는지 명확히 설명합니다. 왜냐하면 "모든 고객이 제품을 삭제할 수 있음"과 같은 상황은 인증 모델 하나가 혼동될 때 발생하기 때문입니다.
• 모든 함정(pitfall)을 문서화. 스크립트 태그(script tags) 내부에서 실행되지 않는 서버 측 렌더링 (server-side rendering) 헬퍼, 빈 옵션 배열을 반환하는 장바구니 응답, 장바구니와 카탈로그 간에 서로 다른 필드 이름 등. 이 각각의 사례는 한 번씩 디버깅 세션을 소모하게 만들었으며, 이후로는 다시 발생하지 않았습니다.

전달 메커니즘 (The delivery mechanism)

대시보드 타일 → 사용자의 프로젝트 ID가 미리 채워진 하나의 프롬프트(prompt) → Claude, ChatGPT 또는 Cursor에 붙여넣기:

https://cdn.websitepublisher.ai/cookbooks/ecommerce.md 에 있는 쿡북을 읽고
이를 사용하여 내 WebsitePublisher 프로젝트 12345에서 완전한 웹숍을 구축하세요.
단계 0(Step 0)부터 시작하여 순서대로 단계를 따르세요.

AI는 레시피를 가져와 단계별로 구축합니다. 동일한 입력 문서, 일관된 출력 형태 — 일관성은 모델이 아니라 컨텍스트 (context)에 존재합니다.

시사점 (Takeaway)

사용자가 AI 에이전트 (AI agents)를 통해 작업한다면, 여러분의 문서가 곧 제품의 접면 (product surface)입니다. 사용자의 AI가 읽을 수 있는 마크다운 (markdown) 파일은 여러분이 이번 분기에 출시할 기능 중 가장 레버리지가 높은 (highest-leverage) 기능이 될 수 있습니다. 저희에게는 그러했습니다.

소프트웨어를 구축할 때 AI가 실제로 어떻게 행동하는지에 대한 짧은 시리즈의 파트 1입니다. 다음 주제: 컨텍스트 전략 (context strategies), 그리고 AI가 진정으로 어려워하는 부분 (이미지, 대용량 파일).