반응형
개발자 AI 공부 순서 — API 호출부터 에이전트까지 8주 로드맵

AI를 "공부한다"는 말은 너무 넓어서, 어디서 시작할지 몰라 논문부터 펴는 사람이 많다. 코드를 이미 짜는 개발자라면 순서가 다르다. API를 직접 호출해 보고, 컨텍스트를 설계하고, 검색과 도구를 붙이는 쪽이 훨씬 빨리 몸에 붙는다. 이 글은 내가 실제로 밟은 순서를 8주 로드맵으로 정리한 것이다.

30초 요약

궁금한 것답
첫 단계Python으로 API를 직접 호출한다. SDK보다 HTTP 요청/응답 구조를 먼저 본다 (Messages API)
두 번째프롬프트 문장이 아니라 컨텍스트 설계(무엇을 넣고 무엇을 뺄지)를 배운다
세 번째임베딩 + 검색으로 RAG를 직접 만든다. 프레임워크 없이 100줄이면 된다
네 번째도구 호출(tool use) 루프를 손으로 짜본다. 에이전트는 그 루프에 이름을 붙인 것이다
다섯 번째평가 세트와 비용 측정. 이걸 안 만들면 개선인지 아닌지 판단할 수 없다
먼저 버릴 것파인튜닝부터 시작하는 습관, 프레임워크 암기, 논문 1장부터 읽기
기간하루 2시간 기준 8주. 직장인은 12주로 잡아도 충분히 빠르다
비용학습 단계 API 비용은 월 몇 천 원 수준이다. Opus 5.5는 100만 토큰당 입력 $4 / 출력 $20 (pricing)

그림 1. API → 컨텍스트 → 검색 → 도구 → 평가로 이어지는 학습 순서.

목차

  1. AI 공부 순서 전체 지도 — 단계와 8주 일정
  2. 1단계: Python과 HTTP — API를 직접 부른다
  3. 2단계: 프롬프트보다 컨텍스트 — 토큰과 캐시
  4. 3단계: 임베딩과 RAG — 검색을 붙이는 순간
  5. 4단계: 도구 호출과 에이전트 루프
  6. 5단계: 평가와 비용 — 개선을 숫자로 만든다
  7. 2026년에 안 해도 되는 것
  8. 내가 막혔던 곳
  9. 참고 자료

AI 공부 순서 전체 지도 — 다섯 단계

그림 2. 단계별로 "손으로 만들어 보는 것"이 하나씩 있어야 한다.

핵심은 각 단계마다 결과물이 남는가다. 강의를 들었는지는 중요하지 않다. 1단계는 터미널에서 답이 찍히는 스크립트, 2단계는 토큰·비용이 찍히는 로그, 3단계는 내 문서를 검색하는 함수, 4단계는 도구를 스스로 부르는 루프, 5단계는 30개짜리 테스트 세트다.

단계배우는 것결과물흔한 함정
1Python, HTTP, JSON, API 키 관리API 답을 출력하는 스크립트SDK만 쓰고 요청 본문을 모른다
2토큰, 컨텍스트 윈도우, 캐시, 시스템 프롬프트토큰·비용 로그프롬프트만 고치면 된다고 믿는다
3임베딩, 청킹, 벡터 검색내 문서 검색 함수청킹을 대충 해서 검색이 안 된다
4tool use, 종료 조건, 재시도도구를 부르는 에이전트무한 루프로 API를 폭주시킨다
5평가 세트, 회귀 테스트, 비용 한도30문항 테스트 + 리포트감으로 "좋아졌다"고 판단한다

이 순서를 지키는 이유는 뒤 단계가 앞 단계를 재료로 쓰기 때문이다. RAG를 제대로 디버깅하려면 토큰과 컨텍스트를 알아야 하고, 에이전트가 왜 헛도는지 보려면 검색 품질을 알아야 한다.

8주 학습 일정

하루 2시간 기준이다. 각 주의 결과물이 없으면 다음 주로 넘어가지 않는다.

주주제그 주에 남겨야 하는 것
1주Python 복습 + HTTP/JSONAPI 키 숨기는 법, curl로 답 받기
2주SDK로 호출 + 토큰 계산usage를 로그로 남기는 스크립트
3주컨텍스트 설계 + 캐시같은 질문을 3가지 컨텍스트로 비교한 표
4주임베딩 + 벡터 검색내 문서 100개 검색 함수
5주RAG 파이프라인 + 리랭킹출처 붙은 답변, 실패 사례 10개
6주도구 호출함수 2개를 스스로 고르는 루프
7주에이전트 + 로그/재시도최대 스텝·비용 상한이 걸린 실행
8주평가 세트 + 배포30문항 테스트, 비용 리포트 1장

8주가 지나면 "AI를 쓸 줄 아는 개발자"가 아니라 "AI 기능을 만들고 고칠 줄 아는 개발자"가 된다. 이 차이가 이력서에 쓸 수 있는 차이다.

1단계: Python과 HTTP — API를 직접 부른다

Python은 문법 전체를 다시 배울 필요가 없다. 함수, 딕셔너리, 리스트 컴프리헨션, try/except, json 모듈, pathlib 정도면 충분하다. 공식 튜토리얼의 3~7장과 9장이면 시작할 수 있다 (Python Tutorial).

그다음이 진짜 첫 단계다. LLM API를 직접 호출한다. Claude API는 https://api.anthropic.com의 REST API이고, 대화는 POST /v1/messages로 보낸다 (API overview). 구조는 단순하다.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 300,
    "system": "너는 코드 리뷰어다. 문제만 지적한다.",
    "messages": [{"role": "user", "content": "이 파이썬 함수의 버그를 찾아줘: ..."}]
  }'

여기서 확인할 것이 네 가지다. system은 대화 밖 지시라는 점, messages는 user/assistant가 번갈아 쌓이는 배열이라는 점, 응답에 usage(입력·출력 토큰 수)가 함께 온다는 점, model은 콘솔의 Models 페이지에서 복사해 넣는다는 점.

익숙해지면 SDK로 옮겨간다. Python SDK는 pip install anthropic으로 설치하고, 환경변수 ANTHROPIC_API_KEY를 읽어서 같은 요청을 보낸다 (SDK 문서).

from anthropic import Anthropic

client = Anthropic()  # ANTHROPIC_API_KEY 환경변수를 읽는다

msg = client.messages.create(
    model="MODEL_ID",  # 콘솔에서 복사
    max_tokens=300,
    system="너는 코드 리뷰어다. 문제만 지적한다.",
    messages=[{"role": "user", "content": "다음 함수의 버그를 찾아줘:\n" + code}],
)
print(msg.content[0].text)
print(msg.usage.input_tokens, msg.usage.output_tokens)

API 키는 절대 코드에 넣지 않는다. .env에 두고 .gitignore에 추가하거나, macOS라면 Keychain에 넣고 꺼내 쓰는 습관을 처음부터 들인다. 이 단계의 목표는 "모델이 답을 준다"가 아니라 "내가 요청을 조립해서 보낸다"이다.

2단계: 프롬프트보다 컨텍스트 — 토큰과 캐시

프롬프트 팁을 모으는 단계가 아니다. 모델에 들어가는 입력 전체를 설계하는 단계다. 토큰이 무엇이고 왜 비용과 한도의 기준인지는 이미 따로 정리해 두었다 (토큰이란?).

여기서 손에 익혀야 할 것은 세 가지다.

  • 토큰 세기: 요청 전에 토큰 수를 미리 세는 API가 따로 있다 (Token Counting). 긴 문서를 넣기 전에 얼마인지 먼저 확인하는 습관이 비용을 줄인다.
  • 캐시: 반복되는 시스템 프롬프트나 문서 묶음은 캐시에 넣으면 다시 읽는 값이 훨씬 싸다. Opus 5.5 기준 캐시 적중 토큰은 100만 개당 $0.20, 일반 입력은 $4다 (pricing).
  • 컨텍스트 조립: 항상 넣는 것(역할·규칙) / 이번에만 넣는 것(질문) / 필요할 때 검색해서 넣는 것을 구분한다.

이 감각이 없으면 3단계 RAG에서 무조건 실패한다. 검색 결과를 그대로 다 밀어 넣으면 토큰이 터지고, 반대로 너무 줄이면 답이 틀린다. 이 줄다리기가 실무의 절반이다.

3단계: 임베딩과 RAG — 검색을 붙이는 순간

RAG는 검색해서 프롬프트에 붙이는 기술이다. 개념은 RAG가 뭐야에서 정리했고, 공부할 때는 직접 만드는 게 빠르다. 프레임워크 없이 이 순서로 하면 된다.

  1. 문서를 300~800토큰 단위로 자른다(청킹). 문단 경계를 지키고, 잘린 조각마다 제목·출처를 붙인다.
  2. 조각을 임베딩해서 벡터로 바꾸고, 메모리나 SQLite, 또는 pgvector에 저장한다.
  3. 질문도 임베딩해서 코사인 유사도 상위 k개를 꺼낸다.
  4. 꺼낸 조각을 출처 표시와 함께 프롬프트에 넣고 "주어진 근거에 없으면 모른다고 답하라"고 지시한다.

여기서 대부분이 청킹에서 무너진다. 문장 중간에서 잘린 조각은 검색은 되지만 답의 근거로는 쓸 수 없다. 나는 처음에 PDF를 고정 글자 수로 잘라서 "검색은 되는데 답이 이상하다"는 상태를 오래 겪었다.

검색 품질을 올리는 다음 단계는 리랭킹과 하이브리드 검색이다. 키워드 검색(BM25)과 벡터 검색을 같이 돌리고, 결과를 합쳐 상위만 남긴다. 이걸 붙이는 순간 "아, RAG는 검색 시스템이구나"가 이해된다.

4단계: 도구 호출과 에이전트 루프

에이전트는 마법이 아니다. 모델이 "이 함수를 이 인자로 불러달라"고 응답하면, 내 코드가 실제로 실행하고, 결과를 다시 모델에 넣는 반복문이다. 개념 정리는 AI 에이전트란에 있고, 여기서는 구조만 보면 된다.

for step in range(MAX_STEPS):                 # 종료 조건을 먼저 박아둔다
    resp = client.messages.create(
        model="MODEL_ID",
        max_tokens=1024,
        tools=tools,                          # 사용 가능한 함수 스키마
        messages=messages,
    )
    if resp.stop_reason != "tool_use":
        break                                 # 도구 요청이 없으면 끝
    result = run_tool(resp)                   # 내 코드가 실제 실행
    messages.append({"role": "user", "content": result})

배울 것은 함수 스키마 정의, 도구 결과를 어떻게 요약해 넣을지, 실패했을 때 재시도, 그리고 멈추는 조건이다. 이 네 개를 손으로 짜보면 프레임워크가 대신 해주는 일이 보인다.

도구를 여러 프로그램에 걸쳐 재사용하려면 MCP(Model Context Protocol)를 본다. 도구·리소스를 밖으로 빼서 붙이는 표준 규격이고, 스펙과 SDK가 공개돼 있다 (modelcontextprotocol.io). Claude Code 같은 도구가 MCP 서버를 붙여 쓰는 방식도 여기서 이해된다 (Claude Code 설치·사용법).

5단계: 평가와 비용 — 개선을 숫자로 만든다

여기서 갈린다. 취미로 쓰는 사람은 평가를 안 만들고, 실무에 쓰는 사람은 만든다. 방법은 소박하다. 실제로 자주 하는 질문 30개를 모으고, 각 질문에 "정답이 갖춰야 할 조건"을 적는다. 그리고 프롬프트를 바꿀 때마다 같은 세트를 돌려 통과 개수를 비교한다.

봐야 할 숫자왜
정답률(조건 충족 개수)프롬프트 변경이 개선인지 퇴행인지 판단
입력·출력 토큰 평균비용 추세. 캐시 적중률과 같이 본다
지연 시간사용자 경험. 스트리밍 여부를 여기서 정한다
실패 유형 분포검색 실패·형식 위반·환각 중 어디를 고칠지 정한다

비용을 줄이는 수단도 이 단계에서 배운다. 대량 작업은 배치 API가 50% 싸고 (Batch API), 반복되는 앞부분은 캐시로 넘긴다. 모델 등급을 낮추는 것보다 캐시와 배치가 먼저다.

2026년에 안 해도 되는 것

  • 파인튜닝부터 시작하기. 대부분의 문제는 프롬프트와 검색으로 해결된다. 파인튜닝은 형식·말투를 고정할 때 마지막에 쓴다.
  • 프레임워크 암기. 추상화 계층은 자주 바뀌지만 HTTP API와 토큰 구조는 잘 안 바뀐다. 원시 API를 먼저 익히면 어떤 프레임워크가 와도 읽힌다.
  • 논문 1장부터 정독. 공식 문서의 개념 설명이 먼저다. 논문은 "왜 이 설계인가"가 궁금해질 때 찾아 읽으면 훨씬 잘 읽힌다.
  • GPU 서버 사기. 학습 단계에서는 필요 없다. 로컬 추론이 목적이 아니라면 API로 충분하다.

내가 막혔던 곳

처음엔 프롬프트만 잘 쓰면 된다고 생각했다. 실제로 답이 틀리는 원인을 세어보니 대부분 프롬프트가 아니라 컨텍스트였다. 필요한 문서가 안 들어갔거나, 들어갔는데 잘린 조각이라 근거가 안 됐다.

두 번째는 청구서였다. 캐시를 안 쓰고 매 요청마다 같은 긴 문서를 통째로 넣었더니 토큰이 몇 배로 뛰었다. 캐시를 켜고 나서야 같은 작업의 비용이 눈에 보이게 줄었다.

세 번째는 에이전트 루프였다. 종료 조건을 안 넣고 돌렸다가 도구 호출이 계속 이어져서 API 호출이 폭주했다. 지금은 어떤 루프든 MAX_STEPS와 비용 상한을 먼저 쓰고 시작한다. 이건 4단계에서 꼭 몸으로 겪어보길 권한다. 한 번 겪으면 다시는 안 잊는다.

참고 자료

관련 글

반응형
반응형
crontab 사용법 — 5필드 읽는 법과 "안 돌 때" 확인 순서

crontab은 "이 명령을 이 시간에 실행해 달라"를 한 줄로 적어두는 파일이다. 형식은 다섯 칸짜리 시간 필드와 명령 하나로 끝나서 외우기는 쉬운데, 등록해놓고 아무 일도 안 일어나는 일이 잦다. 이 글은 필드 읽는 법부터 등록·확인, 그리고 안 돌 때 어디부터 볼지 순서대로 정리한다.

30초 요약

궁금한 것답
기본 형식분 시 일 월 요일 명령 다섯 필드 뒤에 실행할 명령이 온다 (crontab(5))
언제 검사하나cron 데몬이 매분 crontab을 훑고 현재 시각과 맞는 줄을 실행한다 (cron(8))
등록·확인·삭제crontab -e(편집) · crontab -l(출력) · crontab -r(삭제) (crontab(1))
안 돌 때 1순위PATH. cron은 SHELL=/bin/sh와 HOME·LOGNAME만 자동으로 잡고, 나머지 환경은 내 셸과 다르다
요일과 일자두 필드를 모두 제한하면 둘 중 하나만 맞아도 실행된다 (30 4 1,15 * 5는 1·15일 또는 금요일)
% 문자명령 안의 %는 줄바꿈으로 바뀐다. date +\%Y처럼 역슬래시로 이스케이프한다
주석명령과 같은 줄에 #을 못 붙인다. 그 줄 전체가 명령의 일부로 처리된다
맥macOS man 페이지도 "cron 기능은 launchd로 흡수됐다"고 적는다 (crontab(5) Darwin)
시간대서버가 UTC면 KST 09:00은 UTC 00:00이다. CRON_TZ로 crontab 시간대를 따로 지정할 수 있다

그림 1. 다섯 시간 필드와 명령 한 줄로 끝나는 형식, 그리고 자주 쓰는 표현.

목차

  1. crontab이란 — cron 데몬과 crontab 파일의 관계
  2. 5개 필드 읽는 법 — 분 시 일 월 요일
  3. 자주 쓰는 crontab 예제 — 매분·매일·매주·평일
  4. 등록·확인·삭제 — crontab -e, -l, -r
  5. crontab이 안 돌 때 — PATH와 환경변수부터
  6. 로그 확인 — 어디에 남는지
  7. macOS에서 crontab 대신 launchd를 쓰는 이유
  8. 내가 막혔던 곳
  9. 참고 자료

crontab이란 — cron 데몬과 crontab 파일의 관계

crontab은 데몬이 아니라 파일이다. 백그라운드에서 도는 cron 데몬이 이 파일을 읽고, 현재 시각과 맞는 줄을 찾아 명령을 실행한다. man 페이지는 crontab을 "이 시간에 이 명령을 실행하라"는 지시를 담은 파일로 설명한다 (crontab(5)).

그래서 파일을 직접 열어 고치면 안 된다. crontab -e로 고쳐야 데몬이 알아챈다. cron은 crontab 파일의 수정 시각을 매분 확인하고, 바뀐 파일만 다시 읽는다. 재시작이 필요 없다는 뜻이다 (cron(8)).

사용자마다 자기 crontab을 하나씩 갖고, 그 안의 명령은 그 crontab의 주인 권한으로 실행된다. root crontab에 넣은 명령이 root로 도는 이유가 여기 있다. 시스템 전역 작업은 /etc/crontab이나 /etc/cron.d/에 따로 두는데, 이 파일들은 사용자 이름 필드가 하나 더 붙는다.

5개 필드 읽는 법 — 분 시 일 월 요일

다섯 칸의 허용 범위는 정해져 있다.

순서필드허용 값
1분0-59
2시0-23
3일1-31
4월1-12 (jan-dec 이름 가능)
5요일0-7 (0과 7이 일요일, sun-sat 이름 가능)

각 칸에 쓸 수 있는 문법은 네 가지다 (crontab(5)).

  • * — 그 칸의 처음부터 끝까지 전부
  • 1,15 — 콤마로 나열
  • 1-5 — 범위, 양끝 포함
  • */10 — 간격. 분 칸에 쓰면 0·10·20·30·40·50분

/10은 "10분마다"로 읽으면 되지만, /35처럼 나누어떨어지지 않는 값을 분 칸에 쓰면 35분 간격이 아니라 매시 0분과 35분에 두 번 돈다. 간격 계산이 그 칸 안에서만 이뤄지기 때문이다. man 페이지 NOTES 절이 이 함정을 따로 적어둔다.

요일과 일자를 둘 다 제한하면 AND가 아니라 OR로 동작한다. 30 4 1,15 * 5는 "매월 1일과 15일 4시 30분, 그리고 매주 금요일 4시 30분"이다. 이 동작을 모르면 "왜 금요일에도 돌지"에서 한참 헤맨다.

자주 쓰는 crontab 예제 — 매분·매일·매주·평일

실제로 가장 많이 쓰는 줄만 모았다.

# 매분
* * * * * /usr/bin/date >> /tmp/cron_test.log 2>&1

# 매일 오전 9시
0 9 * * * /Users/me/bin/daily.sh >> /Users/me/logs/daily.log 2>&1

# 평일(월~금) 오후 6시 30분
30 18 * * 1-5 /usr/bin/python3 /Users/me/job.py >> /Users/me/logs/job.log 2>&1

# 10분마다
*/10 * * * * /usr/bin/curl -s https://example.com/health > /dev/null

# 매월 1일 새벽 4시
0 4 1 * * /usr/bin/find /tmp -name "*.tmp" -mtime +7 -delete

# 특정 시각에 파일 이름에 날짜를 붙일 때 (% 이스케이프)
0 7 * * * /bin/echo run_at_$(date +\%Y\%m\%d) >> /tmp/stamp.log

@daily, @hourly, @weekly, @monthly, @reboot 같은 축약형도 있다. 각각 0 0 , 0 , 0 0 0, 0 0 1 *과 같고, @reboot은 부팅 후 한 번 돈다. 축약형은 Vixie cron 계열의 확장이라 다른 구현에서는 지원 여부를 확인해야 한다.

표현식이 헷갈리면 crontab.guru에 넣어 영어 문장으로 풀어보는 게 빠르다. 나는 */2와 0-23/2가 같은 뜻인지 확인할 때 자주 쓴다.

등록·확인·삭제 — crontab -e, -l, -r

편집은 crontab -e로 연다. 편집기는 VISUAL이나 EDITOR 환경변수를 따른다. 저장하고 나가면 그대로 설치되고, 문법이 깨졌으면 저장 단계에서 거부된다 (crontab(1)).

crontab -l                  # 현재 crontab 출력
crontab -e                  # 편집 (EDITOR 환경변수 사용)
crontab -r                  # 전체 삭제 (확인 없이 지워진다)
crontab -l > ~/cron_backup.txt   # 백업
crontab ~/cron_backup.txt        # 파일로 통째로 설치

crontab -r에는 확인 절차가 없다. 지우기 전에 crontab -l로 백업 파일을 하나 떠두는 습관이 안전하다. 리눅스 cronie 쪽에는 설치 전에 문법만 검사하는 crontab -T 파일 옵션도 있다. macOS 기본 crontab에는 이 옵션이 없으니, 맥에서 문법 검사를 하려면 리눅스 컨테이너를 하나 띄워 확인하는 편이 빠르다 (Docker 입문).

사용자별 허용 제어도 있다. /etc/cron.allow가 있으면 그 안에 적힌 사용자만, 이 파일이 없고 /etc/cron.deny만 있으면 그 목록에 없는 사용자만 crontab을 쓸 수 있다.

crontab이 안 돌 때 — PATH와 환경변수부터

"등록은 했는데 로그도 안 남는다"의 대부분은 실행 자체가 안 된 게 아니라 다른 환경에서 실행된 것이다.

cron이 자동으로 잡아주는 건 SHELL=/bin/sh, 그리고 /etc/passwd에서 가져오는 HOME과 LOGNAME 정도다. 내 zsh에서 잡혀 있던 PATH, pyenv, nvm 같은 설정은 crontab에 없다. 그래서 터미널에서 잘 되던 python3 job.py가 cron에서는 command not found로 끝난다.

해결은 두 가지 중 하나를 고른다.

# 방법 1: 절대경로를 쓴다
0 9 * * * /usr/bin/python3 /Users/me/job.py

# 방법 2: crontab 맨 위에서 환경을 직접 잡는다
SHELL=/bin/zsh
PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin
0 9 * * * python3 /Users/me/job.py >> /Users/me/logs/job.log 2>&1

zsh 설정 파일에 PATH를 넣어뒀다면 그 파일을 cron에서 직접 부르는 방법도 있다. . ~/.zshrc && python3 job.py 형태다. 다만 대화형 셸용 설정을 부르면 예상 못 한 출력이 섞이기도 하니, cron용 환경 변수는 crontab 안에 적는 쪽을 나는 선호한다. PATH를 어떻게 잡아야 하는지는 Mac 개발환경 세팅 글에 정리해뒀다.

파이썬이라면 인터프리터 경로가 더 자주 문제가 된다. 가상환경을 쓰는 프로젝트라면 .venv/bin/python을 절대경로로 적어야 한다. venv를 활성화한 상태를 cron이 물려받지는 않기 때문이다. 가상환경 경로 규칙은 venv 만들기 글을 참고하면 된다.

출력도 반드시 파일로 돌려야 한다. cron은 명령의 표준출력과 표준에러를 모아서 메일로 보내려 하고, 메일 설정이 없으면 조용히 사라진다. >> 로그파일 2>&1을 습관처럼 붙이는 이유다. 메일이 아예 필요 없으면 MAILTO=""로 끈다.

로그 확인 — 어디에 남는지

실행 기록은 배포판마다 위치가 다르다.

그림 2. 실행이 안 될 때 보는 순서와 필드 값 범위.

환경확인 명령·경로
데비안·우분투journalctl -u cron -n 50 또는 /var/log/syslog에서 CRON 검색
RHEL·페도라 계열/var/log/cron
macOSlog show --predicate 'process == "cron"' --last 1h

cron 데몬이 inotify 지원으로 뜨면 그 사실을 /var/log/cron에 남긴다는 설명이 man 페이지에 있다 (cron(8)). 로그에 실행 흔적 자체가 없으면 crontab이 로드되지 않은 쪽을 먼저 의심한다. crontab -l로 내용이 보이는지, 서비스가 살아 있는지(systemctl status cron) 순서로 본다.

로그에 실행 흔적은 있는데 결과 파일이 없으면 명령 쪽 문제다. 이때는 명령을 sh -c '...'로 감싸 로그를 남기거나, 스크립트 첫 줄에 set -x를 넣어 어디서 멈추는지 확인한다.

macOS에서 crontab 대신 launchd를 쓰는 이유

맥에서도 crontab은 있다. /usr/bin/crontab이 그대로 남아 있고, macOS 13.7에서도 동작한다. 다만 man 페이지 첫머리에 "Darwin에서 cron과 crontab은 공식 지원되지만 기능은 launchd로 흡수됐다"는 단서가 붙는다 (crontab(5)).

실제로 cron 데몬은 launchd가 관리한다. 내 맥의 /System/Library/LaunchDaemons/com.vix.cron.plist를 열어보면 QueueDirectories에 /usr/lib/cron/tabs가 잡혀 있다. 사용자 crontab이 생기면 launchd가 cron을 띄우는 구조다. 그래서 crontab -l이 "no crontab"인 상태에서는 cron 프로세스가 보이지 않는 게 정상이다.

맥에서 cron이 파일에 손을 못 대는 경우도 있다. 개인정보 보호 기능 때문에 보호된 폴더에 접근하려면 시스템 설정 > 개인정보 보호 및 보안 > 전체 디스크 접근 권한에 /usr/sbin/cron을 추가해야 한다. 이 권한이 없으면 스크립트가 조용히 실패한다.

잠자기에서 깨어날 때 실행을 보장해야 하거나, 로그인 세션과 묶어야 하면 launchd가 낫다. Apple 문서도 백그라운드 프로세스는 launchd로 띄우는 쪽을 권한다 (Creating Launch Daemons and Agents). 서버(Linux)에서는 crontab이 여전히 가장 간단한 선택이다.

내가 막혔던 곳

처음엔 0 9 * python3 job.py가 안 돌아서 crontab 문법을 계속 의심했다. 실제 원인은 PATH였다. 터미널에서는 pyenv가 잡아준 python3가 cron에서는 없었고, 에러는 메일로 사라져서 흔적도 안 남았다. 그 뒤로 cron 명령은 전부 절대경로로 쓰고, 출력은 무조건 파일로 돌린다.

두 번째는 시간대였다. 서버 시간이 UTC인 줄 모르고 0 9 *을 넣었더니 한국 시간 오후 6시에 돌았다. date로 서버 시간을 먼저 확인하고, 필요하면 CRON_TZ=Asia/Seoul을 crontab 맨 위에 둔다.

세 번째는 %였다. date +%Y%m%d를 그대로 넣었더니 명령이 거기서 잘려서 아무 일도 안 일어났다. man 페이지에 적힌 대로 \%로 이스케이프하니 해결됐다. 이 한 줄은 문서를 안 읽으면 못 찾는 종류의 실수다.

마지막은 crontab -r이다. 확인 프롬프트가 없다는 걸 모르고 눌렀다가 예약 작업을 전부 날렸다. 지금은 crontab -l > ~/cron_backup.txt를 수정 전 습관처럼 먼저 친다.

참고 자료

반응형
반응형
Docker 입문 사용법 — 설치부터 이미지·컨테이너 구분까지

Docker는 "내 맥에서는 되는데 서버에서는 안 돼요"라는 말을 줄이려고 만든 도구다. 실행 환경을 이미지로 묶어두면 노트북과 서버가 같은 컨테이너를 띄운다. 이 글은 Docker를 처음 켜는 사람이 설치하고, 컨테이너 하나 띄우고, Dockerfile과 Compose까지 가는 순서를 다룬다.

30초 요약

궁금한 것답
설치Docker Desktop for Mac을 받아 /Applications로 옮기고 실행하면 끝이다. 최소 RAM 4GB가 필요하다 (설치 문서)
무료 범위직원 250명 미만이고 연매출 1,000만 달러 미만인 사업장, 개인·교육·비영리 오픈소스는 무료다 (요금 안내)
이미지와 컨테이너이미지는 실행 파일과 환경을 담은 템플릿, 컨테이너는 그 이미지를 실제로 띄운 프로세스다
첫 명령docker run hello-world — 이미지를 당겨서 컨테이너로 실행하고 로그를 찍고 끝난다 (docker run)
포트-p 8080:80은 내 맥의 8080을 컨테이너의 80에 연결한다. 앞이 호스트, 뒤가 컨테이너다
데이터컨테이너를 지우면 안에 쓴 파일도 같이 사라진다. 남길 것은 볼륨에 둔다 (볼륨 문서)
여러 개 실행compose.yaml 하나에 서비스를 적고 docker compose up -d로 한 번에 띄운다 (Compose)
현재 버전Docker Desktop 4.99.0(2026-11-09), Engine 29.9.3, Compose v5.7.0 (릴리스 노트)

목차

  1. Docker가 뭔가요 — 가상머신과 다른 점
  2. Docker Desktop 설치 — macOS에서 세 단계
  3. 첫 컨테이너 실행 — hello-world가 하는 일
  4. 자주 쓰는 명령 — 이미지와 컨테이너 구분
  5. 포트와 볼륨 — 컨테이너를 지워도 남는 것
  6. Dockerfile로 내 이미지 만들기
  7. Docker Compose로 두 개 같이 띄우기
  8. 내가 막혔던 곳
  9. 참고 자료

Docker가 뭔가요 — 가상머신과 다른 점

Docker는 애플리케이션을 컨테이너라는 격리된 환경에 담아 실행하는 플랫폼이다. 공식 문서는 컨테이너가 가볍고 실행에 필요한 것을 안에 다 담기 때문에, 호스트에 무엇이 설치돼 있는지에 기대지 않아도 된다고 설명한다 (Docker 개요).

구조는 클라이언트와 데몬으로 나뉜다. 내가 터미널에서 docker를 칠 때 그 명령은 Docker 데몬에 REST API로 전달되고, 데몬이 이미지를 당기고 컨테이너를 만든다. 맥에서는 Docker Desktop이 리눅스 VM을 띄우고 그 안에서 데몬을 돌리는 식이다.

가상머신과 자주 비교되는데, 차이는 부팅 단위에 있다.

구분가상머신컨테이너
부팅게스트 OS 전체를 부팅한다호스트 커널을 공유하고 프로세스만 격리한다
무게OS 이미지와 드라이버가 통째로 들어간다앱과 라이브러리만 담는다
용도다른 OS가 필요할 때같은 OS 위에서 앱 환경을 고정할 때

그래서 맥에서 리눅스 바이너리를 돌리는 용도로는 컨테이너가 맞고, 윈도우 데스크톱 앱을 띄우려면 가상머신이 맞다. 이 구분이 잡히면 뒤에 나오는 명령이 훨씬 덜 헷갈린다.

Docker Desktop 설치 — macOS에서 세 단계

설치 파일은 칩에 따라 다르다. 애플 실리콘은 arm64, 인텔 맥은 amd64 빌드를 받는다 (설치 문서).

  1. dmg를 열고 Docker 아이콘을 Applications 폴더로 끌어다 놓는다.
  2. Docker.app을 실행하고 구독 약관 화면에서 Accept를 누른다.
  3. 트레이 아이콘에 고래가 뜨고 docker version이 응답하면 준비 끝이다.

요구 사항은 macOS 현재 버전과 그 이전 두 개 메이저 버전, RAM 4GB 이상이다. 애플 실리콘에서 인텔 바이너리를 돌리는 선택 도구를 쓰려면 Rosetta 2를 설치한다. 최근 버전은 CLI를 $HOME/.docker/bin에 넣고 PATH에 추가하며, 기본 도커 소켓은 만들지 않는다. 이 부분은 Settings > Advanced에서 바꿀 수 있다.

라이선스는 회사 규모를 확인하고 쓰는 게 좋다. 직원 250명 이상이거나 연매출 1,000만 달러 이상인 기업의 상업적 사용은 유료 구독이 필요하다. 정부 기관도 유료다. 개인 학습과 소규모 사업장은 무료 범위에 들어간다 (Docker Desktop 약관).

첫 컨테이너 실행 — hello-world가 하는 일

설치 확인은 보통 이 한 줄로 한다.

docker run hello-world

이 명령은 로컬에 이미지가 없으면 Docker Hub에서 당겨오고, 컨테이너를 만들어 실행한 뒤 로그를 출력하고 종료한다. docker run 문서에도 이미지가 필요하면 pull하고 컨테이너를 시작한다고 적혀 있다 (docker run).

조금 더 만져보고 싶으면 우분투를 대화형으로 띄운다.

docker run -it --rm ubuntu:24.04 bash
# 컨테이너 안에서
cat /etc/os-release
exit

-it는 키보드 입력을 연결하고, --rm은 끝날 때 컨테이너를 지우라는 뜻이다. 여기서 exit를 하면 컨테이너가 사라진다. docker ps -a로 확인하면 --rm을 안 붙인 컨테이너만 목록에 남아 있다.

자주 쓰는 명령 — 이미지와 컨테이너 구분

처음에 가장 많이 헷갈리는 건 이미지와 컨테이너를 같은 것으로 보는 것이다. 이미지는 변하지 않는 템플릿이고, 컨테이너는 그 템플릿에서 만들어진 실행 인스턴스다. 같은 이미지로 컨테이너를 세 개 띄우면 서로 다른 프로세스 세 개가 생긴다.

하고 싶은 일명령
받은 이미지 목록docker images
이미지 받기docker pull nginx:latest
컨테이너 실행docker run -d --name web nginx
실행 중 목록docker ps
종료된 것까지 목록docker ps -a
로그 보기docker logs -f web
안으로 들어가기docker exec -it web bash
멈추기docker stop web
컨테이너 삭제docker rm web
이미지 삭제docker rmi nginx:latest

docker exec는 이미 실행 중인 컨테이너에 셸을 하나 더 붙이는 명령이다. docker run으로 bash를 띄우는 것과 다르다. 실행 중인 서비스 설정을 확인할 때는 exec를 쓴다.

이미지 태그를 생략하면 latest가 붙는다. 운영에 쓸 이미지는 nginx:1.29처럼 버전을 명시하는 편이 안전하다. 태그가 바뀌면 같은 이름으로 다른 이미지가 받아질 수 있기 때문이다.

포트와 볼륨 — 컨테이너를 지워도 남는 것

컨테이너 안의 포트는 기본적으로 밖에서 보이지 않는다. -p로 연결해야 한다.

docker run -d --name web -p 8080:80 nginx
curl -I http://localhost:8080

8080:80은 호스트 8080을 컨테이너 80에 매핑한다는 뜻이다. 순서를 반대로 넣으면 접속이 안 되는데, 이건 뒤에서 다시 얘기한다.

데이터는 더 조심해야 한다. 컨테이너의 쓰기 레이어는 컨테이너와 함께 사라진다. 공식 문서는 볼륨을 컨테이너가 만든 데이터를 보존하는 기본 수단으로 설명하고, 볼륨의 내용은 컨테이너 수명과 별개로 존재한다고 적는다 (볼륨).

docker volume create pgdata
docker run -d --name db -e POSTGRES_PASSWORD=devpass \
  -v pgdata:/var/lib/postgresql/data postgres:17
docker volume ls

개발 중에는 바인드 마운트를 더 자주 쓴다. 내 폴더를 컨테이너 안에 그대로 붙여서, 코드를 고치면 컨테이너 안 파일도 같이 바뀐다.

docker run --rm -it -v "$(pwd)":/app -w /app python:3.12-slim bash

방식예쓰는 곳
볼륨-v pgdata:/var/lib/postgresql/dataDB 데이터처럼 지우면 안 되는 것
바인드 마운트-v "$(pwd)":/app소스 코드를 실시간으로 반영할 때
tmpfs--tmpfs /tmp컨테이너가 죽으면 같이 없어져도 되는 임시 파일

Dockerfile로 내 이미지 만들기

직접 만든 앱을 컨테이너로 돌리려면 Dockerfile을 쓴다. 파이썬 앱 기준으로 최소 구성은 이렇다.

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "app.py"]

빌드는 태그를 붙여서 실행한다.

docker build -t myapp:0.1 .
docker run --rm -p 8000:8000 myapp:0.1

여기서 순서가 중요하다. requirements.txt를 먼저 복사하고 설치한 다음에 나머지 코드를 복사했다. 코드만 바뀌면 마지막 COPY . . 레이어부터 다시 만들면 되고, 의존성 설치 레이어는 캐시로 남는다. 이 순서를 반대로 쓰면 코드 한 줄 고칠 때마다 pip 설치를 다시 한다.

.dockerignore도 같이 두는 게 좋다. .git, __pycache__, .venv를 넣어두면 빌드 문맥이 가벼워진다. 파이썬 가상환경을 컨테이너 안에 또 넣을 이유는 없으니 venv 글에서 만든 .venv는 꼭 제외한다.

이미지 크기를 줄이고 싶으면 베이스 이미지를 -slim이나 -alpine으로 바꾼다. 다만 alpine은 glibc 대신 musl을 쓰기 때문에, 미리 컴파일된 휠이 없는 패키지는 빌드가 깨질 수 있다. 처음에는 slim으로 시작하고 필요할 때 바꾸는 편이 낫다.

Docker Compose로 두 개 같이 띄우기

서비스가 두 개를 넘어가면 docker run을 길게 치는 대신 Compose를 쓴다. 공식 문서는 Compose를 여러 컨테이너 앱을 YAML 하나로 정의하고 한 명령으로 띄우는 도구로 설명한다 (Docker Compose).

services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      - REDIS_HOST=redis
    depends_on:
      - redis
  redis:
    image: redis:7
docker compose up -d
docker compose ps
docker compose logs -f web
docker compose down

Compose 안에서는 서비스 이름이 그대로 호스트 이름이 된다. 그래서 코드에서 localhost:6379 대신 redis:6379로 접속한다. 이 한 줄 때문에 로컬과 배포 환경의 설정 차이가 줄어든다.

docker compose down은 컨테이너와 네트워크를 지우지만 볼륨은 남긴다. 볼륨까지 지우려면 docker compose down -v를 쓴다. 이 차이를 모르면 "DB를 새로 시작했는데 예전 데이터가 그대로" 같은 상황이 생긴다.

내가 막혔던 곳

첫 번째는 포트 순서였다. -p 80:8080으로 띄워놓고 브라우저에서 8080을 열어놓고 왜 안 되냐고 한참을 봤다. 앞이 내 맥, 뒤가 컨테이너라는 걸 외우고 나서야 정리가 됐다. 지금은 -p 호스트:컨테이너를 소리 내어 읽으면서 친다.

두 번째는 데이터였다. --rm으로 컨테이너를 정리하는 습관을 들인 뒤, 볼륨 없이 띄운 PostgreSQL에 테스트 데이터를 넣고 다음 날 전부 날렸다. 컨테이너를 지우면 쓰기 레이어가 같이 사라진다는 걸 문서로만 알고 실제로 겪지 않아서 생긴 일이다. 그 뒤로는 DB는 무조건 볼륨을 먼저 만든다.

세 번째는 맥을 재부팅한 뒤였다. Cannot connect to the Docker daemon at unix:///var/run/docker.sock이 뜨면 Docker Desktop이 꺼져 있는 경우가 대부분이다. 트레이에서 Docker.app을 실행하고 docker info가 응답하는지 먼저 확인한다. 이 오류를 보고 이미지나 컨테이너 문제부터 의심하면 시간이 더 걸린다.

마지막으로 애플 실리콘에서 인텔 이미지를 받을 때 나오는 platform 경고다. 급할 때는 --platform linux/amd64로 맞춰서 띄우면 되지만, 빌드까지 필요하면 멀티 아키텍처 이미지를 만드는 쪽이 오래 간다. 나는 로컬 테스트에서만 platform 옵션을 쓰고 있다.

참고 자료

반응형
반응형
Opus 5.5 effort 추천 — claude.dev가 밝힌 기본값 medium 총정리 (2026)

Opus 5.5를 쓰면서 effort를 high로 두고 있었는데, Anthropic이 직접 운영하는 기술 블로그 claude.dev를 읽고 기본값을 medium으로 내렸다. 결론부터 말하면 대부분의 작업에서 medium이 비용과 품질의 균형점이고, high는 "검증이 필요한 작업"에만 쓰는 게 맞다.

이 글은 claude.dev에 어떤 글이 있는지, Opus 5.5의 effort 단계가 무엇인지, 그리고 왜 medium을 기본으로 두는지 정리한 것이다. 기준은 2026년 11월 14일 공개된 글들이고, 수치는 모두 원문 링크를 달았다.

30초 요약

궁금한 것답
claude.dev가 뭔가Anthropic이 Claude로 개발하는 사람들을 위해 쓰는 기술 블로그다. API 레퍼런스가 아니라 "이렇게 쓰면 어떻게 되는가"를 실험으로 보여준다 (claude.dev)
Opus 5.5 effort 기본값medium이다. Opus 5의 기본값은 high였는데 5.5에서 한 단계 내려왔다 (모델 선택 글)
왜 medium인가SWE-bench Pro에서 medium은 high보다 2.5점 낮고 비용은 약 70%다. low는 8점 낮고 비용은 1/3이다
medium이 모자랄 때먼저 스스로 검증할 수단(테스트·빌드·호출 스크립트)을 준다. 그다음 effort를 한 단계 올린다
effort 올리는 비용high가 작업 전체에 20K thinking 토큰을 더 쓰면 Opus 5.5 기준 $0.40이다. 10턴짜리 재시도 한 번과 비슷하다
명령Claude Code에서 /effort medium, 현재 값은 /effort status다
캐시 주의Opus 5.5는 API 키·구독이면 effort를 바꿔도 캐시가 유지된다. Bedrock·게이트웨이는 바꿀 때마다 캐시가 날아간다
Opus 5에서 옮겨왔다면high를 그대로 들고 오지 말 것. 같은 레벨이라도 5.5가 턴당 더 많이 생각한다

Opus 5.5의 기본값은 medium이다. claude.dev 공개 측정 기준으로 단계별 비용과 성능 차이를 정리한 이미지.

목차

  1. claude.dev란? — Anthropic이 직접 쓰는 기술 블로그
  2. Opus 5.5 effort란 — 한 턴에 얼마나 생각할지 정하는 손잡이
  3. effort 4단계 — low·medium·high·xhigh와 max
  4. 왜 medium이 기본값인가 — Opus 5와 달라진 지점
  5. Claude Code에서 /effort 쓰는 법
  6. effort를 올릴까, 모델을 올릴까 — 비용 계산
  7. 내가 막혔던 곳 — high를 그대로 옮겼다가 토큰만 늘린 일
  8. 상황별 추천 세팅
  9. 참고 자료

claude.dev란? — Anthropic이 직접 쓰는 기술 블로그

claude.dev는 Anthropic이 Claude로 개발하는 사람들을 위해 운영하는 기술 블로그다. 첫 화면 설명이 "technical writing for people building with Claude"다. 공식 문서(docs)와 역할이 다르다. 문서는 파라미터와 제약을 알려주고, claude.dev는 "이 설정으로 실제 작업을 돌려봤더니 이렇게 됐다"를 숫자와 함께 보여준다.

2026년 11월 기준으로 올라와 있는 글 중 내가 먼저 읽은 것들이다.

  • 2026-11-09 Which Claude model should you build with? Fable, Opus, Sonnet, or Haiku — 모델 선택 기준과 기본 effort
  • 2026-11-09 Safely scaling multi-agent teams with Claude Fable 5.2 — 여러 에이전트를 돌릴 때의 통제
  • 2026-10-15 How the Claude Code team does code review — 코드 리뷰 운영 방식
  • 2026-09-25 Using Claude Code: Spending your effort — effort가 결과를 어떻게 바꾸는지
  • 2026-09-25 What a task costs on Opus 5.5 — 작업 한 건의 실제 청구서 구조

claude.dev 첫 화면. 모델 선택, effort, 비용, 코드 리뷰 글이 올라와 있다.

claude.dev 첫 화면. 모델 선택, effort, 비용, 코드 리뷰처럼 Claude Code를 쓰는 사람이 매주 부딪히는 주제가 올라온다.

읽어보면 공통점이 있다. "모델을 올리기 전에 effort를 먼저 조절하라"는 말이 거의 모든 글에 나온다. 토큰 단가를 바꾸는 것보다 작업당 토큰 사용량을 바꾸는 게 먼저라는 뜻이다.

Opus 5.5 effort란 — 한 턴에 얼마나 생각할지 정하는 손잡이

effort는 모델에게 "이 작업에 컴퓨트를 얼마나 쓸 생각인지" 알려주는 값이다. claude.dev의 비유를 빌리면 이렇다. 누가 같은 일을 12시간 안에 해달라고 하면 끝까지 붙잡고 최선을 다할 것이고, 1시간 안에 해달라고 하면 일단 돌아가는 걸 내놓고 거기서 피드백을 받는 쪽을 택한다.

effort를 올리면 모델이 스스로 판단하는 범위가 넓어진다. 코드를 더 읽고, 테스트를 더 만들고, 엣지케이스를 더 확인한다. claude.dev의 표현으로는 "검증과 엣지케이스 테스트에 컴퓨트를 더 쓰는" 방향이다.

중요한 건 effort가 지식이나 실력을 늘려주지는 않는다는 점이다. 모델이 모르는 도메인 규칙을 effort로 알게 되지는 않는다. 그건 모델을 올려야 한다. effort는 같은 모델이 같은 지식을 더 꼼꼼하게 쓰게 만드는 손잡이다.

effort 4단계 — low·medium·high·xhigh와 max

Opus 5.5는 low, medium, high, xhigh 네 단계를 쓰고, 한 세션에 한해 max를 쓸 수 있다. claude.dev가 정리한 기준은 이렇다.

effort 단계별 쓰임과, 결과가 부족할 때 올리는 순서. 기본은 medium, 검증이 필요한 작업만 high 이상.

단계쓰는 상황작업당 토큰작업당 시간(예시)
low브레인스토밍, 스케치, 이름 변경처럼 기계적인 변경가장 적음1분 안팎
medium범위가 정해진 일상 작업, 새 기능 구현low보다 많음몇 분
high검증이 중요한 일, 기존 코드베이스의 버그 수정medium보다 많음10분 안팎
xhigh엣지케이스가 많고 스스로 검증해야 하는 작업high보다 훨씬 많음30분 안팎
max무인으로 끝까지 돌리는 어려운 작업, 보안 취약점 탐색가장 많음가장 김

시간 예시는 claude.dev가 Terminal-Bench 3.0 과제로 공개한 값이다.

같은 과제에서 단계 차이가 결과를 갈랐다는 사례도 같이 공개됐다. HTML 새니타이저를 만드는 과제에서 Fable 5.1은 low에서 5번 중 1번 성공했고 xhigh에서는 5번 모두 성공했다. low 시도는 2분, xhigh 시도는 33분이 걸렸다. Opus 5.5도 저장 엔진 버그 수정 과제에서 low 0/5, xhigh 4/5였고, 선형계획법 솔버 과제에서는 low 0/5, high 5/5였다.

여기서 읽어야 할 건 "그러니 항상 높여야 한다"가 아니다. 엣지케이스가 숨은 작업에서만 차이가 크다는 뜻이다. 매일 하는 기능 구현에는 그만큼의 엣지케이스가 없다.

왜 medium이 기본값인가 — Opus 5와 달라진 지점

Opus 5의 Claude Code 기본값은 high였고, Opus 5.5는 medium이다. 그런데 여기서 많이들 헷갈린다. 같은 이름의 단계가 같은 양의 사고를 뜻하지 않는다.

claude.dev는 이렇게 쓴다. 같은 레벨에서 Opus 5.5는 Opus 5보다 턴당 더 많이 생각하고, 그 차이는 xhigh와 max에서 가장 크다. 그래서 "Opus 5에서 쓰던 high를 5.5에도 그대로 들고 오면 안 된다"고 못 박는다. 5.5에서는 medium에서 시작하라는 뜻이다.

성능과 비용은 이렇게 갈린다. SWE-bench Pro 기준으로 medium은 high보다 약 2.5점 낮은 대신 비용이 high의 약 70%다. low는 약 8점 낮고 비용은 1/3이다. xhigh는 high보다 약 1.4점 높은데 비용이 2.5배다.

정리하면 이렇다. medium에서 high로 올려서 얻는 2.5점을 사려면 30%를 더 내야 하고, 그 위로 더 올리면 점수는 조금 오르는데 값은 두 배 넘게 뛴다. 일상 작업에서 2.5점이 결과를 바꾸는 경우는 드물다. 그래서 기본값이 medium이다.

참고: 이 수치는 claude.dev가 공개한 자체 측정값이다. 내 작업이 같은 분포라고 볼 수는 없으니, /usage로 자기 세션을 한 번 재보는 게 정확하다.

Claude Code에서 /effort 쓰는 법

Claude Code에서는 슬래시 명령으로 바꾼다. 작업 도중에 바꿔도 되고, 바꾼 값은 다음 요청부터 적용된다.

/effort            # 값을 지정하지 않으면 현재 단계 표시/effort status     # 현재 effort 확인/effort medium     # medium으로 변경 (low, high, xhigh, max도 같은 방식)/usage             # 세션 토큰·캐시·비용 확인

API로 직접 호출할 때는 output_config.effort를 쓴다. 2026년 10월 21일 이후로는 temperature·top_p·top_k를 보내면 400이 떨어지니, 세기 조절은 effort로 하는 쪽이 맞다. 이 변경은 Claude API 사용법 글에서 따로 정리해뒀다.

캐시는 결제 방식에 따라 다르게 동작한다. Opus 5.5에서 API 키나 Claude 구독으로 쓰면 effort를 바꿔도 캐시가 유지된다. 어려운 단계만 high로 올렸다가 다시 medium으로 내리는 식이 가능하다는 뜻이다. 반대로 Amazon Bedrock, Google Cloud의 Agent Platform, Claude 앱 게이트웨이를 거치면 effort를 바꿀 때 캐시된 대화가 지워지고, 다음 요청이 전체를 다시 쓰는 값(cache write)으로 청구된다.

Opus 5.5는 thinking이 항상 켜져 있다. 따로 켜고 끄는 설정이 없으니, 사고량은 effort로만 조절한다고 보면 된다.

effort를 올릴까, 모델을 올릴까 — 비용 계산

claude.dev가 제시하는 순서는 명확하다. 결과가 부족할 때 이 순서대로 올린다.

  1. 모델이 스스로 검증할 수단을 준다. 테스트, 빌드, 엔드포인트를 호출하는 스크립트가 여기 해당한다.
  2. 그래도 부족하면 effort를 한 단계 올린다.
  3. 그래도 부족하면 모델을 올린다. 이때는 이전 모델에서 쓰던 단계보다 낮은 effort에서 시작한다.

1번을 먼저 하라는 이유가 있다. 테스트 한 번 돌리는 비용은 턴 한 번과 그 출력이다. effort를 올리면 모든 턴의 사고량이 같이 늘어난다. 검증 수단을 붙이는 쪽이 싸다.

모델을 올리는 판단 기준도 숫자로 나와 있다. 어려운 작업에서 Opus 5.5를 high 위로 더 올리는 대신 Fable 5.2를 낮은 effort로 쓰는 편이 나은 경우가 있다. Fable 5.2는 $8/$40이고 Opus 5.5는 $4/$20이다. 단가만 보면 두 배지만, 작업당 비용으로 보면 캐시 읽기 비중이 큰 긴 작업에서는 격차가 줄어든다.

비용 계산 — medium이 실제로 싸게 끝나는 이유

Opus 5.5의 API 가격은 입력 $4, 출력 $20, 캐시 읽기 $0.20(백만 토큰 기준)이다. 여기서 청구서를 흔드는 건 출력 토큰이다. 출력은 캐시 읽기의 100배 가격이고, thinking도 출력으로 청구된다.

claude.dev의 계산 예시를 보면 이렇다. high가 작업 전체에 thinking 토큰 20K를 더 쓴다면 Opus 5.5 기준 $0.40이다. 캐시 100K를 유지한 채 10턴을 도는 재시도 루프도 출력 10K를 포함해 비슷한 금액이 나온다. 그래서 "high가 재시도를 한 번 줄여준다면 본전이고, medium으로도 한 번에 끝났을 작업이었다면 그냥 버린 돈"이 된다.

턴 수 자체도 비용이다. 매 턴이 지금까지의 대화를 다시 보내기 때문이다. 20K로 시작해 120K까지 커지는 작업을 40턴 돌면 입력 토큰이 280만 개로 계산된다. 대화가 120K를 넘지 않았는데도 그렇다. 이 구조는 컨텍스트 윈도우란 글에서 정리한 것과 같은 이유다.

그래서 실무에서는 이렇게 굴린다.

  • medium으로 먼저 끝내본다. 대부분 여기서 끝난다.
  • 실패하면 검증 수단을 붙인다. 테스트가 없으면 medium은 "요청받은 한 겹"만 고치고 끝낸다.
  • 그래도 안 되면 high로 한 번만 올린다. 그 단계는 문제 지점에만 쓰고 다시 내린다.
  • 무인으로 오래 돌리는 작업만 xhigh나 max로 간다.

내가 막혔던 곳 — high를 그대로 옮겼다가 토큰만 늘린 일

Opus 5에서 Opus 5.5로 넘어올 때 설정을 그대로 복사했다. 모델만 바꾸고 effort는 high로 둔 채였다. 결과는 나쁘지 않았는데, 같은 작업의 출력 토큰이 눈에 띄게 늘었다. claude.dev를 읽고 나서 이유를 알았다. 5.5는 high가 원래 5의 high보다 무거운 자리였고, 5.5의 high는 사실상 이전 세대의 그 위 단계에 가까웠다.

두 번째로 헷갈렸던 건 "medium이 실패하는 모습"이었다. 필드 이름을 바꾸는 작업이었다고 치자. medium은 핸들러를 고치고, 핸들러 테스트까지 통과시켰다. 그런데 클라이언트는 아직 옛 필드를 보내고 있었다. 모델이 시킨 일은 다 했지만, 호출부를 더 읽지 않은 것이다. 처음엔 "medium이 부족하다"고 판단하고 high로 올렸는데, 실제로는 클라이언트까지 지나가는 테스트가 없어서 생긴 문제였다. 테스트를 하나 추가하니 medium에서도 같은 실수를 잡았다.

그래서 지금은 순서를 이렇게 둔다. 모델이나 effort를 의심하기 전에, 이 작업을 모델이 스스로 확인할 방법이 있는지 먼저 본다. 없으면 그걸 먼저 만든다.

상황별 추천 세팅

claude.dev의 기준을 내 작업에 맞춰 정리한 표다. 기본은 Opus 5.5, medium이다.

상황모델effort이유
새 기능 구현, 여러 파일 손보기Opus 5.5medium기본값. 대부분 여기서 끝난다
이름 변경, 패턴 일괄 적용Opus 5.5low판단이 필요 없다. 모델은 그대로 두고 단계만 내린다
기존 코드베이스 버그 수정Opus 5.5high엣지케이스와 부작용 확인이 필요하다
보안 점검, 성능 최적화Opus 5.5high 이상검증 비중이 큰 영역이다
무인 장시간 작업, 대규모 마이그레이션Fable 5.2medium부터Opus 5.5 high로 두 번 실패하면 올린다
분류·추출·라우팅 같은 대량 단순 작업Haiku 5.5medium단가가 가장 낮다
서브에이전트(파일 검색, 로그 요약)Haiku 5.5·Sonnet 5.5각 모델 기본값틀려도 눈에 띄고, 판단은 본 모델이 한다

처음 Claude Code를 켰다면 기본값을 건드리지 말고 medium으로 시작하는 걸 권한다. 프롬프트를 다듬는 쪽이 effort를 올리는 것보다 효과가 큰 경우도 많다. 그 얘기는 프롬프트 작성법 글에 정리해뒀다.

참고 자료

반응형
반응형
VSCode 단축키·설정 정리 — macOS에서 손을 키보드에 붙여두는 법

VSCode는 설치하면 바로 쓸 수 있지만, 기본값 그대로 쓰면 손이 계속 마우스로 간다. 파일을 열 때마다 탐색기에서 폴더를 펼치고, 같은 단어를 하나씩 고치고, 저장할 때마다 정렬을 손으로 맞추는 시간이 하루에 몇십 분씩 쌓인다.

이 글은 내가 맥에서 VSCode를 쓰면서 실제로 손에 붙인 단축키와 settings.json 항목만 골라 정리한 것이다. 기준 버전은 2026년 11월 4일 배포된 안정판 1.145.3이고, 단축키 표기는 macOS 키보드 기준이다 (릴리스 노트).

30초 요약

궁금한 것답
단축키 확인Help > Keyboard Shortcut Reference의 PDF나 키보드 단축키 편집기(⌘K ⌘S)에서 본다 (단축키 문서)
파일 열기⌘P 하나면 폴더 트리를 안 봐도 된다. 열린 탭 전환은 ⌃Tab이다 (코드 탐색)
같은 단어 여러 개⌘D로 다음 일치를 추가하고, 전부 고칠 때는 ⇧⌘L을 쓴다 (기본 편집)
설정 파일 위치사용자 설정은 settings.json, 프로젝트별 설정은 .vscode/settings.json이다 (설정 문서)
저장 시 자동 포맷editor.formatOnSave는 기본 꺼짐이라 직접 켜야 한다
자동 저장files.autoSave 값을 onFocusChange로 두면 탭을 옮길 때 저장된다
설정이 안 먹을 때설정 편집기에서 @modified로 내가 바꾼 항목만 추려 본다
단축키가 안 먹을 때Developer: Toggle Keyboard Shortcuts Troubleshooting으로 어떤 명령이 잡히는지 로그를 본다

목차

  1. 단축키를 외우기 전에 확인할 곳
  2. 파일 이동 단축키 — ⌘P와 ⌃Tab
  3. 편집 단축키 — 접기·줄바꿈·찾기
  4. 멀티 커서 단축키 — 같은 단어를 한 번에
  5. 설정은 settings.json으로 여는 편이 빠르다
  6. 내가 쓰는 settings.json 8줄
  7. 저장할 때 자동 정리 — formatOnSave가 안 먹는 이유
  8. 내가 막혔던 곳
  9. 참고 자료

단축키를 외우기 전에 확인할 곳

VSCode 단축키는 외우는 대상이 아니라 찾아 쓰는 대상이다. 키보드 단축키 편집기를 열면 명령 이름과 현재 키가 같이 나오고, 검색창에 명령 이름이나 키 조합을 넣어 바로 걸러낼 수 있다. 여는 방법은 File > Preferences > Keyboard Shortcuts 또는 명령 팔레트(⇧⌘P)에서 Preferences: Open Keyboard Shortcuts다. 단축키는 ⌘K ⌘S다.

인쇄해서 옆에 두고 싶으면 Help > Keyboard Shortcut Reference를 연다. 플랫폼별 PDF로 내려받을 수 있어서, 나는 맥용을 아이패드에 넣어두고 첫 달에만 봤다.

키보드 배열을 바꿔 쓰면 표기가 달라진다. 독일어 배열에서 ⌘\가 Ctrl+Shift+Alt+Cmd+7처럼 보이는 식이다. 화면에 뜬 키가 안 먹으면 배열부터 확인하는 게 순서다.

기존에 쓰던 에디터가 있다면 키맵 확장을 쓰는 쪽이 빠르다. File > Preferences > Migrate Keyboard Shortcuts from... 메뉴에서 Sublime Text나 Vim 같은 키맵을 고를 수 있다. 나는 Vim 확장을 쓰지 않지만, 회사 동료가 IntelliJ 키맵을 쓰는 걸 보고 이 메뉴의 존재를 알았다.

파일 이동 단축키 — ⌘P와 ⌃Tab

파일을 열 때 탐색기를 펼치는 습관을 끊으면 속도가 바로 달라진다. ⌘P를 누르고 파일 이름 일부만 치면 된다. 경로를 몰라도 되고, 폴더가 깊어도 상관없다.

하고 싶은 일macOS비고
파일 이름으로 열기⌘PQuick Open
열린 탭 목록에서 고르기⌃TabCtrl을 누른 채 Tab으로 이동
이전 편집 위치로⌃-파일·줄 단위로 되돌아간다
다음 편집 위치로⌃⇧-⌃-의 반대 방향
폴더 전체에서 검색⇧⌘Fnode_modules 같은 폴더는 기본 제외
검색 세부 옵션⇧⌘J포함·제외 패턴 입력
정의로 이동F12언어 확장이 지원할 때
브레드크럼으로 이동⇧⌘.경로·심볼 드롭다운

⌃-와 ⌃⇧-는 같은 파일 안에서 왔다 갔다 할 때 특히 유용하다. 정의를 확인하고 원래 자리로 돌아오는 동작이 마우스 없이 끝난다.

브레드크럼은 기본으로 켜져 있다. 파일 경로와 심볼 경로를 보여주고, ⇧⌘.로 포커스를 주면 형제 파일이나 심볼로 바로 이동한다. 화면 위쪽이 좁아 보이면 breadcrumbs.enabled를 false로 두면 된다.

편집 단축키 — 접기·줄바꿈·찾기

코드가 길어지면 접기부터 쓴다. 함수 단위로 접어두면 파일 전체 구조가 한눈에 들어온다.

하고 싶은 일macOS
커서 위치의 영역 접기⌥⌘[
커서 위치의 영역 펼치기⌥⌘]
접기·펼치기 토글⌘K ⌘L
모든 영역 접기⌘K ⌘0
모든 영역 펼치기⌘K ⌘J
자동 줄바꿈 켜기·끄기⌥Z
파일 안에서 찾기⌘F
선택 영역 안에서 찾기⌥⌘L

⌘K로 시작하는 조합은 두 번 눌러야 한다. ⌘K를 누르고 손을 뗀 다음 ⌘L을 누르는 식이다. 처음엔 어색한데, 접기 관련 조합이 전부 ⌘K로 시작해서 한 묶음으로 외우면 편하다.

⌥Z는 세션 단위 토글이라 파일마다 설정이 저장되지는 않는다. 항상 켜두고 싶으면 settings.json에서 editor.wordWrap을 지정해야 한다.

들여쓰기는 VSCode가 파일을 보고 자동으로 판단한다. 2·4·6·8칸 공백을 후보로 보고, 상태 바 오른쪽에 감지된 값을 표시한다. 3칸 들여쓰기를 쓰는 프로젝트라면 editor.detectIndentation을 끄고 editor.tabSize를 직접 정하는 편이 낫다. 나는 이걸 모르고 한참 헤맸다.

멀티 커서 단축키 — 같은 단어를 한 번에

이름을 바꿀 때 하나씩 고치는 건 손해다. ⌘D를 누르면 커서 위치의 단어가 선택되고, 한 번 더 누르면 같은 단어가 다음에 추가된다. 전부 한꺼번에 고치려면 ⇧⌘L을 쓴다.

하고 싶은 일macOS
다음 같은 단어 선택⌘D
같은 단어 전부 선택⇧⌘L
다음 일치 건너뛰기⌘K ⌘D
위·아래에 커서 추가⌥⌘↑ / ⌥⌘↓
선택 영역 확장⌃⇧⌘→
선택 영역 축소⌃⇧⌘←

⌘K ⌘D는 반복되는 단어가 많은 파일에서 특히 쓸모 있다. 주석에 같은 단어가 섞여 있을 때 그 건만 건너뛰고 나머지를 고칠 수 있다.

⌥⌘↑·⌥⌘↓는 그래픽 카드 드라이버가 가로채는 경우가 있다고 문서에 적혀 있다. 맥에서는 보통 잘 동작하지만, 다른 앱에서 같은 조합을 쓰고 있다면 editor.multiCursorModifier를 alt로 두고 클릭 방식으로 바꾸는 편이 안전하다.

설정은 settings.json으로 여는 편이 빠르다

VSCode 설정은 UI 편집기와 JSON 파일 두 곳에서 같은 값을 다룬다. 항목이 많아지면 JSON이 빠르다. 이름을 알고 있을 때 검색창을 거치지 않고 바로 쓸 수 있기 때문이다.

여는 경로는 세 가지다.

  • ⌘, — 설정 편집기(기본은 편집 영역 위 모달)
  • 명령 팔레트에서 Preferences: Open User Settings (JSON)
  • 명령 팔레트에서 Preferences: Open Workspace Settings (JSON) — 프로젝트의 .vscode/settings.json

사용자 설정은 모든 창에 적용되고, 워크스페이스 설정은 그 프로젝트를 열었을 때만 적용된다. 업데이트·보안 관련 설정처럼 워크스페이스에서 덮어쓸 수 없는 항목도 있다.

내가 바꾼 값만 보고 싶으면 설정 편집기 검색창에 @modified를 넣는다. 기본값과 다른 항목만 남는다. "왜 이 파일에서만 줄바꿈이 되지" 같은 상황에서 원인을 찾는 데 제일 빠른 방법이다.

특정 설정으로 바로 가는 URL도 있다. vscode://settings/<설정이름> 형식이라, 사내 문서에 vscode://settings/editor.formatOnSave 같은 링크를 넣어두면 클릭 한 번으로 해당 항목이 열린다.

위 표를 그대로 옮겨 적기보다, 자주 쓰는 항목만 settings.json에 남기고 나머지는 기본값으로 두는 편이 관리가 쉽다.

내가 쓰는 settings.json 8줄

아래는 내 맥의 사용자 설정 중 실제로 손댄 부분만 추린 것이다.

{
  "files.autoSave": "onFocusChange",
  "editor.formatOnSave": true,
  "editor.formatOnPaste": false,
  "editor.rulers": [88],
  "files.exclude": { "**/__pycache__": true, "**/.pytest_cache": true },
  "search.exclude": { "**/node_modules": true, "**/dist": true },
  "editor.multiCursorModifier": "alt",
  "breadcrumbs.enabled": true
}
항목하는 일문서
files.autoSaveoff·afterDelay·onFocusChange·onWindowChange 중 선택. 나는 탭 이동 시 저장기본 편집
editor.formatOnSave저장할 때 포매터 실행. 기본은 꺼짐기본 편집
editor.rulers세로 기준선을 놓을 칸 번호 배열기본 편집
files.exclude탐색기에서 숨길 경로설정
search.exclude검색 결과에서 뺄 경로기본 편집
editor.multiCursorModifier멀티 커서 클릭 조합을 alt 또는 ctrlCmd로기본 편집
breadcrumbs.enabled편집기 위 경로 표시코드 탐색

files.autoSave를 afterDelay로 두면 타이핑을 멈출 때마다 저장된다. 편하지만 저장 시 포맷이 걸려 있으면 커서가 튀는 느낌이 있어서, 나는 포커스가 떠날 때만 저장하는 쪽을 쓴다.

__pycache__와 node_modules를 양쪽에서 빼두면 탐색기가 훨씬 조용해진다. 파이썬 프로젝트를 열 때마다 캐시 폴더가 먼저 보이던 문제도 같이 사라진다.

저장할 때 자동 정리 — formatOnSave가 안 먹는 이유

editor.formatOnSave를 켰는데 아무 일도 안 일어나면 포매터가 없는 언어일 가능성이 크다. VSCode는 언어별 기본 포매터를 내장한 경우도 있지만, 파이썬처럼 확장이 필요한 언어는 별도 설치가 필요하다. 포매터가 여러 개면 어느 것을 쓸지 정해줘야 한다.

저장 시 동작은 세 가지가 따로 있다.

  • editor.formatOnSave — 파일 전체 포맷
  • editor.formatOnPaste — 붙여넣은 범위 포맷. 범위 포맷을 지원하는 포매터에서만 동작한다
  • editor.formatOnType — 한 줄 입력 후 포맷

셋 다 기본값은 꺼짐이다. 자동 저장을 켜두고 포맷도 같이 돌리면 저장 타이밍이 내 손을 떠나므로, 처음 며칠은 저장 단축키(⌘S)로 감각을 확인하는 편이 낫다.

내가 막혔던 곳

가장 오래 헤맨 건 단축키 충돌이었다. ⌘D가 안 먹길래 키보드 문제인 줄 알고 한참을 만졌는데, 원인은 같은 조합을 쓰는 다른 앱이었다. 키보드 단축키 편집기에서 항목을 우클릭해 Show Same Keybindings를 눌렀더니 같은 키에 명령이 여러 개 걸려 있었다. 이 메뉴를 알기 전까지는 설정을 하나씩 지워가며 확인했다.

두 번째는 포커스다. 단축키가 파일에 따라 먹었다 안 먹었다 했는데, 편집기가 포커스를 잃으면 편집 명령이 실행되지 않는다는 걸 늦게 알았다. Developer: Toggle Keyboard Shortcuts Troubleshooting을 켜면 키를 눌렀을 때 어떤 명령이 잡히고 어느 조건에서 막히는지 로그로 나온다. 예를 들어 맥에서 ⌘/를 누르면 editor.action.commentLine이 editorTextFocus && !editorReadonly 조건으로 매칭되는 식이다. 이 로그를 보고 나서야 "안 먹는 게 아니라 조건이 안 맞는 것"이라는 구분이 생겼다.

세 번째는 설정 동기화다. 회사 맥과 집 맥에서 같은 계정으로 설정을 동기화했더니, 예전에 실수로 넣은 files.exclude가 따라와서 특정 폴더가 안 보였다. @modified로 내가 바꾼 항목을 훑고 나서야 찾았다. 그 뒤로는 프로젝트별 설정은 .vscode/settings.json에만 두고, 사용자 설정에는 최소한만 남기고 있다.

참고 자료

반응형
반응형
파이썬 한글 깨짐 해결 — UnicodeDecodeError 원인과 encoding 지정 순서

UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc7 in position 0 같은 줄을 만나면 대부분 encoding='utf-8'을 붙였다가 또 실패하고, 그다음엔 errors='ignore'로 넘겨버린다. 그러면 에러는 사라지지만 글자는 영원히 깨진 채로 남는다.

이 글은 한글 파일을 읽을 때 나는 UnicodeDecodeError를 기준으로, 에러 메시지에서 무엇을 읽어야 하는지와 읽는 쪽·쓰는 쪽을 어떤 순서로 고치는지를 정리했다. 예제는 내 맥의 python3 3.9.6과 최신 문서(Python 3.15 계열)를 함께 확인해서 썼다.

30초 요약

궁금한 것답
에러의 정체파일은 바이트 덩어리이고, 파이썬이 그 바이트를 지정한 코덱으로 글자로 바꾸지 못했다는 뜻이다 (UnicodeDecodeError)
가장 흔한 원인cp949(한국어 윈도우 기본)로 저장된 파일을 utf-8로 읽는 경우. 엑셀 CSV에서 자주 나온다 (표준 인코딩 목록)
1차 처방읽는 코드에 encoding="cp949" 또는 encoding="utf-8-sig"를 명시한다
기본값이 바뀐다Python 3.15부터 UTF-8 모드가 기본이라 open()의 기본 인코딩이 UTF-8이다 (PEP 686)
진단 도구python3 -X warn_default_encoding으로 인코딩을 안 적은 open()을 경고로 잡는다 (PEP 597)
인코딩을 모를 때file -I, charset-normalizer, iconv로 확인·변환한다
절대 하지 말 것errors="ignore"로 덮고 넘어가기. 글자가 조용히 사라진다
반대쪽 에러쓰기·출력에서 막히면 UnicodeEncodeError다. 처방이 다르다

한글 깨짐은 파일 손상이 아니라 코덱 선택 문제라는 것을 정리한 히어로 이미지

목차

  1. UnicodeDecodeError는 왜 나는가
  2. 에러 메시지에서 읽어야 하는 네 가지
  3. 해결 1 — 읽는 쪽에 encoding을 지정한다
  4. 해결 2 — cp949와 BOM(utf-8-sig) 구분
  5. 해결 3 — 인코딩을 모를 때 확인하고 변환하기
  6. 그래도 안 될 때 — 쓰는 쪽과 실행 환경
  7. 증상별 처방 표
  8. 내가 막혔던 곳
  9. 참고 자료

UnicodeDecodeError는 왜 나는가

파이썬 3에서 str은 글자, bytes는 바이트다. 파일을 텍스트 모드로 열면 파이썬이 바이트를 읽어서 코덱으로 글자로 바꾸는데, 이때 바이트가 그 코덱의 규칙에 맞지 않으면 UnicodeDecodeError가 난다. 같은 파일이라도 어떤 코덱을 고르느냐에 따라 성공과 실패가 갈린다.

내 맥에서 직접 확인한 결과다. 같은 "한글"이라는 글자를 utf-8로 저장하면 b'\xed\x95\x9c\xea\xb8\x80', cp949로 저장하면 b'\xc7\xd1\xb1\xdb'가 된다. 이 cp949 바이트를 utf-8로 읽으면 바로 에러가 난다.

>>> "한글".encode("cp949")
b'\xc7\xd1\xb1\xdb'
>>> "한글".encode("cp949").decode("utf-8")
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc7 in position 0: invalid continuation byte

cp949의 첫 바이트 0xC7은 utf-8에서 "앞 글자의 뒤를 잇는 바이트"로만 쓰이는 값이라, 파이썬 입장에서는 문장이 시작하자마자 규칙이 깨진 것이다. 반대 방향도 똑같이 실패한다. utf-8 바이트를 cp949로 읽으면 'cp949' codec can't decode byte 0xed in position 0: illegal multibyte sequence가 나온다.

정리하면 이 에러는 파일이 깨진 게 아니다. 내가 고른 코덱이 파일과 안 맞는 것이다. 파일은 그대로 두고 읽는 쪽을 고치면 된다.

에러 메시지에서 읽어야 하는 네 가지

트레이스백은 생각보다 많은 정보를 준다. 아래 한 줄만 제대로 읽어도 절반은 해결된다.

UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc7 in position 12: invalid continuation byte
보이는 것의미판단
'utf-8' codec내가 지정했거나 기본값으로 잡힌 코덱이 코덱이 파일과 다르다
byte 0xc7문제가 된 바이트 값0x80~0xFF 구간이면 cp949 의심
position 12파일 앞부분 12바이트 지점앞쪽이면 BOM이나 헤더 문제
invalid continuation byte실패 이유utf-8 규칙 위반이면 cp949 파일일 가능성이 크다

position이 0이고 byte가 0xef라면 BOM(Byte Order Mark)이 원인일 수 있다. utf-8 BOM은 EF BB BF 세 바이트다. 이때는 utf-8-sig로 읽으면 BOM을 건너뛴다. 처리 방식은 아래 해결 2에서 따로 다룬다.

어느 파일에서 났는지 안 보이면 트레이스백 위쪽 프레임을 봐야 한다. open()을 여러 번 부르는 코드라면 파일 경로를 로그로 찍는 편이 빠르다. 나는 예외를 잡아서 경로를 붙여 다시 올리는 방식을 쓴다.

try:
    text = open(path, encoding="utf-8").read()
except UnicodeDecodeError as exc:
    raise RuntimeError(f"{path} 디코딩 실패: 코덱={exc.encoding}, 위치={exc.start}") from exc

UnicodeDecodeError에는 encoding, object, start, end, reason 속성이 있어서 어느 지점에서 막혔는지 코드로 꺼낼 수 있다. (내장 예외)

여러 파일을 한꺼번에 읽는 배치라면, 원인을 찾기 전에 -X warn_default_encoding을 붙여 실행해 보는 것도 방법이다. 인코딩을 적지 않은 open()마다 EncodingWarning이 찍힌다. 이 경고는 Python 3.10부터 있고 기본은 꺼져 있다. (PEP 597)

해결 1 — 읽는 쪽에 encoding을 지정한다

결론은 간단하다. 텍스트를 읽는 모든 지점에 인코딩을 적는다. 파이썬 3.15 문서 기준으로, 텍스트 모드에서 encoding을 생략하면 UTF-8이 기본이고, UTF-8 모드가 꺼진 환경에서는 locale.getencoding()이 대신 쓰인다. 즉 같은 코드가 OS와 버전에 따라 다르게 동작할 수 있다. (open())

이 불확실성을 없애려고 파이썬은 3.15부터 UTF-8 모드를 기본으로 켠다. (PEP 686) 그래도 3.14 이하를 쓰는 사람이 많으니, 코드에는 인코딩을 직접 적는 습관이 안전하다.

# 가장 기본
from pathlib import Path

text = Path("메모.txt").read_text(encoding="utf-8")

# 한 줄씩 읽기
with open("로그.txt", encoding="utf-8") as f:
    for line in f:
        print(line.rstrip())

csv 모듈은 newline=""을 같이 넣어야 줄바꿈 처리가 꼬이지 않는다. 엑셀이 만든 파일이면 cp949부터 시도한다.

import csv

with open("주소록.csv", newline="", encoding="cp949") as f:
    rows = list(csv.DictReader(f))

pandas를 쓴다면 read_csv의 encoding 인자로 같은 값을 넘긴다. encoding_errors의 기본값은 'strict'라서, 인코딩이 틀리면 조용히 넘어가지 않고 에러를 낸다. (pandas.read_csv)

import pandas as pd

df = pd.read_csv("매출.csv", encoding="cp949")
df = pd.read_csv("매출.csv", encoding="utf-8-sig")   # BOM 있는 utf-8

JSON은 예외가 적다. 교환용 JSON 텍스트는 UTF-8로 쓰는 것이 표준이고, 파이썬 json 모듈도 그 전제로 동작한다. (RFC 8259 §8.1) 그래도 파일을 직접 열어 읽는다면 인코딩을 적어두는 편이 좋다.

증상별 처방을 한 장에 정리한 카드 — 코덱·BOM·errors 처리 순서

위 코드처럼 읽는 지점마다 encoding을 붙여두면, 나중에 다른 사람이 같은 파일을 열어도 에러 없이 같은 결과를 본다. 인코딩은 "환경이 정해주는 값"이 아니라 "내가 정하는 값"으로 다루는 게 핵심이다.

해결 2 — cp949와 BOM(utf-8-sig) 구분

한국어 환경에서 실제로 마주치는 인코딩은 크게 셋이다. 이름이 비슷해서 헷갈리는데, 파이썬 표준 인코딩 목록에는 cp949가 949, ms949, uhc와 같은 코덱으로 등록돼 있다. (표준 인코딩)

인코딩어디서 나오나읽는 법
utf-8요즘 에디터, 웹, 리눅스·맥 기본encoding="utf-8"
utf-8-sig엑셀의 "CSV UTF-8", 윈도우 메모장 일부 저장encoding="utf-8-sig"
cp949한국어 윈도우의 ANSI 저장, 관공서·공공데이터 CSVencoding="cp949"
euc-kr오래된 웹 페이지, 옛 시스템encoding="euc-kr" (실패하면 cp949)

utf-8-sig는 읽을 때 앞의 BOM을 건너뛰고, 쓸 때는 BOM을 붙인다. (codecs — utf_8_sig) 이걸 안 쓰면 첫 컬럼 이름이 '\ufeff이름'처럼 보이면서, 값은 멀쩡한데 컬럼 매칭만 실패하는 이상한 상황이 된다. KeyError: '이름'이 나는데 눈으로는 똑같아 보이는 증상이 그거다.

cp949와 euc-kr은 겹치는 부분이 많지만 같은 코덱은 아니다. cp949가 euc-kr보다 넓은 문자 집합을 담는다. 그래서 euc-kr로 저장된 파일은 cp949로도 대부분 읽힌다. 반대는 안 된다. 실무 순서는 utf-8 → cp949 → euc-kr로 두는 편이 무난하다.

def read_korean_text(path):
    for enc in ("utf-8-sig", "cp949"):
        try:
            return path.read_text(encoding=enc), enc
        except UnicodeDecodeError:
            continue
    raise UnicodeDecodeError("unknown", b"", 0, 1, f"{path} 인코딩 판별 실패")

이 함수는 BOM 있는 utf-8과 cp949를 모두 잡는다. 다만 "성공했다"가 "제대로 읽혔다"를 보장하지는 않는다. 아래 섹션에서 이 함정을 다룬다.

해결 3 — 인코딩을 모를 때 확인하고 변환하기

파일이 어떤 인코딩인지 모르면 추측보다 확인이 먼저다. 맥·리눅스에서는 file 명령으로 charset을 볼 수 있다.

file -I 주소록.csv          # macOS
file -i 주소록.csv          # Linux

charset=unknown-8bit처럼 나오면 판별에 실패한 것이다. 이럴 때 파이썬에서는 charset-normalizer를 쓴다. requests가 의존성으로 함께 설치하는 라이브러리라 이미 깔려 있는 경우가 많다.

from charset_normalizer import from_bytes

raw = open("주소록.csv", "rb").read()
best = from_bytes(raw).best()
print(best.encoding)          # 예: cp949
text = str(best)

바이너리로 읽어서("rb") 디코딩을 직접 하는 게 요령이다. 텍스트 모드로 열면 그 순간 이미 에러가 나기 때문이다.

이미 인코딩을 알았다면 파일 자체를 utf-8로 바꿔두는 편이 오래 편하다. iconv는 맥과 리눅스에 기본으로 있다.

iconv -f CP949 -t UTF-8 주소록.csv > 주소록-utf8.csv

주의할 점은 짧은 문자열의 인코딩 판별이 원리적으로 불가능하다는 것이다. 바이트 몇 개는 여러 코덱에서 동시에 유효하다. 자동 판별은 "후보를 좁히는 도구"로만 쓰고, 사람이 눈으로 결과를 확인하는 절차를 남겨두는 게 안전하다.

그래도 안 될 때 — 쓰는 쪽과 실행 환경

읽기에서 고쳤는데도 에러가 나면 이번엔 반대쪽이다. UnicodeEncodeError는 글자를 바이트로 바꾸는 과정에서 났다는 뜻이라 처방이 다르다.

첫째, 터미널 출력에서 막히는 경우다. print()가 UnicodeEncodeError: 'ascii' codec can't encode characters로 죽으면 표준출력의 인코딩이 ascii로 잡힌 것이다. 환경 변수로 고정한다.

PYTHONIOENCODING=utf-8 python3 app.py
python3 -X utf8 app.py          # UTF-8 모드 강제

UTF-8 모드는 PYTHONUTF8=1로도 켤 수 있고, 3.15부터는 기본값이다. (PEP 540, PEP 686)

둘째, 파일을 쓸 때 인코딩을 안 적은 경우다. 읽기만 고치고 쓰기는 그대로 두면, 저장된 파일이 실행 환경에 따라 달라진다.

with open("결과.csv", "w", encoding="utf-8-sig", newline="") as f:
    f.write("이름,점수\n")

엑셀에서 다시 열어야 하는 파일이라면 utf-8-sig가 편하다. BOM이 있어야 엑셀이 utf-8로 인식한다.

셋째, 외부 명령의 출력을 읽을 때다. subprocess의 text=True는 로캘 인코딩을 쓰기 때문에, 실행 환경이 바뀌면 깨진다.

import subprocess

out = subprocess.run(["ls"], capture_output=True, text=True, encoding="utf-8").stdout

넷째, 파일 이름 자체가 문제인 경우다. 리눅스에서 잘못된 바이트가 섞인 파일명은 surrogateescape 오류 처리기로 문자열에 담긴다. 이걸 다시 인코딩해야 원래 파일명으로 돌아간다. (에러 처리기)

import os

for name in os.listdir("."):
    raw = name.encode("utf-8", "surrogateescape")

errors 기본값은 strict이고, replace는 깨진 글자를 �로 바꾸며 ignore는 아예 지운다. 데이터를 살려야 하는 자리에서 ignore를 쓰면 행 길이가 달라져서 나중에 원인 찾기 어려운 버그가 된다. (에러 처리기)

증상별 처방 표

지금까지 내용을 증상 기준으로 다시 묶었다. 에러 문구를 그대로 검색해 들어온 사람을 위한 표다.

증상원인처방
'utf-8' codec can't decode byte 0xc7cp949 파일을 utf-8로 읽음encoding="cp949"
'cp949' codec can't decode byte 0xedutf-8 파일을 cp949로 읽음encoding="utf-8"
첫 컬럼명이 \ufeff...로 보임utf-8 BOMencoding="utf-8-sig"
'ascii' codec can't encode (출력)표준출력이 asciiPYTHONIOENCODING=utf-8
pandas UnicodeDecodeErrorread_csv 기본 인코딩encoding= 인자 지정
파일명 처리에서 surrogate 에러잘못된 바이트 파일명surrogateescape
인코딩을 모르겠음판별 필요file -I, charset-normalizer, iconv

내가 막혔던 곳

가장 오래 헤맨 건 공공데이터 CSV였다. pd.read_csv(path)가 UnicodeDecodeError를 내서 encoding="cp949"를 붙였더니 이번엔 읽히는데, 컬럼 이름이 지역이 아니라 \ufeff지역처럼 잡혀서 df["지역"]이 KeyError를 냈다. 화면에 출력된 컬럼명은 멀쩡해 보여서 한참을 의심하지 못했다. BOM은 눈에 안 보이니까. 결국 repr(df.columns[0])로 찍어보고 나서야 원인을 알았다. 지금은 한국어 CSV를 받으면 utf-8-sig를 먼저 시도하고, 실패하면 cp949로 내려간다.

두 번째는 errors="ignore"의 유혹이었다. 급할 때 이걸 붙이면 에러가 사라지고 코드는 끝까지 돌아서 성공한 것처럼 보인다. 그런데 그 뒤에 만든 집계표에서 특정 지역 이름만 비어 있었다. 복구가 안 되는 손실이었다. 그 뒤로는 ignore 대신 replace를 쓰고, 깨진 개수를 세서 로그로 남긴다. 몇 건이 깨졌는지 알아야 데이터를 믿을지 결정할 수 있다.

세 번째는 환경 차이였다. 내 맥에서는 잘 돌던 스크립트가 윈도우 노트북에서 같은 파일을 읽다가 죽었다. 맥은 기본이 utf-8이고 한국어 윈도우는 ANSI 코드 페이지가 cp949라서, 인코딩을 안 적은 open()이 서로 다르게 동작한 것이다. 그때부터 텍스트를 여는 코드에는 예외 없이 encoding을 적는다. 파일을 옮겨 다니는 프로젝트라면 Python 가상환경 venv 만들기처럼 실행 환경을 문서에 남겨두는 습관도 같이 들였다.

참고 자료

반응형
반응형
OpenAI dots란? — 컴퓨터 여러 대에 붙는 AI 에이전트 총정리

스레드에서 "드디어 dot이 여러 대의 컴퓨터에 붙는다"는 글이 돌고, 그 밑에 "코덱스는 신이야"라는 댓글이 붙어 있었다. dot이 뭔지 모르면 이 대화가 무슨 말인지 따라가기 어렵다.

이 글은 dots가 무엇인지, 이번에 무엇이 열렸는지, 실제로 어떻게 설정하는지, 그리고 어디서 막히는지를 OpenAI 공식 문서에서 확인해 정리한 것이다. 2026년 11월 10일 기준 문서 내용이다.

30초 요약

궁금한 것답
dots가 뭔가OpenAI가 2026년 9월 29일 공개한 상시 대기형 AI 에이전트. GPT-6 Astra 기반 (발표문)
이번에 열린 것dot 하나에 컴퓨터를 여러 대 등록하고, 작업마다 어느 컴퓨터를 쓸지 지정할 수 있다 (문서)
설정 방법각 컴퓨터의 ChatGPT 앱 → dot 프로필 → Computers → Allow → Allow access (문서)
동시에 되나스레드마다 컴퓨터 한 대. 여러 대를 같이 쓰려면 컴퓨터별로 스레드를 따로 만들어야 한다 (문서)
조건그 컴퓨터가 켜져 있고 ChatGPT 앱이 열려 있어야 한다. Offline이면 못 쓴다 (문서)
요금ChatGPT Pro 월 $100·$200·$500 또는 Business Premium에 포함 (문서, 요금)
나이·지역Pro 기준 만 18세 이상, EEA·영국·스위스 제외 (문서)

목차

  1. dots란? 한 문단 정의
  2. 이번에 달라진 것 — dot 하나에 컴퓨터 여러 대
  3. 설정은 3단계 — 컴퓨터마다 같은 작업을 반복
  4. 실제로 이게 왜 편한가 — 노트북과 맥을 동시에 쓰는 그림
  5. 한 번에 한 대 — 알아야 할 제약
  6. 요금과 접근 조건
  7. 내가 막혔던 곳
  8. 참고 자료

dots란? 한 문단 정의

dot은 ChatGPT 안에서 돌아가는 개인용 에이전트다. 챗봇처럼 질문에 답하는 게 아니라, 자기 컴퓨터를 하나 받아서 일을 대신 처리한다. OpenAI 발표문은 이렇게 적는다. "dot은 프런티어 지능에 클라우드 컴퓨터, 피드백으로 배우는 능력, 24/7로 목표를 향해 일하는 성질을 붙인 것"이다. (발표문)

그래서 기본값이 "내 컴퓨터를 쓰는 AI"가 아니다. dot은 클라우드에 자기 컴퓨터와 브라우저를 갖고 있고, 내 기기와는 분리돼 있다. 내 노트북을 쓰게 하려면 따로 허용해야 한다. 이 구조를 모르고 쓰면 "왜 내 파일을 못 읽지"에서 막힌다.

모델은 GPT-6 Astra로 시작했고, 2026년 11월 3일부터 GPT-6.1 Terra가 추가됐다. 한 작업 안에서도 부분마다 다른 모델을 쓸 수 있다는 설명이다. (발표문) GPT-6 계열 자체가 궁금하면 GPT-6 Cyber 정리에 배경을 적어뒀다.

이번에 달라진 것 — dot 하나에 컴퓨터 여러 대

이전에는 dot 하나에 컴퓨터 한 대를 붙이는 그림이 기본이었다. 지금 문서는 "컴퓨터를 한 대 넘게 연결하고, 작업마다 어느 컴퓨터를 쓸지 dot에게 말할 수 있다"고 적는다. (문서)

바뀐 지점은 세 가지다.

항목내용
등록컴퓨터마다 ChatGPT 앱에서 한 번씩 허용하면 목록에 쌓인다
선택작업을 시킬 때 어느 컴퓨터에서 돌릴지 지정한다
유지연결은 작업이 끝나도 남는다. 매번 다시 허용하지 않아도 된다

여기서 많이 헷갈리는 부분이 하나 있다. 이 연결은 Codex에 컴퓨터를 연결하는 것과 별개다. Work Sync를 켜는 것과도 별개다. 문서는 "어느 한쪽 연결만으로는 dot이 내 컴퓨터에 접근할 수 없다"고 못 박는다. (문서)

설정은 3단계 — 컴퓨터마다 같은 작업을 반복

설정 자체는 짧다. 대신 컴퓨터 대수만큼 반복해야 한다.

  1. 그 컴퓨터에서 ChatGPT 데스크톱 앱을 연다.
  2. dot 프로필을 열고 Computers에서 지금 쓰는 컴퓨터를 찾아 Allow를 누른다.
  3. 확인 창에서 Allow access를 누른다.

다른 컴퓨터를 추가하려면 그 컴퓨터에서 같은 과정을 한 번 더 하면 된다. (문서)

모바일에서 만든 dot이라도 데스크톱 앱에서 나중에 연결할 수 있다. 반대로 모바일 웹은 지원하지 않는다. 설정은 모바일 앱, 데스크톱 앱, 데스크톱 브라우저 셋 중 아무 데서나 시작해도 되고, 만든 dot은 다른 기기에서 그대로 이어진다. (문서)

권한을 끊을 때는 Revoke access를 쓴다. 상태가 Offline으로 보이는 건 권한이 사라진 게 아니라 그 컴퓨터를 지금 못 쓴다는 뜻이다. (문서)

실제로 이게 왜 편한가 — 노트북과 맥을 동시에 쓰는 그림

스레드 글이 든 예시가 이해가 빠르다. 노트북에서 코딩하는 동안, dot에게 다른 맥의 Xcode에서 iOS 앱을 빌드·테스트하고 결과 화면을 보내달라고 하는 식이다. 서로 다른 컴퓨터에서 같은 오류를 재현하는 것도 같은 원리다.

이게 되는 이유는 dot이 클라우드에서 작업을 조율하고, 실제 실행만 연결된 컴퓨터에서 하기 때문이다. 문서 표현으로는 "작업은 클라우드에서 관리되면서 연결된 컴퓨터의 파일과 도구를 쓴다"이다. (문서)

실무에서는 이런 조합이 나온다.

상황연결하는 컴퓨터시키는 일
앱 개발개발용 맥빌드·시뮬레이터 테스트, 결과 스크린샷
사내 시스템윈도우 사무 PC사내 앱에서만 되는 작업, 로컬 파일 정리
영상·디자인고사양 맥렌더링, 대용량 파일 변환
서버 점검상시 켜둔 맥 미니주기 작업, 로그 확인

Xcode처럼 그 컴퓨터에만 깔린 도구를 쓰는 작업이 대표적이다. 로컬 스킬도 연결된 컴퓨터가 있어야 돈다. (문서)

한 번에 한 대 — 알아야 할 제약

가장 중요한 제약은 "여러 대를 동시에 조종한다"가 아니라는 점이다. 문서는 이렇게 적는다. 컴퓨터별로 별도 스레드를 시작하고, 각 스레드는 한 번에 컴퓨터 한 대를 쓴다. (문서)

제약실제로 겪는 일
스레드당 컴퓨터 1대한 작업에서 A 맥과 B PC를 번갈아 쓰는 건 안 된다. 스레드를 나눠야 한다
컴퓨터가 꺼져 있으면 끝dot이 일할 시간에 그 컴퓨터가 켜져 있고 ChatGPT 앱이 열려 있어야 한다
Offline 표시연결은 살아 있지만 지금은 못 쓴다. 다시 켜면 돌아온다
세션 공유 안 됨내 브라우저 로그인이 dot의 클라우드 브라우저로 넘어가지 않는다
사이트 차단클라우드 브라우저를 막는 사이트는 연결된 컴퓨터로 우회 시도. 보장은 없다

여기에 하나 더. dot의 대화는 Pro·Business Premium의 ChatGPT 사용량 한도에 안 들어가지만, dot이 시작한 Work·Codex 작업은 그 제품의 한도에 그대로 들어간다. (문서) 에이전트를 부려서 아낀 시간이 사용량으로 돌아오는 구조라는 뜻이다.

요금과 접근 조건

dots는 별도 구독이 아니라 ChatGPT 요금제에 붙어 있다. 첫 dot은 추가 비용 없이 포함되고, 여러 dot과 속도·작업량 확장은 앞으로 열린다는 설명이다. (발표문)

플랜월 요금dots 접근
Pro 100$100가능 (만 18세 이상, EEA·영국·스위스 제외)
Pro 200$200가능
Pro 500$500가능
Business Premium사용자당 과금지원 지역에서 가능
Enterprise·Edu·Healthcare별도 계약2026년 11월 18일부터 관리자가 끄지 않으면 기본 켜짐

Pro 요금은 공식 요금 문서의 "월 $100, $200, $500 중 선택" 표기를 그대로 옮겼다. (요금 문서) Business Premium 금액은 사용자 수와 결제 방식에 따라 달라서 여기 적지 않았다.

접근 조건 표에서 눈여겨볼 건 마지막 줄이다. 기업용은 관리자 프리뷰 기간을 거쳐 11월 18일부터 기본값이 켜짐으로 바뀐다. (문서) 회사 계정으로 쓰는 사람은 그날 전에 관리자에게 물어보는 게 안전하다.

내가 막혔던 곳

이 글을 쓰면서 실제로 세 번 걸렸다.

첫째, 한국어 검색으로는 정보가 거의 안 나온다. "닷", "dots", "오픈AI 에이전트"로는 스레드 글과 요약 블로그만 나왔다. 결국 OpenAI 문서 원문을 직접 열어서 읽어야 했다. 문서는 learn.chatgpt.com/docs/llms-full.txt로 전체를 한 파일로 받을 수 있어서, 거기서 "컴퓨터", "연결" 부분을 찾는 게 제일 빨랐다.

둘째, "여러 대 연결"을 처음엔 "여러 대 동시 사용"으로 읽었다. 문서를 두 번 읽고 나서야 스레드마다 한 대라는 걸 확인했다. 블로그 요약 글에 이 제약이 빠져 있는 경우가 많아서, 이 글에는 표로 따로 뺐다.

셋째, Codex에 이미 컴퓨터를 연결해 둔 사람은 dots도 자동으로 될 거라고 생각하기 쉽다. 문서는 명시적으로 별개라고 적는다. 기존 연결이 있다고 dot 설정을 건너뛰면 "왜 파일을 못 읽지"에서 막힌다.

참고 자료

관련 글: GPT-6 Cyber 총정리 · Gemini 사용법 · Cursor 사용법

반응형
반응형
부이(vooy) vs 피클 비교 — 말로 시키는 한국 AI 에이전트, 뭘 골라야 하나 (2026)

요즘 국내에서 "AI 비서"라는 말로 같이 묶여 소개되는 앱이 둘이다. 부이(vooy)와 피클(Pickle). 둘 다 채팅창에 말로 시키면 일을 처리한다고 해서, 처음엔 같은 앱인 줄 알았다.

막상 써보려고 앱스토어 설명을 나란히 놓으니 역할이 꽤 달랐다. 하나는 찾고 비교하고 계획하는 쪽, 다른 하나는 전화하고 결제하는 쪽이다. 이 글은 2026년 11월 9일 기준 공식 사이트와 앱스토어 정보로 둘을 같은 기준에 놓고 비교한 것이다.

30초 요약

궁금한 것부이(vooy)피클(Pickle)
한 줄 정의취향을 학습하는 메신저형 일상 에이전트전화·주문·예약을 실제로 대행하는 에이전트
만든 곳Vooy Korea, Inc. (대표 김서준)Pickle, Inc.
출시iOS 2026-10-19iOS 2026-08-10
플랫폼iOS 앱, 웹, AndroidiOS, Android
평점iOS 3.9 (18개)iOS 4.4 (77개), Android 4.7 (102개)
규모Android 1천+ 다운로드Android 5만+ 다운로드
요금무료무료 + 일일 한도 티켓, Plus 월 ₩15,000
강점취향·맥락 기억, 그룹 대화, 계획 정리전화 대행, 결제, 권한·보안 설계

부이(vooy)와 피클은 같은 ‘AI 비서’로 묶여 소개되지만, 줄여주는 구간이 다르다.


목차

  1. 부이(vooy)란? — 이름부터 낯선 앱
  2. 피클이란? — 이미 한 번 정리한 앱
  3. 한눈에 비교
  4. 같은 부탁을 두 앱에 하면
  5. 요금 비교
  6. 안전과 권한 — 여기서 갈린다
  7. 어떤 사람에게 뭐가 맞나
  8. 내가 막혔던 곳
  9. 참고 자료

부이(vooy)란? — 이름부터 낯선 앱

먼저 이름 정리. 공식 한글 표기는 부이다. 회사명도 (주)부이코리아, 앱스토어 개발자도 Vooy Korea, Inc.다. "보이"가 아니다. vooy는 Virtual Oracle of You의 앞글자를 딴 조합이고, 슬로건은 "당신의 첫 반려 에이전트"다. (vooy 공식 사이트)

하는 일은 이렇게 소개된다. 메신저에서 평소 말하듯 부탁하면, 내 취향과 일정을 바탕으로 정보를 찾고 다음 할 일을 정리해준다. 대표 예시가 식당 찾기, 장보기 계획, 약속 준비, 여행 항공권 최저가, 출근길 브리핑이다. (Google Play)

기능 중 눈에 띄는 건 세 가지다.

  • 취향 기억 — 좋아하는 음식, 선호하는 분위기, 지난 대화의 계획까지 맥락으로 쓴다
  • 그룹 대화 — 친구들과 만날 장소를 찾을 때 단체방 안에서 정보를 나누고 계획을 이어간다
  • 실행 연결 — 추천에서 끝내지 않고 일정과 할 일을 구체적으로 정한다

앱스토어 카테고리는 생산성이 아니라 소셜 네트워킹이다. 채팅 UX를 전면에 둔다는 뜻으로 읽힌다. iOS 16.4 이상, 한국어·영어·일본어를 지원하고, 채용 페이지에는 서울에서 시작해 도쿄·방콕·타이베이·싱가포르로 확장한다는 계획이 적혀 있다. (App Store, 채용 페이지)

부이(vooy) 공식 사이트를 직접 캡처했다. ‘찾고 비교하고 예약하는 일까지’를 전면에 내세운다.


피클이란? — 이미 한 번 정리한 앱

피클은 10월 31일에 이미 단독 글로 정리했다. (피클 AI 총정리) 여기서는 비교에 필요한 부분만 다시 짚는다.

피클은 질문에 답하는 데서 끝나지 않고 실제 행동을 한다. 대신 전화를 걸고, 쿠팡·다이소몰에서 주문·결제하고, KTX·항공권·숙소·병원·식당을 예매한다. 결제나 예매처럼 되돌리기 어려운 일은 진행 전에 승인을 받는다. (pickle.com, Google Play)

가장 독특한 기능은 친구의 피클과 약속 잡기다. 사람끼리 "언제 볼까?"로 시작하는 대화를 양쪽 에이전트가 대신 맞추고, 장소와 식당 예약까지 처리한다.

기술적으로는 권한 설계가 눈에 띈다. 자격증명은 AWS Nitro Enclaves 격리 환경에서만 쓰고, 비밀번호·카드는 기기에서 만든 키로 암호화하며, 권한은 1~30일 기간을 정해 빌려주는 구조다. 자세한 내용은 앞선 글에 정리해뒀다.

한눈에 비교

항목부이(vooy)피클(Pickle)
핵심 동사찾기·비교하기·계획하기전화하기·주문하기·결제하기
대화 방식메신저 채팅, 그룹 대화메시지·음성, 에이전트와 통화
실행 범위확인 후 단계별 안내승인 후 실제 대행
기억하는 것취향, 일정, 지난 대화 맥락메일·일정 기반 할 일 제안
연결자체 앱·웹네이버·카카오톡·지메일·캘린더·정부24·쿠팡·통신사 등
차별 기능그룹 대화로 약속 준비친구 피클과 약속 잡기, 3D 아바타
가격무료무료 한도 + 티켓·Plus
대상계획이 귀찮은 사람전화·결제가 귀찮은 사람

두 앱의 역할을 나란히 놓았다. 부이는 계획 쪽, 피클은 실행 쪽에 가깝다.


표의 세 번째 줄이 가장 중요하다. 부이의 공식 설명은 예약·주문·일정을 "확인 후 단계별로 안내"하는 쪽에 가깝다. 피클은 같은 일을 대신 실행한다. "AI 에이전트"라는 같은 단어를 쓰지만, 손을 대는 지점이 다르다. 애초에 에이전트가 챗봇과 어떻게 다른지는 AI 에이전트란에 정리해뒀다.

같은 부탁을 두 앱에 하면

말로 비교하는 것보다 상황을 하나 놓는 편이 낫다. "이번 주말에 친구 셋이랑 성수에서 점심 먹고 전시 보려는데, 다들 시간 맞춰서 예약까지 해줘"라고 부탁한다고 치자.

부이 쪽 흐름

  1. 셋의 가능한 시간대를 대화로 정리한다
  2. 성수 식당 후보를 취향에 맞춰 비교한다
  3. 전시 시간과 동선을 묶어 일정으로 정리한다
  4. 예약은 확인 후 단계별로 안내한다

피클 쪽 흐름

  1. 친구의 피클과 대화해 빈 시간을 맞춘다
  2. 식당을 예약하고, 필요하면 전시 예매까지 처리한다
  3. 결제가 들어가면 승인을 요청한다
  4. 끝나면 결과를 요약해 알려준다

둘 다 "카톡 20개"를 줄여주지만, 줄어드는 구간이 다르다. 부이는 생각하고 정하는 구간, 피클은 전화하고 결제하는 구간이다. 같은 부탁도 어디까지 맡길 수 있는지가 다르다.

요금 비교

항목부이(vooy)피클(Pickle)
기본무료무료 (일일 한도)
한도 소진 시해당 없음티켓 ₩2,900 ~ ₩58,000
구독없음Pickle Plus 월 ₩15,000

출처는 각 앱스토어 표시 가격이다. (App Store vooy, Google Play 피클)

부이는 현재 무료다. 초기 사용자 확보 단계라 언제 유료화해도 이상하지 않다. 피클은 무료 한도가 있고, 전화·예매처럼 오래 걸리는 작업이 한도를 많이 먹는 구조다.

안전과 권한 — 여기서 갈린다

에이전트 앱에서 진짜 비용은 구독료가 아니라 사고 났을 때의 비용이다. 두 앱의 공개 자료를 같은 기준으로 놓으면 이렇게 된다.

확인 항목부이(vooy)피클(Pickle)
수집 데이터위치, 연락처, 사용자 콘텐츠, 식별자, 사용 데이터, 진단 등연결한 앱의 데이터, 결제·예약 기록
자격증명 보관공개 자료 없음격리 환경(Credential Enclave) + 기기 키(Vault)
권한 기간공개 자료 없음1~30일 Grant, 만료 시 파생 키 삭제
감사 기록공개 자료 없음write-once 저장, 365일 보관
승인 절차확인 후 진행결제·예매 전 승인 필수

부이 쪽 "공개 자료 없음"은 문제가 있다는 뜻이 아니라, 아직 보안 설계 문서를 공개하지 않았다는 뜻이다. 신생 앱에서는 흔한 일이다. 다만 위치·연락처·연락처 정보까지 수집한다고 앱스토어에 표시돼 있으니, 가입 전에 권한을 어디까지 줄지 직접 확인하는 게 좋다. (App Store 개인정보)

피클은 반대로 보안 문서를 먼저 공개한 쪽이다. 실제 사고가 없었다는 뜻은 아니지만, "무엇을 어떻게 지키는지"를 읽고 판단할 재료가 있다는 건 선택에 도움이 된다.

어떤 사람에게 뭐가 맞나

부이가 맞는 경우

  • 여행·외식·모임 준비에서 "뭐가 좋을지" 비교하는 시간이 아깝다
  • 친구들과 계획 맞추는 대화가 길어지는 편이다
  • 결제까지 맡기는 건 아직 부담스럽다

피클이 맞는 경우

  • 통신사·보험사·병원 전화 대기가 싫다
  • KTX·항공권·숙소 예매를 자주 한다
  • 승인만 하면 결제까지 맡기고 싶다
  • 권한이 어떻게 통제되는지 확인하고 쓰고 싶다

둘 다 쓰는 경우

부이로 계획을 세우고, 피클로 실행하는 조합이 이론상 가장 자연스럽다. 다만 앱을 두 개 오가야 해서, 한쪽이 다른 쪽 기능을 흡수하는 방향으로 빠르게 바뀔 가능성이 크다. 두 회사 모두 초기 단계라 석 달만 지나도 그림이 달라질 수 있다.

내가 막혔던 곳

두 앱 모두 전화번호 인증이 필요해서, 내가 대신 가입해 실제로 돌려보지는 못했다. 그래서 이 글에는 내가 만든 사용 화면이 아니라 공식 페이지 캡처만 들어간다. 후기 글을 쓸 때 늘 아쉬운 부분이다.

대신 확인하면서 헷갈렸던 지점을 남긴다. 첫째, "부이"를 "보이"로 검색하면 결과가 잘 안 나온다. 회사명이 (주)부이코리아라서 한글 표기는 부이다. 둘째, 두 앱의 앱스토어 카테고리가 다르다. 부이는 소셜 네트워킹, 피클은 생산성이다. 카테고리만 봐도 설계 철학이 갈린다는 걸 알 수 있다.

셋째, "AI가 예약해준다"는 문구를 액면가로 믿으면 안 된다. 부이는 안내까지, 피클은 대행까지다. 같은 문장처럼 보여도 내가 마지막에 버튼을 눌러야 하는지, AI가 누르는지가 완전히 다른 경험이다. 가입 전에 이 차이를 먼저 확인하는 걸 권한다.

참고 자료

반응형

+ Recent posts