AI 도구로 코드를 짜고 사이트를 띄우는 일이 1년 사이에 누구나 할 수 있는 작업이 됐다. 배포까지는 어찌어찌 된다. 진짜 문제는 그 다음에 시작된다 — 사이트가 안 열리고, 로그에 빨간 글씨가 뜨고, 도메인이 만료됐다는 메일이 오는데, 그 단어들이 무슨 뜻인지 모른다.
모르는 단어로는 검색이 안 된다. 검색이 안 되면 같은 문제로 두 번 막힌다. 이 글은 비개발자가 프로그램을 만들고 운영할 때 가장 자주 마주치는 단어 25개를 6개 분야로 묶어 한 줄씩 정리한 사전이다. 외우라는 게 아니라 막힐 때 한 번 보고 검색어를 만들기 위한 참조용이다. 도구 선택이 먼저인 사람은 클로드 채팅·코드·코워크 입문 글이 먼저다.
1. 소스코드·버전관리 (6개)
코드를 어디에 보관하고, 어떻게 바뀐 흔적을 남기느냐에 관한 단어들이다. GitHub를 한 번이라도 열어본 사람이면 모두 화면에서 본 단어다. 의미를 모른 채 버튼만 눌러도 동작은 하지만, 잘못 눌렀을 때 무엇이 망가졌는지 진단이 안 된다.
코드를 모아두는 한 묶음의 공간. GitHub의 한 프로젝트 페이지가 곧 한 레포다. 변경 이력·이슈·설정이 모두 그 안에 들어 있다.
변경사항 한 묶음 + 짧은 설명 메시지. 저장 버튼이 아니라 "여기까지 한 단위로 기록한다"는 도장이다. 잘못되면 이 단위로 되돌릴 수 있다.
평행하게 갈라진 작업 줄기. main이 본 줄기, 새 기능을 시도할 땐 별도 브랜치에서 작업해 본 줄기를 더럽히지 않는다. 망쳐도 그 브랜치만 버리면 된다.
두 브랜치를 합치는 동작. 사이드 브랜치에서 한 작업을 본 줄기에 가져올 때 머지한다. 같은 줄을 양쪽에서 다르게 고쳤으면 "충돌(conflict)"이 떠서 손으로 골라야 한다.
푸시는 내 컴퓨터의 커밋을 GitHub로 올리는 동작, 풀은 GitHub의 변경을 내 컴퓨터로 내려받는 동작. 푸시 안 하면 GitHub에는 어제 상태 그대로다.
PR (풀 리퀘스트)
pull request · PR
"내 브랜치를 본 줄기에 합쳐주세요"라는 공식 요청. 머지 전 다른 사람이 검토할 수 있게 하는 절차다. 1인 프로젝트면 안 써도 무방하지만 흔적을 남기고 싶으면 쓴다.
2. 빌드·배포·인프라 (6개)
완성된 코드를 어떻게 사용자가 보는 사이트로 띄우느냐에 관한 단어들이다. 비개발자가 가장 많이 막히는 구간이고, 한 번 띄워두면 나중에 또 만질 일이 적어 익히기 전에 잊어버리기 쉽다.
사람이 쓴 소스코드를 컴퓨터가 실행할 수 있는 형태로 변환하는 과정. 사이트는 보통 빌드 결과(HTML·JS 묶음)를 서버에 올리고, 사용자는 그것만 본다. 빌드 실패는 99% 코드 문제다.
빌드 결과를 사용자가 접근하는 서버·플랫폼에 올리는 동작. GitHub Pages·Vercel·Cloudflare에 푸시할 때 자동으로 일어나는 그 과정이다. "deploy 실패" = 사이트가 안 바뀜.
환경변수
environment variable · env
API 키·DB 비밀번호처럼 코드에 직접 박으면 안 되는 값을 코드 밖에 두고 불러 쓰는 장치. .env 파일이나 호스팅 설정 페이지에 넣는다. 이게 안 박혀 있어서 "프로덕션에서만 안 됨"이 자주 일어난다.
도메인은 사람이 외우는 주소(q-bot.kr), DNS는 그 주소를 실제 서버 IP로 연결하는 주소록 시스템. DNS 설정을 바꾸면 전 세계에 퍼지는 데 몇 분~몇 시간 걸린다. "사이트가 안 열려요"의 절반은 DNS다.
호스팅은 내 사이트 파일이 실제로 놓이는 서버. CDN은 그 파일을 전 세계 여러 곳에 복사해 가까운 곳에서 빨리 받게 하는 분산망. GitHub Pages·Vercel·Cloudflare는 호스팅 + CDN을 한 묶음으로 제공한다.
한 번 받은 파일을 일정 시간 보관해두고 재사용하는 장치. 빠른 대신, 코드를 고쳐 배포해도 이전 버전이 보이는 원인이 된다. 이상하면 브라우저 강력 새로고침(Cmd/Ctrl+Shift+R) → 그래도 안 되면 CDN 캐시 비우기 순서.
3. 통신·인증 (5개)
내 사이트가 다른 서비스와 데이터를 주고받을 때 등장하는 단어들이다. AI 기능을 붙이거나 결제·로그인을 연동할 때 거의 한 번씩 부딪힌다.
API
application programming interface
한 프로그램이 다른 프로그램에 일을 시키기 위한 창구. "Claude API를 부른다"는 건 내 사이트 코드가 정해진 형식으로 Claude 서버에 요청을 보내고 답을 받는 것이다. 메뉴판 + 주문 창구라고 보면 가깝다.
API 키 / 토큰
API key / token
API를 부를 때 "이건 나"라고 증명하는 길고 복잡한 문자열. 토큰은 보통 시간이 지나면 만료되는 임시 신분증, 키는 만료 없이 계속 쓰는 영구 출입증에 가깝다. 코드에 박아 GitHub에 푸시하면 즉시 폐기·재발급해야 한다.
CORS
cross-origin resource sharing
A 도메인의 브라우저 코드가 B 도메인 API를 부르는 걸 차단·허용하는 규칙. 콘솔에 "Access-Control-Allow-Origin" 빨간 글씨가 뜨면 이 문제다. 해결은 보통 B 쪽 서버에서 A 도메인을 허용해주는 헤더 추가.
HTTPS / SSL
HTTPS · SSL/TLS
주소창의 자물쇠 표시. 사용자와 서버 사이 통신을 암호화하는 장치다. 인증서가 만료되면 브라우저가 빨간 경고로 막아 사용자가 아예 못 들어온다. 호스팅 플랫폼은 보통 자동 갱신해주지만 직접 발급한 경우 만료일 모니터링 필수.
"구글로 로그인" 버튼 뒤에서 일어나는 위임 인증 방식. 내 사이트가 사용자의 구글 비밀번호를 보지 않고도 "이 사람이 맞다"는 사실만 받아오는 구조다. Client ID·Secret 두 값을 받아 환경변수로 넣는다.
4. 데이터베이스 (3개)
사용자 정보·게시글·주문 같은 "지속적으로 쌓이는 데이터"가 사는 곳에 관한 단어다. 단순 정적 사이트면 안 만져도 되지만, 회원·결제·게시판이 붙는 순간 피할 수 없다.
데이터베이스 / 스키마
database (DB) / schema
DB는 데이터를 보관하는 창고, 스키마는 그 창고의 선반 배치도(어떤 테이블이 있고 각 칸에 무슨 형식의 값이 들어가는지). 스키마가 코드와 어긋나면 저장이 실패한다.
DB 구조를 바꾸는 작업과 그 기록. "users 테이블에 phone 컬럼 추가"처럼 변경을 파일로 남겨 순서대로 적용한다. 로컬에서 먹은 마이그레이션이 프로덕션 DB에 안 먹어 있으면 "DB 컬럼 없음" 에러가 난다.
DB에 묻는 질문 한 줄. SELECT * FROM users WHERE id = 3 같은 형식. AI가 짜준 코드가 내부적으로 만들어 보낸다. 디버깅하려면 한 번은 직접 쳐봐야 한다.
5. 환경·도구 (4개)
코드를 만지는 자리에서 매일 보는 단어들. 의미를 모르면 AI가 시키는 명령을 그대로 따라치면서도 무엇이 일어나고 있는지 모른다.
터미널 / CLI
terminal · command line interface
검은 화면에 글자로 컴퓨터에 명령을 내리는 창구. 터미널은 그 창, CLI는 그 창에서 쓰는 도구(예: git, npm). 마우스·아이콘으로 못 하는 작업의 90%를 여기서 한다.
localhost / 포트
localhost · port
localhost는 "내 컴퓨터 자신"을 가리키는 주소, 포트는 그 안에서 어느 프로그램으로 들어갈지 가리키는 번호. http://localhost:3000은 "내 컴퓨터에서 실행 중인 3000번 프로그램"이라는 뜻. 다른 프로그램이 같은 포트를 쓰면 "port already in use" 에러.
패키지 / 의존성
package · dependency
남이 만들어 공개한 코드 묶음과, 내 프로젝트가 그것에 의지하는 관계. npm install·pip install로 설치한다. package.json·requirements.txt에 어떤 패키지의 어떤 버전을 쓰는지 적혀 있다. 버전이 어긋나면 "어제는 됐는데 오늘 안 되는" 일이 생긴다.
프로그램이 실행되면서 남기는 발자국 기록. 사이트가 안 열릴 때 1순위로 봐야 할 곳이고, AI에 디버깅을 부탁할 때 가장 먼저 붙여줘야 할 자료다. 빨간 글씨(error)·노란 글씨(warning)부터 본다.
6. HTTP 상태 코드 (1세트)
마지막은 단어가 아니라 숫자다. 사이트가 응답하는 세 자리 숫자에는 의미가 정해져 있다. 콘솔이나 네트워크 탭에서 가장 많이 보는 다섯 가지만 알면 진단의 절반이 된다.
정상 처리. 200번대(2xx)는 모두 성공이라는 뜻이다.
서버가 요청을 받았지만 "당신은 권한이 없다"는 거절. 로그인은 했는데 관리자 페이지를 열려고 했을 때 자주 본다.
주소는 도착했는데 거기에 해당하는 페이지·파일이 없다는 뜻. 링크 오타·삭제된 페이지·잘못된 이미지 경로가 원인.
500 Internal Server Error
서버 코드 오류
서버 안의 코드가 처리 도중 터졌다는 뜻. 원인은 100가지가 가능하므로 서버 로그를 봐야 한다. 500번대(5xx)는 모두 서버 쪽 문제다.
앞단(CDN·로드밸런서)은 살아 있는데 그 뒤의 진짜 서버가 응답을 못 한다는 뜻. 배포 직후·서버 재시작 중에 잠깐 보이고, 1~2분 뒤 사라지면 무시. 계속 뜨면 백엔드가 죽은 것.
에러 화면이 떴을 때 첫 번째로 봐야 할 것은 숫자 세 자리. 4xx면 내가 보낸 요청 문제, 5xx면 서버 문제다.
7. 막혔을 때 검색하는 법
이 사전의 진짜 쓸모는 "막혔을 때 정확한 검색어를 만드는 것"이다. 비개발자가 가장 많이 잃는 시간은 검색 자체에 있다 — 무엇으로 검색해야 할지 모를 때다.
막힌 화면에서 다음 순서로 단어를 모은다. 1) 빨간 에러 메시지를 그대로 복사한다. 2) 위 사전에서 등장한 단어가 보이면 그것을 키워드에 추가한다. 3) 사용 중인 호스팅·프레임워크 이름을 더한다(예: "Vercel", "Next.js"). 그 셋을 합치면 처음 보는 에러도 90%는 첫 페이지에서 풀린다.
AI에게 물을 때도 같다. "이거 안 돼요"가 아니라 "로컬에서는 200 OK인데 배포하니 502가 뜨고, Cloudflare 로그에 'Origin connection time-out'이 떴습니다" 식으로 단어를 붙이면 답이 한 번에 온다. 단어가 정확하면 추측이 줄고, 추측이 줄면 토큰을 덜 쓴다.
Q렌즈의 시각
이 25개를 외울 필요는 없다. 막힐 때 한 번 펼쳐 보고 닫으면 된다. 한 단어를 처음 마주친 순간에 그 자리에서 정확한 이름을 알게 되는 것 — 그것이 검색을 가능하게 하고, 검색이 가능해야 같은 문제로 두 번 막히지 않는다.
비개발자가 AI 도구로 프로그램을 만들면 모르는 단어를 그대로 두고도 결과물이 나온다는 점이 이전 시대와 가장 다르다. 모르는 채로 작동하는 시스템을 한 달 뒤·반년 뒤에 다시 열었을 때 무엇이 무엇인지 짚을 단어가 손에 있어야 한다. 그렇지 않으면 같은 도움 요청을 처음부터 다시 해야 한다.
단어를 알면 질문이 짧아진다. 질문이 짧아지면 답이 정확해진다. 사전의 쓸모는 거기서 끝난다 — 더 많은 단어로 자신을 무장시키는 게 아니라, 막힌 자리에서 한 줄을 찾을 수 있게 해주는 것이다.