어떤 자료인가

`code-geek/ai-project-template`은 Django 백엔드와 Next.js 프런트엔드를 함께 시작할 수 있는 풀스택 프로젝트 템플릿입니다.

처음부터 로그인, API, 화면, Docker, CI/CD, 테스트 구조를 모두 직접 잡으려면 시간이 많이 걸립니다. 이 자료는 AI 코딩 어시스턴트와 함께 개발할 때 필요한 문서 구조와 Claude Code용 설정까지 포함해, 새 서비스를 빠르게 시작하려는 상황에 잘 맞습니다.

왜 좋은가 / 왜 유명한가

- Django 5.1, Django Ninja, Next.js 15, TypeScript 기반으로 백엔드와 프런트엔드를 한 저장소에서 시작할 수 있습니다.

- Docker, Docker Compose, GitHub Actions 기반 CI/CD 워크플로, 배포 스크립트가 포함된 production-ready 구성을 지향합니다.

- Claude Code agents와 `CLAUDE.md` 파일이 포함되어 있어 AI 보조 개발을 전제로 한 프로젝트 구조를 제공합니다.

- 테스트 도구가 기본 구성되어 있습니다. 백엔드는 Pytest, E2E는 Playwright를 사용하며 예시 테스트도 포함된 것으로 안내되어 있습니다.

- 코드 품질 도구가 함께 들어 있습니다. pre-commit hooks, Ruff linting, mypy type checking 구성이 포함됩니다.

- Python 패키지 관리는 `uv`를 사용하도록 구성되어 있어 빠른 패키지 관리 흐름을 전제로 합니다.

- GitHub의 “Use this template” 기능 또는 GitHub CLI로 바로 새 프로젝트를 만들 수 있어, 템플릿으로 재사용하기 편합니다.

무엇을 할 수 있나 / 무엇이 들어있나

백엔드 구성은 다음과 같습니다.

- Python 3.12

- Django 5.1

- Django Ninja

- PostgreSQL 16

- 개발용 SQLite

- Redis

- 선택 사항으로 Celery task queue

프런트엔드 구성도 바로 사용할 수 있게 잡혀 있습니다.

- Next.js 15 App Router

- React 19

- TypeScript 5.x

- Tailwind CSS

- shadcn/ui

- Zustand 또는 React Context 기반 상태 관리

인프라와 개발 편의 기능도 포함됩니다.

- Docker

- Docker Compose

- GitHub Actions 기반 CI/CD

- AWS ECS/EC2 또는 Vercel 배포 방향의 구성

- 선택 사항으로 Sentry 모니터링

- pre-commit hooks

- Ruff

- mypy

- Pytest

- Playwright

AI 보조 개발용 구성도 이 템플릿의 핵심입니다.

- `.claude/agents/` 디렉터리에 Claude Code용 specialized agents 포함

- `CLAUDE.md` 파일 포함

- 프로젝트 요구사항에 맞게 `CLAUDE.md`를 수정하도록 안내

- README에서 확인되는 agent 예시: `code-reviewer`

설치와 사용법

새 저장소를 만드는 방법은 두 가지입니다. GitHub CLI를 쓰는 경우 공식 README에 제시된 명령은 아래와 같습니다.

# Using GitHub CLI
gh repo create my-project --template code-geek/ai-project-template --public

GitHub 웹에서 진행하려면 저장소 페이지의 “Use this template” 버튼을 사용하면 됩니다.

새로 만든 저장소를 로컬에 받은 뒤 개발 환경을 설정합니다. 아래 명령은 공식 README의 Quick Start에 나온 흐름입니다.

git clone https://github.com/YOUR_USERNAME/my-project
cd my-project

# Run the setup script
./scripts/setup-dev.sh

개발 서버 실행은 Docker 방식이 권장되어 있습니다.

# Using Docker (recommended)
docker-compose up

백엔드와 프런트엔드를 따로 실행할 수도 있습니다.

# Or run separately
cd backend && uv run python manage.py runserver
cd frontend && npm run dev

프로젝트를 자기 서비스에 맞게 바꿀 때는 README의 Customization Guide 흐름을 따라가면 됩니다.

먼저 프로젝트 정보를 교체합니다.

- 전체 프로젝트에서 `Project Name`을 실제 프로젝트명으로 변경

- `package.json` 수정

- `pyproject.toml` 수정

- 프로젝트 요구사항에 맞게 `CLAUDE.md` 파일 수정

환경 설정도 초기 단계에서 바로 확인해야 합니다.

- `.env.example` 파일을 복사해 실제 설정값으로 수정

- Django settings의 `ALLOWED_HOSTS` 수정

- Django settings의 `CORS_ALLOWED_ORIGINS` 수정

- 프런트엔드 `.env.local`에 `NEXT_PUBLIC_API_URL` 설정

공식 README에 명령 형태로 제시된 `.env` 복사 명령은 따로 확인되지 않습니다. 파일명과 설정 항목은 위처럼 안내되어 있으므로, 실제 파일 위치와 값은 저장소를 받은 뒤 내부 파일을 기준으로 맞추면 됩니다.

실제 사용 예시는 다음처럼 잡을 수 있습니다.

첫 번째 예시는 AI 보조 개발용 SaaS MVP입니다. 이 템플릿으로 저장소를 만든 뒤, Django Ninja 쪽에 API를 추가하고 Next.js App Router에서 화면을 붙입니다. 이후 `CLAUDE.md`에 도메인 규칙, API 설계 원칙, 코딩 스타일을 적어두면 Claude Code가 프로젝트 맥락을 더 잘 따라가게 구성할 수 있습니다.

두 번째 예시는 사내 관리자 도구입니다. Docker Compose로 로컬 개발 환경을 맞추고, Django 백엔드에서 데이터 모델과 API를 만든 뒤, Next.js와 shadcn/ui 기반 화면을 추가하는 방식입니다. CI/CD는 `.github/workflows/`를 배포 대상에 맞춰 수정하도록 README에서 안내합니다.

주의할 점

- 템플릿은 시작점입니다. `Project Name`, `package.json`, `pyproject.toml`, `CLAUDE.md`, 환경 변수, CORS, 호스트 설정을 그대로 두면 실제 서비스에 맞지 않습니다.

- Celery, Sentry, 배포 대상 같은 일부 구성은 선택 사항입니다. 필요하지 않은 Celery는 `docker-compose.yml`에서 celery services를 삭제하라고 README에서 안내합니다.

- 인증은 “JWT included”라고 안내되어 있지만, 실제 서비스에 맞는 인증 방식 구현은 별도 작업이 필요합니다. 운영 배포 전에는 비밀키, CORS, 허용 호스트, GitHub repository secrets 설정을 반드시 점검해야 합니다.

출처와 다운로드

공식 저장소: https://github.com/code-geek/ai-project-template

GitHub에서 직접 “Use this template”으로 새 프로젝트를 만들거나, GitHub CLI 명령으로 템플릿 기반 저장소를 생성할 수 있습니다. 하단 첨부파일에서도 자료를 받을 수 있습니다.