어드민 개발 프레임워크

개요

거래처 홈페이지의 어드민을 빠르게 구축하기 위해 제작한 Next.js 기반 어드민 프레임워크입니다. 어드민마다 공통으로 필요한 목록·검색·작성·수정 흐름을 개발 기반으로 정리해, 신규 프로젝트를 빠르게 시작하고 기존 프로젝트를 쉽게 유지보수하는 것을 목표로 잡았습니다.

핵심은 관리 모듈을 추가하는 구조의 설계였고, 과도한 추상화가 모듈의 자율성을 침해하지 않는 적정선을 여러 패턴을 시도하며 찾았습니다.

이 프레임워크로 개인용 업무 도구 Work Manager와 솔라가드 건축용 필름 보증서 서비스 외 2건 프로젝트의 어드민을 개발했습니다.

작업범위

• FSD 기반 app, features, shared 레이어 구조 정의
• manage-modules 기반 CRUD 모듈 구조와 공통 Server Actions 구현
• ActionResult 기반 서버 액션 공통 응답 규약 설계
• 첨부파일 업로드와 에디터 이미지 업로드를 아우르는 파일 시스템 구현
• Next.js 라우트 그룹 기반 라우트 구조 설계
• 개발/유지보수 워크플로우 및 컨벤션 설계
• Supabase 마이그레이션 워크플로우 설계

설계 포인트

Manage modules 기반 관리 기능 개발 구조 설계

디렉토리를 복제하는 것만으로 관리 기능을 추가하고, 각 모듈을 쉽게 커스텀할 수 있는 구조를 목표로 설계했습니다.

_base 디렉토리에 목록·상세·생성·수정 화면, CRUD 처리, 상태 관리, 공통 타입 등 도메인과 관계없는 기반 기능을 두었습니다. 각 도메인 모듈은 _base의 인프라를 가져다 쓰고, CONFIG와 스키마·테이블·폼을 자신의 디렉토리에서 정의해 관리 기능을 추가하고 확장합니다.

컴포넌트들은 과도한 추상화로 커스텀을 방해하지 않도록 분리하고, 모듈별로 파일을 복제해서 사용하는 것을 채택했습니다. 중복 코드와 파일은 늘어나겠지만 구조를 _base에 숨겨두는 패턴이 오히려 러닝커브를 늘리고 커스텀 및 유지보수를 어렵게 한다고 보았습니다.

특히 서버액션에서는 팩토리 패턴을 시도했으나, 실제 프로젝트에 적용하다 보니 시간이 지나 구조를 파악하고 흐름을 추적하기 어려워지는 부작용이 발생했습니다. 따라서 팩토리 패턴을 제거하고 각 모듈에서 _base의 함수를 가져다 쓰거나 직접 작성하는 방향으로 구조를 단순화했습니다. 모든 액션은 ActionResult 하나의 응답 타입으로 성공과 실패를 반환하도록 통일해서 에러 처리의 일관성을 설계했습니다.

Supabase 기반 프로젝트 초기화 및 유지보수 워크플로우 설계

Supabase 초기화 흐름은 PC에 프로그램을 설치하는 과정에 착안해 설계했습니다. 새 프로젝트를 시작할 때 앱을 구동하기 위한 필수 구조를 초기화하도록 마이그레이션을 구성했습니다. 그 외 기본 관리 테이블들은 별도의 마이그레이션 파일로 준비해두어 필요 시 적용할 수 있도록 하였습니다.

개발 중에는 로컬 Supabase CLI에서 마이그레이션 기반으로 작업하도록 컨벤션을 정했습니다. 이러한 구성으로 초기 세팅을 빠르게 가져가고, 개발 중에도 불필요한 의사결정을 줄여 기능 구현에 집중할 수 있게 했습니다.

구조화된 프레임워크의 AI 에이전트 활용 효과

이 프레임워크는 제가 직접 개발할 때의 효율을 위해 설계했지만, AI 에이전트를 붙여보니 구조 자체가 하네스 역할을 했습니다. 정형화된 구조는 에이전트가 임의로 새 구조를 만들 여지를 줄이고, 일정한 패턴으로 결과물을 내도록 강제하는 효과가 있었습니다. 프롬프트와 문서만이 아니라 코드베이스 설계도 에이전트 하네스의 구성 요소가 될 수 있다는 점을 확인할 수 있는 포인트였습니다.