Claude Code와 bkit으로 AX AgentWorks 랜딩페이지를 만들어본 실습 사례

# Claude Code와 bkit으로 AX AgentWorks 랜딩페이지를 만들어본 실습 사례

## 소개

이번 실습에서는 **Claude Code**와 **bkit 플러그인**을 활용해  
AI 기반 에이전트 자동화 솔루션인 **AX AgentWorks 랜딩페이지**를 개발해보았습니다.

단순히 페이지를 만드는 것에서 끝내지 않고,  
**PDCA 방식(Plan-Do-Check-Act)** 으로 개발 과정을 나누어 진행했습니다.

처음 목표는 다음과 같았습니다.

- AI 기반 자동화 솔루션을 소개하는 전문적인 랜딩페이지 만들기
- Next.js와 Tailwind CSS를 활용한 현대적인 UI 구현하기
- Claude Code와 bkit을 사용해 개발 흐름을 구조화하기
- 개발 중 발생한 에러를 해결하며 실습 경험 쌓기

처음에는 결과물이 다소 투박했지만, 사용자 피드백을 반영하면서  
최종적으로 한국어 기반의 세련된 랜딩페이지로 개선할 수 있었습니다.

## 진행 방법

### 1. 개발 환경 확인

먼저 Claude Code 버전을 확인했습니다.

```bash
claude --version

확인 결과 Claude Code 버전은 2.1.168이었고,
bkit 사용 요구사항을 충족하는 상태였습니다.

2. bkit 플러그인 설치

AI 네이티브 개발 흐름을 적용하기 위해 bkit 플러그인을 설치했습니다.

/plugin marketplace add popup-studio-ai/bkit-claude-code
/plugin install bkit@bkit-marketplace
/reload-plugins

설치 후 바로 /pdca, /sprint 등의 명령어가 보이지 않는 문제가 있었습니다.

원인은 플러그인 설치 후 명령어 목록이 자동으로 갱신되지 않았기 때문이었고,
/reload-plugins 명령어를 실행하자 정상적으로 사용할 수 있었습니다.

이후 다음과 같은 기능들을 확인했습니다.

/pdca : PDCA 사이클 관리
/sprint : 스프린트 관리
/code-review : 코드 리뷰
/qa-phase : QA 테스트

3. PDCA 방식으로 개발 진행

이번 실습에서는 개발 과정을 다음과 같이 나누었습니다.

Plan: 계획

먼저 프로젝트 목표와 구조를 정했습니다.

프로젝트명: AX AgentWorks
목적: AI 자동화 솔루션 랜딩페이지 구축
대상: 기업 고객 및 개발자
기술 스택: Next.js, React, Tailwind CSS
구조: Atomic Design + Clean Architecture 방식 참고

Do: 실행

Next.js 프로젝트 구조를 만들고 필요한 패키지를 설치했습니다.

mkdir -p AX-AgentWorks/src/app/components/{atoms,molecules,organisms}
npm init -y
npm install next react react-dom tailwindcss postcss autoprefixer -E

프로젝트 구조는 다음과 같이 구성했습니다.

AX-AgentWorks/
├── src/app/
│   ├── components/
│   ├── globals.css
│   ├── layout.js
│   └── page.js
├── package.json
├── tailwind.config.js
├── postcss.config.js
└── next.config.js

이후 랜딩페이지를 다음 컴포넌트로 나누어 개발했습니다.

Header: 네비게이션 바
Hero: 메인 소개 영역
Features: 주요 기능 소개
CTA: 행동 유도 영역
Footer: 하단 링크 영역

4. 주요 컴포넌트 구현

Header

Header에서는 로고, 메뉴, CTA 버튼, 모바일 햄버거 메뉴를 구현했습니다.

'use client'

import { useState } from 'react'

export default function Header() {
  const [isOpen, setIsOpen] = useState(false)

  return (
    <header className="fixed top-0 w-full bg-white shadow-sm z-50">
      {/* 네비게이션 영역 */}
    </header>
  )
}

모바일 메뉴는 useState로 열림/닫힘 상태를 관리했습니다.

Hero

Hero 섹션에서는 랜딩페이지의 핵심 메시지를 전달했습니다.

AI 기반 자동화 솔루션이라는 뱃지
“업무 효율을 극대화하세요”라는 메인 카피
무료 체험 / 데모 보기 CTA 버튼
우측 일러스트레이션 및 통계 카드

Features

Features 섹션에서는 6가지 주요 기능을 카드 형태로 보여주었습니다.

10배 빠른 업무 처리
엔터프라이즈급 보안
스마트 학습 AI
글로벌 확장 가능
실시간 분석
쉬운 연동

카드는 배열 데이터를 map()으로 렌더링하여 반복 구조를 줄였습니다.

CTA

CTA 영역에서는 사용자가 다음 행동을 할 수 있도록 유도했습니다.

“지금 바로 시작하세요”
무료 체험 시작
전문가 상담
1,000+ 활성 사용자
99.9% 가동 시간
10배 생산성 향상

Footer

Footer에는 제품, 회사, 지원, 법률 관련 링크를 그룹별로 정리했습니다.

5. 개발 중 발생한 문제와 해결

문제 1. Tailwind CSS v4 PostCSS 호환성 문제

개발 서버 실행 중 다음 오류가 발생했습니다.

Error: It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin.
The PostCSS plugin has moved to a separate package.

Tailwind CSS v4부터 PostCSS 플러그인이 별도 패키지로 분리된 것이 원인이었습니다.

해결 방법은 다음과 같았습니다.

npm install @tailwindcss/postcss -E

그리고 postcss.config.js를 다음과 같이 수정했습니다.

module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

문제 2. CommonJS와 ES Module 충돌

다음으로는 모듈 형식 충돌 문제가 발생했습니다.

Specified module format (CommonJs) is not matching the module format of the source code.

원인은 package.json에 있던 설정이었습니다.

"type": "commonjs"

Next.js 프로젝트에서는 import/export 문법을 사용하고 있었기 때문에
해당 설정을 제거하여 문제를 해결했습니다.

문제 3. 초기 디자인 품질 부족

첫 번째 결과물은 기능적으로는 동작했지만, 디자인 완성도가 부족했습니다.

피드백은 다음과 같았습니다.

세련되고 예쁜 랜딩페이지가 아니라 영어 텍스트로만 대충 나열된 느낌이었다.

이 피드백을 바탕으로 전체 디자인을 다시 개선했습니다.

개선한 내용은 다음과 같습니다.

영어 텍스트를 한국어로 변경
Noto Sans KR 폰트 적용
보라색-핑크 계열 그라데이션 적용
카드 호버 애니메이션 추가
플로팅 통계 카드 추가
모바일 메뉴 구현
한글 사용자에게 맞는 문구로 로컬라이징

호버 애니메이션은 다음과 같이 작성했습니다.

.hover-lift {
  transition: all 0.3s ease;
}

.hover-lift:hover {
  transform: translateY(-8px);
  box-shadow: 0 20px 40px rgba(0, 0, 0, 0.1);
}

그라데이션 배경도 커스텀 클래스로 분리했습니다.

.bg-gradient-primary {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

결과와 배운 점

최종 결과

최종적으로 다음과 같은 랜딩페이지를 완성했습니다.

Next.js 기반 랜딩페이지
한국어 중심의 서비스 소개 페이지
반응형 디자인
모바일 햄버거 메뉴
그라데이션 UI
호버 애니메이션
CTA 영역과 기능 소개 섹션
Git을 활용한 버전 관리

최종 프로젝트 구조는 다음과 같습니다.

AX-AgentWorks/
├── src/
│   └── app/
│       ├── components/
│       │   ├── Header.jsx
│       │   ├── Hero.jsx
│       │   ├── Features.jsx
│       │   ├── CTA.jsx
│       │   └── Footer.jsx
│       ├── globals.css
│       ├── layout.js
│       └── page.js
├── next.config.js
├── tailwind.config.js
├── postcss.config.js
├── package.json
├── .gitignore
└── REPORT.md

배운 점 1. AI 도구도 구조화된 프로세스가 중요하다

Claude Code와 bkit을 사용하더라도
무작정 코드를 생성하는 것보다 PDCA처럼 과정을 나누는 것이 훨씬 안정적이었습니다.

특히 다음 흐름이 도움이 되었습니다.

먼저 목표를 정한다.
작은 단위로 실행한다.
결과를 확인한다.
피드백을 반영해 개선한다.

AI를 활용한 개발에서도 결국 중요한 것은
“질문을 어떻게 구조화하고, 결과를 어떻게 검증하느냐”라는 점이었습니다.

배운 점 2. 최신 버전의 도구는 공식 변경 사항을 확인해야 한다

Tailwind CSS v4에서는 PostCSS 플러그인 구조가 바뀌어 있었습니다.

이처럼 프레임워크나 라이브러리의 메이저 버전이 올라가면
기존 방식이 그대로 동작하지 않을 수 있다는 점을 다시 느꼈습니다.

앞으로는 패키지 설치 후 오류가 발생하면
단순히 에러 메시지만 해결하는 것이 아니라
버전 변경에 따른 구조 변화도 함께 확인해야겠다고 느꼈습니다.

배운 점 3. 디자인 피드백은 결과물을 크게 바꾼다

초기 버전은 기능 구현에만 집중하다 보니
실제 사용자가 보기에 매력적인 페이지는 아니었습니다.

하지만 피드백을 받고 나서 다음 요소들을 개선하자
전체 인상이 크게 달라졌습니다.

색상
폰트
문구
여백
카드 디자인
애니메이션
반응형 구조

결국 랜딩페이지는 기능뿐 아니라
첫인상과 메시지 전달력이 매우 중요하다는 것을 배웠습니다.

배운 점 4. 한글 서비스에는 한글 중심 UX가 필요하다

처음에는 영어 텍스트가 섞여 있어 국내 사용자에게 어색했습니다.

한국어 문구와 Noto Sans KR 폰트를 적용하니
페이지의 완성도와 신뢰감이 훨씬 좋아졌습니다.

앞으로 한국어 기반 서비스를 만들 때는
단순 번역이 아니라 사용자 맥락에 맞는 표현과 디자인을 함께 고려해야겠다고 느꼈습니다.

앞으로의 개선 계획

이번 실습에서는 랜딩페이지의 기본 구조를 완성했습니다.

앞으로는 다음 기능들을 추가해보고 싶습니다.

요금제 섹션 추가
고객 후기 섹션 추가
문의 폼 기능 추가
뉴스레터 구독 기능 추가
SEO 최적화
Google Analytics 연동
실제 배포 환경 구성
고객 사례 페이지 제작

마무리

이번 실습은 단순히 랜딩페이지 하나를 만든 작업이 아니라,
AI 도구를 활용해 개발 프로세스를 어떻게 구조화할 수 있는지 경험한 과정이었습니다.

Claude Code와 bkit을 활용하면 빠르게 코드를 만들 수 있었지만,
그 결과물을 좋은 서비스처럼 보이게 만드는 데에는
명확한 목표 설정, 피드백 반영, 반복 개선이 꼭 필요했습니다.

특히 PDCA 방식으로 진행하니
에러가 발생해도 당황하지 않고 단계별로 원인을 찾고 해결할 수 있었습니다.

이번 경험을 통해 AI 개발 도구는
“개발을 대신해주는 도구”라기보다
“개발 과정을 더 빠르고 체계적으로 만들어주는 파트너”에 가깝다는 생각이 들었습니다.

도움 받은 글

실습 보고서: REPORT.md
Claude Code
bkit Claude Code 플러그인
Next.js
Tailwind CSS

🔥<24기 AI 스터디> 10/2 오후 3시까지 신청·변경 가능 🔥