@restnfeel/agentc-starter-kit
Version:
한국어 기업용 CMS 모듈 - Task Master AI와 함께 빠르게 웹사이트를 구현할 수 있는 재사용 가능한 컴포넌트 시스템
617 lines (469 loc) • 15 kB
Markdown
# 🤖 AI 빠른 구현 가이드
**AgentC CMS를 사용한 웹사이트 구현을 위한 AI 전용 레퍼런스**
## 🚀 1분 시작 가이드
### 1️⃣ 기본 설정 (모든 프로젝트 필수)
```bash
npm install @restnfeel/agentc-starter-kit
```
```typescript
// app/layout.tsx
import "@restnfeel/agentc-starter-kit/styles.css";
export default function RootLayout({ children }) {
return (
<html>
<body>{children}</body>
</html>
);
}
```
### 2️⃣ 즉시 사용 가능한 페이지 구조
```typescript
// app/page.tsx
import {
HeroSection,
AboutSection,
ContactSection,
} from "@restnfeel/agentc-starter-kit";
export default function HomePage() {
return (
<main>
<HeroSection title="제목" description="설명" />
<AboutSection title="소개" description="내용" />
<ContactSection
title="연락처"
fields={
[
/* 폼 필드 */
]
}
/>
</main>
);
}
```
### Task Master 워크플로우 (권장)
```bash
# 1. Task Master 초기화 (필수)
task-master init --name="Customer Site" --yes
# 2. AI 모델 설정 (필수)
task-master models --set-main="anthropic/claude-3-5-sonnet-20241022" --set-research="anthropic/claude-3-5-sonnet-20241022"
# 3. PRD 작성 및 태스크 생성
echo "# 고객사 웹사이트
## 요구사항
- 홈페이지 (Hero, About, Features, Contact)
- 반응형 디자인
- Next.js + TypeScript + Tailwind
- Supabase (PostgreSQL, Auth, Storage)
- CMS 관리자 시스템
- 파일 업로드 기능
- 사용자 인증" > scripts/prd.txt
task-master parse-prd scripts/prd.txt --num-tasks=10 --research
# 4. 워크플로우 시작
task-master next # 다음 작업 확인
task-master expand --id=1 --research --force # 첫 번째 태스크 세분화
```
## 📋 컴포넌트 빠른 참조
| 컴포넌트 | 용도 | 필수 Props |
| -------------------- | -------------------- | ------------------------------- |
| `HeroSection` | 메인 상단 섹션 | `title` |
| `AboutSection` | 회사/서비스 소개 | `title`, `description` |
| `FeaturesSection` | 기능/서비스 나열 | `title`, `features[]` |
| `TestimonialSection` | 고객 후기 | `title`, `testimonials[]` |
| `ContactSection` | 연락처/문의 폼 | `title`, `fields[]`, `onSubmit` |
| `GallerySection` | 이미지/비디오 갤러리 | `images[]` |
| `PricingSection` | 가격표 | `title`, `plans[]` |
| `Footer` | 푸터 | `company`, `links[]` |
## 🎯 사이트 유형별 구현 패턴
### 🏢 비즈니스/기업 사이트
```typescript
<HeroSection title="비즈니스 솔루션" ctaButton={{text: "상담 신청", link: "/contact"}} />
<AboutSection title="회사 소개" stats={[{label: "고객수", value: "500+"}]} />
<FeaturesSection title="서비스" features={[{title: "웹개발", description: "..."}]} />
<TestimonialSection title="고객 후기" testimonials={[{content: "...", author: "김고객"}]} />
<ContactSection title="문의" fields={[{type: "text", name: "name", label: "이름"}]} />
```
### 🛒 쇼핑몰/이커머스
```typescript
import { ProductGrid, ShoppingCart } from "@restnfeel/agentc-starter-kit/ecommerce";
<ProductGrid products={[{id: "1", name: "상품명", price: 10000}]} />
<ShoppingCart items={[{id: "1", name: "상품", quantity: 2}]} />
```
### 🎨 포트폴리오
```typescript
import { PortfolioGrid, SkillsSection } from "@restnfeel/agentc-starter-kit/portfolio";
<SkillsSection skills={[{name: "React", level: 95}]} />
<PortfolioGrid projects={[{title: "프로젝트", image: "/img.jpg"}]} />
```
### 📝 블로그
```typescript
import { BlogGrid, BlogSidebar } from "@restnfeel/agentc-starter-kit/blog";
<BlogGrid posts={[{title: "제목", content: "내용", author: {name: "작성자"}}]} />
<BlogSidebar categories={[{name: "카테고리", count: 10}]} />
```
## ⚙️ 관리자 시스템 구현
### 📊 관리자 대시보드
```typescript
// app/admin/page.tsx
import { AdminDashboard } from "@restnfeel/agentc-starter-kit";
export default function AdminPage() {
return (
<AdminDashboard
stats={{ pages: 10, users: 5, media: 50 }}
user={{ name: "관리자", role: "admin" }}
/>
);
}
```
### 📝 페이지 편집기
```typescript
// app/admin/pages/[id]/edit/page.tsx
import { PageEditor } from "@restnfeel/agentc-starter-kit";
export default function EditPage({ params }) {
return (
<PageEditor
pageId={params.id}
onSave={async (data) => {
/* 저장 로직 */
}}
componentLibrary={{ categories: ["Layout", "Content"], search: true }}
/>
);
}
```
### 🖼️ 미디어 관리
```typescript
import { MediaManager } from "@restnfeel/agentc-starter-kit";
<MediaManager onSelect={(files) => console.log(files)} multiSelect={true} />;
```
## 🔧 API 라우트 패턴
### 기본 API 라우트
```typescript
// app/api/contact/route.ts
import { NextRequest, NextResponse } from "next/server";
export async function POST(request: NextRequest) {
const data = await request.json();
// 처리 로직
return NextResponse.json({ success: true });
}
```
### CMS API 라우트
```typescript
// app/api/cms/[...path]/route.ts
import { createCMSApiRoutes } from "@restnfeel/agentc-starter-kit";
const { GET, POST, PUT, DELETE } = createCMSApiRoutes({
database: { type: "postgresql", connection: process.env.DATABASE_URL },
auth: { enabled: true, provider: "nextauth" },
});
export { GET, POST, PUT, DELETE };
```
## 🎨 테마 & 스타일링
### 커스텀 테마
```typescript
// lib/theme.ts
import { createTheme } from "@restnfeel/agentc-starter-kit";
export const theme = createTheme({
colors: { primary: "#3B82F6", secondary: "#64748B" },
fonts: { heading: "Pretendard", body: "Pretendard" },
});
// app/layout.tsx
import { ThemeProvider } from "@restnfeel/agentc-starter-kit";
<ThemeProvider theme={theme}>{children}</ThemeProvider>;
```
### 글로벌 CSS
```css
/* app/globals.css */
@import "@restnfeel/agentc-starter-kit/styles.css";
:root {
--brand-color: #3b82f6;
}
```
## 🌐 다국어 지원
### i18n 설정
```typescript
// lib/i18n.ts
import { createI18n } from "@restnfeel/agentc-starter-kit";
export const i18n = createI18n({
defaultLocale: "ko",
locales: ["ko", "en"],
loadPath: "/locales/{{lng}}/{{ns}}.json",
});
```
### 번역 파일 구조
```
public/locales/
├── ko/common.json # {"nav": {"home": "홈"}}
└── en/common.json # {"nav": {"home": "Home"}}
```
### 다국어 페이지
```typescript
// app/[locale]/page.tsx
import { useTranslation } from "@restnfeel/agentc-starter-kit/i18n";
export default function Page({ params: { locale } }) {
const { t } = useTranslation(locale, "common");
return <HeroSection title={t("hero.title")} />;
}
```
## 📱 반응형 & 최적화
### 반응형 설정
모든 컴포넌트는 기본적으로 반응형 지원
```typescript
<FeaturesSection
columns={3} // 데스크톱: 3열
layout="grid" // 자동으로 모바일에서는 1열
responsive={true} // 반응형 활성화 (기본값)
/>
```
### SEO 최적화
```typescript
// app/layout.tsx
export const metadata = {
title: "사이트 제목",
description: "사이트 설명",
keywords: ["키워드1", "키워드2"],
};
// 개별 페이지
export const metadata = {
title: "페이지 제목",
openGraph: { title: "OG 제목", image: "/og-image.jpg" },
};
```
## 🔐 인증 & 권한
### NextAuth 설정
```typescript
// app/api/auth/[...nextauth]/route.ts
import { createAuthHandler } from "@restnfeel/agentc-starter-kit/auth";
const handler = createAuthHandler({
providers: ["google", "github"],
roles: ["user", "admin", "editor"],
});
export { handler as GET, handler as POST };
```
### 권한 체크
```typescript
import { useSession, requireAuth } from "@restnfeel/agentc-starter-kit/auth";
export default requireAuth(
function AdminPage() {
const { user } = useSession();
return <div>관리자 페이지 - {user.name}</div>;
},
{ roles: ["admin"] }
);
```
## 📊 분석 & 성능
### 분석 도구 설정
```typescript
// lib/analytics.ts
import { createAnalytics } from "@restnfeel/agentc-starter-kit";
export const analytics = createAnalytics({
providers: { googleAnalytics: "GA_ID" },
events: { pageview: true, clicks: true },
});
```
### 성능 모니터링
```typescript
import { performanceMonitor } from "@restnfeel/agentc-starter-kit";
performanceMonitor.track("page_load", { page: "/home" });
```
## 🛠️ 배포 & 환경설정
### 환경 변수
```bash
# .env.local
DATABASE_URL="postgresql://postgres:[PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres"
SUPABASE_URL="https://[PROJECT-REF].supabase.co"
SUPABASE_ANON_KEY="your-anon-key"
NEXTAUTH_SECRET="your-secret"
```
### Vercel 배포
```json
// vercel.json
{
"buildCommand": "npm run build",
"outputDirectory": ".next",
"installCommand": "npm install"
}
```
### Docker 배포
```dockerfile
# Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
CMD ["npm", "start"]
```
## 🚨 자주 발생하는 문제 해결
### 1. 컴포넌트 import 오류
```typescript
// ❌ 잘못된 방법
import { HeroSection } from "@restnfeel/agentc-starter-kit/components";
// ✅ 올바른 방법
import { HeroSection } from "@restnfeel/agentc-starter-kit";
```
### 2. 스타일이 적용되지 않는 경우
```typescript
// layout.tsx에서 CSS import 확인
import "@restnfeel/agentc-starter-kit/styles.css";
```
### 3. TypeScript 타입 오류
```typescript
// 타입을 명시적으로 import
import type { HeroSectionProps } from "@restnfeel/agentc-starter-kit";
```
### 4. 빌드 오류 해결
```bash
# 캐시 삭제 후 재빌드
rm -rf .next node_modules
npm install
npm run build
```
## 📚 추가 리소스
### 공식 문서
- API Reference: `docs/api-reference.md`
- 구현 예제: `docs/examples.md`
- GitHub: `https://github.com/restnfeel/agentc-starter-kit`
### 커뮤니티
- Discord: `discord.gg/agentc`
- Stack Overflow: `[agentc-cms]` 태그
## 🎯 Task Master 활용 가이드
### 핵심 명령어
```bash
# 프로젝트 상태 확인
task-master list # 전체 태스크 목록
task-master next # 다음 작업할 태스크
task-master show <id> # 특정 태스크 상세 정보
# 태스크 관리
task-master add-task --prompt="새 기능 구현" --research
task-master set-status --id=1 --status=done
task-master update-subtask --id=1.2 --prompt="구현 진행 상황"
# 복잡도 분석 및 분해
task-master analyze-complexity --research --threshold=6
task-master expand --id=1 --research --force
task-master expand --all --research --num=5
# 변경사항 반영
task-master update --from=5 --prompt="요구사항 변경사항" --research
task-master update-task --id=3 --prompt="특정 태스크 수정" --research
```
### PRD 템플릿
```text
# [프로젝트명] 웹사이트
## 프로젝트 개요
- 회사: [회사명]
- 유형: [비즈니스/이커머스/포트폴리오/블로그]
- 목표: [주요 목표]
## 페이지 구성
### 홈페이지
- Hero Section (제목, 부제목, CTA)
- About Section (회사 소개)
- Features/Services Section (주요 서비스)
- Testimonials (고객 후기)
- Contact Section (연락처)
### 추가 페이지
- [필요한 페이지들 나열]
## 기술 스택
- AgentC Starter Kit
- Next.js 14 + TypeScript
- Tailwind CSS
- 반응형 디자인
## 특별 요구사항
- [고객별 특수 요구사항]
- [브랜딩 가이드라인]
- [성능 요구사항]
```
### 워크플로우 패턴
#### 1. 프로젝트 초기화 패턴
```bash
# 새 프로젝트 시작
task-master init --name="[프로젝트명]" --yes
task-master models --set-main="anthropic/claude-3-5-sonnet-20241022"
# PRD 생성 및 파싱
[PRD 작성]
task-master parse-prd scripts/prd.txt --num-tasks=12 --research
# 복잡도 분석
task-master analyze-complexity --research --threshold=6
task-master complexity-report
```
#### 2. 개발 사이클 패턴
```bash
# 작업 시작
task-master next # 다음 태스크 확인
task-master show <id> # 태스크 상세 정보
task-master expand --id=<id> --research # 복잡한 태스크 분해
# 개발 진행
task-master set-status --id=<id> --status=in-progress
[구현 작업]
task-master update-subtask --id=<id> --prompt="구현 진행상황"
# 완료 처리
task-master set-status --id=<id> --status=done
```
#### 3. 변경 관리 패턴
```bash
# 새 요구사항 추가
task-master add-task --prompt="[새 요구사항]" --research --priority=high
# 기존 태스크 업데이트
task-master update --from=<id> --prompt="[변경사항]" --research
task-master update-task --id=<id> --prompt="[특정 변경사항]" --research
# 의존성 관리
task-master add-dependency --id=<target> --depends-on=<prerequisite>
task-master validate-dependencies
```
### Task Master 베스트 프랙티스
1. **항상 research 모드 사용**: `--research` 플래그로 더 정확한 분석
2. **적절한 태스크 수**: 10-15개 메인 태스크가 적절
3. **복잡도 임계값**: `--threshold=6` 이상에서 태스크 분해
4. **정기적인 상태 업데이트**: 구현 중 `update-subtask`로 진행사항 기록
5. **의존성 관리**: 태스크 순서가 중요한 경우 의존성 설정
## 💡 AI를 위한 구현 체크리스트
### ✅ 기본 사이트 구현
- [ ] `npm install @restnfeel/agentc-starter-kit`
- [ ] layout.tsx에 CSS import
- [ ] 홈페이지에 기본 섹션들 추가
- [ ] 연락처 폼 API 라우트 생성
- [ ] 반응형 확인 (모바일/태블릿/데스크톱)
### ✅ 관리자 시스템 (선택)
- [ ] `/admin` 디렉토리 생성
- [ ] AdminDashboard 컴포넌트 추가
- [ ] PageEditor 페이지 생성
- [ ] 인증 시스템 설정
- [ ] 권한 관리 구현
### ✅ 고급 기능 (필요시)
- [ ] 다국어 지원 추가
- [ ] 커스텀 테마 적용
- [ ] SEO 최적화
- [ ] 분석 도구 연동
- [ ] 성능 최적화
**🎯 이 가이드로 AI가 30분 내에 완전한 CMS 웹사이트를 구현할 수 있습니다!**
### 기본 Next.js 설정
```bash
# 새 Next.js 프로젝트 생성
npx create-next-app@latest customer-site --typescript --tailwind --app
cd customer-site
# AgentC 모듈 설치
npm install @restnfeel/agentc-starter-kit
npm install @supabase/supabase-js prisma @prisma/client
```
### Prisma 설정
```bash
# Supabase 스키마 동기화
npx prisma db pull
npx prisma generate
# 또는 기본 스키마 적용
npx prisma db push
```