크롬 확장프로그램은 생각보다 간단한 구조로 이루어져 있습니다. manifest.json 파일 하나, HTML 팝업 하나, JavaScript 몇 줄이면 브라우저 툴바에 올라가는 나만의 도구를 만들 수 있습니다. 여기에 Claude Code 같은 AI 코딩 도구를 더하면, 코딩 경험이 없어도 아이디어를 설명하는 것만으로 동작하는 확장프로그램을 완성할 수 있습니다.
이 튜토리얼에서는 "현재 페이지의 글자 수를 세어주는 확장프로그램"을 예제로 사용합니다. 팝업을 클릭하면 현재 웹페이지의 텍스트 글자 수가 바로 표시되는 간단하고 실용적인 유틸리티입니다. 이 예제를 통해 확장프로그램의 기본 구조를 익히면, 이후에는 어떤 아이디어든 같은 방식으로 만들 수 있습니다.
Windows + WSL(Windows Subsystem for Linux) 환경 기준으로 설명합니다. WSL 터미널에서 파일을 만들고, Windows Chrome 브라우저에서 테스트하는 방식입니다.
사전 준비
시작하기 전에 아래 항목을 먼저 확인합니다. Claude Code는 WSL 터미널 안에서 실행하는 AI 코딩 도구입니다. 설치되어 있지 않다면 먼저 설치해야 합니다.
시작 전 확인사항
0/4 완료
WSL 터미널을 열고 npm install -g @anthropic-ai/claude-code 를 실행합니다. Node.js 18 이상이 필요합니다.
Step 1: 프로젝트 폴더 만들기
모든 크롬 확장프로그램은 하나의 폴더 안에 파일이 모여 있는 구조입니다. 먼저 WSL 터미널을 열고 프로젝트 폴더를 만듭니다. 폴더 이름은 영문 소문자와 하이픈(-) 조합으로 짓는 것이 관례입니다.
$ mkdir word-counter-extension $ cd word-counter-extension
폴더를 만들었으면 Claude Code를 실행합니다. 이 폴더 안에서 실행해야 Claude Code가 프로젝트 컨텍스트를 올바르게 파악합니다.
$ claude ╭───────────────────────────────╮ │ Claude Code v1.x │ │ ✓ API 연결 완료 │ ╰───────────────────────────────╯ >
Step 2: Claude Code로 파일 구조 생성하기
Claude Code가 실행되면 자연어로 원하는 것을 설명합니다. 이것이 바이브코딩의 핵심입니다. 코드를 직접 쓰는 것이 아니라, 무엇을 만들고 싶은지 설명하면 AI가 코드를 생성해 줍니다.
크롬 확장프로그램을 만들어줘. Manifest V3 기준으로. 기능: 툴바 아이콘을 클릭하면 팝업이 뜨고, 현재 웹페이지의 텍스트 글자 수를 세어서 보여줘. 파일 구성: - manifest.json (manifest_version: 3) - popup.html - popup.js - content.js (페이지에서 텍스트를 읽어오는 content script) - icons 폴더 안에 icon16.png, icon48.png, icon128.png 자리 표시 파일 스타일은 간결하게. 한국어 UI로 만들어줘.
스크롤 근처에서 인터랙션이 활성화됩니다.
Claude Code가 파일들을 생성하면 아래와 같은 구조가 만들어집니다.
word-counter-extension/
word-counter-extension/
manifest.json
popup.html
popup.js
content.js
icons/
icon16.png
icon48.png
icon128.png스크롤 근처에서 인터랙션이 활성화됩니다.
Step 3: manifest.json 이해하기
manifest.json은 확장프로그램의 신분증 역할을 합니다. 이름, 버전, 어떤 파일을 사용하는지, 어떤 권한이 필요한지를 Chrome에 알려주는 핵심 파일입니다. Claude Code가 생성한 파일을 확인해 보겠습니다.
{
"manifest_version": 3,
"name": "글자 수 세기",
"version": "1.0",
"description": "현재 페이지의 텍스트 글자 수를 세어줍니다.",
"icons": {
"16": "icons/icon16.png",
"48": "icons/icon48.png",
"128": "icons/icon128.png"
},
"action": {
"default_popup": "popup.html",
"default_icon": {
"16": "icons/icon16.png",
"48": "icons/icon48.png",
"128": "icons/icon128.png"
}
},
"content_scripts": [
{
"matches": ["<all_urls>"],
"js": ["content.js"]
}
],
"permissions": ["activeTab"]
}핵심 필드를 하나씩 살펴보겠습니다.
| 필드 | 역할 |
|---|---|
| manifest_version: 3 | Manifest V3 형식 사용. 2024년부터 V3가 필수 기준. |
| action.default_popup | 툴바 아이콘 클릭 시 열릴 HTML 파일 지정. |
| content_scripts | 웹페이지에 자동으로 주입할 JS 파일과 적용할 URL 패턴 지정. |
| permissions | 확장프로그램이 사용할 Chrome API 권한 목록. |
Chrome 확장프로그램 설정 파일의 버전 규격입니다. 2024년부터 V3가 표준이 되었고, 이전 V2는 더 이상 새 확장프로그램에 사용할 수 없습니다. V3에서는 백그라운드 스크립트 대신 Service Worker를 사용하는 것이 가장 큰 변화입니다.
Step 4: popup.html과 popup.js 확인하기
팝업은 툴바 아이콘을 클릭했을 때 나타나는 작은 창입니다. 일반 HTML 파일과 동일한 구조이지만, 한 가지 제약이 있습니다. 보안 이유로 팝업 HTML 안에 JavaScript를 직접 작성할 수 없고, 반드시 외부 .js 파일로 분리해야 합니다.
<!DOCTYPE html>
<html lang="ko">
<head>
<meta charset="UTF-8">
<style>
body {
width: 220px;
padding: 16px;
font-family: sans-serif;
text-align: center;
}
h2 { font-size: 14px; margin: 0 0 12px; color: #333; }
#count {
font-size: 36px;
font-weight: bold;
color: #1a73e8;
}
#label { font-size: 12px; color: #666; margin-top: 4px; }
button {
margin-top: 12px;
padding: 6px 16px;
background: #1a73e8;
color: white;
border: none;
border-radius: 4px;
cursor: pointer;
font-size: 13px;
}
</style>
</head>
<body>
<h2>글자 수 세기</h2>
<div id="count">-</div>
<div id="label">글자</div>
<button id="btn">지금 세기</button>
<script src="popup.js"></script>
</body>
</html>document.getElementById('btn').addEventListener('click', async () => {
const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
const results = await chrome.scripting.executeScript({
target: { tabId: tab.id },
func: () => document.body.innerText.length,
});
const charCount = results[0].result;
document.getElementById('count').textContent =
charCount.toLocaleString();
});popup.js에서 chrome.scripting.executeScript()를 사용하려면 manifest.json의 permissions에 "scripting"을 추가해야 합니다. Claude Code에게 "scripting 권한도 추가해줘"라고 말하면 자동으로 수정해 줍니다.
scripting 권한을 추가한 최종 permissions 부분은 다음과 같습니다.
"permissions": ["activeTab", "scripting"]Step 5: 아이콘 만들기
확장프로그램을 Chrome에 로드하려면 아이콘 파일이 필요합니다. 실제 디자인 파일이 없어도 테스트 단계에서는 단색 PNG 파일로 대체할 수 있습니다. Claude Code에 아이콘 생성을 요청합니다.
icons 폴더 안에 icon16.png, icon48.png, icon128.png 파일을 만들어줘. 파이썬으로 단색 파란색(#1a73e8) 정사각형 PNG를 각각 16x16, 48x48, 128x128 크기로 생성하는 스크립트를 만들고 실행해줘.
스크롤 근처에서 인터랙션이 활성화됩니다.
Claude Code가 Pillow 라이브러리를 사용해 Python 스크립트를 만들고 실행합니다. 스크립트 실행 후 icons 폴더에 세 개의 PNG 파일이 생성되면 성공입니다.
$ python3 create_icons.py ✓ icons/icon16.png 생성 ✓ icons/icon48.png 생성 ✓ icons/icon128.png 생성
테스트용 단색 아이콘은 동작 확인용입니다. Chrome Web Store에 등록할 때는 브랜드 로고나 의미 있는 아이콘으로 교체해야 합니다. Figma나 Canva에서 무료로 만들 수 있습니다.
Step 6: 로컬 테스트 — chrome://extensions
파일 준비가 끝났으면 Chrome에 로드해서 실제로 동작하는지 확인합니다. Chrome에는 개발 중인 확장프로그램을 ZIP 파일 없이 바로 로드할 수 있는 개발자 모드가 있습니다.
Chrome에 확장프로그램 로드하기
Chrome 확장프로그램 페이지 열기
Chrome 주소창에 chrome://extensions 를 입력하고 Enter를 누릅니다.
개발자 모드 켜기
오른쪽 상단의 '개발자 모드' 토글을 켭니다. 켜면 새 버튼 세 개가 나타납니다.
폴더 경로 확인하기
WSL에서 만든 파일은 Windows 탐색기에서 \\wsl$\Ubuntu\home\[사용자명] 경로로 접근할 수 있습니다. 파일 탐색기 주소창에 이 경로를 입력하면 WSL 홈 디렉터리가 열립니다.
'압축 해제된 확장 프로그램 로드' 클릭
버튼을 클릭하고 word-counter-extension 폴더를 선택합니다.
툴바 아이콘 확인
확장프로그램이 정상 로드되면 Chrome 툴바 오른쪽에 아이콘이 나타납니다. 퍼즐 아이콘을 클릭해서 핀으로 고정할 수 있습니다.
Windows 파일 선택 대화상자에서 WSL 폴더를 선택할 때는 파일 탐색기 주소창에 \\wsl$\Ubuntu\home\사용자명\word-counter-extension 처럼 전체 경로를 직접 입력하면 더 쉽습니다.
동작 확인
아무 웹페이지(예: 뉴스 기사, 블로그 글)를 열고 확장프로그램 아이콘을 클릭합니다. 팝업이 뜨고 '지금 세기' 버튼을 누르면 현재 페이지의 글자 수가 숫자로 표시됩니다. 이 숫자가 나타나면 확장프로그램이 정상적으로 동작하는 것입니다.
코드를 수정한 후 다시 로드하기
코드를 수정한 후에는 chrome://extensions 페이지에서 해당 확장프로그램의 새로고침 버튼(원형 화살표)을 눌러야 변경 사항이 반영됩니다. manifest.json을 수정했을 때는 반드시 새로고침이 필요하고, popup.html이나 popup.js만 수정했을 때는 팝업을 닫고 다시 열면 반영됩니다.
Step 7: Claude Code로 기능 추가하기
기본 동작을 확인했으면 Claude Code에 추가 기능을 요청할 수 있습니다. 바이브코딩의 진짜 장점은 여기서 나옵니다. 코드를 이해하지 않아도 원하는 기능을 말로 설명하면 됩니다.
현재 글자 수만 표시하는데, 단어 수(띄어쓰기 기준)도 함께 표시해줘. 팝업에 '글자 수: 1,234 / 단어 수: 567' 형태로 보여줘.
스크롤 근처에서 인터랙션이 활성화됩니다.
페이지 전체 글자 수 말고, 사용자가 드래그해서 선택한 텍스트의 글자 수도 함께 보여줘. 선택한 텍스트가 없으면 '선택된 텍스트 없음'이라고 표시해줘.
스크롤 근처에서 인터랙션이 활성화됩니다.
Claude Code가 코드를 수정하면, chrome://extensions에서 새로고침 버튼을 누르고 다시 테스트합니다. 이 사이클을 반복하면서 기능을 완성해 나갑니다.
Step 8: Chrome Web Store 배포 기초
로컬에서 잘 동작하는 확장프로그램을 만들었다면 Chrome Web Store에 등록해 다른 사람들도 사용할 수 있게 할 수 있습니다. 배포 전에 아래 준비물을 먼저 갖춰야 합니다.
배포 전 준비 체크리스트
- Google 계정으로 Chrome 개발자 대시보드 가입 (1회 $5 수수료)
- 확장프로그램 ZIP 파일 준비 (폴더 전체를 ZIP으로 압축)
- 스크린샷 최소 1장 (1280x800 또는 640x400 픽셀)
- 아이콘 128x128 PNG (투명 배경 권장)
- 설명 텍스트 (영어 또는 한국어, 132자 이내 단문 설명)
스크롤 근처에서 인터랙션이 활성화됩니다.
ZIP 파일 만들기
WSL 터미널에서 폴더 전체를 ZIP으로 압축합니다. 확장프로그램 폴더의 상위 디렉터리로 이동한 뒤 실행합니다.
$ cd ~ $ zip -r word-counter-extension.zip word-counter-extension/ adding: word-counter-extension/ (stored 0%) adding: word-counter-extension/manifest.json (deflated 42%) adding: word-counter-extension/popup.html (deflated 51%) adding: word-counter-extension/popup.js (deflated 38%) adding: word-counter-extension/content.js (deflated 35%) adding: word-counter-extension/icons/icon16.png (stored 0%) adding: word-counter-extension/icons/icon48.png (stored 0%) adding: word-counter-extension/icons/icon128.png (stored 0%)
개발자 대시보드에 업로드하기
Chrome Web Store 등록 절차
Chrome 개발자 대시보드 접속
chrome.google.com/webstore/devconsole 에 접속해서 Google 계정으로 로그인합니다. 처음 가입하면 $5 등록비를 결제합니다. 이후 등록한 모든 확장프로그램에 적용됩니다.
새 항목 추가
'새 항목' 버튼을 클릭하고 준비한 ZIP 파일을 업로드합니다.
상품 정보 입력
이름, 설명, 스크린샷, 카테고리, 개인정보 처리 방침을 입력합니다. 개인정보 처리 방침은 GitHub Pages나 Notion 페이지로 만들어서 URL을 입력하면 됩니다.
심사 제출
'심사 제출' 버튼을 클릭합니다. 심사는 보통 수 일 내에 완료되며, 결과는 이메일로 통보됩니다.
Chrome Web Store 심사는 수 일에서 최대 수 주가 걸릴 수 있습니다. 확장프로그램이 실제로 선언한 권한만 사용하는지, 사용자 데이터를 무단으로 수집하지 않는지 검토합니다. 단순 유틸리티 확장프로그램은 대부분 빠르게 통과됩니다.
자주 막히는 문제
확장프로그램 개발 과정에서 자주 발생하는 오류와 해결 방법을 정리했습니다. 오류가 발생하면 chrome://extensions 페이지에서 해당 확장프로그램의 '오류' 버튼을 클릭해 상세 내용을 먼저 확인합니다.
아이콘 파일을 찾을 수 없다는 오류가 납니다
manifest.json에 적힌 아이콘 경로와 실제 파일 위치가 다를 때 발생합니다. icons/icon16.png라고 적었다면 확장프로그램 폴더 안에 icons 폴더가 있고 그 안에 icon16.png가 있어야 합니다. 대소문자도 정확히 일치해야 합니다.
팝업을 클릭해도 아무것도 안 나옵니다
팝업 HTML 파일 경로가 잘못되었거나, JavaScript 파일에 문법 오류가 있을 가능성이 높습니다. 팝업 창을 우클릭하고 '검사'를 선택해서 개발자 도구의 콘솔 탭에서 오류 메시지를 확인합니다.
chrome.scripting.executeScript 오류가 납니다
manifest.json의 permissions 배열에 "scripting"이 없거나, 확장프로그램이 접근할 수 없는 페이지(chrome:// 로 시작하는 Chrome 내부 페이지)에서 실행을 시도했을 때 발생합니다. 일반 웹페이지에서 테스트하고, scripting 권한을 추가한 후 확장프로그램을 새로고침합니다.
코드를 수정했는데 변경 사항이 반영되지 않습니다
chrome://extensions 페이지에서 해당 확장프로그램의 새로고침 버튼(원형 화살표 아이콘)을 클릭해야 합니다. manifest.json을 수정했을 때는 반드시 이 새로고침이 필요합니다.
WSL에서 만든 폴더를 Windows Chrome이 찾지 못합니다
Windows 파일 선택 대화상자에서 주소창에 \\wsl$\Ubuntu\home\사용자명 를 직접 입력하면 WSL 파일 시스템에 접근할 수 있습니다. Ubuntu 외에 다른 배포판을 사용한다면 Ubuntu 자리에 해당 배포판 이름을 입력합니다.
스크롤 근처에서 인터랙션이 활성화됩니다.
다음 단계
글자 수 세기 확장프로그램을 완성했다면 이제 구조를 이해한 것입니다. manifest.json, popup, content script, 권한 선언이라는 네 가지 요소가 모든 크롬 확장프로그램의 기반입니다. Claude Code에 다른 아이디어를 설명하면 같은 방식으로 새로운 확장프로그램을 만들 수 있습니다.
다음 아이디어로 도전해 볼 만한 확장프로그램 예시입니다.
다음 프로젝트 아이디어
- 현재 페이지의 모든 링크를 팝업에 목록으로 표시하는 링크 추출기
- 특정 단어를 형광펜으로 하이라이트하는 텍스트 강조 도구
- 페이지 스크롤 위치를 저장하고 복원하는 북마크 확장프로그램
- 선택한 텍스트를 Claude API로 보내서 요약해주는 AI 요약기
스크롤 근처에서 인터랙션이 활성화됩니다.
더 깊이 탐구하고 싶다면 Google의 Chrome Extensions 공식 시작하기 튜토리얼에서 Hello World부터 탭 관리까지 단계별로 학습할 수 있습니다. manifest.json에서 사용 가능한 모든 필드와 권한은 Manifest V3 공식 레퍼런스에서 확인합니다.
성공지식백과에서는 바이브코딩과 AI 도구 활용법을 매주 정리해 발행합니다. 뉴스레터를 구독하면 새 튜토리얼이 발행될 때마다 알림을 받을 수 있습니다.
VS Code에서 Claude Code 시작하기
Windows에서 VS Code를 설치하고, Claude Code 익스텐션을 설정하고, 첫 대화를 시작하는 과정을 단계별로 안내합니다.
Claude Code 완벽 가이드
Claude Code의 설치부터 CLI 명령어, 단축키, 설정, MCP, 서브에이전트까지 모든 기능을 한 곳에 정리했습니다.
바이브코딩의 함정 — 보안, 디버깅, 유지보수 문제
AI가 생성한 코드는 빠르지만 안전하지 않을 수 있습니다. 인증 결함, XSS, 의존성 공급망 공격, 이해할 수 없는 코드, 기술부채 누적까지 — 바이브코딩이 만들어내는 실제 보안 위험과 대응 전략을 정리했습니다.
성공지식백과 뉴스레터
AI 도구와 바이브코딩 튜토리얼을 매주 받아보세요.