비개발자용 시작
이 가이드는 풀타임 개발자가 아닌 분을 위한 안내입니다. 동작하는 확장 프로그램을 직접 띄우는 순간까지 한 단계씩 따라가게 짜여 있습니다. 도중에 막히면 05-troubleshooting을 옆 탭에 켜두고 같은 증상을 찾아 보면 됩니다.
어떤 분을 염두에 두고 썼나
이 base를 집어 드는 분 중에는 풀타임 개발자가 아닌 경우가 적지 않습니다. 그래서 톤이 손잡이 친절하게 잡혀 있습니다. 다음 세 가지를 가정합니다.
- 터미널과 Node, git이 처음일 수 있다고 봅니다. 그래서 명령은 한 줄씩 풀어 적습니다.
- 첫 실행에는 Supabase나 자체 서버 같은 외부 서비스가 필요 없습니다. 기본 백엔드 모드는
console-log이고, 이 모드에서는 결과가 브라우저 콘솔에 찍히기만 합니다. - 코드는 AI가 씁니다. 이 가이드에서는 Claude Code를 씁니다. 어떤 확장을 만들고 싶은지만 알면 됩니다.
이미 익숙한 부분이 있다면 그 단계는 훑고 넘어가도 됩니다. 다만 한 번씩은 눈으로 지나가 두는 편이 좋습니다. 기대와 다르게 동작하는 자리를 만났을 때 어디로 돌아와야 하는지가 머릿속에 남기 때문입니다.
6단계
| 단계 | 무엇을 하나 | 대략 시간 |
|---|---|---|
| 1 01-prerequisites | Node, git, Chrome, Claude Code 설치 | 처음이면 20~40분 |
| 2 02-clone-and-install | base 받기와 의존성 설치 | 5~10분 |
| 3 03-first-run | "프로젝트 세팅" 입력 후 console-log 모드로 첫 실행 | 15~30분 |
| 4 04-real-backend (선택) | Supabase 또는 자체 서버 연결 | 30분~1시간 |
| 5 05-troubleshooting | 자주 막히는 자리 모음 | 필요할 때만 |
| 6 06-distribution (선택) | 사용자에게 배포 | 30분~2시간 |
이미 Node와 git, MV3 manifest가 익숙한 분이라면 전문가용 매뉴얼이 더 짧은 호흡으로 같은 base를 풉니다.
막혔을 때
가장 먼저 볼 자리는 05-troubleshooting입니다. 첫 실행에서 흔히 부딪히는 자리는 거의 거기에 정리돼 있습니다.
거기에도 같은 증상이 없으면 에러 메시지를 그대로 복사해서 Claude Code에 붙여 넣고 "이거 어떻게 고쳐?" 라고 물어 보세요. 다음에 시도할 만한 한 수가 보통 따라옵니다.
그래도 풀리지 않으면 GitHub 이슈를 열거나 팀 Slack에 글을 올립니다. 세 가지를 함께 적어 주세요.
- 어디서 막혔는지 (어느 파일, 어느 명령)
- 에러 메시지 전체
- 환경 정보 (운영체제, Node 버전, Chrome 버전)
처음 한 번이 가장 느립니다. 환경이 한 번 잡히고 나면 다음 확장을 만들 때는 1단계를 통째로 건너뛰게 되고, 전체 흐름이 눈에 띄게 짧아집니다.