잘커라 도움말

이 확장은 내 사이트 소스를 내 컴퓨터에서 고치고, 눈으로 확인한 뒤, 올리는 것까지를 돕습니다. 왼쪽 잘커라 아이콘을 누르면 나오는 목록이 전부이고, 같은 항목을 F1(명령 팔레트)에서 “잘커라”로 검색해도 됩니다.

처음 한 번만 하는 것

1. 로그인

「로그인」을 누르면 브라우저가 열립니다. 평소 잘커라 콘솔에 쓰시는 계정 그대로입니다. 브라우저에서 승인하면 편집기로 돌아옵니다.

2. 사이트 고르기

「사이트」 아래 줄을 눌러 작업할 사이트를 고릅니다. 사이트가 여럿이면 여기서 바꿔 가며 씁니다. 고른 사이트는 그룹 이름 옆에 흐린 글씨로 늘 보입니다.

3. 소스 가져오기 — 셋 중 하나

순서가 아니라 택일입니다. 지금 상황에 맞는 하나만 고르시면 됩니다.

	언제
예제로 시작	아직 소스가 없다. 잘커라가 준비한 시작 소스로 시작한다.
사이트 소스 받기	지금 사이트에 올라가 있는 소스를 내려받아 이어서 고친다.
폴더 연결	이미 가지고 있는 소스(직접 만들었거나 개발사에서 받은 것)를 이 사이트에 붙인다.

빈 폴더에 받습니다. 이미 파일이 있는 폴더에는 받지 않습니다 — 고치던 것을 덮어쓰지 않기 위해서입니다. (편집기가 만든 .vscode 폴더는 있어도 괜찮습니다.)

AI 에게 시켜 고치기 — 먼저 하나 깔아야 합니다

말로 고치시려면 AI 편집기 확장이 하나 더 필요합니다. 잘커라 확장은 소스를 받고 보여 주고 올리는 일을 하지, 소스를 고치지는 않습니다. 고치는 것은 AI 몫입니다.

셋이 각각 다른 층이라 헷갈리기 쉬운데, 이렇게 나뉩니다.

	하는 일
잘커라 확장 (이 확장)	소스 받기 · 프리뷰 · 올리기 · 버전 전환
AI 확장 (Claude Code / Codex)	소스를 읽고 고칩니다
에이전트 연결(MCP)	AI 가 내 사이트 데이터를 볼 수 있게 하는 통로

어느 것을 깔까요

둘 중 아무거나 하나면 됩니다. 이미 쓰시는 구독이 있으면 그쪽이 낫습니다.

	설치	로그인
Claude Code	확장 탭에서 `Claude Code` 검색	Anthropic 계정 (Pro / Max 구독에 포함)
Codex	확장 탭에서 `Codex` 검색	ChatGPT 계정 (Plus / Pro 구독에 포함)

둘 다 까셔도 충돌하지 않습니다. 서로 다른 아이콘으로 나란히 뜨고, 같은 폴더를 각자 읽습니다. 하나로 고치고 다른 하나에게 검토시키는 식으로 쓰셔도 됩니다.

AI 이용료는 잘커라와 무관합니다. 쓰시는 분 구독으로 돕니다. 그래서 어떤 AI 를 쓰시든, 아예 AI 없이 직접 고치시든, 그다음 흐름은 똑같습니다. 저희 도구에 묶이지 않습니다.

실제로 하는 모습

잘커라 확장 → 사이트 소스 받기
잘커라 확장 → 프리뷰 시작 — 열린 브라우저 탭은 그대로 두십시오
AI 에게 말합니다 — “메인 페이지 큰 제목을 ‘이번 주 신상 입고’로 바꿔줘”
AI 가 파일을 고쳐 저장하면 브라우저가 알아서 바뀝니다
마음에 들 때까지 3–4 를 반복합니다
잘커라 확장 → 배포 전 검사 → 새 버전 올리기 → 지금 전환

3–4 를 오가는 것이 실제 작업입니다. AI 는 파일만 고치고, 올리고 켜는 것은 잘커라 확장이 합니다. 일부러 나눠 둔 것입니다 — AI 가 실수로 사이트까지 바꿔 버리는 일이 없습니다.

매일 쓰는 흐름

   고친다  →  프리뷰 시작  →  배포 전 검사  →  새 버전 올리기  →  버전 전환

프리뷰 시작

내 컴퓨터에서 사이트를 띄우고 실제 브라우저 탭으로 엽니다. 편집기 안 미리보기 창이 아닌 이유는, 그 창은 쿠키와 보안 정책이 실제 탭과 달라 “여기선 됐는데 올리니 다르다”가 생기는 자리이기 때문입니다.

첫 실행은 몇 분 걸립니다. 사이트를 띄우는 데 필요한 부품(의존성)을 처음 한 번 받아 두기 때문입니다. 두 번째부터는 빠릅니다. 진행 중에 또 누르셔도 두 개가 뜨지는 않습니다.

준비하는 동안에는 로그아웃과 초기화가 잠시 거절됩니다. 준비가 끝나면 다시 하실 수 있습니다 — 로그아웃한 뒤에 프리뷰가 뒤늦게 뜨는 일이 없게 하기 위해서입니다.

준비가 시간 안에 끝나지 않으면 뜨다 만 서버까지 정리하고 알려 드립니다. 안 떴다고 알린 것이 뒤에서 계속 도는 일은 없습니다.

소스를 고치고 저장하면 브라우저가 알아서 바뀝니다. 프리뷰를 다시 시작할 필요 없습니다.

배포 전 검사

올리기 전에 짚을 만한 것을 알려 줍니다. 조언입니다 — 올리기를 막지 않습니다. 경고가 있어도 올리실 수 있고, 판단은 쓰시는 분 몫입니다.

새 버전 올리기

지금 폴더의 소스를 묶어 잘커라에 올립니다. 올리기까지입니다.

방문자가 보는 사이트는 그대로입니다. 올린 것은 새 버전으로 쌓일 뿐이고, 사이트를 그 버전으로 바꾸는 것은 따로 하는 일입니다. 실수로 잘못 올려도 아무도 못 봅니다.

「발행」이라 부르지 않는 이유가 이것입니다 — 하지 않은 일을 이름이 말하면, 사이트가 바뀐 줄 알고 확인하지 않게 됩니다.

확인창이 어느 사이트에 올리는지 먼저 알려 드립니다. 폴더와 사이트는 따로 정해지므로 (폴더는 그대로 두고 사이트만 바꾸실 수 있습니다) 여러 사이트를 다루실 때 꼭 확인해 주십시오.

올린 뒤 서버가 그 버전을 만듭니다(사이트 종류에 따라 몇 분). 편집기가 그동안 진행을 보여 주고, 끝나면 「버전 N 가 준비됐습니다」와 함께 「지금 전환」 단추를 띄웁니다. 그것을 누르면 바뀝니다.

기다리는 창의 취소는 기다리기만 그만두는 것입니다. 빌드는 서버에서 계속되고, 끝나면 「버전 전환」 목록에 나옵니다.
서버가 만들지 못하면(소스에 문제가 있으면) 이유를 알려 드립니다. 사이트는 그대로입니다.
나중에 바꾸셔도 됩니다 — 「버전」의 버전 전환, 또는 콘솔에서.

올릴 때 빼는 것이 있습니다. 사이트가 되는 데 필요 없거나, 올라가면 안 되는 것들입니다.

	무엇
부품·산출물	`node_modules` · `.next` · `dist` · `out` · `.turbo` · `.vercel` — 서버가 다시 만듭니다
비밀	`.env` 로 시작하거나 `.env` 로 끝나는 모든 파일(`.envrc` · `.env~` 포함) · `.pem` `.key` `.p12` `.pfx` `.p8` · `.netrc` `_netrc` · `.git-credentials` · `.npmrc` · `.yarnrc.yml` · `credentials.json` · `service-account.json` · `firebase-adminsdk*.json` · SSH 키(`id_rsa` `id_dsa` `id_ecdsa` `id_ed25519`)
편집기·도구 설정	`.vscode` · `.idea` · `.mcp.json` · `.claude` · `.git`
자격증명 폴더	`.ssh` · `.aws` — 폴더째 빠집니다
OS 부스러기	`.DS_Store`

뺀 것은 이름을 알려 드립니다. 비밀로 판단해 뺀 파일이 있으면 「출력」 패널의 잘커라 채널에 이름이 남습니다. 이름만 비슷할 뿐 비밀이 아닌 파일(예: turkey.key)이 빠졌다면 이름을 바꿔 다시 올리십시오 — 규칙을 느슨하게 하는 것보다 그쪽이 안전합니다. 폴더도 마찬가지입니다 — config.env 같은 이름의 폴더는 통째로 빠지고, 그것도 이름을 알려 드립니다.

⚠ .env.example 처럼 값이 비어 있는 예시 파일도 함께 빠집니다. 환경변수 설명이 필요하시면 env.example.md 같은 다른 이름으로 두십시오.

왜 .vscode 와 .mcp.json 까지 빼나요. 둘 다 저희가 만드는 파일이고, 그 안에는 어느 사이트로 작업 중인지와 연결하신 AI 도구 설정이 들어 있습니다. 사이트가 되는 데는 쓰이지 않는데, 소스에 실려 나가면 그 소스를 받아 여신 분의 편집기가 엉뚱한 사이트를 가리킬 수 있습니다.

이름이 비슷할 뿐인 평범한 소스(environment.ts, keyboard.ts 같은)는 그대로 올라갑니다.

버전

버전 이력 — 지금까지 올린 버전을 봅니다. ▶ 표시가 지금 켜져 있는 버전입니다. 읽기만 합니다. 아무것도 바뀌지 않습니다.
버전 전환 — 켜져 있지 않은 버전 중 하나를 골라 사이트를 그 버전으로 바꿉니다. 누르면 방문자가 보는 화면이 바로 바뀝니다.

목록에는 켤 수 있는 버전만 나옵니다. 아직 만들어지는 중이거나 실패한 버전은 보이지 않습니다 — 고를 수 없는 것을 보여 주고 나서 거절하지 않으려고 그렇게 했습니다.

앞으로 가는 것과 뒤로 가는 것이 같은 일이라 하나로 두었습니다. 방금 올린 새 버전을 켜는 것도, 어제 버전으로 물러나는 것도 여기서 합니다. 지금 켜져 있는 버전은 목록에 나오지 않습니다 — 이미 그것이기 때문입니다.

두 단계로 나눈 이유. 올리는 것과 켜는 것을 한 번에 하면, 잘못 고친 것이 확인 없이 손님에게 갑니다. 올리기는 조용하고 전환은 한 번 더 묻습니다.

에이전트 연결(MCP) — AI 에게 내 데이터를 보여 주기

무엇이 달라지나요

AI 는 파일을 이미 읽습니다. 폴더를 열어 뒀으니까요. 이 기능이 여는 것은 파일에 없는 것 — 지금 등록된 상품, 들어온 주문, 예약, 사이트 설정 같은 서버 쪽 데이터입니다.

차이가 이렇게 납니다.

	“상품 목록 페이지 만들어줘” 라고 했을 때
연결 없이	AI 가 그럴듯한 가짜 상품을 지어냅니다. 실제 데이터 모양과 안 맞아 붙이면 깨집니다.
연결 후	AI 가 실제 상품을 조회해서, 그 모양에 맞는 화면을 만듭니다.

한 번만 하면 됩니다

「만들기」 → 에이전트 연결(MCP) 을 누릅니다
폴더에 파일 셋이 생깁니다
- .mcp.json — 어디에 연결할지
- AGENTS.md — AI 가 지킬 규약 (정본은 llms.txt 를 가리킵니다)
- CLAUDE.md — 위 파일을 참조하라는 한 줄
AI 확장을 껐다 켭니다 — 이걸 안 하시면 반영되지 않습니다
AI 가 처음 이 도구를 쓸 때 브라우저 로그인이 한 번 뜹니다 (잘커라 계정입니다)

그 뒤로는 그냥 말하시면 됩니다.

“지금 등록된 상품 종류를 보고, 그에 맞는 목록 페이지를 만들어줘” “예약 가능한 시간대를 어떻게 받아오는지 확인하고 예약 폼을 만들어줘”

AI 가 알아서 필요한 도구를 골라 조회합니다.

알아 두실 것

.mcp.json 에 열쇠는 안 들어갑니다. 로그인해서 그때그때 받습니다. 그래서 이 파일을 동료와 나눠 가지셔도 안전하고, 각자 자기 계정으로 로그인해 씁니다.
연결은 편의이지 필수가 아닙니다. 연결하지 않고 직접 고쳐 「새 버전 올리기」만 쓰셔도 똑같이 동작합니다.

`.env.local` 은 무엇인가요

프리뷰가 내 사이트 데이터를 불러오려면 주소와 열쇠가 필요합니다. 그 다섯 줄이 여기 적힙니다.

칸	뜻
`ZALKERA_API_BASE`	잘커라 서버 주소
`ZALKERA_TENANT`	내 사이트 코드
`ZALKERA_STOREFRONT_KEY`	프리뷰용 열쇠 (`oqsk_…`)
`ZALKERA_SITE_URL`	사이트 주소
`NEXT_PUBLIC_ZALKERA_PREVIEW`	프리뷰 모드 표시

이 다섯 칸만 확장이 손대고, 직접 적어 두신 다른 줄은 그대로 둡니다.

이 파일은 절대 올라가지 않습니다. 열쇠가 들어 있기 때문입니다.
열쇠는 한 번에 한 대에서만 유효합니다. 다른 컴퓨터에서 프리뷰를 켜면 이쪽이 끊깁니다. 알림은 새로 켠 컴퓨터에 뜹니다(“다른 기계에서 켜 둔 프리뷰 N개가 해제되었습니다”). 끊긴 쪽에서는 프리뷰 화면이 데이터를 못 불러오는 것으로 나타납니다.
열쇠에는 기한이 있습니다. 남은 기한은 사이드바에 보이고, 프리뷰를 켜 둔 동안 알아서 갱신됩니다.
로그아웃하면 이 줄은 지워지고 서버에서도 폐기됩니다. 프리뷰를 먼저 멈추셨거나 편집기를 껐다 켜셨어도 마찬가지입니다.

확장 자신에 관한 것

새 판이 나오면

확장이 서버와 인사할 때 이 판으로도 되는지 물어봅니다. 더 나은 판이 있으면 알림이 한 번 뜨고, 「업데이트」를 누르시면 VS Code 의 확장 화면에서 이 확장이 열립니다. 설치는 VS Code 가 합니다 — 저희가 파일을 내려받아 갈아 끼우지 않습니다.

같은 소식은 하루에 한 번만 뜹니다. 창을 여러 번 열어도 다시 묻지 않습니다.
새 판이 또 나오면 그때는 바로 알려 드립니다.
계약이 아예 안 맞는 낡은 판이면 알림이 아니라 하던 일이 멈추고 이유를 말합니다. 그때는 업데이트하셔야 이어집니다.

VS Code 가 확장을 자동으로 업데이트하도록 두셨다면 대개 이 알림을 보실 일이 없습니다.

어느 npm 으로 설치할까요

의존성을 내려받을 때 쓸 npm 을 고르실 수 있습니다. 설정에서 zalkera.npm 입니다.

값	하는 일
`bundled` (기본)	확장이 품고 있는 npm 을 씁니다. 컴퓨터에 npm 이 없어도 됩니다.
`system`	이 컴퓨터에 깔린 npm 을 씁니다. 사내 레지스트리·별도 설정을 쓰실 때.
`auto`	깔린 npm 이 조건에 맞으면(9 이상) 그것을, 아니면 품은 것을 씁니다.

고른 것을 못 쓰면 말하고 멈춥니다. 조용히 다른 npm 으로 바꿔 돌리지 않습니다 — 그러면 결과만 남고 무엇이 돌았는지 아무도 모릅니다. 지금 무엇을 쓰는지는 진단에 경로까지 나옵니다.

어느 쪽을 고르시든 저희는 찾아 둔 경로를 그대로 실행합니다. 이름(npm)으로 부르면 어느 프로그램이 뜰지를 운영체제가 정하고, 그 탐색은 지금 열어 둔 폴더부터 시작합니다 — 받으신 소스 안에 같은 이름의 파일이 있으면 그것이 돕니다. 그래서 이름으로 부르지 않습니다. 같은 이유로 bundled 로 두시면 이 컴퓨터의 npm 은 찾지도 실행하지도 않습니다.

이 설정은 컴퓨터 단위입니다. 폴더마다 다르게 둘 수 없습니다 — 받아서 여는 소스가 「어떤 프로그램을 실행할지」를 정하면 안 되기 때문입니다.

설치 스크립트는 돌리지 않습니다

의존성을 받을 때 꾸러미가 딸려 보내는 설치 스크립트를 실행하지 않습니다(--ignore-scripts). 그 설치는 방금 받으신 소스 폴더 안에서 돌기 때문에, 그 폴더가 시키는 것은 무엇이든 그대로 실행됩니다.

설치 스크립트가 필요한 꾸러미가 이 프로젝트에 있으면 이름을 대고 알려 드립니다 — 그 꾸러미가 제대로 안 설 수 있습니다.

잘 안 될 때

진단

지금 무엇이 없어서 안 되는지 한 번에 봅니다. 문의하실 때 이 결과를 함께 보내 주시면 가장 빠릅니다.

초기화

처음 상태로 되돌립니다.

지웁니다 — 로그인 · 작업 사이트 설정 · 프리뷰 열쇠(서버에서도 폐기)
남깁니다 — 받은 소스 폴더와 그 안의 내용

소스는 지우지 않습니다. 폴더까지 지우고 싶으시면 초기화 뒤 안내에 나오는 「폴더 위치 열기」로 찾아 직접 지우십시오. 도구가 사람 파일을 지우지 않는 편이 낫다고 보아 그렇게 두었습니다.

자주 있는 것

「이 계정에 연결된 사이트가 없습니다」 계정은 맞는데 사이트 소속이 없을 때 나옵니다. 잘커라에 문의해 주십시오.

「폴더가 비어 있지 않습니다」 받으려는 폴더에 이미 파일이 있습니다. 빈 폴더를 새로 만들어 그곳에 받으십시오.

프리뷰가 안 열립니다 첫 실행이면 몇 분 기다려 주십시오. 그 뒤에도 안 되면 「진단」을 먼저 보십시오. 아래 「출력」 패널의 잘커라 채널에 진행 내역이 그대로 남습니다.

「받은 파일이 폴더 밖을 가리킵니다」·「항목이 너무 많습니다」 받은 꾸러미가 정상이 아닙니다. 아무것도 풀지 않고 멈춘 것이니 폴더는 그대로입니다. 그대로 잘커라에 알려 주십시오.

안 지키는 약속은 적지 않습니다

소스는 쓰시는 분 것입니다. 언제든 통째로 내려받아 다른 곳에서 고치실 수 있습니다.
이 확장이 없어도 콘솔에서 zip 업로드로 같은 일을 하실 수 있습니다. 여기서 편해질 뿐입니다.
되돌리기 어려운 자리를 만지면 막지 않고 알려만 드립니다. 판단은 쓰시는 분이 하십니다.

이 문서의 최신본은 https://zalkera.github.io/zalkera-devtools/ 에 있습니다. 확장에 함께 담긴 사본은 인터넷이 안 될 때를 위한 것이라, 웹 쪽이 더 새로울 수 있습니다.