@restnfeel/agentc-starter-kit NPM

🚀 AgentC CMS Starter Kit

완전한 엔터프라이즈급 CMS 모듈 - AI가 쉽게 구현할 수 있는 재사용 가능한 CMS 시스템

📋 목차

🚀 빠른 시작

1. 설치

npm install @restnfeel/agentc-starter-kit
# 또는
yarn add @restnfeel/agentc-starter-kit

2. Supabase 설정 (기본 BaaS)

Supabase 프로젝트 생성
- Supabase 콘솔에서 새 프로젝트 생성
- 데이터베이스 비밀번호 설정

환경 변수 설정

cp .env.example .env.local

.env.local 파일에 Supabase 정보 입력:

DATABASE_URL="postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF].supabase.co:5432/postgres"
SUPABASE_URL="https://[YOUR-PROJECT-REF].supabase.co"
SUPABASE_ANON_KEY="your-supabase-anon-key"
NEXTAUTH_SECRET="your-nextauth-secret"

# RAG 챗봇용 LLM API 키 (OpenAI, Anthropic 등)
LLM_API_KEY="your-llm-api-key"

데이터베이스 마이그레이션
```
npx prisma db push
npx prisma generate
```
Supabase Storage 설정 (RAG 챗봇용)
- Supabase 콘솔에서 Storage > Create Bucket > "documents" 생성
- 버킷 정책에서 업로드 권한 설정

3. 기본 사용법

import {
  HeroSection,
  AboutSection,
  AuthProvider,
  createSupabaseAdapter,
} from "@restnfeel/agentc-starter-kit";
import { createClient } from "@supabase/supabase-js";

// Supabase 클라이언트 생성
const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);

// 인증 어댑터 설정
const authAdapter = createSupabaseAdapter(supabase);

export default function Home() {
  return (
    <AuthProvider {...authAdapter}>
      <HeroSection
        title="AgentC로 빠른 웹사이트 구축"
        subtitle="AI와 함께 하는 현대적인 CMS 솔루션"
        ctaText="시작하기"
        ctaLink="/get-started"
      />
      <AboutSection
        title="왜 AgentC인가?"
        content="개발자와 기업을 위한 완벽한 웹사이트 구축 솔루션"
      />
    </AuthProvider>
  );
}

🏗️ 모듈 개요

📦 포함된 구성 요소

1. 섹션 컴포넌트 라이브러리 (28개)

import {
  HeroSection,
  AboutSection,
  FeaturesSection,
  GallerySection,
  ContactSection,
  TestimonialSection,
  PricingSection,
  TeamSection,
  FAQSection,
  CTASection,
} from "@restnfeel/agentc-starter-kit/components";

2. CMS 관리 시스템

import {
  PageEditor,
  ComponentLibrary,
  MediaManager,
  UserManager,
  ContentTypeManager,
} from "@restnfeel/agentc-starter-kit/admin";

3. API 시스템

import {
  createCMSApiRoutes,
  mediaUploadHandler,
  contentValidator,
} from "@restnfeel/agentc-starter-kit/api";

4. RAG 기반 AI 챗봇 시스템

import {
  ChatbotProvider,
  FloatingChatButton,
  ChatDock,
  DocumentUploader,
  KnowledgeEditor,
  RAGManager,
} from "@restnfeel/agentc-starter-kit/chatbot";

📱 컴포넌트 사용법

Hero 섹션 기본 사용

import { HeroSection } from "@restnfeel/agentc-starter-kit";

function HomePage() {
  return (
    <HeroSection
      title="환영합니다"
      subtitle="최고의 서비스를 제공합니다"
      backgroundImage="/hero-bg.jpg"
      ctaButton={{
        text: "시작하기",
        link: "/get-started",
        variant: "primary",
      }}
      features={["빠른 구현", "완전한 커스터마이징", "엔터프라이즈급 보안"]}
    />
  );
}

Features 섹션 사용

import { FeaturesSection } from "@restnfeel/agentc-starter-kit";

function FeaturesPage() {
  const features = [
    {
      icon: "🚀",
      title: "빠른 배포",
      description: "몇 분 안에 사이트를 배포할 수 있습니다",
      link: "/docs/deployment",
    },
    {
      icon: "🔒",
      title: "보안",
      description: "엔터프라이즈급 보안이 기본 제공됩니다",
      link: "/docs/security",
    },
    {
      icon: "📱",
      title: "반응형",
      description: "모든 디바이스에서 완벽하게 작동합니다",
      link: "/docs/responsive",
    },
  ];

  return (
    <FeaturesSection
      title="핵심 기능"
      description="우리 제품의 주요 특징들을 확인해보세요"
      features={features}
      layout="grid" // 'grid' | 'list' | 'cards'
      columns={3}
    />
  );
}

Gallery 섹션 사용

import { GallerySection } from "@restnfeel/agentc-starter-kit";

function PortfolioPage() {
  const images = [
    {
      src: "/portfolio/project1.jpg",
      alt: "프로젝트 1",
      title: "웹 개발",
      description: "현대적인 웹사이트 구축",
    },
    {
      src: "/portfolio/project2.jpg",
      alt: "프로젝트 2",
      title: "모바일 앱",
      description: "크로스 플랫폼 앱 개발",
    },
  ];

  return (
    <GallerySection
      title="포트폴리오"
      images={images}
      layout="masonry" // 'grid' | 'masonry' | 'carousel'
      lightbox={true}
      showThumbnails={true}
    />
  );
}

Contact 폼 섹션 사용

import { ContactSection } from "@restnfeel/agentc-starter-kit";

function ContactPage() {
  return (
    <ContactSection
      title="문의하기"
      description="궁금한 점이 있으시면 언제든 연락주세요"
      fields={[
        { type: "text", name: "name", label: "이름", required: true },
        { type: "email", name: "email", label: "이메일", required: true },
        { type: "tel", name: "phone", label: "전화번호" },
        { type: "textarea", name: "message", label: "메시지", required: true },
      ]}
      onSubmit={(data) => {
        // 커스텀 처리 로직
        console.log("Form submitted:", data);
      }}
      contactInfo={{
        address: "서울시 강남구 테헤란로 123",
        phone: "02-1234-5678",
        email: "contact@company.com",
        hours: "평일 9:00-18:00",
      }}
    />
  );
}

RAG 기반 AI 챗봇 사용

import {
  ChatbotProvider,
  FloatingChatButton,
  DocumentUploader,
  KnowledgeEditor,
  RAGManager,
} from "@restnfeel/agentc-starter-kit";

// 고객 사이트에 AI 챗봇 추가
function CustomerSite() {
  return (
    <ChatbotProvider
      vectorStorePath="/store"
      llmApiKey={process.env.LLM_API_KEY}
      initialQuestions={3}
      supabaseConfig={{
        url: process.env.NEXT_PUBLIC_SUPABASE_URL,
        anonKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY,
        bucket: "documents",
      }}
    >
      <main>
        <HeroSection />
        <FeaturesSection />

        {/* 우측 하단 플로팅 챗봇 버튼 자동 표시 */}
        <FloatingChatButton />
      </main>
    </ChatbotProvider>
  );
}

// 관리자 지식 베이스 관리
function AdminKnowledgeBase() {
  return (
    <div className="admin-knowledge">
      <h2>AI 챗봇 학습 관리</h2>

      {/* 문서 업로드 (Supabase Storage) */}
      <DocumentUploader
        onUpload={(files) => console.log("업로드된 문서:", files)}
        acceptedTypes={["pdf", "doc", "docx", "txt"]}
        storage="supabase"
        bucket="documents"
        maxFileSize="10MB"
      />

      {/* 직접 지식 입력 */}
      <KnowledgeEditor
        onSave={(content) => console.log("저장된 지식:", content)}
        placeholder="사업 아이템에 대해 개조식으로 설명해주세요..."
        autoSave={true}
      />

      {/* RAG 시스템 관리 */}
      <RAGManager
        vectorStore="/store"
        onReindex={() => console.log("벡터 재인덱싱 시작")}
        showMetrics={true}
        showPreview={true}
      />
    </div>
  );
}

⚙️ CMS 관리자 구현

1. 관리자 대시보드

// app/admin/page.tsx
import { AdminDashboard } from "@restnfeel/agentc-starter-kit/admin";

export default function AdminPage() {
  return (
    <AdminDashboard
      user={{
        name: "관리자",
        role: "admin",
        avatar: "/admin-avatar.jpg",
      }}
      stats={{
        pages: 12,
        components: 28,
        media: 156,
        users: 8,
      }}
      quickActions={[
        { label: "새 페이지", action: "create-page", icon: "📄" },
        { label: "컴포넌트 추가", action: "add-component", icon: "🧩" },
        { label: "미디어 업로드", action: "upload-media", icon: "🖼️" },
      ]}
    />
  );
}

2. 페이지 에디터

// app/admin/pages/[id]/edit/page.tsx
import { PageEditor } from "@restnfeel/agentc-starter-kit/admin";

export default function EditPage({ params }: { params: { id: string } }) {
  return (
    <PageEditor
      pageId={params.id}
      onSave={(pageData) => {
        // 페이지 저장 로직
        console.log("Saving page:", pageData);
      }}
      componentLibrary={{
        categories: ["content", "media", "layout", "interactive"],
        search: true,
        dragAndDrop: true,
      }}
      preview={{
        enabled: true,
        responsive: true,
        realtime: true,
      }}
    />
  );
}

3. 컴포넌트 라이브러리 관리

// app/admin/components/page.tsx
import { ComponentLibraryManager } from "@restnfeel/agentc-starter-kit/admin";

export default function ComponentsPage() {
  return (
    <ComponentLibraryManager
      components={[
        {
          type: "hero",
          category: "layout",
          metadata: {
            title: "Hero Section",
            description: "페이지 상단 메인 섹션",
            tags: ["header", "banner", "main"],
            icon: "🎯",
          },
        },
        // ... 더 많은 컴포넌트들
      ]}
      onComponentSelect={(component) => {
        // 컴포넌트 선택 처리
      }}
      filters={{
        category: true,
        search: true,
        tags: true,
      }}
    />
  );
}

🔌 API 사용법

1. API 라우트 설정

// app/api/cms/[...slug]/route.ts
import { createCMSApiRoutes } from "@restnfeel/agentc-starter-kit/api";

const { GET, POST, PUT, DELETE } = createCMSApiRoutes({
  database: {
    type: "postgresql", // 또는 "mysql", "sqlite"
    connection: process.env.DATABASE_URL,
  },
  auth: {
    enabled: true,
    provider: "nextauth", // 또는 "custom"
    roles: ["admin", "editor", "viewer"],
  },
  media: {
    storage: "local", // 또는 "s3", "cloudinary"
    maxSize: "10MB",
    allowedTypes: ["image/*", "video/*", "application/pdf"],
  },
});

export { GET, POST, PUT, DELETE };

2. 미디어 업로드 API

// app/api/upload/route.ts
import { mediaUploadHandler } from "@restnfeel/agentc-starter-kit/api";

export const POST = mediaUploadHandler({
  destination: "uploads/",
  generateThumbnails: true,
  imageOptimization: {
    quality: 80,
    formats: ["webp", "jpeg"],
    sizes: [400, 800, 1200],
  },
  onSuccess: (fileInfo) => {
    console.log("File uploaded:", fileInfo);
  },
});

3. 콘텐츠 검증 API

// app/api/content/validate/route.ts
import { contentValidator } from "@restnfeel/agentc-starter-kit/api";

export const POST = async (request: Request) => {
  const contentData = await request.json();

  const validation = contentValidator(contentData, {
    schema: "page", // 또는 "component", "media"
    strict: true,
    sanitize: true,
  });

  if (!validation.isValid) {
    return new Response(
      JSON.stringify({
        error: "Validation failed",
        details: validation.errors,
      }),
      { status: 400 }
    );
  }

  return new Response(
    JSON.stringify({
      success: true,
      sanitizedData: validation.data,
    })
  );
};

🎨 커스터마이징

1. 테마 시스템

// lib/theme.ts
import { createTheme } from "@restnfeel/agentc-starter-kit/theme";

export const customTheme = createTheme({
  colors: {
    primary: "#3B82F6",
    secondary: "#10B981",
    accent: "#F59E0B",
    background: "#FFFFFF",
    text: "#1F2937",
  },
  fonts: {
    heading: "Pretendard, sans-serif",
    body: "Pretendard, sans-serif",
    mono: "JetBrains Mono, monospace",
  },
  spacing: {
    xs: "0.5rem",
    sm: "1rem",
    md: "1.5rem",
    lg: "2rem",
    xl: "3rem",
  },
  breakpoints: {
    sm: "640px",
    md: "768px",
    lg: "1024px",
    xl: "1280px",
  },
});

// app/layout.tsx에서 적용
import { ThemeProvider } from "@restnfeel/agentc-starter-kit/theme";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ThemeProvider theme={customTheme}>{children}</ThemeProvider>
      </body>
    </html>
  );
}

2. 커스텀 컴포넌트 생성

// components/CustomHero.tsx
import { BaseSection } from "@restnfeel/agentc-starter-kit/base";

interface CustomHeroProps {
  title: string;
  subtitle?: string;
  backgroundVideo?: string;
  particles?: boolean;
}

export function CustomHero({
  title,
  subtitle,
  backgroundVideo,
  particles = false,
}: CustomHeroProps) {
  return (
    <BaseSection
      className="min-h-screen flex items-center justify-center relative"
      background={backgroundVideo ? "video" : "gradient"}
    >
      {backgroundVideo && (
        <video
          autoPlay
          muted
          loop
          className="absolute inset-0 w-full h-full object-cover"
        >
          <source src={backgroundVideo} type="video/mp4" />
        </video>
      )}

      {particles && <ParticleBackground />}

      <div className="relative z-10 text-center text-white">
        <h1 className="text-6xl font-bold mb-4">{title}</h1>
        {subtitle && <p className="text-xl opacity-90">{subtitle}</p>}
      </div>
    </BaseSection>
  );
}

3. 스타일 오버라이드

/* styles/custom.css */
@import "@restnfeel/agentc-starter-kit/styles.css";

/* 커스텀 스타일 */
.agentc-hero {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

.agentc-button-primary {
  background: linear-gradient(45deg, #ff6b6b, #ff8e8e);
  box-shadow: 0 4px 15px rgba(255, 107, 107, 0.3);
}

.agentc-card {
  backdrop-filter: blur(10px);
  background: rgba(255, 255, 255, 0.1);
  border: 1px solid rgba(255, 255, 255, 0.2);
}

🤖 RAG 기반 AI 챗봇 시스템

AgentC Starter Kit에는 LangChain JS 기반의 강력한 RAG (Retrieval-Augmented Generation) 챗봇 시스템이 포함되어 있습니다.

주요 특징

지능형 문서 학습: PDF, DOC, TXT 파일을 업로드하여 자동 학습
개조식 지식 입력: 관리자가 직접 사업 정보를 입력 가능
벡터 검색: 학습된 내용에서 유사도 기반 답변 생성
Supabase 통합: 문서는 Supabase Storage에 안전하게 저장
즉시 사용: 간단한 컴포넌트 추가로 챗봇 완성

빠른 설정

// 1. ChatbotProvider로 앱 감싸기
<ChatbotProvider
  vectorStorePath="/store"
  llmApiKey={process.env.LLM_API_KEY}
  supabaseConfig={{
    url: process.env.NEXT_PUBLIC_SUPABASE_URL,
    anonKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY,
    bucket: "documents"
  }}
>
  <YourApp />
</ChatbotProvider>

// 2. 플로팅 챗봇 버튼 추가
<FloatingChatButton />

관리자 지식 베이스 구축

// 문서 업로드
<DocumentUploader
  storage="supabase"
  bucket="documents"
  acceptedTypes={['pdf', 'doc', 'txt']}
  onUpload={(files) => console.log('학습 시작:', files)}
/>

// 직접 지식 입력
<KnowledgeEditor
  placeholder="회사 소개, 제품 정보 등을 입력하세요..."
  onSave={(content) => console.log('지식 저장:', content)}
/>

// 학습 상태 관리
<RAGManager
  vectorStore="/store"
  showMetrics={true}
  onReindex={() => console.log('재학습 시작')}
/>

고객 경험

플로팅 버튼: 우측 하단에 채팅 아이콘 표시
클릭 시 채팅창: 깔끔한 채팅 인터페이스 노출
추천 질문: 학습된 내용 기반 3가지 질문 자동 제시
지능형 답변: 업로드된 문서와 입력된 지식에서만 답변

이 시스템을 통해 고객은 24시간 언제든지 정확한 정보를 얻을 수 있고, 관리자는 간편하게 지식 베이스를 관리할 수 있습니다.

🔧 고급 기능

1. 워크플로우 시스템

// lib/workflow.ts
import { createWorkflow } from "@restnfeel/agentc-starter-kit/workflow";

export const contentWorkflow = createWorkflow({
  stages: [
    { name: "draft", label: "초안", color: "gray" },
    { name: "review", label: "검토 중", color: "yellow" },
    { name: "approved", label: "승인됨", color: "green" },
    { name: "published", label: "게시됨", color: "blue" },
  ],
  transitions: [
    { from: "draft", to: "review", role: "editor" },
    { from: "review", to: "approved", role: "admin" },
    { from: "approved", to: "published", role: "admin" },
  ],
  notifications: {
    email: true,
    slack: process.env.SLACK_WEBHOOK_URL,
  },
});

2. 다국어 지원

// lib/i18n.ts
import { createI18n } from "@restnfeel/agentc-starter-kit/i18n";

export const i18n = createI18n({
  defaultLocale: "ko",
  locales: ["ko", "en", "ja"],
  fallbackLocale: "en",
  loadPath: "/locales/{{lng}}/{{ns}}.json",
  detection: {
    order: ["path", "cookie", "header"],
    caches: ["cookie"],
  },
});

// 사용법
import { useTranslation } from "@restnfeel/agentc-starter-kit/i18n";

function MyComponent() {
  const { t } = useTranslation("common");

  return (
    <div>
      <h1>{t("welcome")}</h1>
      <p>{t("description")}</p>
    </div>
  );
}

3. SEO 최적화

// lib/seo.ts
import { createSEOManager } from "@restnfeel/agentc-starter-kit/seo";

export const seoManager = createSEOManager({
  defaultMeta: {
    title: "사이트 제목",
    description: "사이트 설명",
    keywords: ["키워드1", "키워드2"],
    openGraph: {
      siteName: "사이트명",
      type: "website",
      image: "/og-image.jpg",
    },
  },
  autoGenerate: {
    sitemap: true,
    robots: true,
    schema: true,
  },
});

// 페이지별 SEO 설정
import { SEOHead } from "@restnfeel/agentc-starter-kit/seo";

export default function Page() {
  return (
    <>
      <SEOHead
        title="페이지 제목"
        description="페이지 설명"
        canonical="https://example.com/page"
        schema={{
          "@type": "Article",
          headline: "페이지 제목",
          author: "작성자명",
        }}
      />
      <main>{/* 페이지 내용 */}</main>
    </>
  );
}

4. 성능 모니터링

// lib/analytics.ts
import { createAnalytics } from "@restnfeel/agentc-starter-kit/analytics";

export const analytics = createAnalytics({
  providers: {
    googleAnalytics: process.env.GA_TRACKING_ID,
    mixpanel: process.env.MIXPANEL_TOKEN,
    custom: {
      endpoint: "/api/analytics",
      events: ["pageview", "click", "form_submit"],
    },
  },
  privacy: {
    cookieConsent: true,
    anonymizeIP: true,
    respectDNT: true,
  },
});

🎯 Task Master 워크플로우

이 모듈은 Task Master AI 시스템과 함께 사용하도록 최적화되어 있습니다. AI가 체계적으로 고객 사이트를 구현할 수 있습니다.

Task Master 초기 설정

# 1. Task Master 초기화
npm install -g task-master-ai
task-master init --name="Customer Website" --description="고객사 웹사이트 구현"

# 2. AI 모델 설정 (권장)
task-master models --setup
# 또는 빠른 설정
task-master models --set-main="anthropic/claude-3-5-sonnet-20241022" --set-research="anthropic/claude-3-5-sonnet-20241022"

PRD 기반 프로젝트 생성

PRD 작성 (scripts/prd.txt):

# 고객사 웹사이트 프로젝트

## 프로젝트 개요
- 회사명: [고객사명]
- 사이트 유형: [비즈니스/이커머스/포트폴리오/블로그]
- 주요 기능: [필요한 기능들]
- 백엔드: Supabase (PostgreSQL, Auth, Storage)

## 기술 스택
- Frontend: Next.js 14 + TypeScript + Tailwind CSS
- Backend: Supabase (BaaS)
- Database: PostgreSQL (Supabase)
- Auth: Supabase Auth + NextAuth.js
- File Storage: Supabase Storage
- State Management: Zustand
- UI Components: @restnfeel/agentc-starter-kit

## 필수 페이지
- 홈페이지 (Hero, About, Features, Contact)
- 제품/서비스 소개
- 고객 후기
- 연락처/문의하기
- 관리자 시스템 (CMS)

## Supabase 설정 요구사항
- 사용자 인증 (이메일/비밀번호, 소셜 로그인)
- 콘텐츠 관리 (페이지, 미디어)
- 파일 업로드 및 저장
- 실시간 업데이트 (선택사항)

태스크 자동 생성:

task-master parse-prd scripts/prd.txt --num-tasks=15 --research

표준 워크플로우

# 1. 다음 작업 확인
task-master next

# 2. 복잡한 태스크 세분화 (예: Supabase 설정)
task-master expand --id=1 --research --force
# 생성 예시:
# 1.1 Supabase 프로젝트 생성 및 설정
# 1.2 환경 변수 구성
# 1.3 Prisma 스키마 생성
# 1.4 데이터베이스 마이그레이션
# 1.5 Supabase Auth 설정

# 3. 태스크 상태 업데이트
task-master set-status --id=1.1 --status=done

# 4. 진행률 확인
task-master list --status=pending

# 5. 구현 노트 추가
task-master update-subtask --id=1.2 --prompt="Supabase URL과 키 설정 완료"

# 6. 다음 단계로 진행
task-master next

AI 개발자를 위한 Task Master 활용법

프로젝트 시작: PRD를 분석하여 체계적인 태스크 생성
우선순위 관리: 의존성과 우선순위에 따른 작업 순서 결정
복잡도 분석: AI가 각 태스크의 난이도를 분석하여 적절한 분해
진행 상황 추적: 실시간으로 프로젝트 진행률 모니터링
변경사항 관리: 고객 요구사항 변경 시 관련 태스크 자동 업데이트

자세한 Task Master 가이드는 Task Master 워크플로우 가이드를 참조하세요.

🚀 배포 및 운영

1. 환경 변수 설정

# .env.local
DATABASE_URL="postgresql://user:password@localhost:5432/cms"
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-secret-key"

# Supabase (기본 BaaS)
SUPABASE_URL="https://your-project.supabase.co"
SUPABASE_ANON_KEY="your-supabase-anon-key"

# RAG 챗봇 AI API
LLM_API_KEY="your-openai-or-anthropic-api-key"

# 미디어 저장소 (선택사항 - Supabase Storage 사용 시 불필요)
CLOUDINARY_CLOUD_NAME="your-cloud-name"
CLOUDINARY_API_KEY="your-api-key"
CLOUDINARY_API_SECRET="your-api-secret"

# 이메일 서비스
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USER="your-email@gmail.com"
SMTP_PASSWORD="your-app-password"

# 분석
GOOGLE_ANALYTICS_ID="GA_TRACKING_ID"

2. 빌드 및 배포

# 프로덕션 빌드
npm run build

# Vercel 배포
npx vercel

# Docker 배포
docker build -t my-cms .
docker run -p 3000:3000 my-cms

3. 성능 최적화

// next.config.js
module.exports = {
  experimental: {
    appDir: true,
  },
  images: {
    domains: ["res.cloudinary.com"],
    formats: ["image/webp", "image/avif"],
  },
  compress: true,
  poweredByHeader: false,
};