AI-Native 시대의 웹 플랫폼 구축을 위한 Teach-Stack

Claude Code 및 Codex와 같은 도구들은 소프트웨어 엔지니어링이 이루어지는 방식을 완전히 재편했습니다. 이러한 새로운 툴링은 훨씬 더 빠른 개발과 반복 (iteration)을 가능하게 하지만, 프로젝트가 장기적으로 계속 진화할 수 있도록 코드를 유지보수 가능하고 확장 가능하게(scalable) 유지하는 것이 중요합니다.

여기에 설명된 모든 기술을 사용하여 초기 구조를 갖춘 템플릿 프로젝트를 GitHub에서 확인할 수 있습니다: https://github.com/MartinXPN/nextjs-firebase-mui-starter

스타트업에서 일할 때는 반복 (iteration)의 속도가 핵심입니다. 요구사항은 빠르게 변하고, 기능은 매일 추가되며, 코드는 급격히 수정됩니다. 이러한 조건에서는 사용자가 가능한 최상의 경험을 누릴 수 있도록 보장하면서도, 빠른 반복을 가능하게 하는 기술을 선택하는 것이 매우 중요합니다.

지난 4년 정도 동안, 우리는 Profound Academy를 구축하면서 많은 현대적 기술들을 실험해 왔습니다. 따라서 이 블로그 포스트에서는 높은 유지보수성을 가진 코드베이스, 확장 가능한 인프라 (infrastructure), 그리고 훌륭한 사용자 경험을 제공하면서도 빠르게 구축할 수 있게 해주는 전체 기술 스택 (tech stack)을 소개하고자 합니다. 인증 (Authentication)부터 UI까지 모든 것을 다룰 것이며, 백엔드 (backend), 호스팅 (hosting), 테스트 (testing) 등에 대해서도 이야기할 것입니다!

AI 에이전트 (AI Agents), 기술 (Skills), 그리고 MCP 서버

AI 에이전트 (AI Agents)는 버그 수정, 새로운 기능 추가, 성능 개선을 포함하여 빠른 반복 (iteration)과 신속한 개선을 가능하게 합니다. 하지만 장기적인 관점에서 코드를 유지보수 가능하게 유지하는 것이 중요합니다. AI 도구들은 과도한 엔지니어링 (overengineer)을 하고 프로젝트에 수천 줄의 코드를 추가하는 것을 매우 쉽게 만듭니다. 아직 존재하지 않는 문제를 해결하려는 충동을 억제하고, (코드, 인프라, 그리고 사용자 경험 측면 모두에서) 단순함을 유지하는 것이 중요합니다.

에이전트 중심 소프트웨어 개발 시대 (Agentic Software Development Era)에서도 작고 단순한 설정을 갖는 것이 도움이 됩니다. 에이전트들이 더 잘 협업하고, 기능은 더 빠르게 추가되며, 버그는 더 쉽게 수정되고, 코드 또한 인간이 유지보수할 수 있기 때문입니다.

따라서 우리는 프로덕션(production)에 푸시되는 코드를 작업할 때 AI 에이전트(AI Agents)를 사용하는 방식에 있어 균형 잡히고 미묘한(nuanced) 접근 방식을 취하기로 했습니다. AI 에이전트의 설정 방법은 매우 간단합니다:

AGENTS.md 또는 CLAUDE.md 파일을 가능한 한 작게 유지하세요. 여기에는 에이전트와의 모든 대화에서 반복적으로 언급해야 하는 내용과, 에이전트가 계속해서 실수하는 프로젝트 특화 사항들만 포함되어야 합니다.
거대한 AGENTS.md 파일은 실제로 LLM(대규모 언어 모델)의 성능을 저하시키고 유용성을 떨어뜨릴 수 있습니다.
스킬(skills)의 경우, 현재 대화와 관련된 스킬만 설치하고 대화가 끝나면 제거하는 것이 가장 좋습니다.
설치된 스킬의 수와 AGENTS.md 파일의 크기에 있어서는 '적을수록 좋다(Less is more)'는 원칙이 적용됩니다.
다음은 유용할 수 있는 몇 가지 스킬들입니다 (컨텍스트 윈도우(context window)를 오염시킬 수 있으므로 항상 설치해 두지는 마세요):
- UI/UX 스킬: https://github.com/nextlevelbuilder/ui-ux-pro-max-skill
- React/NextJS 스킬: https://github.com/vercel-labs/agent-skills
- Firebase 스킬: https://github.com/firebase/agent-skills
- PostHog 스킬: https://github.com/posthog/skills

MCP 서버(MCP Servers)의 경우, PostHog에서 제공하는 서버를 사용하면 에러 트레이스(Error traces)와 로그에 쉽게 접근할 수 있어 디버깅(debugging) 및 문제 해결에 도움이 됩니다.

Context7은 LLM을 위한 코드 문서(code documentation)를 제공하는 MCP 서버입니다. 이를 통해 에이전트들이 라이브러리와 프레임워크의 최신 문서를 참조할 수 있습니다.

대부분의 경우, 에이전트들은 MCP 서버의 추가적인 도움 없이도 스스로 문제를 파악할 만큼 충분히 똑똑합니다. 그래서 저는 MCP 서버를 설치하거나 활성화해야 할 일이 거의 없다는 것을 알게 되었습니다.

프론트엔드 (Frontend)

핵심 프론트엔드 (Frontend) 기술로서, React는 많은 풀스택 (Full-stack) 프로젝트에서 최고의 선택지로 꼽힙니다. Vue나 Svelte와 같은 다른 옵션들도 있지만, React는 방대한 라이브러리 범위를 갖추고 있다는 점에서 빛을 발합니다. 이 거대한 생태계 덕분에 새로운 기능을 추가하고 빠르게 변경하는 것이 용이하며, 이것이 바로 많은 개발자가 선호하는 이유입니다.

하지만 프론트엔드 라이브러리로서의 React는 Google이나 Bing과 같은 검색 엔진과 잘 맞지 않는 경우가 많습니다. 이러한 검색 엔진들은 봇 (Bot)을 사용하여 페이지의 HTML을 훑어보고 그 콘텐츠를 이해합니다. 그러나 React로 구축된 페이지는 대개 서버로부터 비어 있는 HTML 바디 (Body)로 시작합니다. 이는 만약 여러분의 웹사이트가 Google, Bing 또는 다른 검색 엔진의 검색 결과에 나타나기를 원한다면, 서버에서 오는 첫 번째 콘텐츠에 페이지에 대한 올바른 정보가 담긴 HTML 요소들이 포함되도록 보장해야 함을 의미합니다.

그 지점에서 Next.js가 빛을 발합니다. Next.js는 서버 사이드 렌더링 (Server-side rendering, SSR)과 정적 웹사이트 생성 (Static website generation, SSG)을 제공하는 React 프레임워크입니다. 따라서 Next.js로 구동되는 페이지는 서버에서 먼저 렌더링된 후 HTML이 브라우저로 전송되므로, 페이지의 초기 콘텐츠가 페이지에 대한 모든 필요한 정보를 포함하도록 보장합니다. 페이지가 렌더링된 후에는 필요한 JavaScript만 클라이언트로 전송되어, 사용자 브라우저로 전송되는 번들 (Bundle)을 최소화합니다. 이는 사용자 경험 (User experience, UX)과 검색 엔진 봇이 페이지를 이해하는 능력을 모두 향상시킵니다.

Next.js 프로젝트의 최신 표준은 app router이며, 이는 개발자들이 증분 정적 재생성 (Incremental static regeneration, ISR), 부분 사전 렌더링 (Partial pre-rendering, PPR) 및 사용자 경험을 개선하고 앱을 더 빠르게 느끼게 만드는 여러 다른 기능들을 쉽게 사용할 수 있도록 해줍니다. 따라서 저는 app router로 프로젝트를 시작하는 것을 강력히 권장합니다.

React는 서버 사이드 방향으로 이동하고 있으며 (PHP와 다소 유사해지고 있습니다), Next.js의 app router는 "서버 우선 (server-first)" React 컴포넌트를 개발하기 위한 훌륭한 개발자 경험 (Developer Experience)을 제공합니다. Next.js의 캐싱 (caching), TurboPack, 그리고 AI 에이전트 친화적인 설정과 같은 기능들은 쉽고 빠른 구축과 반복 (iteration)을 가능하게 합니다.

UI

웹 앱을 개발할 때, 기업의 전통적인 워크플로우는 기획, UI/UX 디자인, 구현, 그리고 디자이너와 개발자 간의 수많은 피드백 과정을 포함한 여러 단계를 거칩니다. 스타트업은 빠른 반복이 필요하며, 개발 주기를 짧게 유지하는 것이 매우 중요합니다.

저희의 경험상, UI/UX를 진행하는 가장 효율적인 방법은 견고한 UI 프레임워크(저희의 경우 MUI)를 선택하고, 디자이너에게 Figma에서 모든 것을 만들게 한 뒤 개발자가 이를 React 앱에서 다시 구현하도록 요청하는 대신 디자인 템플릿을 따르는 것이었습니다. 저희는 코드베이스 (codebase)를 단일 진실 공급원 (single source of truth)으로 유지했습니다. 이것은 말 그대로 저희의 시간을 몇 달이나 아껴주었습니다!

MUI는 가장 일반적인 유스케이스 (use cases)를 아우르는, 커스터마이징이 매우 용이한 풍부한 컴포넌트 컬렉션을 보유하고 있습니다. 좋은 점은 모든 것이 커스터마이징 가능하다는 것이지만, 기본 설정 (defaults)이 매우 훌륭하기 때문에 대부분의 경우 컴포넌트의 기본 동작과 외형을 그대로 사용하게 됩니다.

MUI를 사용했을 때 얻는 보너스 중 하나는 React 컴포넌트로 사용할 수 있는 방대한 아이콘 컬렉션을 제공한다는 점입니다. 덕분에 앱에 아이콘을 포함하는 과정이 매우 직관적입니다.

MUI의 대안으로는 다음과 같은 것들이 있습니다:

shadcn/ui는 매우 인기 있는 현대적인 대안입니다. 다만, 라이브러리 코드(CLI를 통해)를 코드베이스에 직접 복사하여 붙여넣는 것이 좋은 아이디어인지에 대해서는 스스로 확신이 서지 않습니다.
Ant Design 또한 훌륭한 대안입니다.
Chakra UI도 UI 프레임워크로 사용할 수 있습니다.
이전에 NextUI로 알려졌던 HeroUI 역시 훌륭합니다.

어떤 사람들은 단순히 styled components를 사용할 것을 제안합니다. 어떤 이들은 Tailwind CSS를 사용하기도 합니다. 하지만 styled components와 Tailwind CSS 모두 여전히 많은 양의 CSS를 작성해야 합니다. 이는 UI 프레임워크 (UI Framework)를 사용하는 것과 비교했을 때 최상의 개발자 경험 (Developer Experience)을 제공하지 못할 수 있으며, 특히 웹사이트의 모든 페이지를 직접 디자인하는 것을 피하고자 한다면 더욱 그렇습니다.

다양한 템플릿 스토어에서 영감을 얻을 수 있습니다:

MUI Store는 매우 훌륭하며 멋진 UI 템플릿을 많이 포함하고 있습니다: https://mui.com/store
Dribbble에도 괜찮은 템플릿들이 있습니다 - https://dribbble.com/tags/react_template

또는, AI 에이전트 (AI Agent)에게 여러 개의 프로토타입 (Prototype)을 디자인하도록 요청한 뒤 그중 가장 좋은 것을 선택할 수도 있습니다. 생성된 UI를 개선하기 위해 UI/UX 스킬과 같은 기능을 추가할 수 있습니다: https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.

폼 (Forms)

폼 (Forms)은 풀스택 (Full-stack) 프로젝트의 큰 부분입니다. 저희의 경험상, Zod와 React Hook Form은 함께 사용할 때 매우 잘 작동하며 폼을 생성하는 데 필요한 모든 기능을 제공합니다. 이 조합에서 Zod는 스키마 검증 (Schema validation) (타입, 최소/최대 범위, 길이, 열거형 (Enums) 등)을 제공하고, React Hook Form은 폼과 상호작용할 수 있는 유연한 API를 제공합니다. 이 두 라이브러리를 사용하면 동일한 폼과 상호작용하는 컴포넌트 (Component)를 중첩시키고, 서로 다른 복잡한 검증을 수행하며, 데이터를 즉시 업데이트할 수 있습니다. 이들은 폼 작업을 너무나 쉽게 만들어 줍니다.

백엔드, 인증, 그리고 데이터베이스 (Backend, Authentication, and Database)

Firebase 및 Supabase와 같은 플랫폼은 서비스형 백엔드 (Backend as a Service, BaaS)를 제공하여, 자체 인프라를 유지 관리하지 않고도 수백만 명의 사용자로 확장할 수 있도록 도와줍니다. 저희는 현재 인증 (Authentication), 스토리지 (Storage), 데이터베이스 (Database) (Firestore), 그리고 커스텀 백엔드 로직을 처리하기 위한 서버리스 함수 (Serverless functions)를 위해 Firebase를 사용하고 있습니다.

인증 (Authentication)

인증 (Authentication)에 사용할 수 있는 아주 훌륭한 제품 중 하나는 Clerk이지만, 저희는 현재 기본 Firebase 인증 시스템을 사용하고 있으며 이는 매우 잘 작동합니다. Firebase는 심지어 UI 코드를 작성하지 않고도 Firebase 인증을 설정할 수 있도록 도와주는 firebaseui-web이라는 별도의 패키지도 제공합니다.

인증 (Authentication)이 제대로 작동하려면, Firebase가 문제없이 인증을 처리할 수 있도록 Next.js 애플리케이션을 auth.profound.academy에 배포하기도 합니다.

데이터베이스 (Database)

전통적인 방식(프론트엔드 분리 + 데이터베이스를 포함한 백엔드 분리)으로 대규모 프로젝트를 개발할 때, 보통 프론트엔드에서 트리거되어 데이터베이스 항목을 수정하는 수많은 API 호출이 발생하게 됩니다. 많은 프로젝트에서 이러한 호출의 80%는 단순한 CRUD (Create, Read, Update, Delete) 작업입니다. 나머지 20%는 더 복잡한 작업(여러 항목을 업데이트하거나 여러 소스에서 데이터를 읽고 집계하는 작업 등)을 포함합니다. Firebase가 수행하는 매우 영리한 일 중 하나는 이 80%에 최적화되어 있다는 점입니다. 덕분에 불필요한 API 엔드포인트 (API endpoints) 없이도 프론트엔드에서 데이터를 매우 쉽게 조작할 수 있습니다 (더 복잡한 로직이 필요한 나머지 20%는 Firebase Functions로 처리할 수 있습니다).

이는 다음 두 가지 구성 요소로 구현됩니다:

Firestore Rules: 액세스 관리(access management) 및 권한(permissions)과 관련된 모든 사항은 firestore.rules라는 단일 파일로 격리됩니다. 이를 통해 Firebase가 사용자가 주어진 데이터를 읽을 수 있는지, 혹은 생성/업데이트/삭제할 수 있는지를 자동으로 확인하므로, API 엔드포인트(API Endpoints)가 모든 함수에서 매번 사용자 권한을 확인할 필요가 없습니다. 이러한 격리는 코드를 작성할 때 불필요한 상용구 코드(boilerplate code)를 획기적으로 줄여주므로 매우 가치 있는 기능입니다.
Firestore Client SDK: 데이터의 생성(create), 읽기(read), 업데이트(update), 삭제(delete)는 Firebase SDK를 통해 처리됩니다. 이는 실시간 업데이트(real-time updates) 감지, 카운터 증가(incrementing counters), 업데이트 일괄 처리(batching updates)와 같은 유용한 기능들을 많이 제공합니다. 이 모든 과정은 firestore.rules에 따라 자동으로 검증됩니다!

Firestore를 사용할 때 한 가지 주의할 점은 데이터를 저장하는 멘탈 모델(mental model)입니다. Firestore는 읽기 작업(read operations, 대개 대부분을 차지함)에 최적화되어 있기 때문에, 데이터를 비정규화(denormalized)된 상태로 유지하도록 권장합니다. 이는 특히 SQL 배경을 가진 사람들에게는 직관에 어긋날 수 있습니다. Firestore의 데이터 모델링(data modeling)에 대한 세부 사항을 설명하는 훌륭한 강연이 여기 있습니다: link.

전반적으로 Firestore는 훌륭한 사용자 경험(특히 실시간 변경 리스너(real-time change listeners)를 통해)과 개발자 경험을 제공하며, 이를 통해 빠르게 움직이고 변화하는 요구사항에 맞춰 애플리케이션 전체를 적응시키기가 용이합니다.