질문이 달라졌다
Next.js에서 서버 로직을 짤 때 예전엔 선택지가 하나였다. API Route를 만들고, 클라이언트에서 fetch로 호출하면 끝. 그런데 App Router가 도입되고 Server Actions가 등장하면서 매번 맞닥뜨리는 질문이 생겼다. 이건 Server Action으로 짜야 할까, Route Handler로 짜야 할까?
이 질문이 더 날카로워진 맥락이 있다. OpenAI Codex 같은 AI 코딩 에이전트가 '코드를 생성'하는 수준을 넘어 '업무를 실행'하는 단계로 진화하고 있다는 점이다. 아웃소싱타임스 보도에 따르면 Codex는 이제 파일 분석, 앱 연동, 자동 실행까지 직접 수행하는 실행형 AI로 전환되고 있다. AI가 Next.js 코드를 대신 짜주는 속도가 빨라질수록, 인간 개발자가 먼저 내려야 할 아키텍처 판단은 오히려 더 명확해야 한다.
Server Actions의 본질: UI 레이어의 뮤테이션 프리미티브
dev.to에 올라온 기술 분석(Next.js Server Actions vs API Routes)을 보면, Server Actions의 정체를 가장 잘 설명하는 문장이 있다. "We only call them Server Actions when they're invoked from the client." 클라이언트에서 호출될 때만 Server Action이고, 서버 컴포넌트에서 직접 호출하면 그냥 일반 비동기 함수다.
이 설계가 중요한 이유는 실행 모델에서 드러난다. Server Action이 호출되면 단순히 서버 함수가 실행되는 게 아니라, 뮤테이션 → RSC 리렌더 → 새 UI 스냅샷 → 클라이언트 병합이라는 파이프라인이 순차적으로 돌아간다. React가 UI 일관성을 보장하기 위해 의도적으로 설계한 구조다. 즉 여러 Server Action을 동시에 호출하면 병렬로 실행되지 않는다. React는 현재 스펙상 한 번에 하나씩 순차 처리한다.
이게 버그처럼 느껴질 수 있지만 사실 아키텍처적 시그널이다. Server Actions는 UI 레이어의 뮤테이션 도구다. 클라이언트-서버 API 레이어를 대체하는 게 아니라, 폼 제출이나 버튼 클릭 같이 UI 흐름과 직결된 뮤테이션을 위해 설계된 프리미티브다.
Route Handlers의 본질: 독립적인 HTTP 엔드포인트
Route Handlers는 다르다. React 렌더링 라이프사이클과 완전히 분리된 표준 HTTP 엔드포인트다. GET, POST 등 모든 HTTP 메서드를 지원하고, 요청들은 완전히 병렬로 실행된다. 외부 서비스, 모바일 앱, 써드파티 웹훅이 소비해야 하는 엔드포인트라면 Route Handler가 유일한 선택이다.
결국 판단 기준은 하나다. 이 로직이 UI 흐름에서 발생하는 뮤테이션인가, 아니면 독립적인 API 계약이 필요한 트랜스포트 레이어 문제인가. 전자라면 Server Action, 후자라면 Route Handler다. 둘은 경쟁하는 게 아니라 서로 다른 계층의 책임을 맡고 있다.
MCP 클라이언트 아키텍처가 주는 힌트
여기서 흥미로운 유추가 생긴다. dev.to에서 다룬 MCP(Model Context Protocol) 클라이언트 아키텍처다. AI 시스템에서 모델(결정)과 서버(실행) 사이를 연결하는 것이 MCP 클라이언트의 역할이다. 모델이 직접 서버를 호출하는 게 아니라, 클라이언트가 컨텍스트를 제공하고, 모델 결정을 해석하고, 서버로 요청을 라우팅한다.
이 구조가 Next.js 아키텍처 판단과 묘하게 겹친다. Server Action은 React가 중간 레이어로서 뮤테이션과 렌더링을 조율하는 구조—마치 MCP 클라이언트처럼 UI와 서버 로직 사이를 관리한다. Route Handler는 이 조율 레이어를 우회해 직접 HTTP 인터페이스를 열어두는 방식이다. AI 에이전트가 어떤 Next.js 코드를 생성하든, 이 두 레이어의 책임 경계를 명확히 설계해두지 않으면 에이전트가 만든 코드는 일관성 없는 뒤섞임이 된다.
AI 에이전트에게 아키텍처를 위임하기 전에
Cursor나 Codex 같은 AI 에이전트를 Next.js 개발에 활용할 때 실제로 가장 많이 발생하는 문제가 바로 이 레이어 혼동이다. 에이전트는 요청을 받으면 일단 동작하는 코드를 생성한다. Route Handler가 맞는 자리에 Server Action을 넣기도 하고, 그 반대도 생긴다. 단기적으로 작동하지만 병목이 생기거나 외부 연동이 필요해질 때 문제가 드러난다.
해결책은 에이전트에게 더 정교한 프롬프트를 주는 게 아니다. 팀이 공유하는 아키텍처 원칙을 먼저 문서화하는 것이다. "UI-driven mutation은 Server Action, 외부 소비 API는 Route Handler" 같은 한 줄 원칙이 CLAUDE.md나 프로젝트 컨텍스트 파일에 있느냐 없느냐가, AI가 생성하는 코드 품질을 결정한다.
전망: 레이어 판단이 개발자의 핵심 역량이 된다
AI 코딩 에이전트가 '실행형'으로 진화할수록 코드 생성 속도는 계속 빨라진다. 하지만 아키텍처 판단—이 로직이 어느 레이어에 있어야 하는가—은 자동화되기 어렵다. 비즈니스 맥락, 팀의 협업 구조, 서비스의 확장 방향을 함께 고려해야 하는 결정이기 때문이다.
Server Actions vs Route Handlers 선택은 작은 기술적 디테일처럼 보이지만, 실제로는 이 시스템에서 UI와 서버가 얼마나 강하게 결합되어야 하는가를 결정하는 아키텍처 철학의 표현이다. AI가 빠르게 코드를 채워나갈수록, 그 코드가 올바른 자리에 놓이도록 설계 기준을 먼저 잡아두는 것이 프론트엔드 개발자의 가장 중요한 역할이 되고 있다.