ww-w-ai/bkit-claude-code

초보자(Starter) 스킬

액션

액션	설명	예시
init	프로젝트 초기화 (/init-starter 기능)	/starter init my-portfolio
guide	개발 가이드 표시	/starter guide
help	초보자 도움말	/starter help

init (프로젝트 초기화)

1. 프로젝트 디렉토리 구조 생성 (HTML/CSS/JS 또는 Next.js)
2. package.json 생성 (Next.js 선택 시)
3. CLAUDE.md 생성 (레벨: Starter 지정)
4. docs/ 폴더 구조 생성 (PDCA 문서용)
5. 파이프라인 저장소 초기화 — lib/pdca/status.js의 writeBkitMemory()가 .bkit/state/memory.json (.bkit-memory.json에서 마이그레이션된 경로)에 기록합니다. 이 파일은 프로젝트 레벨과 9단계 pipelineStatus를 보관하며, 5, 6, 9단계의 파이프라인 Stop 훅에서 읽습니다. PDCA 단계가 저장되는 위치는 이것이 아닙니다 — .bkit/state/pdca-status.json입니다.

guide (개발 가이드)

• 현재 프로젝트 상태 분석
• Starter 레벨에 적합한 다음 단계 제안
• 1~3단계 중심의 파이프라인 가이드

help (초보자 도움말)

• HTML/CSS/JS 기본 개념 설명
• 자주 묻는 질문에 답변
• 예제 코드 제공

대상 독자

• 프로그래밍을 처음 배우는 사람
• 간단한 웹사이트를 만들고 싶은 사람
• 포트폴리오 사이트가 필요한 사람

기술 스택

옵션 A: 순수 HTML/CSS/JS (완전 초보자용)

HTML5        → 웹 페이지 구조
CSS3         → 스타일링
JavaScript   → 동적 기능 (선택 사항)

옵션 B: Next.js (프레임워크 사용)

Next.js 14+  → React 기반 프레임워크
Tailwind CSS → 유틸리티 CSS
TypeScript   → 타입 안전성 (선택 사항)

언어 계층 안내 (v1.3.0)

권장: Tier 1 언어만 사용 (Python, TypeScript, JavaScript)

Starter 레벨은 최대 AI 도구 지원을 받는 AI-Native 개발에 집중합니다.

계층	허용 여부	이유
Tier 1	✅ 예	완전한 AI 지원, Vibe Coding 최적화
Tier 2	⚠️ 제한적	Dynamic 레벨을 고려하세요
Tier 3-4	❌ 아니요	Dynamic/Enterprise로 업그레이드하세요

프로젝트 구조

옵션 A: HTML/CSS/JS

project/
├── index.html          # 메인 페이지
├── about.html          # 소개 페이지
├── css/
│   └── style.css       # 스타일
├── js/
│   └── main.js         # JavaScript
├── images/             # 이미지 파일
├── docs/               # PDCA 문서
│   ├── 01-plan/
│   └── 02-design/
└── README.md

옵션 B: Next.js

project/
├── src/
│   ├── app/
│   │   ├── layout.tsx      # 공통 레이아웃
│   │   ├── page.tsx        # 메인 페이지
│   │   └── about/
│   │       └── page.tsx    # 소개 페이지
│   └── components/         # 재사용 가능한 컴포넌트
├── public/                 # 정적 파일
├── docs/                   # PDCA 문서
├── package.json
├── tailwind.config.js
└── README.md

핵심 개념 설명

HTML (웹 페이지 구조)

<!-- 기본 구조 -->
<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8">
    <title>내 웹사이트</title>
    <link rel="stylesheet" href="css/style.css">
</head>
<body>
    <header>헤더</header>
    <main>본문 내용</main>
    <footer>푸터</footer>
</body>
</html>

CSS (웹 페이지 스타일링)

/* 기본 스타일 */
body {
    font-family: 'Inter', sans-serif;
    margin: 0;
    padding: 0;
}

/* 가운데 정렬 */
.container {
    max-width: 1200px;
    margin: 0 auto;
    padding: 20px;
}

/* 반응형 (모바일 대응) */
@media (max-width: 768px) {
    .container {
        padding: 10px;
    }
}

Next.js App Router (페이지 생성)

// app/page.tsx - 메인 페이지
export default function Home() {
  return (
    <main className="container mx-auto p-4">
      <h1 className="text-3xl font-bold">
        환영합니다!
      </h1>
    </main>
  );
}

// app/about/page.tsx - 소개 페이지
// URL: /about
export default function About() {
  return (
    <div className="container mx-auto p-4">
      <h1>소개</h1>
      <p>저는 ...입니다</p>
    </div>
  );
}

Tailwind CSS (빠른 스타일링)

// 자주 사용하는 클래스
<div className="
  container    // 가운데 정렬
  mx-auto      // 자동 좌/우 여백
  p-4          // 패딩 16px
  text-center  // 텍스트 가운데 정렬
  text-xl      // 큰 텍스트
  font-bold    // 굵은 텍스트
  bg-blue-500  // 파란 배경
  text-white   // 흰색 텍스트
  rounded-lg   // 둥근 모서리
  hover:bg-blue-600  // 마우스 오버 시 색상 변경
">

배포 방법

GitHub Pages (무료)

1. GitHub 저장소 생성
2. 코드 푸시
3. 설정 → Pages → 소스: main 브랜치
4. https://username.github.io/repo-name 에서 접속

Vercel (Next.js에 권장)

1. vercel.com에 가입 (GitHub 연동)
2. "New Project" → 저장소 선택
3. "Deploy" 클릭
4. URL이 자동으로 생성됨

제한 사항

❌ 로그인/회원가입 (서버 필요)
❌ 데이터 저장 (데이터베이스 필요)
❌ 관리자 페이지 (백엔드 필요)
❌ 결제 기능 (백엔드 필요)

업그레이드 시점

다음이 필요하면 Dynamic 레벨로 이동하세요:

→ "로그인 기능이 필요해요"
→ "데이터를 저장하고 싶어요"
→ "관리자 페이지가 필요해요"
→ "사용자들이 서로 소통할 수 있게 하고 싶어요"

Starter 레벨을 위한 bkit 기능 (v1.5.1)

출력 스타일: bkit-learning (권장)

최고의 학습 경험을 위해 학습 출력 스타일을 활성화하세요:

/output-style bkit-learning

이 스타일은 다음을 제공합니다:

• 각 작업 후 학습 포인트 제공: 무엇을 왜 했는지 설명
• TODO(learner) 마커: 직접 실습할 수 있도록 유도
• 초보자 난이도에 맞춘 개념 설명

에이전트 메모리 (자동 활성화)

bkit 에이전트는 세션 간에도 학습 진행 상황을 자동으로 기억합니다. 별도 설정이 필요 없습니다 — starter-guide 에이전트는 user 범위 메모리를 사용하므로 다른 프로젝트에서도 학습 맥락이 유지됩니다.

에이전트 팀

에이전트 팀은 Starter 레벨 프로젝트에서 사용할 수 없습니다. Dynamic 레벨로 업그레이드하면 2인 팀 병렬 PDCA 모드가 잠금 해제됩니다.

---

자주 하는 실수

실수	해결 방법
이미지가 표시되지 않음	경로 확인 (./images/photo.jpg)
CSS가 적용되지 않음	link 태그 경로 확인
페이지 이동이 작동하지 않음	href 경로 확인 (./about.html)
모바일에서 깨짐	<meta name="viewport"> 태그 확인