ww-w-ai/bkit-codex

초보자(Starter) 스킬

초보자와 비개발자를 위한 정적 웹 개발 가이드입니다.

액션

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

init (프로젝트 초기화)

1. 프로젝트 디렉토리 구조 생성 (HTML/CSS/JS 또는 Next.js)
2. package.json 생성 (Next.js 선택 시)
3. AGENTS.md 생성 (레벨: Starter 지정)
4. docs/ 폴더 구조 생성 (PDCA 문서용)
5. .pdca-status.json 초기화

guide (개발 가이드)

• 현재 프로젝트 상태 분석
• Starter 레벨에 적합한 다음 단계 제안
• Phase 1-3 중심 Pipeline 가이드 (1 -> 2 -> 3 -> 6 -> 9)

help (초보자 도움말)

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

대상 사용자

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

기술 스택

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

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

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

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

언어 계층 가이드

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

계층	허용 여부	이유
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">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <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>
  );
}

배포 방법

GitHub Pages (무료)

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

Vercel (Next.js 권장)

1. vercel.com 가입 (GitHub 연동)
2. "New Project" -> 저장소 선택
3. "Deploy" 클릭

제한 사항

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

업그레이드 시점

다음이 필요하면 Dynamic 레벨 ($dynamic)로 이동하세요:

• 로그인 기능
• 데이터 저장
• 관리자 페이지
• 사용자 커뮤니케이션 기능

파이프라인 흐름 (Starter)

Phase 1 -> 2 -> 3 -> 6(정적) -> 9

API(Phase 4), 디자인 시스템(Phase 5 선택사항) 건너뛰기, SEO는 Phase 7에서만 수행.

흔한 실수

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