03. 첫 실행

이 단계의 목표는 단순합니다. 외부 서비스를 건드리지 않고, 내 컴퓨터에서 확장이 처음부터 끝까지 한 바퀴 도는 모습을 직접 보는 것입니다. 모드는 console-log 입니다. 결과가 브라우저 콘솔에 찍히기만 하고 네트워크로 나가지 않습니다. 보통 30분 안에 끝납니다.

1) base 디렉토리에서 Claude Code 실행

02-clone-and-install에서 cd my-extension 까지 했다면 같은 자리에서 다음 명령을 실행합니다.

claude

Claude Code 프롬프트가 뜨면 CLAUDE.md 와 자동화 규칙을 조용히 읽어 들입니다. 화면에 출력이 별로 안 보일 수 있는데 정상입니다.

2) 한 줄로 시작

Claude Code 프롬프트에 다음 둘 중 하나를 입력합니다.

프로젝트 세팅

또는 영어로 start extension development. 어느 쪽이든 orchestrate-extension 스킬을 트리거합니다. 오케스트레이터가 단계별로 질문을 던지기 시작합니다.

3) AI의 질문에 답하기

순서대로 몇 가지 질문이 옵니다. 처음이라면 아래 표의 권장 답이 가장 안전합니다. 이 결정들은 영구적이지 않으니 너무 깊이 고민하지 않아도 됩니다.

AI가 묻는 것	처음에 무난한 답
트리거 UI 모드 (popup, sidepanel, popup+sidepanel, window)	sidepanel. 우측에 도킹되고, 바깥을 클릭해도 닫히지 않아서 학습 단계에 편합니다. Chrome 114 이상이 필요합니다.
확장 이름과 한 줄 설명	TBD 같은 자리만 잡는 값으로 충분합니다. 컨셉이 정해지면 그때 갱신합니다.
content script가 동작할 도메인	비워 두거나 https://example.com/* 정도를 임시로 둡니다.
기본 백엔드 모드 (console-log, server-relay, supabase-direct)	console-log. 외부 세팅이 없어서 첫 실행을 빠르게 확인할 수 있습니다.
MCP 서버를 등록할지	"none"이 가장 쉬운 답입니다. Supabase로 가게 되면 그때 MCP를 추가하면 됩니다.

이 단계의 목표는 어쨌든 한 바퀴를 도는 것이지, 이상적인 설정을 단번에 잡는 것이 아닙니다.

4) AI가 코드를 만드는 동안

이 시간 동안 오케스트레이터가 다음을 알아서 합니다.

• 디렉토리 골격 만들기 (src/app/, src/widgets/ 등)
• manifest.config.ts 작성
• 백엔드 어댑터, 옵션 페이지, background worker, content script, sidepanel 코드 생성
• 빌드 실행과 zip 패키징

화면에 Phase 1 Architect 완료 같은 진행 줄이 흘러갑니다. 머신 속도와 네트워크에 따라 5~15분 정도 걸립니다. 이 시간 동안 오케스트레이터를 지켜보고 있을 필요는 없습니다.

5) Chrome에 확장 로드

빌드가 끝나면 소스 옆에 dist/ 디렉토리가 생깁니다. Chrome이 로드하는 자리는 바로 이 폴더입니다.

1. 주소창에 chrome://extensions 를 입력합니다.
2. 01-prerequisites에서 켜 둔 개발자 모드 토글이 여전히 켜져 있는지 확인합니다.
3. 압축해제된 확장 프로그램을 로드합니다 를 클릭합니다.
4. 파일 선택 창에서 my-extension/dist/ 를 고릅니다.

정상적으로 로드되면 chrome://extensions 페이지의 확장 목록에 본인 확장 카드가 한 장 추가됩니다. 카드 안에 본인 확장의 이름과 짧은 설명이 보이면 정상입니다. 카드에 빨간색 "오류" 표시가 뜨면 빌드가 실패했거나 manifest가 잘못된 상태이니, "오류" 글자를 눌러 메시지를 확인하고 다시 빌드합니다.

:::note 스크린샷 실제 캡처는 추후 docs-screenshot 스킬로 추가됩니다. static/img/chrome-ext/beginner/first-run-01-extension-loaded.png 자리. :::

6) 동작 확인

여기서 첫 실행이 눈에 보입니다.

1. 아무 웹 페이지를 엽니다 (https://example.com 같은 자리도 괜찮습니다).
2. 브라우저 우측 상단의 확장 아이콘을 클릭합니다. 사이드패널이 우측에서 슬라이드해 들어옵니다.
3. 사이드패널 안에서 Analyze and send 버튼을 누릅니다.
4. F12를 눌러 DevTools를 열고 Console 탭으로 갑니다. 분석된 페이지 데이터가 console.log 로 찍혀 있어야 합니다.

여기까지가 첫 실행입니다. 외부 서비스 하나 걸치지 않고 확장이 한 바퀴를 돈 셈입니다.

콘솔에 아무것도 안 보이면 어느 콘솔을 보고 있는지부터 확인합니다. 사이드패널 자체의 콘솔은 사이드패널 안에서 우클릭 → "검사" 로 열립니다. background service worker의 콘솔은 따로입니다. chrome://extensions 의 내 확장 카드에서 "세부정보" → "Service Worker" 링크를 누르면 따로 떠오릅니다. 분석된 데이터는 보통 background 콘솔에 찍힙니다. 자세한 안내는 05-troubleshooting의 "Analyze and send 가 콘솔에 아무것도 안 찍습니다" 항목에 있습니다.

7) src/ 한 번 둘러보기

여기까지 왔으면 오케스트레이터가 만들어 둔 폴더 모양을 한 번 훑어 두면 좋습니다.

src/
├── app/sidepanel/           ← 방금 사용한 사이드패널의 진입점
├── app/options/             ← chrome://extensions 의 "옵션" 에서 열리는 페이지
├── app/background/          ← 메시지 라우팅 (자체 UI 없음)
├── app/content/             ← 페이지에 주입돼 DOM을 분석
├── widgets/page-analysis/   ← 사이드패널 안의 메인 UI
├── shared/api/backend/      ← console-log, server-relay, supabase 어댑터
└── ...

이 구조를 모두 이해할 필요는 아직 없습니다. 무언가 바꾸고 싶을 때는 Claude Code에 원하는 변화를 그냥 말로 알려 주는 것이 보통 가장 빠른 길입니다. 어느 파일이 어디에 매핑되는지는 AI가 압니다.

다음 단계

가고 싶은 자리	이 매뉴얼의 어느 곳
실제 백엔드(서버 또는 Supabase)로 데이터 보내기	04-real-backend
확장 컨셉 바꾸기 (다른 페이지 분석 등)	Claude Code에 "확장 컨셉을 X로 바꿔줘" 라고 입력
사용자 손에 확장 전달 (zip, Web Store, self-host .crx)	06-distribution
무언가 깨졌을 때	05-troubleshooting