개발 개념·용어 사전

1. 파일·폴더·확장자 — 자동화의 입출력

자동화는 사람이 보는 화면이 아니라 파일을 주고받습니다. 확장자(파일 뒤 .xxx)가 그 파일의 성격을 말해줍니다.

왜 중요한가? "엑셀은 사람용, CSV/JSON은 자동화용"이라는 구분만 잡아도 AI에게 일을 정확히 시킬 수 있습니다.

2. 스크립트와 런타임 — 코드를 실제로 실행하는 것

• 스크립트(script): 컴퓨터가 순서대로 실행하는 명령문 묶음(예: analyze.py). 우리 실습의 pipeline/*.py가 스크립트입니다.
• 런타임(runtime): 그 코드를 실행해 주는 엔진. Python 코드는 Python이, JavaScript 코드는 Node.js가 실행합니다.
• 라이브러리/패키지: 특정 일을 대신해 주는 코드 부품(엑셀 처리 pandas, 웹 자동화 playwright 등). pip install로 설치합니다.

비유: 스크립트는 악보, 런타임은 그 악보를 연주하는 악기, 라이브러리는 미리 만들어진 연주 패턴입니다.

3. 터미널·명령줄(CLI) — Claude Code를 쓰는 검은 창

터미널(terminal)은 마우스 클릭 대신 명령어를 타이핑해서 컴퓨터에 일을 시키는 창입니다(윈도우는 PowerShell). Claude Code도 여기서 실행합니다.

• CLI(명령줄 인터페이스): 버튼이 아니라 글자 명령으로 쓰는 방식.
• 경로(path): 파일·폴더의 위치 주소(예: C:\work\project).
• 현재 폴더: 터미널이 지금 보고 있는 폴더. cd 폴더명으로 이동. "이 폴더에서 Claude Code를 연다"가 곧 "자동화의 작업 범위를 정한다"는 뜻.

비개발자 팁: 명령어를 외울 필요 없습니다. "터미널은 폴더 안에서 명령을 받는 창"이라는 것과, 어느 폴더에서 여느냐만 신경 쓰면 됩니다.

4. Git과 버전관리 — "되돌릴 수 있다"는 안전망

Git은 파일(특히 코드)의 변경 이력을 저장하는 도구입니다. 문서의 무한 "수정 기록"이라고 보면 됩니다.

• 커밋(commit): 현재 상태를 한 장면으로 저장. "여기까지 잘 됐음" 도장.
• 되돌리기: 잘못 고쳐도 이전 커밋으로 안전하게 복구.
• GitHub: Git으로 관리한 코드를 클라우드에 백업·공유하는 서비스.

왜 중요한가? 자동화는 고치고 또 고칩니다. "틀려도 되돌릴 수 있다"는 안전망이 있어야 과감히 실험합니다. 강의에서는 명령을 외우지 말고 이 개념만 잡으면 됩니다.

5. API — 프로그램끼리 대화하는 창구 (가장 중요)

API(Application Programming Interface)는 한 프로그램이 다른 프로그램에게 일을 요청하고 응답받는 약속된 창구입니다.

비유: 식당의 주문서입니다. 손님(내 코드)이 정해진 양식으로 주문(요청)하면, 주방(상대 서비스)이 음식(응답)을 돌려줍니다. 주방 내부를 몰라도 주문서 양식만 맞으면 됩니다.

핵심 용어:

• 요청(request) / 응답(response): 내가 보내는 것 / 받는 것.
• 엔드포인트(endpoint): 요청을 보내는 주소(URL).
• API 키(API key): "나는 허가된 사용자다"를 증명하는 비밀 열쇠. 비밀번호처럼 다룸(7번).
• 상태코드(status code): 응답이 잘 됐는지 알려주는 숫자 — 200 성공, 401/403 권한 없음, 404 없음, 429 한도 초과, 500 서버 오류.
• 요청 한도(rate limit)·요금: 대부분의 API는 사용량 제한·과금이 있음.

왜 중요한가? "메일 자동발송", "Gemini 연동", "구글 시트 연동"이 전부 API를 호출하는 일입니다. API 개념 하나면 이 셋이 같은 원리로 보입니다.

6. 인증 방식 — API 키 vs OAuth vs 서비스 계정

API를 쓰려면 "내가 누구인지" 증명하는 인증이 필요합니다. 방식이 셋입니다.

핵심: 구글 스프레드시트·캘린더 등 구글 서비스를 코드로 쓰면 보통 OAuth(개인용) 또는 서비스 계정(자동화용)을 발급받습니다. 어떤 방식이든 그 인증키는 비밀이며 .env/별도 파일로 보관합니다(7번).

7. 환경변수와 비밀키 — 절대 코드에 적지 않기

API 키·비밀번호는 코드에 직접 쓰지 않습니다. 대신 환경변수나 .env 파일에 따로 두고 코드가 불러 씁니다.

.env  (이 파일은 git에 올리지 않는다 → .gitignore에 추가)
GEMINI_API_KEY=여기에_키
GOOGLE_SHEETS_CREDENTIALS=경로/또는/키

• 왜? 코드를 공유하거나 GitHub에 올리면 키가 그대로 노출됩니다. 노출된 키는 남이 내 요금으로 사용할 수 있습니다.
• 규칙: .env는 .gitignore에 넣어 버전관리에서 제외. 키는 화면 공유·캡처에도 주의.

이 강의 사이트도 같은 원칙으로 만들어졌습니다(비밀키 없음, 정적 파일만).

8. 메일 자동발송 — SMTP vs 메일 API

메일을 코드로 보내는 방법은 크게 둘입니다.

우리 실습의 안전 원칙(최지혜 파이프라인과 동일):

1. 코드는 메일을 바로 보내지 않는다. 먼저 초안 + 발송 로그(mail-log)만 만든다.
2. 사람이 내용을 검토하고 승인(approve)해야 발송 "대상"이 된다.
3. 실제 발송은 승인된 건에 대해서만. (강의 데모에서는 실제 발송하지 않음)

왜 이렇게? 자동 발송은 한 번 나가면 되돌릴 수 없습니다. 특히 고객·금융 메일은 반드시 발송 전 사람 승인 단계를 둡니다.

9. 웹훅(Webhook)과 알림 자동화

웹훅은 "어떤 일이 생기면 자동으로 알려줘"를 거꾸로 구현한 것입니다. 내가 계속 물어보는(polling) 대신, 상대 서비스가 정해진 주소(URL)로 알림을 밀어 넣어 줍니다.

• 예: 슬랙 Incoming Webhook — 발급받은 URL로 메시지를 보내면 슬랙 채널에 자동으로 뜸. "보고서 생성 완료" 같은 알림에 사용.
• 메일이 "내가 보내는 것"이라면, 웹훅 알림은 "이벤트가 생기면 자동으로 채널에 뜨는 것".

자동화 맥락: 파이프라인이 끝나면 슬랙/메일로 "검토해 주세요" 알림을 보내는 식으로 사람-승인 흐름과 연결합니다. (여기서도 외부로 나가는 내용은 기밀 확인)

10. AI를 API로 연동 — Gemini·Claude 같은 LLM API

ChatGPT/Gemini/Claude를 채팅창이 아니라 코드에서 부르는 것이 LLM API 연동입니다.

• 내 코드가 "이 자료를 요약해줘" 같은 프롬프트를 요청으로 보내면, 모델이 텍스트를 응답으로 돌려줍니다.
• 토큰(token): 모델이 글을 처리하는 단위(대략 단어 조각). 사용량·요금이 토큰으로 계산됩니다.
• API 키가 필요하고, 키는 .env에 보관합니다(7번).

(개념 흐름)
내 스크립트 → [프롬프트 + API키] → Gemini/Claude API → [요약 텍스트] → 내 파일에 저장

강의 맥락: Claude Code로 만드는 자동화 안에서, 일부 단계(요약·분류·문안 생성)를 LLM API로 처리할 수 있습니다. 단, 회사 기밀·고객정보는 외부 API로 보내기 전에 샘플화/익명화하고, 회사 보안정책(예: 특정 도구 차단)을 따릅니다.

11. MCP — Claude가 내 도구에 연결되는 통로

MCP(Model Context Protocol)는 Claude 같은 AI가 외부 도구·자료(파일, 구글 드라이브, DB, API 등)에 표준 방식으로 연결되게 해주는 약속입니다.

• MCP 서버: "이 도구를 Claude가 쓸 수 있게" 연결해 주는 어댑터. (예: 구글 드라이브 MCP, DB MCP)
• Claude Desktop·Claude Code에 MCP를 붙이면, AI가 그 도구를 직접 읽고/쓰며 일합니다.

구분: API는 "프로그램끼리" 연결하는 일반 개념, MCP는 그중 "AI 비서가 여러 도구를 한 방식으로 쓰게" 표준화한 것. 최지혜님처럼 MCP를 써봤다면, "Claude가 도구에 꽂히는 USB 규격" 정도로 이해하면 됩니다.

12. 구글 스프레드시트 API 연동 — 시트를 코드로 읽고 쓰기

구글 시트를 자동화 입력/출력으로 쓰려면 Google Sheets API로 연결합니다.

개념 흐름:

1. 구글 클라우드에서 API 사용 설정 + 인증 정보(OAuth 또는 서비스 계정) 발급(6번).
2. 그 인증키를 .env/파일로 안전하게 보관.
3. 코드가 시트를 읽기(데이터 입력) 또는 쓰기(결과 기록)로 사용.

언제 쓰나? 입력이 CSV가 아니라 "여러 사람이 같이 보는 구글 시트"일 때, 또는 자동화 결과를 시트에 자동 기록해 팀이 공유할 때. 개념은 5·6번과 동일한 API 호출 + 인증키 보관입니다.

13. 저장소 — 파일·스프레드시트·데이터베이스

자동화 결과를 어디에 쌓느냐의 선택지입니다.

강의 맥락: 처음에는 파일이면 충분합니다. "매월 기록이 쌓이고 과거를 조회"하는 단계가 되면 그때 DB(예: SQLite, Supabase)를 도입합니다. 개념만 알아두세요.

14. 배포(Deployment) — 내 PC를 넘어 누구나 접속하게

배포는 내 컴퓨터에서만 열리던 결과물을 인터넷 주소(URL)로 누구나 접속할 수 있게 올리는 일입니다.

• 로컬(local): 내 PC에서만 보이는 상태(file://로 HTML 열기, localhost로 임시 서버 띄우기).
• 도메인(domain): 사람이 외우는 주소(예: thefavorite.kr).
• noindex: 검색에 안 뜨게 하는 표시(공유는 되지만 검색 노출 차단).

강의 맥락: 우리가 만든 보고서·대시보드 HTML을 링크로 공유하려면 배포가 필요합니다. 다만 실명·기밀이 있으면 비공개 링크 + 검색 차단 + 사용 후 내리기를 지킵니다.

15. 자동 실행 — 스케줄러로 "알아서 매월"

만든 자동화를 정해진 시각에 알아서 실행하게 하는 것이 스케줄링입니다.

• 윈도우 작업 스케줄러 / cron(맥·리눅스): "매월 1일 09시에 run_all.py 실행" 같은 예약.
• 별도 설치 없이, PC가 켜져 있으면 동작.

흐름: 사람이 매번 누르지 않아도 입력만 갈아끼우면 자동으로 결과가 만들어지는 단계가 자동화의 완성형입니다.

16. 실전 문제 — 한글 깨짐·에러·로그 읽기

비개발자가 가장 자주 막히는 지점들입니다. 막히는 건 정상이고, 읽는 법만 알면 됩니다.

• 한글 깨짐(인코딩): 글자 저장 방식이 안 맞으면 한글이 ???나 깨진 문자로 보입니다. 표준은 UTF-8. 엑셀에서 CSV로 저장할 때 "CSV UTF-8"을 고르면 대부분 해결됩니다.
• 에러 메시지: 빨갛게 길게 뜨는 글은 무섭지만, 보통 맨 아랫줄에 핵심 원인이 있습니다("파일 없음", "권한 없음" 등). 그 줄을 그대로 Claude Code에 붙여넣고 "이 에러 고쳐줘"라고 하면 됩니다.
• 로그(log): 프로그램이 "무슨 일을 했는지" 남긴 기록(예: 우리 실습의 mail-log.json, 터미널 출력). 잘못됐을 때 로그부터 봅니다.
• 디버깅(debugging): 문제의 원인을 찾아 고치는 일. AI에게는 "어디까지 됐고 무엇이 안 된다"를 구체적으로 알려줄수록 빨리 고칩니다.

마음가짐: 에러는 실패가 아니라 "여기를 고치라"는 안내문입니다. 메시지를 그대로 AI에게 전달하는 것만으로 대부분 풀립니다.

17. 빠른 용어 사전

다시 강조: 외우지 마세요. "메일·Gemini·구글 시트 = 전부 API 호출 + 인증키 보관", "공유하려면 배포", "되돌리려면 Git", "에러는 맨 아랫줄을 AI에게" — 이 네 줄만 기억하면 충분합니다.