처음 Claude Code를 켰을 때 가장 막막했던 건 "뭘 먼저 만져야 하지?"였다. 설정 파일, 에이전트, 슬래시 커맨드, MCP — 단어부터 낯설었다. 그래서 손에 익을 때까지 한 가지 원칙을 정했다. 남이 잘 다듬어 둔 출발점부터 빌리자. 그 출발점이 bkit이었고, 그걸로 익숙해진 다음 직접 만들어 본 게 대시보드였다. 이 글은 그 두 단계에서 내가 실제로 배운 것들을 정리한 기록이다.
1단계 — bkit으로 환경 부트스트랩하기
왜 bkit부터 시작했나
bkit-starter는 Claude Code 초보자를 위한 스타터 번들이다. 안에 들어 있는 슬래시 커맨드만 봐도 학습 순서가 그려진다.
/bkit-starter:first-claude-code— 완전 초보자용 쇼케이스/bkit-starter:setup-claude-code— 프로젝트 자동 분석 후 최적 설정/bkit-starter:learn-claude-code— 체계적인 학습 커리큘럼/bkit-starter:upgrade-claude-code— 최신 트렌드 반영 업그레이드
순서가 정해져 있는 게 마음에 들었다. "일단 돌려보고 → 내 프로젝트에 맞춰보고 → 배워보고 → 따라잡자" 라는 흐름.
배운 것 ①: 설정 파일은 "선언"이지 "지시"가 아니다
setup-claude-code를 돌려보면서 가장 크게 바뀐 인식이다. 처음엔 Claude에게 "이렇게 행동해 줘"라고 적으면 될 줄 알았는데, 자동화는 메모리/프롬프트가 아니라 settings.json의 hook에서 동작한다는 걸 알게 됐다. "매번 X 해줘" 같은 요청은 사람한테 부탁하는 문장이 아니라, harness에 등록해야 동작하는 이벤트였다.
배운 것 ②: 슬래시 커맨드는 "묶음 워크플로우"다
first-claude-code 한 줄을 치면 여러 개의 단계가 줄줄이 실행됐다. 이걸 보면서 슬래시 커맨드가 단순한 별칭이 아니라, "내가 자주 반복하는 일을 한 단어로 줄이는 도구" 라는 걸 체감했다. 나중에 직접 대시보드를 만들 때도, 자주 쓰는 명령을 슬래시로 묶는 게 자연스러워졌다.
배운 것 ③: 업그레이드는 환경의 일부다
upgrade-claude-code를 돌리고 나서야, Claude Code 생태계가 빠르게 변하고 있다는 걸 실감했다. 모델, 스킬, MCP 서버, 설정 표준이 계속 갱신된다. "한 번 세팅하고 끝"이 아니라 "주기적으로 업그레이드를 도는 것"이 정상 흐름이라는 걸 받아들이게 됐다.
2단계 — 대시보드 만들기
bkit 흐름이 손에 익은 다음, 내가 실제로 쓸 대시보드를 만들기로 했다. Next.js App Router 기반으로, 라우트 그룹 (dashboard) 안에 영역을 나눴다.
app/(dashboard)/
├── admin/
├── calendar/
├── sales/
├── wiki/
├── db/
└── layout.tsx
각각 별개의 도메인이지만 같은 레이아웃을 공유한다. 이 구조를 잡으면서 배운 게 가장 많았다.
배운 것 ④: 라우트 그룹은 "URL은 안 바뀌고 코드만 묶는다"
(dashboard) 처럼 괄호로 감싸면 URL 경로에 포함되지 않는다. 즉 /admin은 그대로 /admin인데, 코드 상으로는 같은 그룹 안에 묶여 같은 layout.tsx를 공유한다. "URL 설계"와 "코드 조직"을 분리할 수 있다는 게 라우트 그룹의 본질이라는 걸 직접 짜보면서 알았다.
배운 것 ⑤: 한 화면 = 하나의 도메인
처음엔 대시보드를 "모든 걸 한 페이지에 욱여넣는 곳"으로 생각했다. 그런데 admin / calendar / sales / wiki로 영역을 나눠 보니, 각 화면은 하나의 도메인만 책임지면 된다는 게 명확해졌다. 일정은 calendar, 매출은 sales, 지식은 wiki. 한 곳에 다 넣지 않은 게 결과적으로 유지보수를 훨씬 쉽게 만들었다.
배운 것 ⑥: 공통은 layout, 다른 건 page
layout.tsx는 사이드바·헤더·인증 가드처럼 모든 화면에 공통인 골격을 담는다. 각 폴더 안의 page.tsx는 그 화면만의 콘텐츠다. 이 구분을 일관되게 지키면, 새로운 섹션을 추가할 때 폴더 하나만 만들면 끝난다. "어디에 코드를 둘지" 고민하는 시간이 거의 사라졌다.
배운 것 ⑦: 작은 페이지부터 시작해서 키운다
simple-web-page 같은 1페이지짜리 HTML도 처음엔 가볍게 봤는데, 막상 대시보드를 만들다 보니 그 작은 페이지가 알려준 게 컸다. "중앙 정렬 한 줄을 반응형으로 띄우는 것" 부터 단단히 짜면, 그 위에 카드·테이블·차트를 얹어도 무너지지 않는다. 처음부터 거창한 컴포넌트 라이브러리부터 깔지 않고, 필요한 만큼만 올린 게 잘한 선택이었다.
두 단계를 합쳐서 느낀 것
bkit이 알려준 건 "환경은 선언적으로, 워크플로우는 묶어서, 업그레이드는 정기적으로" 였다. 대시보드를 만들면서 배운 건 "URL과 코드는 분리, 한 화면은 한 도메인, 공통은 layout, 시작은 작게" 였다.
이 둘이 묘하게 닮아 있 다. 반복되는 건 한 번 잘 정의해서 묶고, 다른 건 명확하게 분리한다. 결국 좋은 도구도, 좋은 코드 구조도 같은 원칙 위에 서 있다는 걸 이번에 알았다.
다음에 해볼 것
setup-claude-code로 다시 한 번 프로젝트 분석 돌려서, 대시보드 코드에 맞춘 설정 정리대시보드 각 섹션에 어울리는 MCP 서버 연결 (calendar ↔ Google Calendar, wiki ↔ Notion 등)
자주 쓰는 작업을 내 슬래시 커맨드로 정의해 보기
upgrade-claude-code를 주기적 루틴으로 등록
