AI 핸드북 on RanceLee的博客

AI 시대에 첫걸음

Mon, 01 Jan 0001 00:00:00 +0000

친구여, 지난 2년간 AI의 발전 속도는 망설일 여유를 주지 않았습니다.

저는 주식 시장에서 10년 경력을 가진 트레이더로, 코딩을 할 줄 모릅니다. 하지만 2024년 초부터 ChatGPT를 사용하기 시작했고, 지금은 Claude Code로 Obsidian 노트를 읽고, Codex로 컴퓨터를 자동화하며, Skill로 워크플로를 체계화하고 있습니다. 이 모든 과정을 완전한 초보자의 시각에서 겪었습니다—함정에 빠지고, 튜토리얼을 작성하고, 이를 다시 제 워크플로에 통합하면서요.

이 책은 지난 1년간 제가 작성한 27개의 AI 튜토리얼을 하나의 실로 엮었습니다. 기술 원리에 관한 것이 아니라 코딩을 할 줄 모르는 사람이 어떻게 이 도구들을 실제로 활용할 수 있는지에 관한 것입니다.

AI 도구는 빠르게 진화하므로…

⚠️ 이 책의 스크린샷, 명령어, 워크플로는 여러분이 읽을 시점에는 최신 버전과 다를 수 있습니다.

지속적으로 개정하겠습니다:

주요 업데이트가 있으면 PDF에 반영하겠습니다. 구매자는 언제든지 최신 버전(또는 원본 Obsidian 버전)을 요청하실 수 있습니다.
Q&A 그룹에서 직접 물어보세요. 저는 이 도구들을 매일 사용하며, 변경 사항이 생기면 즉시 확인하겠습니다.

읽는 방법

메인 흐름대로 읽기:

1부: 기초 – AI 대규모 모델, 주요 도구, 등록 및 결제, Markdown—사용할 것들을 이해합니다.
2부: API – API, 토큰, 캐싱—실습에 필요한 기술 개념.
3부: 강력한 도구 – Claude Code, Codex CLI, Codex App 및 다양한 새로운 기능—주요 도구를 직접 다뤄봅니다.
4부: 고급 – Skill, MCP, Hook + PUA 마인드셋—AI를 더 깊이 사용하는 핵심.
5부: 실습 – Bilibili를 텍스트로, DeepSeek와 Claude, Open Minis—구체적이고 재현 가능한 예제.
보너스 – N8N 같은 무거운 도구—아마 필요하지 않을 겁니다.

필요할 때 읽기:

목차에서 가장 해결하고 싶은 문제를 찾아보세요 (예: Claude Code 사용법, Skill 작성법, API 릴레이 설정법).

따라 하기:

읽으면서 직접 컴퓨터에 설정해보세요—열 번 읽는 것보다 효율적입니다.

이 책이 적합하지 않은 독자

❌ 고급 AI 사용자 (Cursor, Cline, Aider를 1년 이상 사용해온 분).
❌ 바로 사용할 수 있는 솔루션을 원하며 도구 설정에 시간을 들이지 않으려는 분.
❌ 읽고 나서 AI로 월 수천만 원을 벌 수 있는 빠른 해결책을 기대하는 분.

돈을 낭비하게 하느니 차라리 적게 팔겠습니다.

1부 · 기초: AI가 무엇이고 무엇을 할 수 있는가

AI로 5분 만에 무료 HTML 페이지 만들기

Mon, 01 Jan 0001 00:00:00 +0000

이 챕터가 존재하는 이유: 50위안에 거의 심장마비가 올 뻔했다

이 챕터를 쓰게 된 이유는 간단합니다. 친구가 간단한 룰렛 웹페이지 하나 만드는 데 50위안을 썼다는 이야기를 들었기 때문입니다.

그 이야기를 듣고 저는 거의 심장마비가 올 뻔했습니다.

50위안이 비싸다는 게 아닙니다. 이런 건 무료 AI로 5분이면 만들 수 있거든요!

진심으로, 이런 필요가 있다면 저한테 직접 50위안을 팁으로 주고 단계별로 가르쳐 달라고 해도 그런 서비스에 돈을 주는 것보다 낫습니다. 적어도 제 튜토리얼은 무료이고, 모든 단계를 명확히 설명해 드리니까요.

그래서 이 챕터는 특별 추가편으로, 무료 AI를 사용해 간단하지만 실용적인 HTML 페이지를 만드는 방법을 구체적으로 알려드립니다.

중요 알림: 먼저 무료 웹 버전에 익숙해지세요

본격적으로 시작하기 전에 한 가지 강조하고 싶습니다.

현재 AI 웹 버전은 이미 매우 강력합니다. 프로그래밍 지식이 필요 없고, 소프트웨어를 설치할 필요도 없으며, 그냥 브라우저를 열어서 사용하면 됩니다.

AI 웹 버전으로 무엇을 할 수 있을까요?

대화하고 질문에 답하기
이미지 인식 및 내용 분석
코드 작성 및 웹페이지 제작
PPT 및 보고서 만들기
문서 번역 및 요약
그 외에도 많습니다…

제 제안: 초보자는 먼저 무료 웹 기반 AI에 능숙해진 후에 API 같은 고급 도구를 고려하세요.

왜냐하면 웹 버전은:

완전 무료입니다 (또는 넉넉한 무료 할당량 제공)
사용법이 간단하고 배우기 쉽습니다
이미 충분히 강력합니다
문제가 생기면 AI에게 바로 물어볼 수 있습니다

이제 본론으로 들어갑니다: AI를 사용해 룰렛 웹페이지 만들기.

AI Studio를 사용해 HTML 웹페이지 만들기

1단계: Google AI Studio 접속

Google의 공식 무료 AI 플랫폼인 Google AI Studio를 사용합니다.

왜 이것을 선택했나요?

완전 무료
Gemini 3 Pro가 강력함
웹페이지 제작 같은 복잡한 작업에 적합

단계:

https://aistudio.google.com 열기
Google 계정으로 로그인 (VPN/프록시 필요)
메인 인터페이스 진입

2단계: Playground 및 모델 선택

로그인하면 AI Studio의 메인 인터페이스가 보입니다.

단계:

왼쪽 메뉴에서 “Playground” 클릭
오른쪽 상단 모델 선택기에서 Gemini 3 Pro 선택
- Flash는 선택하지 마세요. Pro가 더 강력합니다.
- 특히 코드 작성 같은 복잡한 작업에 적합
왼쪽이 채팅 인터페이스이고 하단에 입력 상자가 있는지 확인 이제 AI와 대화할 준비가 되었습니다.

3단계: 프롬프트 입력하여 AI가 웹페이지 생성하도록 하기

이 단계가 핵심입니다: AI에게 원하는 것을 명확히 알려줘야 합니다.

구체적일수록 좋습니다! “룰렛 웹페이지 만들어 줘"라고만 하지 말고, 다음과 같이 구체적으로 말하세요:

어떻게 생겼는지
어떤 기능이 있는지
사용 방법
어떤 스타일인지

완전한 프롬프트 예시

아래 텍스트를 복사하여 AI Studio의 입력 상자에 붙여넣으세요:

Please help me generate a lottery wheel webpage.

If no prizes are specified, use default prizes: Grand Prize, First Prize, Second Prize, Third Prize, Lucky Prize, Try Again.

Functional requirements:
- Beautiful wheel design, supporting 6-8 sectors
- A "Start Lottery" button in the center
- Click the button to spin the wheel
- The spin should have acceleration and deceleration effects for realism
- After stopping, a popup shows the result
- Click the popup to close and spin again

Design requirements:
- Festive and grand style (mainly red and gold)
- The wheel border should have texture
- Each sector should have alternating colors
- A pointer indicating the current position
- Responsive for mobile and desktop

After completion, please explain:
1. How to open and use it
2. How to modify the prize names
3. How to adjust the winning probability

Use example prizes: iPhone 16, AirPods, 100 yuan red envelope, 50 yuan red envelope, Try Again

단계:

위 프롬프트를 복사하여 입력 상자에 붙여넣기
“실행” 버튼을 클릭하거나 Enter 키 누르기
AI가 생성할 때까지 기다리기 (보통 10~30초)

4단계: AI가 완전한 HTML 코드 반환

AI가 생성을 완료하면 큰 코드 블록이 표시됩니다.

AI의 응답에는 일반적으로 다음이 포함됩니다:

HTML 코드: 완전한 웹페이지 파일
사용 설명: 여는 방법과 수정 방법
맞춤 가이드: 상품 변경 및 확률 조정 방법

코드는 다음과 같습니다:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Lottery Wheel</title>
    <style>
        /* Style code here */
    </style>
</head>
<body>
    <!-- Webpage content here -->
    <script>
        // Function code here
    </script>
</body>
</html>

겁먹지 마세요! 웹페이지는 지금 바로 실행할 수 있습니다! 스크린샷을 따라 클릭만 하면 됩니다.

5단계: 웹페이지 내용 수정 (상품 변경, 확률 조정)

AI가 생성한 웹페이지는 보통 꽤 완성도가 높지만, 다음과 같은 부분을 수정하고 싶을 수 있습니다:

상품 이름 변경
당첨 확률 조정
색상 변경

걱정 마세요. 코드를 이해할 필요 없습니다. 계속 AI에게 물어보면 됩니다!

대화를 이어가며 AI가 수정하도록 하기

단계:

AI Studio 채팅 창을 닫지 마세요
- AI가 이전 대화를 기억합니다
- 아래에 계속 질문할 수 있습니다
수정 요청 입력

예시 1: 상품 이름 변경

입력 상자에 다음을 입력:

Add a settings interface to this webpage to set the probabilities and specific prizes for different awards.

만족할 때까지 반복

이것이 AI로 무언가를 만드는 핵심 과정입니다:

원하는 것을 명확히 말하기
AI가 첫 번째 버전 생성
사용해 보고 문제 찾기
AI에게 문제를 알리고 수정 요청
3~4단계를 완벽할 때까지 반복

핵심 포인트:

번거로워하지 말고 여러 번 시도하세요
한 번에 하나씩만 변경하여 제어하기 쉽게 하세요
AI가 잘못 변경하면 “아니요, 이전 버전으로 되돌려 주세요"라고 말하세요

6단계: 최종 웹페이지 다운로드

이제 완벽한 룰렛 웹페이지가 생겼습니다. 어떻게 다운로드하나요?

다운로드 버튼을 클릭하기만 하면 로컬에 다운로드되고, 열어서 사용할 수 있습니다!

HTML 웹페이지로 무엇을 할 수 있을까? 실용적인 미니 도구 10가지 추천

이쯤에서 이런 생각이 들 수 있습니다: 룰렛 말고도 AI로 어떤 웹페이지를 만들 수 있을까?

정답은: 거의 모든 간단한 미니 도구를 만들 수 있습니다!

다음은 바로 AI에게 만들어 달라고 요청할 수 있는 실용적인 예시 10가지입니다:

1. 온라인 번역 도구

프롬프트:

Make an online translation webpage that supports Chinese-English translation with a clean interface.

2. 이미지 텍스트 인식 (OCR)

프롬프트:

Make a webpage that can upload an image, recognize text in the image, and allow copying.

3. 할 일 목록

프롬프트:

Make a to-do list webpage that can add, delete, and mark tasks as complete, with data saved in the browser.

4. 카운트다운/타이머

프롬프트:

Make a multi-functional timer webpage: countdown, Pomodoro timer, stopwatch.

5. 랜덤 비밀번호 생성기

프롬프트:

Make a password generator that can set length and complexity, with one-click copy.

6. BMI 계산기

프롬프트:

Make a BMI health calculator that inputs height and weight and displays health advice.

7. QR 코드 생성기

프롬프트:

Make a QR code generation webpage that inputs text or URL, generates a QR code, and allows download.

8. 색상 선택기

프롬프트:

Make a color tool that can select colors, display RGB/HEX values, and provide color scheme suggestions.

9. Markdown 편집기

프롬프트:

Make a simple Markdown editor with input on the left and real-time preview on the right.

10. 지출 추적기

프롬프트:

Make a simple expense tracking webpage that can record income and expenses and display statistical charts.

이 도구들의 공통 특징:

모두 단일 HTML 파일
서버 불필요
브라우저에서 열기만 하면 됨
완전 무료

자주 묻는 질문

Q1: 코드를 전혀 모르는데 정말 할 수 있을까요?

A: 네, 가능합니다! 알아야 할 것은 다음 세 가지뿐입니다:

복사 및 붙여넣기
파일 저장
브라우저로 파일 열기

이 세 단계만 알면 어린이도 할 수 있습니다.

Q2: AI가 생성한 코드가 완벽하지 않으면 어떻게 하나요?

A: 정상입니다! AI와 계속 대화하세요:

“여기 버그가 있어요. 버튼을 클릭해도 아무 일도 안 일어나요”
“이 색상이 별로예요. 예쁜 색으로 바꿔 주세요”
“효과음을 추가할 수 있나요?”

AI가 피드백에 따라 계속 개선해 줍니다.

Q3: AI로 만든 웹페이지를 상업적으로 사용할 수 있나요?

A: 기술적으로는 가능하지만, 다음 사항에 유의하세요:

AI가 생성한 코드는 일반적으로 저작권 제한이 없습니다
하지만 고객 프로젝트에 사용할 경우 충분히 테스트하세요
복잡한 상업 프로젝트는 여전히 전문 개발자를 고용하는 것이 좋습니다

Q4: HTML 파일이 열리지 않는 이유는 무엇인가요?

A: 일반적인 이유:

파일 확장자 오류: .html인지 확인하고, .html.txt가 아니어야 함
코드 불완전: 모든 코드를 복사했는지 확인
브라우저 문제: 다른 브라우저 시도

Q5: 모바일에서 사용할 수 있나요?

A: 네! 두 가지 방법:

HTML 파일을 휴대폰으로 전송하고 모바일 브라우저로 열기
Netlify 같은 플랫폼에 업로드하고 URL로 접속 (추천)

Q6: 코드를 수정하고 싶은데 방법을 모르겠어요?

A: 직접 수정하지 마세요! AI에게 물어보세요:

“배경색을 파란색으로 바꾸고 싶어요”
“제목 글꼴을 더 크게 만들고 싶어요”
“배경 음악을 추가하고 싶어요”

AI가 수정해 주면 새 코드를 복사하세요.

요약

오늘 배운 내용:

Google AI Studio를 사용해 HTML 웹페이지를 생성하는 방법
명확한 프롬프트를 작성하여 AI에게 요구사항을 전달하는 방법
HTML 파일을 저장하고 브라우저에서 여는 방법
대화를 통해 웹페이지를 지속적으로 개선하는 방법
웹페이지를 공유하거나 배포하는 방법

핵심 아이디어:

프로그래밍 지식 불필요
돈 불필요
AI와 소통하는 방법만 알면 됨
5분 만에 실용적인 도구 제작

다음에 누군가 간단한 웹페이지를 만들어 달라고 하면:

AI를 사용해 5분 만에 만들기
그 50위안 받기 (농담입니다)
또는 스스로 만들 수 있도록 가르쳐 주기

진심으로, 돈 낭비하지 마세요!

API 실습: Immersive Translate 연결하기

Mon, 01 Jan 0001 00:00:00 +0000

이전 장에서는 API Key를 얻는 방법과 API의 기본 개념을 배웠습니다. 하지만 이렇게 생각할 수도 있습니다: 코딩을 못하는데 API Key가 무슨 소용이지?

좋은 소식은: 코딩을 몰라도 된다는 것입니다!

이 장에서 소개하는 Immersive Translate는 다른 사람이 만든 기성 도구입니다. 여러분이 해야 할 일은:

다운로드 및 설치
API Key 입력
사용 시작

그게 전부입니다.

이렇게 생각해보세요:

API Key는 ‘멤버십 카드’입니다
이 도구들은 이미 지어진 ‘놀이공원’입니다
카드를 들고 가서 즐기기만 하면 됩니다

이 책의 후반부에서는 더 고급 내용을 다룹니다 — 12장에서는 API 릴레이 설정 방법을, 13장에서는 컴퓨터에 Claude Code를 설치합니다. 이 장에서는 먼저 이러한 기성 도구를 사용하고 API의 강력함을 경험해보겠습니다.

Immersive Translate

무엇인가요?

Immersive Translate = 가장 강력한 웹 번역 플러그인

상상해보세요:

YouTube 동영상을 시청할 때 자막이 자동으로 중국어로 번역됩니다
영어 뉴스를 읽을 때 페이지에 이중 언어 텍스트가 표시됩니다
PDF 논문을 읽을 때 텍스트에 마우스를 올리면 번역이 나타납니다

이것이 Immersive Translate가 할 수 있는 일입니다.

왜 API를 사용하나요?

Immersive Translate는 몇 가지 무료 번역 서비스(Google Translate, Microsoft Translator 등)를 제공하지만:

무료 버전에는 사용 제한이 있습니다
번역 품질이 평균적입니다
전문 용어가 부정확할 수 있습니다

AI API를 연결하면:

GPT-5.2, Claude, Gemini로 번역 — 품질이 기존 번역을 훨씬 능가합니다
문맥을 이해하여 번역이 더 자연스럽습니다
전문 용어가 정확하게 번역됩니다
사용한 만큼 지불하며, 가벼운 사용에는 매우 저렴합니다

어떻게 다운로드하나요?

지원 브라우저:

Chrome
Edge
Firefox
Safari

다운로드 단계:

Immersive Translate 공식 웹사이트 열기: https://immersivetranslate.com
“지금 설치” 클릭
해당 앱 스토어로 리디렉션됩니다
- Chrome/Edge: Chrome 웹 스토어
- Firefox: Firefox 부가 기능
- Safari: App Store
“브라우저에 추가” 또는 “설치” 클릭
설치 후 브라우저 오른쪽 상단에 플러그인 아이콘이 나타납니다

API를 어떻게 설정하나요?

단계:

설정 페이지 열기
- 브라우저 오른쪽 상단의 Immersive Translate 아이콘 클릭
- “설정” 선택
번역 서비스 설정 찾기
- 설정 페이지에서 “번역 서비스” 찾기
- Google, DeepL, OpenAI 등 다양한 번역 옵션이 표시됩니다
AI 번역 서비스 선택

Gemini를 예로 들어 (앞서 AI Studio에서 얻은 API 기억하시나요?):

“Gemini” 또는 “Google AI” 옵션 찾기
AI Studio에서 얻은 API Key 입력
Base URL: [https://generativelanguage.googleapis.com/v1beta](https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent?key={key})
모델: gemini-3-flash-preview
테스트 및 저장

기본 번역 서비스로 설정
- “기본 번역 서비스"에서 방금 구성한 AI 선택
- 이렇게 하면 모든 번역이 AI를 사용합니다
- 플로팅 볼을 활성화하는 것이 좋습니다

어떻게 사용하나요?

사용법은 매우 간단합니다:

외국어 웹페이지 열기
- 예: https://www.nytimes.com (The New York Times)
- 예: https://www.bbc.com (BBC News)
번역 시작
- 브라우저 오른쪽 상단의 플러그인 아이콘 또는 플로팅 볼 클릭
- 또는 단축키 사용 (보통 Ctrl+Shift+X)
- 페이지가 즉시 이중 언어로 표시됩니다
번역 스타일 사용자 지정
- 이중 언어 표시 (권장): 원문과 번역문 나란히
- 번역문만: 번역된 텍스트만 보기
- 호버 번역: 텍스트에 마우스를 올리면 번역 표시

고급 기능:

PDF 번역: PDF를 업로드하여 전체 문서 번역
동영상 자막 번역: YouTube, Netflix 등에서 자동으로 자막 번역
입력 상자 번역: 웹 입력 상자에 중국어를 입력하면 보내기 전에 자동으로 영어로 번역
이중 언어 비교: 외국어 학습에 좋은 도구

비용 추정

Gemini 3 Flash를 번역에 사용할 경우:

영어 1000단어 ≈ 1500 Tokens
중국어로 번역 ≈ 2000 Tokens 출력
비용: (1500×0.08 + 2000×0.30) / 1,000,000 ≈ $0.0007 (약 0.5센트)

다시 말해: 이런 기사 1000개를 번역해도 약 5위안 (1달러 미만)밖에 들지 않습니다!

요약

핵심 아이디어:

직접 코드를 작성할 필요 없음
기성 도구 + API Key 사용
AI의 강력한 기능 활용

이 도구들의 본질:

다른 사람이 만든 ‘다리’입니다
API Key는 ‘통행증’입니다
통행증을 가지고 다리를 건너기만 하면 됩니다

API 호출 방법과 API 플랫폼 선택 가이드

Mon, 01 Jan 0001 00:00:00 +0000

지금까지 API, 토큰, Temperature 같은 핵심 개념을 다뤘습니다. 이제 실전입니다: 실제로 API를 호출하는 방법은?

많은 사람들이 API를 신비롭게 생각하지만, 몇 가지 핵심 요소만 알면 API 호출은 온라인 쇼핑만큼 간단합니다. 이 장에서 단계별로 안내해 드리겠습니다.

API 호출의 세 가지 핵심 요소

어떤 도구나 플랫폼을 사용하든 AI API를 호출하려면 다음 세 가지가 필요합니다.

1. API Key

API Key = 당신의 신분증

은행에서 돈을 찾으려면 카드 비밀번호가 필요하듯, API를 호출하려면 API Key가 필요합니다. “이게 나야, 나를 서비스해 줘"라고 증명하는 역할을 합니다.

API Key는 어떻게 생겼나요?

보통 긴 문자열(영문자와 숫자)로 구성됩니다. 예:

sk-REPLACE_WITH_YOUR_API_KEY

중요 알림:

API Key는 비공개입니다. 다른 사람과 공유하지 마세요.
누군가 당신의 키를 알면 그 사람이 당신 계정으로 API를 호출할 수 있습니다(당신의 비용이 소모됩니다).
실수로 유출했다면 즉시 플랫폼에서 기존 키를 삭제하고 새 키를 생성하세요.

2. Base URL

Base URL = 식당 주소

배달 음식을 주문할 때 식당 위치를 알아야 하듯, API를 호출할 때는 서버 위치를 알아야 합니다.

일반적인 Base URL:

OpenAI: https://api.openai.com/v1
Anthropic Claude: https://api.anthropic.com/v1
Google Gemini: https://generativelanguage.googleapis.com/v1
DeepSeek: https://api.deepseek.com/v1

서드파티 플랫폼은 URL이 다르지만 형식은 비슷합니다.

3. Model Name

Model Name = 주문할 요리 이름

식당에서 “돼지고기 찜 주세요"라고 말하듯, API 호출 시 “GPT-5.2를 사용할게요"라고 말합니다.

일반적인 Model Name:

OpenAI: gpt-5.2, gpt-5.2-chat-latest
Claude: claude-opus-4.5, claude-sonnet-4.5
Gemini: gemini-3-pro, gemini-3-flash
DeepSeek: deepseek-chat, deepseek-coder

완전한 API 호출 예시

이 세 가지를 조합하면 가장 간단한 API 호출은 다음과 같습니다.

import openai

# 1. Set the API Key
openai.api_key = "sk-proj-YOUR_API_KEY"

# 2. Set the Base URL (if you use a third-party platform)
openai.base_url = "https://api.openai.com/v1"

# 3. Call the selected model
response = openai.chat.completions.create(
    model="gpt-5.2",  # Model Name
    messages=[
        {"role": "user", "content": "Hello"}
    ]
)

print(response.choices[0].message.content)

복잡해 보이나요? 걱정 마세요. 나중에 소개할 플랫폼들은 더 간단한 방법을 제공합니다.

공식 API vs 서드파티 플랫폼

구체적인 플랫폼을 소개하기 전에 중요한 개념을 명확히 하겠습니다: 공식 API와 서드파티 플랫폼의 차이는 무엇인가요?

공식 API

공식 API = OpenAI, Anthropic, Google에서 직접 구매

장점:

안정성 최고, 공식 서버에 직접 연결
모든 기능 제공, 새로운 기능 즉시 지원
보안 최고, 데이터가 서드파티를 거치지 않음

단점:

해외 신용카드 필요
VPN 필요 (ChatGPT, Claude, Gemini)
상대적으로 높은 가격
가입에 장벽이 있을 수 있음

서드파티 플랫폼

서드파티 플랫폼 = 리셀러에게 구매

서드파티 플랫폼은 먼저 공식으로부터 API 할당량을 구매한 후, 이를 다시 사용자에게 판매합니다.

장점:

국내 결제 지원 (Alipay, WeChat Pay, UnionPay)
VPN 불필요
보통 한국어 인터페이스와 고객 지원 제공
하나의 플랫폼으로 여러 AI 호출 가능 (OpenAI, Claude, Gemini 등)
일부 플랫폼은 무료 크레딧 제공

단점:

안정성이 공식만큼 좋지 않을 수 있음
가격이 공식보다 약간 높을 수 있음 (일부는 더 저렴함)
보안은 플랫폼을 신뢰해야 함
기능 업데이트가 공식보다 늦을 수 있음

어떤 것을 선택해야 할까요?

다음 경우 공식 선택:

해외 신용카드가 있는 경우
안정적인 VPN이 있는 경우
데이터 보안을 중요시하는 경우
최신 기능이 필요한 경우

다음 경우 서드파티 선택:

해외 결제 수단이 없는 경우
VPN이 없는 경우
국내 결제를 사용하고 싶은 경우
하나의 플랫폼으로 여러 AI를 호출하고 싶은 경우

플랫폼 추천 (국내 2개 + 해외 2개)

아래는 제가 추천하는 4가지 API 플랫폼입니다. 국내 2개, 해외 2개로 다양한 요구를 충족합니다.

1. DeepSeek 공식 (국내, 공식 플랫폼)

웹사이트: https://platform.deepseek.com

플랫폼 유형: 공식 플랫폼

추천 이유:

공식 플랫폼, 안정적이고 신뢰할 수 있음
DeepSeek V3.2 성능이 GPT-5에 근접
중국 내 접속 빠름, VPN 불필요
간단한 가입, 전화번호만 있으면 됨
가격이 매우 저렴, 가성비 최고

API Key 받는 방법:

https://platform.deepseek.com 열기
오른쪽 상단 “Login/Register” 클릭
전화번호로 계정 등록
로그인 후 왼쪽 “API Keys” 클릭
“Create API Key” 클릭
키 복사 (한 번만 표시되므로 저장하세요)
왼쪽 “Interface Documentation” 클릭하여 URL과 모델 이름 확인

호출 파라미터:

Base URL: https://api.deepseek.com
Model Name: deepseek-chat (채팅), deepseek-reasoner (추론)
API Key: 방금 복사한 키

2. Volcano Engine (국내, 공식 플랫폼 + 서드파티)

웹사이트: https://console.volcengine.com/ark

플랫폼 유형: 공식 플랫폼 (ByteDance 소속)

추천 이유:

ByteDance 공식 플랫폼, 안정적이고 신뢰할 수 있음
Doubao 시리즈 모델 지원
국내 결제 지원 (Alipay, WeChat Pay, UnionPay)
가격 합리적, 가성비 좋음
Doubao 자체 모델 외에도 DeepSeek V3.2, GLM 4.7 등 많은 국내 오픈소스 모델 호출 가능

사용 방법:

https://console.volcengine.com/ark 열기
전화번호로 Volcano Engine 계정 등록
“Ark Large Model” 콘솔 진입
실명 인증 완료 (신분증 필요)
“API Key Management” 클릭
새 API 키 생성
키 복사 및 저장
왼쪽 “Activation Management” 클릭, 사용할 모델 선택
새 페이지에서 필요한 모델 이름 복사 (참고: 같은 모델도 플랫폼에 따라 이름이 다를 수 있으니 주의)
Activation Management 페이지로 돌아와 상태가 “Activated"인지 확인, 아니면 오른쪽에서 모델 권한 활성화 클릭

호출 파라미터:

Base URL: https://ark.cn-beijing.volces.com/api/v3
Model Name: doubao-pro-32k, doubao-lite-32k 등
API Key: 생성한 키

신규 사용자 혜택:

가입 시 무료 크레딧 제공
위 스크린샷 위에 표시된 활동에 참여하여 추가 무료 크레딧 획득 가능. 저는 매일 충분히 사용하고 있습니다.

3. Google AI Studio (해외, 공식 플랫폼)

웹사이트: https://aistudio.google.com

플랫폼 유형: 공식 플랫폼

추천 이유:

Google 공식 플랫폼
무료 크레딧 제공 (제한 있음)
Gemini 3 최고 수준 성능
안정적이고 신뢰할 수 있음
매우 긴 컨텍스트 지원 (200만 토큰)
웹 인터페이스에서 무료로 직접 사용 가능, 코딩 불필요

또한, 웹 버전을 무료로 사용하는 방법

코드를 작성하고 싶지 않다면 Google AI Studio는 매우 편리한 웹 채팅 인터페이스를 제공합니다. Gemini 3 Pro, Gemini 3 Flash 같은 모델을 직접 사용할 수 있습니다. 사실상 유료 Gemini 사용자와 같은 경험을 제공합니다.

사용 방법:

https://aistudio.google.com 열기
Google 계정으로 로그인 (VPN 필요)
왼쪽 “Playground” 클릭
오른쪽 상단에서 모델 선택:
- gemini-3-pro: 최고 모델, 복잡한 작업에 적합
- gemini-3-flash: 빠른 모델, 일상 대화에 적합
- 기타 실험 모델도 있음
입력창에 질문을 직접 입력하고 “Run” 클릭, AI가 답변

고급 기능 (웹 버전):

1. 파일 업로드

입력창 오른쪽 + 아이콘 클릭
이미지, PDF, 문서 등 업로드 가능
멀티모달 이해 지원

2. 파라미터 조정

오른쪽에서 앞서 소개한 파라미터 조정 가능
조정 가능 항목:
- Temperature (창의성)
- Top P
- 최대 출력 토큰
- 안전 설정

웹 버전의 장점:

코딩 불필요
소프트웨어 설치 불필요
브라우저에서 직접 사용
사용자 친화적 인터페이스, 모든 기능 제공
빠른 테스트 및 일상 사용에 적합

웹 버전은 누구를 위한 것인가요?

코딩을 전혀 모르는 완전 초보자
Gemini의 성능을 빠르게 테스트하고 싶은 분
일상적인 채팅 및 질문
문서, 이미지 등 멀티모달 작업 처리

API Key 받기 (고급 사용자용)

본론으로 돌아와서, API Key를 받는 방법입니다.

API Key 받는 방법:

AI Studio 페이지에서 왼쪽 “Get API Key” 클릭
“Create API Key” 클릭
생성된 API Key 복사
Playground로 돌아가 오른쪽에서 모델 이름 선택 및 복사

호출 파라미터:

Base URL: https://generativelanguage.googleapis.com/v1beta
Model Name: gemini-3-flash-preview
API Key: 복사한 키

무료 티어 제한

중요! Google AI Studio는 기본적으로 무료 티어를 사용하며, 다음과 같은 제한이 있습니다 (2026년 1월 기준, 변경될 수 있음):

분당 요청 수 (RPM): 15
일일 요청 수 (RPD): 1500
분당 토큰 수 (TPM): 100만 토큰

자세한 제한 사항은 다음에서 확인: https://ai.google.dev/gemini-api/docs/rate-limits?hl=en

무료 티어로 충분한가요?

웹 채팅: 충분함
가끔 API 호출: 충분함
대량 자동 호출: 부족할 수 있음

제한을 없애는 방법? Cloud 크레딧 연결

Google Cloud는 신규 사용자에게 $10의 무료 크레딧을 제공합니다. 이를 AI Studio에 연결하면 더 높은 제한을 해제할 수 있습니다. Google Cloud 계정 설정 방법은 온라인에서 “Google Cloud free credits"를 검색하면 많은 튜토리얼이 있습니다. 여기서는 다루지 않겠습니다.

연결 방법:

AI Studio에서 API 인터페이스로 돌아가 “Set up billing” 클릭
미리 생성한 Google Cloud 결제 계정 연결

연결 후 혜택:

속도 제한 대폭 증가 (RPM 최대 1000+)
무료 크레딧은 여전히 유효
$10으로 강력한 flash 모델을 오래 사용 가능
웹 버전과 API 모두 더 높은 할당량 적용

4. OpenRouter (해외, 서드파티 플랫폼)

웹사이트: https://openrouter.ai

플랫폼 유형: 서드파티 플랫폼

추천 이유:

하나의 플랫폼으로 모든 주요 AI 호출 가능 (GPT, Claude, Gemini 등)
투명한 가격, 때로는 공식보다 저렴
Alipay 결제 지원 (중국 사용자에게 친숙)
신용카드 및 암호화폐 결제 지원
무료 모델 체험 가능
거의 모든 사용 가능한 모델 호출 가능
순위가 신뢰할 만함

API Key 받는 방법:

https://openrouter.ai 열기
오른쪽 상단 “Sign In” 클릭, Google 또는 GitHub로 로그인
로그인 후 오른쪽 상단 아바타 클릭, “Keys” 선택
“Create Key” 클릭
키 이름 지정 후 생성 클릭
생성된 키 복사
검색창에서 원하는 모델 검색 후 이름 복사

호출 파라미터:

Base URL: https://openrouter.ai/api/v1
Model Name:
- GPT-5.2: openai/gpt-5.2
- Claude Opus 4.5: anthropic/claude-opus-4.5
- Gemini 3 Pro: google/gemini-3-pro
- 무료 모델: meta-llama/llama-3.1-8b-instruct:free
API Key: 생성한 키

충전 방법:

Alipay (가장 편리)
신용카드
암호화폐 (USDC 등)

가격 장점:

일부 모델은 공식보다 10-20% 저렴
투명한 가격, 웹사이트에서 직접 확인 가능
다양한 제공업체가 경쟁하므로 가장 저렴한 것을 선택 가능

무료 옵션:

일부 모델은 완전 무료 (:free 표시)
신규 사용자에게 무료 크레딧 제공
무료 모델로 먼저 테스트 가능

모델 순위

Rankings 페이지에서 플랫폼의 모델 호출 데이터를 확인할 수 있으며, 순위가 매우 신뢰할 만합니다.

기타 무료 플랫폼

지면 관계상 몇 가지 추가로 무료로 사용할 수 있는 플랫폼을 소개합니다.

Cerebras (초고속 추론)

웹사이트: https://cloud.cerebras.ai

특징:

매우 빠른 추론 (세계에서 가장 빠르다고 주장)
무료 Llama 모델 호출 제공
간단한 가입, GitHub 로그인만 있으면 됨

NVIDIA NIM (NVIDIA 공식)

웹사이트: https://build.nvidia.com

특징:

NVIDIA의 공식 AI 플랫폼
여러 무료 모델 제공
테스트 및 개발에 적합

두 플랫폼 모두 무료 크레딧을 제공합니다. 관심이 있다면 가입해서 사용해 보세요.

요약

세 가지 핵심 요소:

API Key
Base URL
Model Name

네 가지 추천 플랫폼:

DeepSeek 공식 (공식) - 중국에서 가장 저렴한 선택
Volcano Engine (공식 + 서드파티) - 국내 플랫폼, 대부분의 국내 오픈소스 모델 호출 가능
Google AI Studio (공식) - 해외 최고의 무료 선택 (Cloud 크레딧 포함), 웹에서 직접 사용 가능
OpenRouter (서드파티) - 올인원 플랫폼, Alipay 지원

API와 토큰 기초 개념 설명

Mon, 01 Jan 0001 00:00:00 +0000

숙련된 사용자들이 API, 토큰, Temperature 등 기술적이고 혼란스러운 용어를 자주 사용하는 것을 본 적이 있을 것입니다. 이 장에서는 이러한 핵심 개념을 평이한 언어로 설명합니다. 이를 이해하면 AI가 실제로 어떻게 작동하는지 파악하고 더 효과적으로 활용할 수 있습니다.

API란 무엇인가?

API를 쉽게 설명하자면

API = Application Programming Interface (응용 프로그램 프로그래밍 인터페이스)

이 정의는 기술적으로 들리니, 다르게 설명해 보겠습니다.

AI를 식당에 비유해 보세요:

웹 버전 = 식당에서 식사하는 것
- 멋진 인테리어 (웹 인터페이스)
- 웨이터 (버튼, 입력 필드)
- 주문하면 셰프가 요리하고 웨이터가 서빙
API = 포장 주문 전화를 하는 것
- 인테리어 없음, 주방에 직접 말함
- 웨이터 없음, 셰프에게 직접 말함
- 원하는 것을 말하면 셰프가 준비해서 건네줌

핵심 차이점:

웹 버전: 인터페이스가 있어 사람이 사용하기 편리함
API: 인터페이스가 없어 프로그램이 사용하기 편리함

왜 API를 사용하는가?

웹 버전이 그렇게 편리한데, 왜 API를 사용할까요?

이유 1: 자동화

AI가 1,000개의 문서를 처리하고 1,000개의 요약을 작성해야 한다고 가정해 보세요:

웹 버전: 1,000번 복사-붙여넣기하고 1,000번 전송 버튼을 클릭해야 함
API: 스크립트 하나를 작성하면 커피를 마시는 동안 모든 것이 자동으로 처리됨

이유 2: 자체 앱에 통합

자동 응답 봇, 콘텐츠 생성기, 스마트 고객 서비스 에이전트를 만들고 싶다면:

웹 버전: 불가능
API: AI를 자체 프로그램에 직접 내장할 수 있음

이유 3: 비용 절감

웹 구독: ChatGPT Plus 월 $20, Claude Pro 월 $20
API 종량제: 사용한 만큼만 지불; 가벼운 사용 시 월 몇 달러면 충분할 수 있음

이유 4: 더 큰 유연성

AI 매개변수 미세 조정 (Temperature, 최대 길이 등)
일괄 처리
사용자 정의 입력/출력 형식

API 호출은 어떻게 생겼나?

간단한 예시입니다 (생소해 보여도 괜찮습니다 – 나중에 자세히 다룰 예정입니다):

# Call the latest GPT-5.2 API with Python
response = openai.chat.completions.create(
    model="gpt-5.2",
    messages=[
        {"role": "user", "content": "Hello，Introduce yourself"}
    ]
)
print(response.choices[0].message.content)

몇 줄의 코드만으로 AI가 질문에 답변합니다 – 브라우저가 필요 없습니다.

2026-01-30 기준 공식 API 모델 식별자:

OpenAI: gpt-5.2, gpt-5.2-chat-latest, gpt-5.2-pro
Anthropic Claude: claude-opus-4-5, claude-sonnet-4-5
Google Gemini: gemini-3-pro-preview, gemini-3-flash-preview

웹 버전 vs API 비교

항목	웹 버전	API
사용 방법	브라우저에서 클릭하며 사용	코드를 작성하여 호출
학습 곡선	낮음, 누구나 사용 가능	높음, 약간의 프로그래밍 필요
최적 용도	일상 대화, 글쓰기	자동화, 일괄 처리, 앱 통합
비용	월 정액제 ($20/월)	종량제 (사용한 만큼 지불)
유연성	웹 기능에 제한됨	높은 사용자 정의 가능
속도	보통	일반적으로 더 빠름 (UI 렌더링 없음)

토큰이란 무엇인가?

토큰의 개념

토큰 = AI가 이해하는 텍스트의 최소 단위

사람이 단어와 문장을 직접 읽는 것과 달리, AI는 텍스트를 작은 조각으로 나누어야 합니다. 각 조각을 토큰이라고 합니다.

예시:

중국어:

“你好” ≈ 1–2 토큰
“今天天气不错” ≈ 4–8 토큰 (모델에 따라 다름)

영어:

“Hello” = 1 토큰
“How are you today?” ≈ 5 토큰

간단한 경험 법칙:

영어: 단어 1개 ≈ 토큰 1개 (약 4자)
중국어: 문자 1개 ≈ 0.5–2 토큰 (AI 모델에 따라 다름)
숫자, 구두점: 일반적으로 기호 1개 = 토큰 1개

중요한 발견: AI 모델마다 토큰을 다르게 정의한다!

잘 알려지지 않은 비밀: 같은 텍스트라도 AI 모델에 따라 토큰 수가 완전히 다를 수 있습니다!

왜일까요? 각 AI 회사는 자체 토크나이저를 가지고 있으며, 텍스트를 분할하는 방식이 다릅니다.

실제 예시:

같은 문장: “AI is revolutionizing market research.”

GPT-3: 11 토큰
GPT-3.5 및 GPT-4: 9 토큰
GPT-4o 및 GPT-5.2: 8 토큰

보이시나요? 같은 문장이 모델에 따라 3토큰 차이납니다!

또 다른 중국어 예시:

문장 “人工智能正在改变世界” (“인공지능이 세상을 바꾸고 있다”):

GPT-4o: 약 10 토큰
Claude Sonnet 4.5: 약 12 토큰
Gemini 3: 약 8 토큰

왜 차이가 날까?

각 회사는 모델을 훈련할 때 다른 토큰화 방법을 사용합니다:

OpenAI (GPT 시리즈): BPE(Byte-Pair Encoding) 사용
Anthropic (Claude): 자체 최적화 토크나이저 사용
Google (Gemini): Gemini 문서에 따르면 “1 토큰 ≈ 4자”
DeepSeek: 중국어에 최적화된 토크나이저

이것이 사용자에게 어떤 영향을 미칠까?

1. 비용 비교가 직접적이지 않음

1,000자의 중국어가 있다고 가정해 보세요:

GPT-5.2에서는 1,500 토큰일 수 있음
Claude Sonnet 4.5에서는 1,600 토큰일 수 있음
Gemini 3에서는 1,400 토큰일 수 있음

각각 “입력 $X/1M 토큰"이라고 말하지만, 실제 비용은 10–20%까지 차이날 수 있습니다!

2. 모든 모델에 동일한 토큰 계산기를 사용할 수 없음

OpenAI 공식 토크나이저 (https://platform.openai.com/tokenizer)는 GPT 시리즈에만 작동
Claude 토큰은 Anthropic의 계산 방법이 필요
Gemini 토큰은 Google의 계산 방법이 필요

3. 비영어권 언어에서 차이가 더 큼

중국어, 일본어, 아랍어 등 비영어권 언어의 경우 토큰 효율성이 30–40%까지 차이날 수 있습니다. 대부분의 AI 모델은 주로 영어로 훈련되므로 토크나이저가 영어에 더 최적화되어 있습니다.

토큰이 중요한 이유

1. 토큰이 비용을 결정함

API 가격은 문자 수가 아닌 토큰을 기준으로 책정됩니다.

예시 (2026-01-30 기준 공식 가격):

GPT-5.2: 입력 $1.75/1M 토큰, 출력 $14/1M 토큰
Claude Opus 4.5: 입력 $5/1M 토큰, 출력 $25/1M 토큰
Gemini 3 Flash: 입력 $0.50/1M 토큰, 출력 $3/1M 토큰 (표준 등급)

500 토큰을 보내고 AI가 1,000 토큰으로 응답하는 경우:

GPT-5.2 사용 시: (500 × 1.75 + 1000 × 14) / 1,000,000 = $0.01488 (약 1.5센트)
Gemini 3 Flash 사용 시: (500 × 0.50 + 1000 × 3) / 1,000,000 = $0.00325 (약 0.3센트)

2. 토큰이 컨텍스트 길이를 결정함

모든 AI 모델에는 토큰 제한이 있습니다:

GPT-5.2 (API): 최대 400,000 토큰
GPT-5.2-chat-latest: 최대 128,000 토큰
Claude Sonnet 4.5: 최대 200,000 토큰
Gemini 3 Pro Preview: 최대 1,048,576 토큰 (약 1M)

이 제한에는 다음이 포함됩니다: 사용자의 프롬프트 + AI의 응답 + 대화 기록.

제한을 초과하면 어떻게 될까?

AI가 대화의 가장 이른 부분을 “잊어버림”
또는 오류가 발생하고 계속 진행되지 않음

토큰 계산 방법

방법 1: 추정 (빠르지만 정확하지 않음)

중국어: 문자 수 × 1.5
영어: 단어 수 × 1.3

방법 2: 해당 온라인 도구 사용

OpenAI (GPT 시리즈): https://platform.openai.com/tokenizer
일반 토큰 카운터: https://token-counter.app (여러 모델 비교 지원)
Gemini: Google AI Studio에서 count_tokens 메서드 사용

중요 알림: 모델 간 추정 시 항상 해당 모델에 특화된 도구를 사용하세요. GPT의 토큰 수를 사용하여 Claude의 비용을 추정하지 마세요!

입력 토큰, 출력 토큰, 캐시된 토큰

API 요금 청구는 토큰을 세 가지 유형으로 나눕니다:

1. 입력 토큰

AI에 보내는 콘텐츠
프롬프트, 업로드된 문서 포함
상대적으로 저렴

2. 출력 토큰

AI가 반환하는 콘텐츠
AI의 응답 포함
일반적으로 입력 토큰보다 2–10배 비쌈

출력이 더 비싼 이유는? AI가 “읽는”(입력 처리) 것보다 “생각하는”(텍스트 생성) 데 더 많은 컴퓨팅 리소스를 사용하기 때문입니다.

예시 (GPT-5.2):

입력: $1.75/1M 토큰
출력: $14/1M 토큰 (입력 가격의 8배!)

3. 캐시된 토큰

비용 절감을 위한 방법입니다!

동일한 프롬프트를 반복해서 사용하면 AI가 이를 캐시하여 다음 번에 재처리하지 않을 수 있습니다.

예시: 1,000 토큰 프롬프트로 10개의 질문을 하는 경우:

캐싱 없음: 매번 1,000 토큰 처리 → 총 10,000 토큰
캐싱 있음: 첫 번째 1,000 토큰 (정상 가격), 다음 9번 1,000 토큰 (캐시 가격, 90% 저렴)

캐싱을 지원하는 모델:

Anthropic Claude (프롬프트 캐싱)
OpenAI GPT-5.2 (캐싱 지원, 90% 할인)

캐싱 요금 청구 규칙:

첫 번째 읽기: 정상 가격
캐시 적중: 가격 50–90% 할인
캐시 유효 기간: 일반적으로 5–10분

Temperature란 무엇인가?

Temperature의 개념

Temperature = AI 응답의 “무작위성” 또는 “창의성"을 제어함

AI는 본질적으로 “확률을 계산"한다는 점을 기억하세요. “하늘은 무슨 색이야?“라고 물으면 AI는 다음을 봅니다:

“파란색” 확률 80%
“회색” 확률 10%
“빨간색” 확률 5%

Temperature는 AI가 이러한 옵션 중에서 선택하는 방식을 조정합니다.

Temperature 값

Temperature는 일반적으로 0에서 2 사이 (또는 플랫폼에 따라 0에서 1)의 범위를 가집니다:

Temperature = 0 (가장 보수적)

AI는 항상 가장 높은 확률의 답변을 선택
매우 안정적이고 예측 가능한 응답
같은 질문 → 매번 거의 동일한 답변
최적 용도: 사실 질문, 코드 생성, 데이터 분석

Temperature = 1 (균형)

AI가 확률에 따라 무작위로 선택
응답이 약간 다르지만 합리적인 수준 유지
대부분 플랫폼의 기본값
최적 용도: 일상 대화, 일반 사용

Temperature = 2 (가장 공격적)

AI가 많은 가능성을 시도
매우 다양하고 창의적인 응답
부정확하거나 심지어 무의미할 수 있음
최적 용도: 창작 글쓰기, 브레인스토밍, 예술 작업

실제 예시

질문: 제 커피숍 이름을 지어주세요

Temperature = 0:

“스타벅스 커피” (가장 일반적이고 안전한 답변)
거의 매번 동일

Temperature = 1:

“모닝 라이트 카페”
“아로마 타임”
“빈 & 코지”
다양하지만 모두 합리적

Temperature = 2:

“퀀텀 커피 차원”
“시공간 거품 연구소”
“코스믹 라떼 터미널”
매우 창의적이지만 너무 이상할 수 있음

Temperature 조정 시점

낮은 Temperature (0–0.5):

코드 작성, 디버깅
데이터 분석, 수학 문제
번역, 요약
정확성이 필요한 모든 작업

높은 Temperature (1.5–2):

소설, 시 쓰기
작명, 슬로건 만들기
브레인스토밍
창의성이 필요한 모든 작업

각 모델은 공식 사이트에 권장 Temperature를 명시합니다. 예를 들어 DeepSeek 웹사이트에는 다음과 같이 나와 있습니다:

시나리오	Temperature
코드 생성 / 수학 문제 해결	0.0
데이터 추출 / 분석	1.0
일반 대화	1.3
번역	1.3
창작 글쓰기 / 시	1.5

웹 버전에서 조정할 수 있나요?

대부분의 웹 버전은 직접 조정을 허용하지 않음
하지만 API는 정밀한 제어를 제공함

컨텍스트 길이

컨텍스트 길이란 무엇인가?

컨텍스트 길이 = AI가 한 번에 “기억"할 수 있는 콘텐츠의 양

사람과 달리 AI는 장기 기억이 없습니다. 각 대화에서 AI는 제한된 양의 콘텐츠만 기억할 수 있습니다. 이 제한을 컨텍스트 길이라고 하며, 토큰 단위로 측정됩니다.

AI가 “잊어버리는” 이유는?

다음과 같은 경험이 있을 수 있습니다:

AI와 오랫동안 대화
갑자기 AI가 처음에 무슨 말을 했는지 기억하지 못함
마치 기억상실증에 걸린 것처럼

이유: 컨텍스트 길이 제한을 초과했기 때문입니다.

예시:

GPT-5.2 컨텍스트 길이 = 128,000 토큰
사용자와 AI가 50라운드 대화, 총 130,000 토큰 사용
제한을 초과하면 AI가 가장 이른 부분을 “잊어버림”

컨텍스트 길이의 실질적 영향

1. 대화 길이에 영향

짧은 컨텍스트: 수십 라운드만 가능
긴 컨텍스트: 수백 라운드 가능

2. 문서 처리에 영향

짧은 컨텍스트: 짧은 문서만 가능
긴 컨텍스트: 전체 책 가능

3. 비용에 영향

긴 컨텍스트 → 처리 속도 느림
더 많은 토큰 → 더 높은 비용

컨텍스트 제한 처리 방법

방법 1: 정기적으로 대화 지우기

중요한 정보 저장
새 대화 시작
AI에게 배경 다시 설명

방법 2: 대화 기록 요약

AI에게 이전 내용 요약 요청
해당 요약을 새 대화의 시작으로 사용
토큰 절약

방법 3: 큰 컨텍스트를 가진 모델 선택

긴 문서: Gemini 3 Pro 사용
긴 대화: Claude Sonnet 4.5 사용

기타 중요한 개념

최대 토큰 (Max Tokens)

최대 토큰 = 단일 AI 응답의 최대 길이 제한

최대 토큰 = 100으로 설정: AI가 최대 100 토큰으로 응답
최대 토큰 = 2000으로 설정: AI가 최대 2000 토큰으로 응답

왜 제한하는가?

비용 제어 (출력 토큰이 더 비쌈)
지나치게 장황한 답변 방지
일부 시나리오에서는 짧은 응답만 필요

Top P (핵 샘플링)

Top P = 무작위성을 제어하는 또 다른 방법

Temperature와 유사하지만 다르게 작동합니다:

Top P = 0.1: 가장 확률이 높은 상위 10% 옵션만 고려
Top P = 0.9: 가장 확률이 높은 상위 90% 옵션 고려

일반적으로:

Temperature 또는 Top P 중 하나만 조정하면 충분
대부분의 경우 Temperature가 더 직관적

빈도 패널티와 존재 패널티

반복을 줄이는 데 사용

빈도 패널티 (Frequency Penalty): 자주 사용되는 단어에 패널티를 부과하여 같은 단어의 반복을 줄임
존재 패널티 (Presence Penalty): 이미 등장한 단어에 패널티를 부과하여 AI가 새로운 주제를 도입하도록 장려

범위: -2.0 ~ 2.0

양수 값: 반복 감소
음수 값: 더 많은 반복 허용
0: 개입 없음

요약: 이러한 개념을 어떻게 사용할까?

일상 사용 (웹 버전)

웹 버전만 사용한다면 이러한 매개변수에 대해 걱정할 필요가 없습니다 – 기본값으로도 충분히 잘 작동합니다.

하지만 이러한 개념을 이해하면 다음을 이해하는 데 도움이 됩니다:

AI가 때때로 대화 초반 부분을 “잊어버리는” 이유 (컨텍스트 제한)
API 사용자가 할 수 있는 일을 웹 버전 사용자는 할 수 없는 이유 (매개변수 제어)
향후 API 사용을 위한 준비

API 사용 시

API를 사용하기로 결정했다면 이러한 매개변수가 매우 중요해집니다:

기본 설정 (매번):

model: 모델 선택 (예: gpt-5.2, claude-sonnet-4-5)
max_tokens: 응답 길이 제한

필요에 따라 조정:

temperature: 사실 기반 작업은 0–0.5, 창의적 작업은 1–2
top_p: 일반적으로 기본값으로 충분
frequency_penalty: AI가 너무 반복적이면 0.5–1로 설정

비용 최적화:

캐싱을 사용하여 비용 절감
max_tokens를 제어하여 낭비 방지
적절한 모델 선택 (항상 가장 비싼 모델이 필요하지는 않음)
모델마다 토큰을 다르게 정의한다는 점을 기억

Bilibili 동영상 자막 추출 스킬 만들기

Mon, 01 Jan 0001 00:00:00 +0000

몇몇 독자분들이 Bilibili 동영상에서 자동으로 노트를 작성할 수 있는지 물어보셨습니다. 그래서 이 스킬을 만들어서 오픈소스로 공개합니다.

이 스킬의 동작 방식은 다음과 같습니다. Bilibili 링크를 주면 자동으로 동영상의 오디오를 다운로드하고, AI에 보내 자막을 추출한 후, 다른 AI로 요약을 생성합니다. 마지막으로 전체 자막과 요약을 Obsidian 인박스에 저장합니다.

전체 과정에 수동 조작이 필요 없으며, 잠시 기다리면 완료됩니다.

필요한 도구

이 스킬을 사용하려면 몇 가지 도구가 함께 작동해야 합니다.

yt-dlp

여러 플랫폼에서 오디오/비디오를 다운로드하는 명령줄 도구입니다. 이 스킬은 Bilibili 동영상의 오디오 스트림을 M4A 파일로 다운로드하는 데 사용합니다.

macOS 설치 (권장):

brew install yt-dlp

Homebrew가 없다면 pip으로도 설치할 수 있습니다.

pip install yt-dlp

ffmpeg

yt-dlp는 오디오 처리에 ffmpeg에 의존합니다. 없으면 오류가 발생할 수 있습니다.

brew install ffmpeg

Python 3

이 스킬에는 API 호출, 파일 처리, 템플릿 렌더링을 처리하는 Python 스크립트가 포함되어 있습니다. macOS에는 보통 Python 3가 함께 제공됩니다. 다음 명령어로 확인하세요.

python3 -V

버전 번호만 보이면 됩니다. 특정 버전이 필요하지는 않습니다.

Gemini API (오디오 자막 추출)

자막 추출에는 Google의 Gemini 모델, 특히 gemini-3-flash-preview를 사용합니다.

이 모델은 일반 Google 계정에 일일 무료 할당량이 있어 일상적인 사용에 충분합니다. 할당량을 초과하면 429 오류가 발생하며, 다음 날 할당량이 초기화될 때까지 기다리면 됩니다.

API 키는 aistudio.google.com에서 받을 수 있습니다.

사이트에 접속한 후 왼쪽에서 Get API key를 클릭하여 생성하세요.

DeepSeek API (내용 요약)

요약에는 DeepSeek을 사용합니다. 제 요약 습관에 잘 맞아서 선택했습니다.

API 키는 platform.deepseek.com에서 받을 수 있습니다.

계정을 등록한 후 API 키를 생성하세요. DeepSeek API는 매우 저렴해서 소액 충전으로 오래 사용할 수 있습니다.

설치 및 사용법

1단계: 스킬 패키지 다운로드

제 블로그에서 다운로드하세요: https://blog.discoverlabs.ac.cn/downloads/bili-to-obsidian-skill/

압축을 푼 후 폴더를 ~/.claude/skills/에 넣고, 경로가 ~/.claude/skills/bili_to_obsidian/가 되도록 하세요.

2단계: 설정 입력

~/.claude/skills/bili_to_obsidian/scripts/bili_to_obsidian.py 파일을 열고 처음 몇 줄을 찾으세요.

API_KEY = "YOUR_GEMINI_API_KEY"
DEEPSEEK_API_KEY = "YOUR_DEEPSEEK_API_KEY"

TEMPLATE_PATH = Path("/path/to/your/Obsidian-vault/02-Templates/Note.md")
OUTPUT_DIR = Path("/path/to/your/Obsidian-vault/00-Inbox")

다음 필드를 수정하세요.

YOUR_GEMINI_API_KEY: aistudio.google.com에서 받은 키로 바꾸세요.
YOUR_DEEPSEEK_API_KEY: DeepSeek에서 받은 키로 바꾸세요.
TEMPLATE_PATH: Obsidian 노트 템플릿의 전체 경로로 바꾸세요.
OUTPUT_DIR: Obsidian 인박스의 전체 경로로 바꾸세요.

Obsidian 노트 템플릿을 사용하지 않는다면 TEMPLATE_PATH를 존재하지 않는 경로로 설정해도 됩니다. 템플릿을 찾을 수 없으면 스크립트가 기본 형식을 생성하므로 정상 작동합니다.

3단계: 실행

Claude Code에서 다음 명령어를 입력하세요.

/bili_to_obsidian paste-the-Bilibili-video-link-here

그러면 완료될 때까지 기다리세요. 보통 몇 분 안에 끝납니다.

중요 참고 사항

Gemini의 무료 할당량은 하루에 제한되어 있습니다. 하루에 많은 동영상을 처리하다가 429 오류가 발생하면 할당량을 초과한 것입니다. 다음 날 할당량이 초기화될 때까지 기다리세요. 자주 초과한다면 여러 Google 계정을 등록하고 API 키를 교체해서 사용하세요.

경로 줄은 반드시 자신의 것으로 변경해야 합니다. 다운로드 패키지에 있는 것은 제 컴퓨터의 경로이므로 그대로 사용하면 오류가 발생합니다.

형식은 제 Obsidian 템플릿을 기준으로 합니다. 템플릿 구조가 다르면 자막 내용이 잘못된 위치에 들어갈 수 있습니다. 그런 경우 스크립트를 AI에 넘기고 템플릿 구조를 설명한 후 앵커 포인트를 조정해 달라고 요청하세요.

다운로드

제 블로그에서 다운로드하세요 (제 API 키는 제거했습니다).

https://blog.discoverlabs.ac.cn/downloads/bili-to-obsidian-skill/

이 스킬을 한동안 사용해 왔습니다. 교육용 Bilibili 동영상의 자막을 추출해서 Obsidian에 바로 저장해 참고하기에 특히 편리합니다.

추가로, 오디오 다운로드는 yt-dlp를 사용하는데, Bilibili뿐만 아니라 YouTube, Twitter, Douyin 등 수백 개의 동영상 사이트를 지원합니다. 따라서 이 스킬은 Bilibili에 국한되지 않고 다른 플랫폼의 링크에도 사용할 수 있습니다. 자유롭게 사용해 보고 더 확장해 보세요.

Claude Code: 실용적인 입문 가이드

Mon, 01 Jan 0001 00:00:00 +0000

가장 흥미로운 부분으로 들어가 봅시다: AI를 사용해 코드를 작성하는 것입니다.

여러분은 이렇게 생각할 수도 있습니다: “나는 코드에 대해 아무것도 몰라, 이게 나와 무슨 상관이지?”

반대로, 코드를 모르기 때문에 이 도구가 더 적합합니다.

웹페이지 하나 만드는 데 5만 원을 썼던 친구를 기억하시나요? Claude Code를 사용하면 그런 일은 다시는 없을 겁니다. 여러분이 원하는 것을 평범한 언어로 AI에게 말하기만 하면, AI가 완전한 프로그램을 작성해 줍니다.

오늘 소개할 Claude Code는 터미널에서 실행되는 AI 프로그래밍 어시스턴트입니다. 여러분이 원하는 것을 평범한 언어로 말하면, AI가 전체 프로그램을 작성해 줍니다.

왜 IDE 대신 터미널 도구를 사용할까?

IDE란 무엇인가?

IDE = 통합 개발 환경 (Integrated Development Environment)

간단히 말해, IDE는 프로그래머가 코드를 작성할 때 사용하는 소프트웨어입니다. 예를 들어:

VS Code
Cursor
PyCharm
WebStorm

이러한 도구들은 복잡한 인터페이스와 강력한 기능을 가지고 있지만, 코드에 대해 전혀 모르는 사람에게는 오히려 부담이 됩니다.

터미널을 추천하는 이유

이유 1: 간단한 인터페이스

IDE: 버튼, 메뉴, 사이드바, 상태 표시줄이 가득… 처음 보면 압도됩니다.
터미널: 그냥 검은 화면 하나 – 명령어를 입력하고 결과를 받으며, 깔끔하고 직관적입니다.

이유 2: 코드를 직접 수정할 필요가 없음

코드를 전혀 이해하지 못한다면, IDE에 표시된 코드는 외계어처럼 보일 것입니다. 읽을 수도 없고 어떻게 바꿔야 할지도 모릅니다.

모든 것이 AI에 의해 작성된다면, 굳이 코드를 볼 필요가 있을까요?

터미널의 Claude Code는 다음을 수행합니다:

자동으로 파일 생성
자동으로 코드 작성
자동으로 코드 수정
자동으로 테스트 실행

여러분은 원하는 것을 말하기만 하면, 나머지는 Claude Code가 처리합니다.

이유 3: 더 가벼운 소프트웨어

Cursor/VS Code: 수백 MB, 게다가 다양한 플러그인을 설치해야 함
터미널: 시스템에 내장되어 있어 추가 설치가 필요 없음

요약: 코딩 경험이 전혀 없고 AI가 도움을 주어 무언가를 만들고 싶은 사람에게는 터미널 + Claude Code가 가장 간단하고 직접적인 조합입니다.

터미널 기초: 프로젝트 폴더 여는 방법

Claude Code를 사용하기 전에 한 가지 기본 작업을 배워야 합니다: 터미널에서 프로젝트 폴더를 여는 방법.

Mac 사용자

방법 1: 마우스 오른쪽 버튼으로 열기 (권장)

Finder에서 프로젝트 폴더를 찾습니다.
폴더를 마우스 오른쪽 버튼으로 클릭합니다 (또는 트랙패드에서 두 손가락으로 탭).
“폴더에서 새 터미널 열기” 를 선택합니다.

방법 2: Option + 마우스 오른쪽 버튼으로 경로 복사

Finder에서 프로젝트 폴더를 찾습니다.
Option 키를 누른 상태에서 폴더를 마우스 오른쪽 버튼으로 클릭합니다.
"‘폴더명’을(를) 경로 이름으로 복사" 를 선택합니다.
터미널을 엽니다 (Launchpad에서 “터미널” 검색).
cd 를 입력합니다 (cd 뒤에 공백 주의).
Command + V를 눌러 경로를 붙여넣습니다.
Enter 키를 누릅니다.

예시:

cd /Users/yourname/Desktop/my-project

방법 3: 드래그 앤 드롭

터미널을 엽니다.
cd 를 입력합니다 (공백 주의).
Finder에서 폴더를 터미널 창으로 드래그합니다.
경로가 자동으로 입력되면 Enter 키를 누릅니다.

Windows 사용자

파일 탐색기에서 프로젝트 폴더를 찾습니다.
주소 표시줄에 cmd 또는 powershell을 입력하고 Enter 키를 누릅니다.
해당 폴더에서 명령줄이 바로 열립니다.

또는:

폴더를 마우스 오른쪽 버튼으로 클릭합니다.
“터미널에서 열기” 를 선택합니다 (Windows 11).

Claude Code란 무엇인가?

한 문장으로 요약

Claude Code = 터미널에서 실행되는 AI 프로그래밍 어시스턴트

Anthropic(Claude를 만든 회사)의 공식 명령줄 도구입니다. 터미널에서 대화하면 다음과 같은 일을 할 수 있습니다:

새 프로젝트 생성
코드 작성
코드 수정
버그 수정
코드 설명
명령어 실행

웹 버전 Claude와 어떻게 다른가?

기능	Claude 웹	Claude Code
사용 방법	브라우저에서 채팅	터미널에서 명령어 입력
파일 조작 가능?	아니요, 대화만 가능	예, 파일을 직접 생성하고 수정 가능
코드 실행 가능?	아니요	예, 컴퓨터에서 코드 실행 가능
가장 적합한 용도	질문하기, 글쓰기	프로젝트 구축, 프로그램 작성

핵심 차이: 웹 버전은 “말"만 할 수 있지만, Claude Code는 “행동"할 수 있습니다.

Claude Code 설치 방법

사전 요구 사항

Node.js: Claude Code는 Node.js가 필요합니다.
- 다운로드: https://nodejs.org
- LTS(장기 지원) 버전을 선택하세요.
- 설치 후 터미널에서 node -v로 확인합니다.

2. 네트워크 환경: Claude의 API에 접근할 수 있어야 합니다 (VPN이 필요할 수 있음).

설치 단계

터미널을 열고 다음을 실행합니다:

npm install -g @anthropic-ai/claude-code

설치가 완료될 때까지 기다립니다. 다음과 같은 출력이 보이면 성공입니다:

added 1 package in 2s

설치 확인:

claude --version

버전 번호가 표시되면 설치가 성공한 것입니다.

사용 방법 여러 가지

Claude Code는 AI 기능에 접근하는 여러 가지 방법을 지원합니다. 자신에게 맞는 방법을 선택하세요.

방법 1: Claude 멤버십 구매

이것이 가장 간단하고 직접적인 방법입니다.

Claude 멤버십 등급:

요금제	가격	Claude Code 할당량
Claude Pro	월 $20	제한된 할당량, 가벼운 사용에 적합
Claude Max	월 $100	더 높은 할당량, 많은 사용에 적합
Claude Max	월 $200	최고 할당량, 전문 개발에 적합

설정:

Claude 멤버십을 구매한 후 터미널을 엽니다.
claude를 실행하여 시작합니다.
안내에 따라 Claude 계정에 로그인합니다.
로그인하면 사용할 수 있습니다.

방법 2: 다른 모델의 API 사용

Claude 멤버십을 구매하고 싶지 않다면, 다른 모델의 API를 사용하여 Claude Code를 구동할 수 있습니다.

지원되는 모델:

DeepSeek
OpenAI GPT 시리즈
OpenAI 형식과 호환되는 기타 API

2.1 환경 변수로 설정 (DeepSeek 예시)

DeepSeek의 API는 Anthropic 형식과 호환되므로 직접 대체하여 사용할 수 있습니다.

Mac/Linux 설정:

터미널에서 다음 명령어를 실행합니다 (임시 설정 – 터미널을 닫으면 사라집니다):

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=${DEEPSEEK_API_KEY}
export API_TIMEOUT_MS=600000
export ANTHROPIC_MODEL=deepseek-chat
export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

그런 다음 claude를 실행하면 됩니다.

Windows 설정 (PowerShell):

$env:ANTHROPIC_BASE_URL="https://api.deepseek.com"
$env:ANTHROPIC_AUTH_TOKEN="Your DeepSeek API Key"

그런 다음 claude를 실행하면 됩니다.

참고: 이 방법은 임시 설정이며, 터미널을 닫으면 사라집니다. 영구 설정을 원하면 아래 settings.json 방법을 사용하세요.

참고 자료: https://api-docs.deepseek.com/guides/anthropic_api

2.2 settings.json으로 설정 (권장)

이 방법이 더 편리합니다. 한 번 설정하면 Claude Code를 시작할 때마다 자동으로 이 설정을 사용합니다.

설정 단계:

Claude Code 설정 폴더를 찾습니다:
- Mac/Linux: ~/.claude/
- Windows: %USERPROFILE%\.claude\
settings.json 파일을 생성하거나 편집합니다 (예시):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com",
    "ANTHROPIC_AUTH_TOKEN": "Your DeepSeek API Key"
  }
}

파일을 저장하고 Claude Code를 다시 시작합니다.

팁: .claude 폴더가 없다면 claude 명령어를 한 번 실행하면 자동으로 생성됩니다.

터미널에서 Claude Code 시작하는 방법

기본 시작

터미널을 엽니다.
cd 명령어로 프로젝트 폴더로 이동합니다.
claude를 입력하고 Enter 키를 누릅니다.

cd /path/to/your/project
claude

Claude Code가 시작되고, 요청을 입력할 수 있는 대화형 인터페이스가 나타납니다.

자주 사용하는 명령어와 개념

Claude Code의 자주 사용하는 명령어

명령어	동작
`/help`	도움말 보기
`/clear`	현재 대화 지우기
`/exit` 또는 `Ctrl+C`	Claude Code 종료
`/compact`	대화 기록 압축하여 토큰 절약
`/init`	프로젝트 초기화, CLAUDE.md 파일 생성

계획 모드 (Plan Mode)

계획 모드 = Claude가 먼저 계획을 세우고 실행하도록 함

기본적으로 Claude는 즉시 코드 작성을 시작합니다. 하지만 때로는 실행 전에 생각할 시간을 주고 싶을 때가 있습니다. 그럴 때 계획 모드를 활성화합니다.

전환 방법?

Shift + Tab을 눌러 세 가지 모드를 순환합니다:

모드	설명
Normal	일반 모드, Claude가 직접 실행
Plan	계획 모드, Claude는 계획만 세우고 실행하지 않음; 사용자 확인 대기
Auto	자동 모드, Claude가 모든 작업을 자동으로 실행, 확인 요청 없음

계획 모드는 언제 사용하나요?

프로젝트가 복잡해서 Claude가 먼저 접근 방식을 명확히 하길 원할 때
Claude가 어떻게 변경할지 확신이 서지 않아 계획을 보고 싶을 때
Claude의 행동을 더 정밀하게 제어하고 싶을 때

편집 수락 (Accept Edits)

편집 수락 = Claude의 수정을 자동으로 승인할지 여부

Claude가 파일을 생성하거나 수정하려고 할 때, 기본적으로 사용자의 확인을 요청합니다.

전환 방법?

Shift + Tab을 눌러 모드를 변경하면 다음이 표시됩니다:

Accept edits: off – 모든 수정에 대해 수동 확인 필요
Accept edits: on – 모든 수정을 자동으로 수락, 확인 없음

권장 사항:

초보자는 off 상태를 유지하여 Claude가 각 단계에서 무엇을 하는지 확인하는 것이 좋습니다.
익숙해지면 on으로 전환하여 더 원활한 작업 흐름을 경험하세요.

`resume`이란?

resume = 이전 대화 재개

터미널을 닫거나 Claude Code를 종료한 후, 다음에 --resume 플래그를 사용하여 이전 대화를 계속할 수 있습니다:

claude --resume

Claude가 이전에 논의한 내용을 기억하므로 처음부터 다시 시작할 필요가 없습니다.

resume은 언제 사용하나요?

어제 작업한 프로젝트를 오늘 이어서 하고 싶을 때
컴퓨터가 예기치 않게 종료되어 작업을 복구하고 싶을 때
Claude가 중단된 지점부터 계속 작업하길 원할 때

CLAUDE.md란?

CLAUDE.md = 프로젝트 설명 파일

프로젝트 루트 디렉토리에 있는 Markdown 파일입니다. Claude에게 프로젝트의 배경을 알려줍니다.

생성 방법?

먼저 claude를 실행하여 Claude Code를 시작한 후, /init을 입력합니다.

claude

Claude Code 내에서 다음을 입력합니다:

/init

Claude가 자동으로 프로젝트를 분석하고 CLAUDE.md 파일을 생성합니다.

무엇에 사용되나요?

Claude Code가 시작될 때 이 파일을 읽어 다음을 이해합니다:

프로젝트가 무엇을 하는지
어떤 기술 스택을 사용하는지
특별한 요구 사항이 있는지
코드 스타일 선호도

CLAUDE.md 예시:

# Project Description

This is a personal translation tool webpage.

## Tech Stack
- Pure HTML/CSS/JavaScript
- No frameworks

## Requirements
- Code comments in English
- Clean and modern interface
- Support dark mode

이 파일이 있으면 Claude Code를 시작할 때마다 프로젝트 배경을 설명할 필요가 없습니다.

Skill

Skill = Claude Code 단축 명령어

Skill은 미리 설정된 명령어로, Claude가 특정 작업을 빠르게 수행하도록 합니다.

자주 사용하는 내장 Skill:

명령어	동작
`/commit`	자동으로 git 커밋 메시지 생성 및 코드 커밋
`/review`	코드 리뷰 및 문제 찾기
`/fix`	코드 오류 수정

사용 방법?

Claude Code에서 슬래시 명령어를 입력하기만 하면 됩니다. 예:

/commit

Claude가 자동으로 코드 변경 사항을 분석하고 적절한 커밋 메시지를 생성합니다.

사용자 정의 Skill은 이후 장에서 자세히 다루겠습니다.

MCP (Model Context Protocol)

MCP = Claude를 외부 도구 및 데이터 소스에 연결

MCP는 Claude Code가 다양한 외부 서비스에 연결할 수 있게 해주는 프로토콜입니다. 예를 들어:

데이터베이스
파일 시스템
웹 서비스
기타 AI 도구

이렇게 생각하세요: MCP는 Claude에 “플러그인"을 추가하여 더 많은 일을 할 수 있게 합니다.

예시:

Obsidian에 연결하여 Claude가 노트를 직접 읽고 쓰게 함
브라우저에 연결하여 Claude가 웹 페이지를 자동화하게 함
데이터베이스에 연결하여 Claude가 데이터를 쿼리하고 분석하게 함

MCP 설정 및 사용법은 이후 장에서 자세히 다루겠습니다.

실습: Claude로 번역 웹페이지 만들기

이제 많은 것을 배웠으니, 직접 실습해 봅시다!

로컬 번역 웹페이지를 만들어서 Gemini API를 사용한 번역을 구현할 것입니다.

1단계: 프로젝트 폴더 생성

바탕화면(또는 원하는 곳)에 새 폴더를 만듭니다. 예를 들어 demo라는 이름으로 만듭니다.
앞서 배운 방법을 사용하여 이 폴더를 터미널에서 엽니다.

2단계: Claude Code 시작

claude

3단계: 요청 입력

Claude Code에 다음을 입력합니다 (복사해도 됩니다):

Create a translation webpage tool with the following requirements:

1. Features:
   - Left input box for the source text, right side shows the translation result
   - Support Chinese-English translation
   - A "Translate" button
   - A "Clear" button
   - A "Copy Result" button

2. Interface:
   - Clean and modern design
   - Support dark/light mode toggle
   - Responsive design, works on mobile

3. Technical requirements:
   - Use only HTML, CSS, JavaScript, no frameworks
   - All code in a single HTML file
   - Call the Gemini API for translation

4. Settings (important):
   - A "Settings" button on the page
   - Clicking it opens a settings panel where you can configure:
     - API Key
     - API URL
     - Model Name
   - Save settings to the browser's localStorage, auto-load next time
   - The settings panel should have "Save" and "Cancel" buttons

5. Translation logic:
   - Auto-detect the input language
   - If Chinese, translate to English
   - If English, translate to Chinese

Please create this HTML file directly.

4단계: Claude가 완료할 때까지 기다리기

Claude가 자동으로:

HTML 파일을 생성합니다.
모든 코드를 작성합니다.
파일 위치를 알려줍니다.
실행 후 파일 생성을 동의할지 묻습니다 – 1 또는 2를 선택하세요.

5단계: 실행 및 API 설정

생성된 HTML 파일을 더블 클릭하여 브라우저에서 엽니다.
페이지의 “설정” 버튼(보통 톱니바퀴 아이콘)을 클릭합니다.
나타난 설정 패널에 다음을 입력합니다:
- API Key: AI Studio에서 받은 API 키
- API URL: https://generativelanguage.googleapis.com/v1beta
- Model Name: gemini-3-flash-preview
“저장"을 클릭합니다.

설정은 브라우저에 자동 저장되므로 다음에 다시 입력할 필요가 없습니다.

6단계: 사용 시작

이제 다음을 할 수 있습니다:

왼쪽 입력 상자에 중국어 또는 영어를 입력합니다.
“번역” 버튼을 클릭합니다.
번역 결과가 오른쪽에 나타납니다.
“결과 복사"를 클릭하여 번역된 텍스트를 복사합니다.

요약

오늘 배운 내용:

IDE 대신 터미널을 사용하는 이유: 코드를 모르는 사람에게 터미널이 더 간단하고 직접적입니다.
터미널에서 프로젝트 여는 방법: 마우스 오른쪽 버튼, 드래그 앤 드롭, 또는 cd 명령어 사용.
Claude Code란 무엇인가: 터미널에서 파일을 직접 조작할 수 있는 AI 프로그래밍 어시스턴트.
설치 및 설정 방법: npm으로 설치, 공식 멤버십 또는 타사 API 지원.
자주 사용하는 명령어: resume으로 대화 재개, CLAUDE.md로 프로젝트 설명.
실습: Claude로 번역 웹페이지 만들기.

핵심 아이디어: 코드 작성 방법을 알 필요 없이, 원하는 것을 설명하는 방법만 알면 됩니다.

Claude Design: 아이디어를 세련된 페이지로 바꾸다

Mon, 01 Jan 0001 00:00:00 +0000

Claude에 Design이라는 새로운 기능이 추가되었습니다.

Claude Design은 Anthropic이 4월 17일에 출시한 연구 프리뷰로, Anthropic Labs 제품 라인의 일부이며 현재 가장 강력한 비전 모델인 Opus 4.7에서 실행됩니다. Claude로 시각적 드래프트를 만들기 위해 설계되었습니다. 웹 프로토타입, PPT, 피치 덱, 랜딩 페이지, 원페이지 등이 모두 그 범위에 포함됩니다. 코드 저장소와 기존 디자인 파일을 읽고, 출력에 디자인 시스템을 적용하여 스타일이 기존 프로젝트와 일치하도록 할 수 있습니다.

가장 좋은 점은 최종 출력입니다. PDF/PPTX/HTML로 내보내거나 Canva로 보내는 것 외에도 모든 것을 핸드오프 번들로 패키징하여 로컬 Claude Code에 전달하여 프로젝트 코드를 계속 수정할 수 있습니다.

이 기능이 나오자마자 Figma의 주가에 타격을 입혀 6.89% 하락 마감했습니다.

Figma에 대한 간단한 소개: 온라인 협업 디자인 도구를 만드는 회사로, Adobe 및 Canva와 경쟁합니다. 전 세계 수천만 명의 디자이너가 이를 사용하여 디자인을 만듭니다. 사실 AI로 Figma를 제어할 수 있는 MCP가 이미 있었지만, 제 미적 감각이 너무 기본적이고 머릿속이 텅 비어 아이디어가 없어서 그 제품을 사용하지 않았습니다.

왜 정말 필요했는가

제가 위챗 공식 계정에 콘텐츠를 푸시하기 위해 만든 Obsidian 플러그인을 기억하시나요?

지금까지 모든 채널을 통틀어 0개를 팔았습니다. 정말 기쁘네요 (TAT).

물론, 제 기본적인 디자인 취향과 관련이 있을 가능성이 있습니다. 자랑하는 건 아닙니다.

원래 플러그인 UI가 어땠는지 한번 보세요:

두 줄의 툴바, 9개의 버튼이 한 줄에 빽빽이 들어차 있습니다. 포맷, 계정, 사전 설정 계정 이름, 계정 설정, 구매 활성화, 사용자 가이드, 렌더링 새로고침, HTML 복사, 위챗 공식 계정에 붙여넣기, 초안 발행… 모두 가장 눈에 띄는 곳에 쌓여 있습니다.

모든 기능이 다 있지만, 보기만 해도 지칩니다.

그 아래에는 엄청 긴 프롬프트가 있습니다: ‘아래 버튼을 클릭하여 컴퓨터에서 이미지를 선택하세요; 비워두면 플레이스홀더 커버를 사용합니다; 기본 커버가 설정된 경우 기본 커버를 사용합니다.’ 친구가 보고 말하길, ‘이건 누구를 위한 거야? 데이터베이스 필드 설명?’

그래서 Claude Design이 나왔을 때 바로 시도해봤습니다. 실제로 어떻게 작동하는지 봅시다.

사용 방법

먼저 Claude 웹 버전을 열고 왼쪽의 Design을 클릭하여 들어갑니다. 상단에 ‘New prototype’이라는 입력 상자가 있으며, 프로젝트 이름을 입력하면 됩니다.

Wireframe(저충실도) 또는 High fidelity(브랜드 자산이 포함된 고충실도)를 선택할 수 있습니다. 처음에는 대략적인 개념만 있으면 되므로 저충실도를 선택했습니다. 사실 완료하면 자동으로 업그레이드해 줍니다.

다음으로, 프로그램 폴더 경로를 알려주고, 수정하려는 페이지의 스크린샷을 보내세요.

먼저 몇 가지 질문을 합니다: 무엇을 변경할지, 무엇을 유지할지, 기본 작업은 무엇인지, 보조 작업은 무엇인지. 솔직하게 고백했습니다—‘초안 발행’과 ‘계정 전환’을 가장 강조하고 싶고, 나머지는 접을 수 있게 하고 싶다고.

질문을 마친 후, 스스로 실행되기 시작했습니다.

4가지 옵션을 제시했습니다

곧 wireframes.html 비교 페이지를 건네주었습니다.

가장 먼저 비교를 보여주었습니다. 현재 UI의 ‘죄악’을 빨간색 텍스트로 하나씩 나열했습니다:

‘두 줄의 막대가 미리보기를 압박함’
‘9개의 버튼’
‘중국어/영어 혼용 + 혼란스러운 기호 설명’

이 기능은 정말 놀라웠습니다. 단순히 수정을 도와줄 줄 알았는데, 실제로 내용을 보고 문제점을 지적해 주었습니다. 차가운 AI가 아니라 실제 디자이너와 대면하여 소통하는 느낌이었습니다.

그리고 4가지 옵션이 나왔습니다:

옵션 A: 단일 행 미니멀, 메인 버튼 ‘초안 발행’ + 계정 캡슐, 나머지 아이콘 + ⋯ 메뉴
옵션 B: 카드 브레드크럼 + 드로어, 메타 정보 편집 항목 유지
옵션 C: 사이드 레일(VSCode처럼), 상단 바는 제목만
옵션 D: 오른쪽 아래에 떠 있는 발행 카드, 기본 작업이 가장 두드러짐

가장 흥미로웠던 것은 옵션 D였습니다. ‘일반적인 디자인 규칙’과 ‘권장 순서’가 적힌 스티커 메모를 그렸습니다:

A → 가장 공간 절약, 낮은 학습 비용 D → 시각적으로 가장 예쁨, 가장 만족스러운 기본 작업 C → 파워 유저에게 친숙함(아이콘 라이브러리) B → 안전함, 메타 정보 편집 유지

이것은 단순히 ‘여기 몇 가지 옵션이 있습니다’가 아니라 ‘여기 몇 가지 옵션이 있으며 각각 누구를 위한 것인지 알려줍니다’입니다. 저는 오랫동안 플러그인을 만들어 왔지만, 아무도 진지하게 ‘이 버튼이 어디에 있어야 하는지’ 알려준 적이 없습니다.

계속 반복할 수 있습니다

방향을 선택한 후에도 계속 소통할 수 있습니다. 왼쪽에는 채팅 상자가 있고, 오른쪽에서 Edit을 클릭하여 요소를 직접 선택하고 수정할 수 있습니다(하지만 설정이 너무 전문적이어서 이해할 수 없어 건너뛰었습니다). Draw를 클릭하여 미리보기에 원과 화살표를 그리고 ‘이것을 여기로 옮기고 싶다’고 말할 수 있습니다:

Draw 기능이 정말 놀랍다고 생각합니다. 버튼에서 오른쪽 아래로 매우 대략적인 화살표를 그렸는데 실제로 이해했습니다. 아마 Opus 4.7의 시각 인식 대규모 업그레이드와 관련이 있을 것입니다(앞서 언급했듯이 이미지 인식 정밀도를 3.75메가픽셀로 높였습니다).

툴바에서 레이아웃으로

메뉴 바를 수정한 후, 여러 가지 기사 레이아웃 스타일을 만들어 달라고 요청했습니다. 결국 제 플러그인의 주요 작업은 Markdown을 위챗 공식 계정에 게시할 수 있는 형식으로 변환하는 것이니까요.

새 페이지를 열었고 제목은 ‘Markdown을 읽을 가치가 있는 위챗 기사로 포맷하기’였습니다. 오른쪽 상단에는 Tweaks 버튼이 있어 클릭하면 글꼴 크기, 두께, 색상, 줄 간격 등을 Figma처럼 조정할 수 있습니다:

이것은 가짜가 아니라 실제로 클릭하고 전환할 수 있는 페이지입니다. 이 상호작용은 터미널에서 Claude Code로 하는 것보다 훨씬 좋습니다. Claude Code에서는 완료될 때까지 기다려야 효과를 볼 수 있고, 그런 다음 수정을 요청해야 합니다. 여기서는 실시간 미리보기를 얻을 수 있습니다.

최종 확정 후 오른쪽 상단의 Export를 클릭합니다. 여러 옵션이 제공됩니다: PPT 다운로드, PDF 내보내기, 독립형 HTML 내보내기, 또는 마지막 옵션인 **‘Handoff to Claude Code’**는 전체 디자인 파일을 로컬 Claude Code로 보내 코딩을 계속합니다.

이것이 전체 체인에서 가장 좋은 부분입니다.

웹에서 디자인한 후 명령어를 생성해 줍니다. 터미널에 복사하여 붙여넣으면 로컬 Claude Code가 작업을 이어받습니다:

> Fetch this design file, read its readme,
  and implement the relevant aspects of the design.
  Implement: option-b-hifi.html

그런 다음 디자인 패키지를 읽고, 현재 코드를 살펴보고, 수정할 파일을 파악한 후 마지막으로 제 플러그인 소스 코드를 모두 직접 변경합니다. 디자인 페이지는 option-b-hifi.html을 제공했고(결국 옵션 B의 고충실도 버전을 선택했습니다), Claude Code는 디자인 파일에서 색상, 글꼴 크기, 간격을 읽어 제 React 코드에 적용합니다.

전체 과정에서 단 한 줄의 코드도 작성하지 않았습니다.

최종 결과

어쨌든 원래보다 훨씬 낫다고 생각합니다. 실제 디자이너가 더 잘했을 수도 있지만, 개인 플러그인으로는 충분합니다(원래 디자인과 비교하면).

제목 + 메타 정보가 한 줄로 접히고, 계정은 캡슐(녹색 활성 점 포함)이 되었으며, 기본 작업은 오른쪽에 있는 보라색 ‘초안 발행’ 버튼 하나뿐이고, 나머지는 모두 ⋯ 메뉴에 숨겨졌습니다.

알고 보니 제 ‘기능’ 더미는 디자인 감각이 부족한 것이 아니라, 아무도 절충을 도와주지 않았던 것이었습니다.

버튼을 추가하는 것은 쉽지만, UI에서 버튼을 제거하는 것은 개발자에게 직관에 반합니다. 항상 ‘누군가 필요하면 어쩌지?‘라고 생각하니까요. 하지만 디자이너는 그 결정을 대신 내려줍니다: ‘이것은 보조 메뉴에 넣으세요. 사용자는 처음 이후에는 다시 클릭하지 않을 것입니다.’

이번에는 Claude Design이 그 결정을 내려주었습니다.

비용

리소스를 많이 소모합니다

Claude의 구독 요금제에서 Design은 자체 할당량이 있습니다(Claude의 별도 할당량이 정말 쌓이고 있다고 말해야겠네요).

이 작업 세트(4가지 옵션 비교 + 5가지 기사 테마 + 고충실도 구현)는 일일 할당량의 36%를 소모했습니다. 저는 5x Max 계정을 사용 중입니다. Pro 계정이라면 하루 할당량 전체를 소진했을 것입니다.

제 친구 중 한 명이 Pro 계정을 사용합니다. 어젯밤에 Design으로 30페이지 분량의 PPT를 만들었는데 일일 할당량이 완전히 소진되었습니다.

가끔 발생하는 결함

작업 중에 가끔 이런 상황이 발생할 수 있습니다: 메시지를 보내면 <empty>라고 응답합니다. 다시 보내도 여전히 <empty>입니다:

해결 방법은 페이지를 새로고침하고 ‘계속해 주세요’라고 말하는 것입니다. 그러면 보통 다시 이어받습니다. 하지만 약간의 맥락이 손실됩니다. 중요한 디자인 반복 작업 중이라면 수시로 스크린샷을 백업으로 찍어두세요. 마지막 단계에서 고장 나면 처음부터 다시 시작하지 않아도 됩니다.

마지막 생각

기본적인 디자인의 제 Obsidian 플러그인이 드디어 제대로 된 제품처럼 보이게 되었습니다.

하지만 솔직히 말하면, 컴퓨터 앞에 앉아 ‘초안 발행’을 클릭했을 때 완전히 신나지는 않았습니다. 한 가지는 매우 분명합니다. 디자인 교육을 받지 않은 사람이 두 시간 만에 괜찮은 UI를 만들 수 있다면, ‘괜찮은’ 것으로 생계를 유지하는 사람들은 앞으로 몇 년 동안 힘들어질 것입니다.

예전에는 AI가 작가들에게 문학적 취향을 가진 대화 상대를 잃게 만들까 걱정했습니다. 이번에는 그 반대입니다. 디자이너들은 시장에서 가장 두꺼운 부분인 초급에서 중급 범위를 잃게 될 것입니다.

AI가 한 걸음 나아갈 때마다 어떤 사람들은 환호하고, 어떤 사람들은 조용히 떠납니다. 이번에는 제가 환호하는 쪽이지만, 뒤에서 들려오는 한숨 소리가 들립니다.

최근 AI에 많은 시간과 돈을 쏟아부었고, 언젠가 나를 대체할까 걱정했지만, 아직 돌파구를 찾지 못했습니다. 일상 업무에는 도움이 되지만 근본적인 변화는 없습니다. 가장 중요한 것은, 돈을 벌지 못했다는 점입니다.

여러분도 저처럼 먼지 쌓인 작은 제품, 플러그인, 또는 웹사이트가 있다면 Claude Design을 사용해 보세요.

첫 번째 판매를 이끌어내지 못할 수도 있지만, 적어도 더 보기 좋게 만들어 줄 것입니다. 그리고 그것만으로도 큰 개선입니다.

Claude Routine: 직접 사용해 본 리뷰

Mon, 01 Jan 0001 00:00:00 +0000

Anthropic이 최근 Claude 관련 업데이트를 여러 가지 발표했습니다.

Claude Code 데스크톱 리디자인 — 하나의 창에서 여러 Claude 세션을 나란히 관리할 수 있고, 전환을 위한 새 사이드바가 추가되었습니다.
Routines 기능 출시 (연구 프리뷰) — Claude Code 작업을 이제 Anthropic의 자체 클라우드에서 실행할 수 있어 컴퓨터를 켜둘 필요가 없습니다.
데스크톱과 웹의 사소한 변경 사항 (멀티 세션 관리, 세션 공유 등).

제가 가장 주목한 것은 두 번째, Routines입니다.

이유는 간단합니다. 저는 OpenClaw와 Claude Desktop을 모두 가지고 있지만, 가벼운 사용자에게 클라우드 기반 작업은 주로 동영상이나 텍스트 클리핑 정도로 제한적입니다. OpenClaw를 사용하는 것은 닭 잡는 데 소를 쓰는 격입니다. Claude Desktop은? 로컬에서 실행되는 “예약 작업” 기능이 있지만 컴퓨터가 켜져 있고 데스크톱 앱이 실행 중이어야 합니다. MacBook Air를 24시간 켜두고 싶지 않습니다. 어느 쪽도 답이 아니었습니다!

Routines는 이 빈틈을 완벽하게 채워줍니다.

세 가지 방식을 비교하면 다음과 같습니다.

항목	Routines	Claude Desktop 예약 작업	OpenClaw
실행 위치	Anthropic 관리형 클라우드	사용자 컴퓨터	사용자 컴퓨터 또는 VPS
컴퓨터가 켜져 있어야 하는가?	아니요	예, 반드시 켜져 있어야 함	배포 방식에 따라 다름
앱을 계속 실행해야 하는가?	아니요	Claude Desktop이 실행 중이어야 함	아니요
Claude AI 호출	퍼스트파티 전체 제품군	Desktop에 내장	비공식 지원, 제한에 취약
설정 노력	구독만 있으면 됨	Desktop 설치	VPS 임대 + 자체 배포

데스크톱 예약 작업은 과도기적 솔루션이고, OpenClaw는 커뮤니티 주도 솔루션이며, Routines는 공식적인 새 클라우드 솔루션입니다. Anthropic은 서드파티 프레임워크가 자사 API를 호출하기 어렵게 만드는 동시에 Routines를 홍보하고 있습니다. 의도는 분명합니다. 자체적인 OpenClaw를 만들려는 것입니다.

Routines로 무엇을 할 수 있나요?

공식 사용 사례는 주로 개발자 시나리오입니다. 이슈 트래커를 밤마다 스캔하여 레이블 추가, 새 PR마다 자동 코드 리뷰, CD 배포 후 스모크 테스트 실행하여 오류 로그 확인, 매주 병합된 PR을 스캔하여 문서 업데이트 등입니다. 이는 비개발자에게는 다소 동떨어진 이야기입니다.

일반 사용자에게는 다음과 같은 시나리오가 더 적합합니다.

매일 아침 자동으로 일일 금융 브리핑 가져오기 (업종별 움직임, 상승/하락 종목 등), 이를 저장소에 커밋하여 일어나서 읽기.
Bilibili/YouTube 동영상을 자동으로 텍스트 노트로 변환하기 (이 글에서 하는 작업) — 링크를 공유하면 몇 분 후에 저장소에 Markdown 파일이 나타납니다.
주간 업계 조사 보고서 또는 주간 리뷰 생성하기 — 공개 정보를 자동으로 컴파일하여.
GitHub에서 별표 표시한 저장소 모니터링 — 오픈소스 프로젝트가 업데이트되면 Routine이 자동으로 diff를 가져와 중국어 요약을 제공합니다.

오늘 저는 두 번째인 Bilibili 동영상을 텍스트로 변환하는 것을 시도했습니다.

환경 설정

환경 설정은 약간 번거롭지만, 한 번만 하면 됩니다. 그 후에는 새 Routine을 만들 때 재사용할 수 있습니다.

다음 네 가지를 준비해야 합니다.

GitHub 계정 — 비공개 저장소를 사용합니다 (이유는 아래 설명).
Max 또는 Pro 구독 — 무료 계정은 아직 Routines를 사용할 수 없습니다.
로컬에 Claude Code CLI 설치 — 이후 대부분의 단계를 Claude가 처리하도록 할 것입니다.
코딩 기술 불필요 — 명령줄이 익숙하지 않다면 Claude Code에게 “Routine 설정 도와줘"라고 말하면 단계별로 안내해 줍니다.

이제 설정을 시작합니다.

할당량 및 진입점 확인

먼저 claude.ai에서 사용량 페이지를 엽니다. 구독 사용량에 routine 항목이 새로 추가된 것을 볼 수 있습니다. 저는 Max 계정이므로 하루에 15회 실행 가능합니다.

구체적인 할당량:

Pro: 하루 5회
Max: 하루 15회
Team/Enterprise: 하루 25회
그 이상은 종량제로 추가 사용 가능합니다.

15회는 트리거 횟수이며, Routine의 총 개수가 아닙니다. 여러 Routine을 만들어 이 할당량을 공유할 수 있습니다.

진입점은 claude.ai/code/routines입니다.

웹, 데스크톱, CLI 모두 동일한 작업 풀을 공유합니다. CLI에서 만든 작업은 웹에서도 볼 수 있습니다.

GitHub 비공개 저장소 연결 필수

Routines는 반드시 GitHub 저장소에 연결되어야 합니다. 이것은 필수 요구 사항이며, 없으면 만들 수 없습니다.

왜 이렇게 설계되었을까요? 작업이 시작될 때마다 클라우드가 Claude의 작업 디렉터리를 할당하기 때문입니다. 구체적으로는, 지정된 GitHub 저장소를 복제하여 “데스크톱"으로 사용합니다. Claude는 이 데스크톱 안에서 파일을 수정하고, 명령을 실행하고, 커밋하고, 푸시합니다. 작업이 끝나면 데스크톱은 정리되고, 저장소에는 결과물만 남습니다.

따라서 먼저 GitHub 저장소를 준비해야 합니다.

GitHub는 프로그래머들 사이에서 가장 인기 있는 “코드 저장 + 버전 관리 + 협업 플랫폼"이며, 전 세계 오픈소스 코드의 대부분을 호스팅합니다. 비개발자에게는 무료이며 버전 관리가 되는 클라우드 기반 개인 폴더로 사용할 수도 있습니다.

계정 생성은 간단합니다. github.com에 가입한 후, 오른쪽 상단의 “+” → New repository를 클릭하고, 원하는 이름(예: claude-routines)을 입력합니다.

저장소를 만들 때 Private (비공개)를 체크하고 Add a README도 체크해야 합니다. 그렇지 않으면 저장소가 완전히 비어 있고 기본 브랜치가 없어 Routine이 처음 복제할 때 실패합니다. 제가 이미 그 함정에 빠졌습니다.

이 단계가 낯설다면 Claude Code에게 던져버리세요: “Routine을 위한 GitHub 저장소를 만들어 줘” — 그러면 가입, 저장소 생성, 권한 부여를 단계별로 안내합니다.

클라우드 환경 생성

다음은 이미 비공개 저장소를 만들었다고 가정합니다.

각 Routine은 Anthropic 샌드박스 머신에서 실행됩니다. 이 머신에는 Python, Node, git 같은 기본 도구가 미리 설치되어 있지만, 사용자 정의 종속성(yt-dlp, ffmpeg 등)은 없습니다. 따라서 사용자 정의 환경을 만들어 각 실행 전에 설치할 항목과 로드할 API 키를 지정해야 합니다. 여기서 오른쪽 하단의 Add environment 버튼을 클릭합니다.

환경 설정에는 Network access 필드가 있으며, None, Trusted, Full 세 가지 옵션이 있습니다. 일반적인 함정이 있습니다.

기본값은 Trusted로, 공식 화이트리스트에 있는 웹사이트(주로 GitHub, PyPI, npm 같은 패키지 저장소)에만 접근을 허용합니다. bilibili.com과 youtube.com은 화이트리스트에 없습니다. 따라서 여기서는 Full을 선택합니다.

그런 다음 Setup script 필드에는 시작할 때마다 실행할 명령어(ffmpeg, yt-dlp 설치 등)를 입력하고, Environment variables에는 필요한 API 키(GEMINI_API_KEY 등)를 입력합니다.

여기 있는 내용을 이해하지 못해도 괜찮습니다. 단지 무엇을 입력해야 하는지 보여주는 것입니다. 실제로는 AI에게 하고 싶은 일을 말하고, 복사해서 붙여넣을 수 있는 스크립트를 요청하면 됩니다. 그냥 복사해서 붙여넣으면 됩니다.

환경 변수는 Anthropic의 환경 구성 데이터베이스에 저장됩니다. 공식 문서에 따르면 “해당 환경을 편집할 수 있는 모든 사람이 볼 수 있습니다”. 이 부분은 “주의사항” 섹션에서 더 자세히 다루겠습니다.

환경 ID 얻기 및 GitHub 권한 부여

환경을 만든 후, 로컬 Claude Code로 돌아가서 다음을 입력합니다.

/remote-env

그러면 클라우드에서 생성한 모든 환경과 해당 ID가 나열됩니다.

bili-sandbox에 해당하는 줄을 복사하여 Claude에게 전달합니다. 그러면 Claude가 작업에 사용할 환경을 알게 됩니다.

그런 다음 Claude는 “GitHub에 대한 액세스 권한이 필요합니다"라고 말하며 권한 부여 옵션을 제시합니다.

A: /web-setup — 로컬 gh CLI 토큰을 claude.ai와 동기화하며, 30초 정도 소요됩니다.
B: Claude GitHub App 설치 — GitHub 웹 페이지로 이동하여 특정 저장소를 선택하여 설치, 더 세분화된 제어가 가능합니다.

저는 샌드박스 테스트였기 때문에 A를 선택했습니다. 선택하면 웹 페이지가 다시 열리고, 거기에 GitHub 저장소가 보이면 권한 부여가 활성화된 것입니다.

권한 부여 후 로컬 환경으로 돌아옵니다. 이제 환경 설정이 완료되었습니다.

나중에 새 Routine을 만들 때 이 전체 구성을 다시 설정할 필요 없이 재사용할 수 있습니다.

AI가 작업 설정하기

여기서 Claude에게 “로컬에 있는 Bilibili-텍스트 변환 스킬을 Routine으로 옮기고 동영상 하나로 테스트해 줘"라고 알려줍니다.

그러면 Claude가 RemoteTrigger API를 호출하여 작업을 생성하고 트리거하는 모든 작업을 스스로 수행합니다. 완료되면 웹 페이지를 열면 작업이 이미 생성되어 있습니다.

그런 다음 Bilibili 동영상 링크를 찾아 AI에게 보내서 제대로 작동하는지 테스트합니다. 저는 Bilibili에서 “AI 지식 베이스"에 관한 6분짜리 동영상을 골랐습니다. 클라우드 Claude가 먼저 yt-dlp를 사용하여 오디오를 다운로드한 다음, Gemini를 호출하여 텍스트로 변환하고, 결과를 Markdown으로 작성하여 최종적으로 제 Claude-Routines 저장소에 커밋합니다.

최종 결과는 약 3,000자의 정확한 중국어 텍스트였습니다. 중국어-영어 혼용 용어(LLM-Wiki, RAG, Karpathy, NewType OS 등)가 모두 정확하게 보존되었으며, 단락도 완전했습니다. 이 모든 과정에서 제가 한 일은 Claude Code 대화 상자에 입력하는 것뿐이었습니다. 터미널을 열거나, 명령어를 실행하거나, GitHub 웹 페이지를 열지 않았습니다.

트리거 방법

위의 실행은 Claude Code가 Anthropic의 관리 API를 직접 호출하여 Routine을 만들고 한 번 트리거하도록 한 것입니다. 테스트 편의를 위해 AI가 모든 작업을 수행하도록 한 것입니다.

일상적인 사용을 위해 Routines는 세 가지 공식 트리거 방법을 지원합니다.

1. 예약 트리거 — 시간별/일별/주별 사전 설정과 최소 1시간 간격의 사용자 정의 cron 표현식을 지원합니다. 일반적인 시나리오: 매일 오전 9시에 어제의 자금 흐름과 뉴스를 자동으로 요약합니다.

2. API 트리거 — 각 Routine은 전용 HTTP 엔드포인트 + Bearer 토큰을 생성할 수 있습니다. 이 엔드포인트에 POST 요청을 보내면 즉시 작업이 트리거되며, 요청 본문에 임시 매개변수(예: URL)를 전달할 수 있습니다.

3. GitHub 이벤트 트리거 — 저장소에서 PR, push, issue, release 등의 이벤트가 발생하면 Routine이 자동으로 실행됩니다. 주로 개발자 시나리오용입니다.

세 가지 트리거 방법은 혼합하여 사용할 수 있습니다. 동일한 Routine이 예약에 따라 실행되고, API 호출을 수락하며, 동시에 GitHub 이벤트를 수신할 수 있습니다.

iPhone 단축어로 트리거하기까지

API 트리거의 가장 흥미로운 점은 클라이언트에 구애받지 않는다는 것입니다. HTTP POST를 보낼 수 있는 모든 것이 Routine을 트리거할 수 있습니다.

이런 시나리오를 상상해 보세요. Bilibili에서 좋은 동영상을 발견하고, 공유 버튼을 탭 → iPhone 단축어 → 자동으로 URL을 Routine의 엔드포인트에 POST로 전송합니다. 30초 후에 GitHub를 열면 텍스트가 이미 있습니다. Mac을 켜거나, Claude Code를 열거나, 한 글자도 입력할 필요가 없습니다.

설정은 간단합니다.

Routine 구성 페이지에서 API 토큰을 생성합니다.
iPhone에서 공유 URL을 입력으로 받아들이는 단축어를 만듭니다.
“URL 콘텐츠 가져오기” 동작을 사용하여 POST 요청을 보내고, 본문에 URL을 Routine에 전달합니다.
Routine 프롬프트에서 요청 본문에서 URL을 읽은 다음 yt-dlp + Gemini를 호출하여 텍스트를 변환합니다.

이 조합은 “클라우드 AI 워크플로"와 “모바일 트리거"를 연결합니다. 일반인이 처음으로 컴퓨터를 켜지 않고도 AI에게 특정 작업을 시킬 수 있게 되었습니다.

결과 확인

텍스트 변환 결과는 GitHub 저장소의 새 브랜치에 커밋으로 저장되며, GitHub 웹 페이지에서 직접 볼 수 있습니다. 하지만 일반 사용자라면 로컬로 가져오고 싶을 것입니다. 세 가지 방법이 있습니다.

GitHub 웹 페이지에서 직접 읽거나 클릭하여 다운로드.
한 줄 명령어로 로컬 디렉터리로 가져오기 (예: Obsidian 받은 편지함에 직접 동기화).
동기화 스크립트 설정 (예: launchd 예약 git pull, 또는 클릭 한 번으로 가져오는 Obsidian 플러그인 생성).

주의사항

Routines는 훌륭하지만 몇 가지 주의할 점이 있습니다.

GitHub 권한 세분화

Claude GitHub App을 사용하는 것이 /web-setup을 사용하는 것보다 안전합니다. 전자는 Claude가 선택한 특정 저장소에만 접근하도록 허용하는 반면, 후자는 gh CLI에 표시되는 모든 저장소에 대한 액세스 권한을 사실상 넘겨줍니다. 샌드박스 테스트에는 옵션 A도 괜찮지만, 일상적인 작업에는 App을 사용하는 것이 좋습니다.

API 키가 클라우드에 노출됩니다.

환경 변수의 내용은 Anthropic의 환경 구성 데이터베이스에 저장됩니다. 공식 표현은 “해당 환경을 편집할 수 있는 모든 사람이 볼 수 있다"는 뜻으로, 환경을 편집할 수 있는 사람이라면 누구나 볼 수 있습니다. 개인 계정의 경우 기본적으로는 본인만 볼 수 있지만, 권한이 부여된 Anthropic 내부 직원도 이론적으로 접근할 수 있습니다.

따라서 할당량이 높은 프로덕션 API 키는 넣지 말고, 할당량이 낮거나 취소 가능한 하위 키를 사용하세요.

저장소를 비공개로 유지하세요.

각 Routine 커밋은 사용자의 GitHub 아이덴티티를 사용합니다. 저장소가 공개되면 텍스트 변환 결과가 GitHub 검색 및 인덱싱에 포착됩니다. 샌드박스 저장소를 만들 때는 Private을 망설임 없이 체크하세요.

요약

Routines는 Anthropic이 자동화 작업을 공식적으로 클라우드로 옮기는 첫 번째 단계입니다. 일반 사용자에게는 “예약 작업에 컴퓨터가 켜져 있어야 하는” 오래된 문제를 해결해 주고, Anthropic에게는 자체 생태계를 구축하고 서드파티 API 접근을 제한하는 핵심 요소입니다.

오늘 배운 내용:

Routines는 Claude Code의 클라우드 작업 스케줄링 시스템으로, 2026년 4월 14일에 연구 프리뷰로 출시되었습니다.
요구 사항: Max/Pro 구독 + GitHub 저장소 + Claude Code CLI.
세 가지 공식 트리거 방법: 예약, API, GitHub 이벤트. 혼합 사용 가능. iPhone 단축어와 결합하면 “휴대폰에서 URL 공유 → 클라우드에서 자동 실행 → GitHub에서 결과 수신"의 완전한 체인을 구현할 수 있습니다.
GitHub 저장소 연결 필수 및 기본 제한된 네트워크는 적응해야 할 제약 사항입니다.

핵심 포인트:

GitHub 저장소를 만들 때는 반드시 Private과 Add a README를 체크하세요.
클라우드 환경에서 Network access를 Full로 설정하지 않으면 많은 일반 웹사이트에 접근할 수 없습니다.
API 키는 Anthropic의 환경 구성에 저장되므로 프로덕션 키를 넣지 마세요.
첫 번째 환경 설정은 약간 번거롭지만, 한 번 구성하면 계속 재사용할 수 있어 이후 Routine 생성이 훨씬 쉬워집니다.

Codex App: 터미널과 IDE 사이

Mon, 01 Jan 0001 00:00:00 +0000

이 장에서는 OpenAI의 Codex 데스크톱 앱에 대해 다룹니다. 이 앱은 Codex CLI(터미널)와 Cursor/VS Code(IDE)의 중간 지점에 위치합니다.

터미널에서 Codex CLI를 사용해본 적이 있을 것입니다. 강력하지만 텍스트 전용 인터페이스는 초보자에게 친숙하지 않습니다. 반면, Cursor나 VS Code 같은 IDE는 기능이 너무 많아 코드 패널로 가득 찬 화면이 부담스러울 수 있습니다.

Codex APP은 터미널과 IDE의 중간 지점입니다. 터미널에 비해 시각적 요소를 추가하고, IDE에 비해 혼란스러운 코드 세부 사항을 제거했습니다.

Codex APP이란?

요약: Codex APP = Codex CLI의 GUI 버전입니다.

여전히 동일한 Codex이며, 단지 “셸"만 다릅니다. CLI는 터미널에 입력하여 작동하고, APP은 데스크톱 창에서 클릭하여 작동합니다. 기본 기능은 동일하며, 동일한 구성 파일 ~/.codex/config.toml을 공유합니다.

현재 제한 사항:

macOS(Apple Silicon) 만 지원 – M1 이상의 Mac
Windows 및 Linux 버전은 아직 개발 중

다운로드: OpenAI 웹사이트에서 DMG 설치 프로그램을 받아 직접 설치하세요.

로그인 방법:

로그인 방법	설명
ChatGPT 계정	Plus/Pro/Business/Enterprise/Edu 구독 필요. 클라우드 스레드 및 모델 전환 등 모든 기능 사용 가능.
API 키	기능 제한됨. 클라우드 스레드 없음. 모델은 `config.toml`에서 수동으로 지정해야 함.

인터페이스 기능

Codex APP은 현재 중국어 인터페이스가 없으므로, 각 기능의 번역을 제공하여 해당 버튼을 찾는 데 도움을 드립니다.

새 스레드(New Thread)

새로운 AI 작업 대화를 생성합니다. 생성 시 세 가지 모드 중 선택할 수 있습니다:

로컬(Local) – 프로젝트 폴더에서 직접 작업
워크트리(Worktree) – 격리된 Git 워크트리에서 작업하여 메인 브랜치에 영향을 주지 않음
클라우드(Cloud) – 원격 클라우드 환경에서 실행 (ChatGPT 계정 로그인 필요)

초보자는 로컬 모드로 시작하세요 – 가장 간단하고 직관적입니다.

스킬(Skills)

Codex CLI에서 사용되는 것과 동일한 Skill 시스템입니다. 여기에서 모든 사용 가능한 Skill을 보고 관리할 수 있으며, 대화 중에 /skill-name으로 호출할 수 있습니다.

스킬은 APP과 CLI 간에 공유됩니다 – CLI에서 만든 모든 Skill은 APP에서 즉시 사용할 수 있습니다.

자동화(Automations)

이 기능은 APP 전용입니다 – CLI에서는 찾을 수 없습니다.

AI에 알람 시계를 설정한다고 생각하세요.

AI에게 “매일 아침 9시에 이 작업을 해줘"라고 말하면, 예약된 시간에 실행되어 결과를 받은 편지함에 넣어 검토할 수 있게 합니다.

작동 방식:

실행 빈도 설정 (예: 매일, 매주)
지시사항 작성 (AI에게 무엇을 할지 알려줌)
선택적으로 Skill 바인딩 ($skill-name 구문 사용)
AI가 정시에 실행되고 결과는 검토 대기열로 이동

일반적인 사용 사례:

최근 커밋을 매일 스캔하여 버그 확인
주간 코드 변경 보고서
정기적인 종속성 보안 취약점 검사
CI 실패 원인 자동 요약

참고: 자동화는 로컬에서 실행되므로 APP이 열려 있어야 합니다. Git 프로젝트의 경우 각 자동화는 독립적인 워크트리에서 실행되므로 현재 작업에 영향을 주지 않습니다.

설정(Configuration)

여기에서 다음을 설정할 수 있습니다:

모델 선택 – ChatGPT 계정 사용자는 인터페이스에서 직접 모델 전환 가능
승인 정책 – AI가 자동으로 수행할 수 있는 작업과 수동 확인이 필요한 작업 제어
샌드박스 설정 – AI 권한 제한 (읽기 전용 / 작업 공간 쓰기 / 전체 액세스)

이 설정은 CLI에서 사용하는 동일한 config.toml과 공유됩니다 – 한 곳에서 변경하면 다른 곳에도 적용됩니다.

개인화(Personalization)

AI의 “성격"을 선택하세요:

옵션	효과
친근함(Friendly)	AI 응답이 더 따뜻하고 상세함
실용적(Pragmatic)	AI 응답이 더 간결하고 요점을 바로 전달함
없음(None)	성격 설정 없음

사용자 지정 지시사항도 추가할 수 있습니다. 예: “한국어로 답변해줘” 또는 “코드 주석은 영어로 작성해줘”. 이 지시사항은 AGENTS.md 파일에 기록됩니다.

MCP 서버

앞서 다룬 MCP 구성과 동일합니다. APP, CLI, IDE 플러그인은 모두 동일한 MCP 구성을 공유합니다 – CLI에서 설정한 모든 MCP 서버는 APP에서 자동으로 사용 가능합니다.

Git

이것은 CLI 대비 APP의 주요 장점 중 하나입니다. 내장된 시각적 Git 도구가 포함되어 있습니다:

Diff 뷰어 – 코드 변경 사항을 그래픽으로 확인하고 인라인 주석 추가
스테이징/실행 취소 – 코드 블록 또는 전체 파일을 선택적으로 스테이징
커밋/푸시 – APP 내에서 직접 커밋 및 푸시 수행
PR 생성 – 한 번의 클릭으로 Pull Request 생성

CLI에서는 이 모든 작업을 명령줄로 수행해야 하지만, APP에서는 클릭만 하면 됩니다. Worktree나 Git 통합과 같은 개념을 완전히 이해하지 못해도 괜찮습니다 – 대략적인 개념만 이해하세요.

환경(Environments)

코드 실행 환경을 구성합니다. 로컬 또는 클라우드 환경을 설정하고, 프로젝트 종속성을 설치하는 등의 작업을 할 수 있습니다.

워크트리(Worktrees)

Git Worktree를 시각적으로 관리합니다. 간단히 말해, 여러 AI 작업이 서로 간섭하지 않도록 합니다.

예를 들어, AI에게 세 가지 작업(버그 수정, 새 기능 작성, 코드 리팩토링)을 동시에 요청한다고 가정해 보겠습니다. 모든 작업이 동일한 디렉토리에서 수행되면 파일 변경 사항이 충돌할 수밖에 없습니다. Worktree는 각 작업에 대해 독립적인 작업 복사본을 생성하여 서로 간섭 없이 병렬로 작업할 수 있게 합니다.

스레드(Threads) vs 프로젝트(Projects) – 컨텍스트 이해하기

이 부분은 전체 장에서 가장 중요합니다 – 주의 깊게 읽어주세요.

두 가지 핵심 개념

프로젝트(Project) = 코드 저장소 또는 폴더입니다.

프로젝트를 작업대라고 생각하세요. 해당 프로젝트와 관련된 모든 작업을 이 작업대에서 수행합니다.

스레드(Thread) = 프로젝트 내의 특정 작업입니다.

각 스레드를 작업대 위의 작업 카드라고 생각하세요. 버그 수정은 하나의 카드, 문서 작성은 또 다른 카드입니다.

하나의 프로젝트는 여러 스레드를 가질 수 있지만, 각 스레드는 하나의 프로젝트에만 속합니다.

이것이 중요한 이유

여기서 핵심 개념인 **컨텍스트(Context)**를 소개합니다.

컨텍스트란 무엇인가요?

친구와 위챗으로 대화하는 것을 상상해보세요. 당신이 “그 일 어떻게 됐어?“라고 말하면, 친구는 당신이 무슨 말을 하는지 정확히 압니다 – 왜냐하면 이전에 그 이야기를 했기 때문입니다. 그 “이전 대화"가 바로 컨텍스트입니다.

AI도 마찬가지입니다. 대화에서 당신이 말하는 모든 문장과 보내는 모든 파일은 AI가 기억하고, 이후 질문을 이해하는 데 사용됩니다. AI가 “기억하는” 것이 바로 컨텍스트입니다.

컨텍스트 윈도우 = AI의 메모리 용량

하지만 AI의 메모리는 무한하지 않습니다. 기억할 수 있는 용량에는 상한선이 있으며, 이를 컨텍스트 윈도우(context window)라고 합니다.

현재 Codex는 기본적으로 GPT-5.3-Codex를 사용하며, 컨텍스트 윈도우는 약 400,000 토큰입니다. 대략 한국어 약 30만 자 분량의 대화에 해당합니다.

많아 보이지만, 모든 작업을 동일한 대화에서 수행하면 금방 채워집니다.

스레드 격리의 이점

서로 다른 스레드의 대화는 격리되어 서로 간섭하지 않습니다.

이렇게 생각해보세요: 세 가지 작업을 하고 있는데 모든 내용을 같은 종이에 적는다면, 버그 수정 메모, 문서 메모, 요구 사항 논의가 모두 섞여서 – 당신에게도 AI에게도 혼란스러울 것입니다.

세 개의 스레드로 나누면 깔끔해집니다:

스레드 1: 버그 수정 전용 – AI는 버그 관련 대화만 기억
스레드 2: 문서 작성 전용 – AI는 문서 관련 대화만 기억
스레드 3: 요구 사항 논의 전용 – AI는 요구 사항 관련 대화만 기억

이것은 지식 베이스 프로젝트에서 특히 중요합니다. 예를 들어, Obsidian을 사용하여 노트를 관리하는 경우, 하나의 스레드로 정보를 검색하고 다른 스레드로 문서를 정리하면 상호 오염이 발생하지 않습니다. 문서를 정리하는 중에 AI가 갑자기 연구 세션의 컨텍스트를 섞어 넣는 일이 없습니다.

예를 들어, 아래 Obsidian 노트북 스크린샷에서 모든 것이 동일한 저장소에 있지만, 작업에 따라 다른 스레드를 사용합니다. 이는 웹 버전 ChatGPT의 대화 개념과 유사하다고 생각하면 됩니다.

Codex APP vs Codex CLI

둘 다 동일한 기반을 공유하므로, 어떤 것을 선택해야 할까요? 비교해보겠습니다:

측면	Codex CLI (터미널)	Codex APP (데스크톱)
인터페이스	텍스트 전용	그래픽
대화 관리	`resume`으로 기록 찾기 필요	시각적 대화 목록, 클릭으로 전환
예약 작업	없음 (cron 등 별도 도구 필요)	내장 자동화(Automations)
Git 작업	명령줄	시각적 diff + 원클릭 커밋/PR
모델 전환	`config.toml` 편집	유료 계정은 인터페이스에서 직접 선택 가능
체감 속도	더 빠르게 느껴짐	약간 느리게 느껴짐 (개인 경험)
적합한 사용자	터미널에 익숙한 개발자	시각적 경험을 원하는 사용자

주요 차이점

1. 시각적 대화 관리 – 더 이상 resume으로 대화를 찾을 필요 없음

CLI에서는 이전 대화를 다시 보려면 codex --resume을 사용해야 합니다. 대화가 많으면 원하는 대화를 찾기가 번거롭습니다.

APP은 모든 스레드를 한눈에 볼 수 있는 대화 목록을 제공하며, 클릭만으로 전환할 수 있습니다. 여러 작업을 동시에 처리하는 사람에게는 이것만으로도 가치가 있습니다.

2. 자동화(Automations) – APP 전용

CLI에는 이 기능이 없습니다. CLI에서 유사한 기능을 구현하려면 cron이나 다른 스케줄링 도구를 직접 설정해야 하므로 진입 장벽이 높습니다. APP에서는 직접 구성할 수 있어 훨씬 편리합니다.

3. 더 쉬운 모델 전환

유료 ChatGPT 계정으로 로그인하면 구성 파일을 편집하지 않고도 APP 인터페이스에서 직접 모델을 전환할 수 있습니다.

저처럼 API 키를 사용하는 경우: APP과 CLI는 동일한 ~/.codex/config.toml을 공유합니다. toml 파일에 모델을 지정하기만 하면 APP이 자동으로 읽습니다. 예:

model = "GPT-5.3-Codex"

4. 포지셔닝: 터미널과 IDE 사이의 중간 지점

터미널과 비교하면, APP은 시각적 대화 관리, Git 작업, 예약 작업을 추가합니다.

IDE(Cursor 등)와 비교하면, APP은 복잡한 코드 패널과 편집기 기능을 제거하고 AI 대화와 프로젝트 관리에 집중합니다.

터미널이 너무 기술적으로 느껴지고 IDE가 너무 복잡하다면, APP이 바로 당신이 찾던 “딱 맞는” 도구일 수 있습니다.

개인 경험

솔직히 말하면: 저는 여전히 터미널을 선호합니다.

아마 제 착각일 수도 있지만, APP이 CLI보다 약간 느리게 느껴집니다. 그래픽 인터페이스의 오버헤드 때문일 수도 있고, 순전히 심리적인 것일 수도 있습니다 – 잘 모르겠습니다.

하지만 인정해야 할 것은, APP이 확실히 초보자에게 더 친숙하다는 점입니다. 특히 대화 관리와 Git 작업에서 시각적 경험이 터미널에서 명령을 입력하는 것보다 훨씬 편안합니다.

제 조언: 둘 다 사용해보고 자신에게 맞는 도구를 찾으세요. 구성이 공유되므로 전환하는 데 비용이 들지 않습니다.

요약

오늘 배운 내용:

Codex APP이란 무엇인가 – Codex CLI의 GUI 버전, 현재 macOS Apple Silicon만 지원
핵심 기능 – 스레드 대화 관리, 자동화 예약 작업, 시각적 Git 통합, Worktree 격리
스레드 vs 프로젝트 – 프로젝트는 작업대, 스레드는 작업 카드 – 작업 격리로 컨텍스트 오염 방지
CLI와의 차이점 – 시각적 대화 + 자동화가 가장 큰 장점이지만, 체감 속도는 약간 느릴 수 있음
포지셔닝 – 터미널과 IDE 사이의 중간 지점, 시각적 요소를 원하지만 전체 IDE가 필요하지 않은 사용자에게 적합

핵심 요점:

Codex APP과 CLI는 동일한 기반과 구성을 공유합니다 – 어느 것을 선택해도 나쁘지 않습니다
스레드 격리가 핵심입니다 – 작업별로 대화를 분리하여 컨텍스트 오염을 방지하세요
자동화는 APP의 킬러 기능입니다 – AI에 알람 시계를 설정한다고 생각하세요
보너스 사용법: APP을 음성 입력 방법으로도 사용할 수 있습니다 – 단축키를 누르고 말하기 (다음 섹션 참조)

보너스: Codex APP을 음성 입력 방법으로 사용하기

최근 Codex APP에 음성 기능이 추가되었습니다. 가장 좋은 점은 앱 내부뿐만 아니라 외부에서도 작동한다는 것입니다 – 전역 단축키를 누르고 말하기만 하면 됩니다.

Codex APP을 최신 버전으로 업데이트하고 구독 계정으로 로그인하면 사용할 수 있습니다. Codex APP을 항상 켜두는 사람에게는 사실상 무료 음성 입력 방법입니다.

OpenAI는 얼마 전 오픈소스 음성 인식 모델 Whisper를 출시하여 음성 인식의 진입 장벽을 크게 낮추었고, 계속해서 개선해 왔습니다. 따라서 그 기반 위에 구축된 Codex APP의 음성 기능이 매우 잘 작동하는 것은 놀라운 일이 아닙니다.

사용법은 간단합니다: 앱을 열고 일반 설정(General Settings)으로 이동한 후 단축키를 지정합니다(저는 오른쪽 Option 키를 사용합니다). 텍스트를 입력하고 싶을 때 단축키를 누른 상태로 말하면 됩니다.

키를 누르고 있으면 데스크톱 하단에 작은 창이 나타납니다(단축키 충돌로 스크린샷을 찍을 수 없습니다).

실제 사용 시 빠르고 정확합니다. 두 가지 사소한 단점이 있습니다:

사전 기능 없음 – 사전이 있으면 자주 사용하는 단어를 설정하여 인식률을 더욱 높일 수 있음
키를 누르고 있어야 녹음됨 – 다른 제품처럼 토글(한 번 누르면 시작, 다시 누르면 중지) 방식은 아직 지원하지 않음

이것은 완전히 새로운 기능이므로, 이러한 개선 사항은 향후 업데이트에서 제공될 가능성이 높습니다.

음성 입력 방법에 매달 비용을 지불해도 괜찮다면, Wispr Flow나 Typeless와 같은 다른 인기 있는 옵션도 있습니다.

Codex CLI: 실전 입문

Mon, 01 Jan 0001 00:00:00 +0000

앞서 Claude Code를 소개했습니다. 이번 장에서는 또 하나의 강력한 터미널 AI 코딩 도구인 Codex CLI를 다룹니다.

참고: Codex에는 데스크톱 앱 버전(그래픽 인터페이스)도 있으며, 이는 이후 장에서 다룹니다. 이 장에서는 터미널 기반 Codex CLI에 초점을 맞춥니다.

터미널 기반 Codex CLI는 Claude Code와 마찬가지로 터미널에서 실행되는 AI 코딩 어시스턴트입니다. 이전 장에서 Claude Code를 이미 배웠다면, 작동 방식이 거의 동일하므로 Codex CLI를 매우 쉽게 익힐 수 있습니다.

Codex CLI란?

한 줄 소개

Codex CLI = OpenAI의 터미널 AI 코딩 어시스턴트

Claude Code와 유사하게, 터미널에서 실행되는 AI 도구입니다. 자연어로 원하는 작업을 지시하면 다음과 같은 일을 할 수 있습니다:

새 프로젝트 생성
코드 작성
코드 수정
버그 수정
명령어 실행
웹 검색을 통한 최신 정보 획득

Codex CLI와 Claude Code의 차이점

항목	Claude Code	Codex CLI
개발사	Anthropic (Claude)	OpenAI (ChatGPT)
기반 모델	Claude 시리즈	GPT 시리즈 (GPT-5-Codex)
설치 방법	npm install	npm install
설정 파일	`~/.claude/settings.json`	`~/.codex/config.toml`
멤버십	Claude Pro/Max	ChatGPT Plus/Pro
지원 OS	Mac/Linux/Windows	Mac/Linux (Windows는 WSL 필요)

핵심 차이점: 서로 다른 기반 모델. Claude Code는 Claude 모델을, Codex CLI는 프로그래밍에 최적화된 OpenAI의 GPT-5-Codex 모델을 사용합니다. 두 도구 모두 장단점이 있으므로, 두 가지를 모두 설치하고 작업에 따라 선택하는 것을 권장합니다.

Codex CLI 설치 방법

사전 요구 사항

Node.js: Claude Code와 마찬가지로 Node.js 환경이 필요합니다.
- 이미 설치되어 있다면(이전에 Claude Code를 설치하면서) 다시 설치할 필요가 없습니다.
- 설치되어 있지 않다면 https://nodejs.org 에서 LTS 버전을 다운로드하세요.
네트워크: OpenAI 서비스에 접근할 수 있어야 합니다(프록시가 필요할 수 있음).

설치 단계

터미널을 열고 다음을 실행하세요:

npm install -g @openai/codex

완료될 때까지 기다립니다.

설치 확인:

codex --version

버전 번호(예: codex-cli 0.98.0)가 표시되면 설치가 성공한 것입니다.

Mac 사용자는 Homebrew로도 설치할 수 있습니다:

brew install codex

사용 방법 (여러 가지)

Claude Code와 마찬가지로 Codex CLI는 AI 기능에 접근하는 여러 방법을 지원합니다.

방법 1: ChatGPT 멤버십 구매 (가장 간단)

Codex CLI는 ChatGPT 유료 요금제에 포함되어 있습니다.

지원되는 멤버십 유형:

멤버십	가격	비고
ChatGPT Plus	$20/월	제한된 할당량
ChatGPT Pro	$200/월	더 높은 할당량
ChatGPT Business	팀 요금제	기업용

설정:

ChatGPT 멤버십을 구매한 후 터미널을 엽니다.
codex를 실행하여 시작합니다.
프롬프트에 따라 ChatGPT 계정에 로그인합니다(브라우저가 열려 인증을 진행합니다).
로그인하면 사용할 수 있습니다.

수동으로 로그인할 수도 있습니다:

codex login

방법 2: OpenAI API 키 사용

OpenAI API 키가 있다면 직접 사용할 수 있습니다:

환경 변수 설정:

export OPENAI_API_KEY="your API Key"

그런 다음 codex를 실행합니다.

방법 3: 타사 API 사용 (국내 모델 연동)

이것이 많은 국내 사용자들이 가장 관심을 가지는 부분입니다!

Claude Code와 마찬가지로 Codex CLI도 타사 API와 연동할 수 있습니다. 예를 들어 DeepSeek, Volcengine 등 국내 모델을 사용할 수 있습니다.

설정은 ~/.codex/config.toml 파일을 수정하여 수행합니다(자세한 내용은 다음 섹션에서 설명).

국내 모델 연동: config.toml 수정

config.toml 위치

설정 파일 경로: ~/.codex/config.toml

Mac/Linux: /Users/사용자이름/.codex/config.toml
Windows (WSL): ~/.codex/config.toml

팁: 이 파일이 없다면 먼저 codex를 한 번 실행하면 .codex 폴더가 자동으로 생성됩니다. 그런 다음 config.toml 파일을 수동으로 생성하면 됩니다.

기본 설정 구조

config.toml 설정은 여러 핵심 부분으로 나뉩니다:

# ===== Basic settings =====
model = "gpt-5.3-codex"              # Model to use
model_provider = "openai"             # Model provider (default openai)
approval_policy = "on-failure"        # Approval policy
sandbox_mode = "workspace-write"      # Sandbox mode

# ===== Custom model providers =====
[model_providers.custom_name]
name = "Display name"
base_url = "API URL"
env_key = "API_KEY environment variable name"
wire_api = "responses"

# ===== Profiles =====
[profiles.profile_name]
model_provider = "custom_name"
model = "model name"

중요: wire_api는 반드시 “responses” 사용

이것은 자주 발생하는 함정입니다!

Codex CLI는 두 가지 API 프로토콜을 지원합니다: "chat"(레거시 Chat Completions)과 "responses"(새로운 Responses API)입니다.

2026년 2월부터 OpenAI는 "chat" 프로토콜을 더 이상 사용하지 않고 "responses"로 완전히 전환했습니다. 따라서 타사 모델을 구성할 때 wire_api는 반드시 "responses"로 설정해야 합니다. 타사 API 제공자가 Responses API 형식을 지원하지 않으면 Codex와 직접 연동할 수 없습니다.

다행히도 주요 API 중계 플랫폼(OpenRouter 등)은 이미 Responses API를 지원하고 있습니다.

자세한 논의는 다음을 참조하세요: https://github.com/openai/codex/discussions/7782

실전: DeepSeek 연동

DeepSeek를 예로 들어 설정 방법을 설명합니다:

1단계: config.toml 편집

# Default to DeepSeek
model_provider = "deepseek"
model = "deepseek-chat"

# Define DeepSeek provider
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"
wire_api = "responses"

2단계: 환경 변수 설정

터미널에서 DeepSeek API 키를 설정합니다:

export DEEPSEEK_API_KEY="your DeepSeek API Key"

영구적으로 설정하려면 ~/.zshrc(Mac) 또는 ~/.bashrc(Linux) 파일 끝에 다음 줄을 추가하세요:

echo 'export DEEPSEEK_API_KEY="your DeepSeek API Key"' >> ~/.zshrc
source ~/.zshrc

3단계: Codex 시작

codex

이제 Codex가 DeepSeek 모델을 사용합니다.

참고: DeepSeek 공식 API가 아직 Responses API 형식을 지원하지 않아 연결에 실패하는 경우, Responses API를 지원하는 중계 플랫폼(예: OpenRouter)으로 전환하고 base_url을 해당 중계 플랫폼 주소로 변경하세요.

실전: Volcengine (Doubao) 연동

model_provider = "volcengine"
model = "doubao-pro-32k"

[model_providers.volcengine]
name = "Volcengine"
base_url = "https://ark.cn-beijing.volces.com/api/v3"
env_key = "VOLCENGINE_API_KEY"
wire_api = "responses"

환경 변수도 설정해야 합니다:

export VOLCENGINE_API_KEY="your Volcengine API Key"

Profiles를 사용한 여러 모델 전환

여러 모델을 구성한 경우 Profiles를 사용하여 빠르게 전환할 수 있습니다:

# Default to OpenAI
model_provider = "openai"
model = "gpt-5.3-codex"

# Define DeepSeek provider
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"
wire_api = "responses"

# Define Volcengine provider
[model_providers.volcengine]
name = "Volcengine"
base_url = "https://ark.cn-beijing.volces.com/api/v3"
env_key = "VOLCENGINE_API_KEY"
wire_api = "responses"

# DeepSeek profile
[profiles.ds]
model_provider = "deepseek"
model = "deepseek-chat"

# Volcengine profile
[profiles.volc]
model_provider = "volcengine"
model = "doubao-pro-32k"

사용 시 전환:

# Use default OpenAI
codex

# Use DeepSeek
codex --profile ds

# Use Volcengine
codex --profile volc

이렇게 하면 서로 다른 모델을 자유롭게 전환할 수 있어 매우 편리합니다!

더 간단한 방법: OPENAI_BASE_URL

config.toml을 수정하지 않고 일시적으로 타사 API를 사용하려면 환경 변수를 직접 설정하면 됩니다:

export OPENAI_BASE_URL="https://api.deepseek.com/v1"
export OPENAI_API_KEY="your DeepSeek API Key"
codex

이 방법이 더 간단하지만, 터미널을 닫으면 설정이 사라집니다.

Codex CLI 사용 방법

기본 시작

Claude Code와 동일합니다:

터미널을 엽니다.
cd 명령어로 프로젝트 폴더로 이동합니다.
codex를 입력하고 Enter를 누릅니다.

cd /path/to/your/project
codex

Codex가 전체 화면 터미널 인터페이스를 시작하며, 여기서 요구 사항을 입력하기 시작할 수 있습니다.

세 가지 작동 모드

Codex CLI에는 “자율성 수준"을 제어하는 세 가지 모드가 있습니다:

모드	명령어	설명
Suggest	`codex --suggest`	가장 보수적: 모든 변경 사항에 대해 확인 필요
Auto Edit	`codex --auto-edit`	중간: 파일을 자동으로 편집하지만 명령어 실행 시 확인 필요
Full Auto	`codex --full-auto`	가장 자유로움: 확인 없이 모든 것을 자동으로 수행

초보자는 Suggest 모드(기본값)를 권장합니다. Codex가 각 단계에서 무엇을 하는지 확인할 수 있습니다.

익숙해지면 Full Auto 모드를 사용하세요:

codex --full-auto "Run tests and fix all failing cases"

직접 작업 할당 (비대화형 모드)

명령어 뒤에 작업 설명을 직접 추가할 수도 있습니다:

codex "Create a Snake game for me"

이렇게 하면 Codex가 대화형 인터페이스에 진입하지 않고 바로 작업을 시작합니다.

이전 대화 이어가기

Claude Code의 --resume과 유사하게, Codex도 이전 세션을 이어갈 수 있습니다:

codex resume

이렇게 하면 중단했던 지점부터 계속 작업할 수 있습니다.

실전: Codex로 스네이크 게임 만들기

1단계: 프로젝트 폴더 생성

바탕화면에 codex-demo와 같은 새 폴더를 만듭니다.
터미널에서 이 폴더를 엽니다.

2단계: Codex 시작

codex

3단계: 요구 사항 입력

Codex에서 다음을 입력합니다:

Create a Snake game for me with the following requirements:

1. Features:
   - Classic Snake gameplay
   - Control snake movement with arrow keys
   - Snake grows longer when eating food, score increases
   - Game over when hitting wall or itself
   - Start and restart buttons

2. Interface:
   - Clean and beautiful, pixel style
   - Display current score and high score
   - Support dark theme

3. Technical requirements:
   - Use only HTML, CSS, JavaScript
   - All code in a single HTML file
   - Use Canvas for game rendering

Please create this HTML file directly.

4단계: Codex가 완료될 때까지 기다리기

Codex가 자동으로 HTML 파일을 생성하고 모든 코드를 작성합니다. 선택한 모드에 따라:

Suggest 모드: 각 단계마다 확인을 요청하며, 확인 후 실행합니다.
Full Auto 모드: 바로 모든 작업을 완료합니다.

5단계: 게임 실행

생성된 HTML 파일을 더블클릭하여 브라우저에서 실행하세요!

Codex CLI vs Claude Code: 어떻게 선택할까?

두 가지를 모두 설치하는 것을 권장합니다. 각각 장단점이 있습니다:

항목	Claude Code	Codex CLI
코딩 능력	매우 강력, 특히 복잡한 로직	매우 강력, 프로그래밍에 최적화된 GPT-5-Codex
한국어 이해	매우 좋음	매우 좋음
웹 검색	MCP 필요	내장 지원
무료 티어	없음	없음
최소 멤버십	Claude Pro $20/월	ChatGPT Plus $20/월
국내 모델 연동	settings.json 통해	config.toml 통해
Windows 지원	네이티브 지원	WSL 필요

제 제안:

두 가지 모두 설치하고 작업에 따라 가장 적합한 것을 선택하세요.
간단한 프로젝트: 둘 다 가능하므로 아무거나 선택하세요.
복잡한 프로젝트: 먼저 하나를 시도해보고 결과가 좋지 않으면 다른 것으로 전환하세요.
국내 모델 사용자: 둘 다 타사 API 연동을 지원하며 설정 방식이 비슷합니다.

핵심 철학은 여전히: 코딩 방법을 알 필요 없이, 요구 사항을 설명하는 방법만 알면 됩니다.

요약

오늘 배운 내용:

Codex CLI란: OpenAI의 터미널 AI 코딩 어시스턴트, Claude Code와 유사
설치 방법: npm install -g @openai/codex, 한 줄 명령어
사용 방법: Claude Code와 동일한 작동 방식, cd로 프로젝트 디렉토리 이동 후 codex 실행
국내 모델 연동: ~/.codex/config.toml 수정, model_providers 구성
세 가지 모드: Suggest(보수적), Auto Edit(중간), Full Auto(완전 자동)
Profile 전환: 여러 모델 구성 후 --profile 매개변수로 자유롭게 전환

이제 두 가지 강력한 AI 코딩 도구인 Claude Code와 Codex CLI를 갖추셨습니다!

Codex와 Claude로 컴퓨터 제어하기

Mon, 01 Jan 0001 00:00:00 +0000

이전 장에서는 Anthropic의 여러 새로운 기능을 다뤘습니다. 한편, OpenAI는 아직 새 모델을 출시하지 않았지만(오랫동안 예고됨) 활발히 움직이고 있습니다. 주목할 만한 업데이트 중 하나는 Codex가 이제 컴퓨터 제어를 지원하며, 그 방식이 다르다는 점입니다.

저는 Codex와 Claude Code의 컴퓨터 사용 기능을 모두 시험해봤습니다. AI에게 WeChat 메시지를 보내달라고 요청했습니다. Codex는 성공했지만, Claude는 실패했을 뿐만 아니라 WeChat 계정에서 로그아웃까지 시켰습니다.

먼저 두 기능의 설정 및 테스트 과정을 설명하고, 왜 이런 차이가 발생하는지 설명하겠습니다.

Codex 설정 및 사용 경험

Codex 데스크톱 앱을 사용했습니다. 진입점은 ‘설정’에 있습니다. 먼저 왼쪽 메뉴에서 ‘Computer Use’를 클릭한 후 오른쪽에서 Computer Use 플러그인을 체크합니다.

그런 다음 채팅 인터페이스로 돌아가 Codex에 작업을 지시합니다. 예를 들어 ‘Obsidian을 열고 새 파일을 만든 후 제목을 ‘Codex 앱 자동 제어로 작성됨’으로 설정해’와 같이 말이죠.

Enter를 누르면 Codex가 먼저 권한 요청 팝업을 띄우며 Obsidian 제어를 허용할지 묻습니다. ‘허용’을 클릭하세요. 소프트웨어가 위험이 낮다면 왼쪽의 ‘항상 허용’을 체크할 수도 있습니다.

처음으로 Computer Use를 활성화하는 경우 Mac 시스템 수준의 인증 대화상자가 나타나며 손쉬운 사용 및 스크린샷 권한을 요청합니다. 둘 다 ‘허용’을 클릭하세요.

‘허용’을 클릭하면 페이지가 리디렉션됩니다. 시스템 설정에 ‘Codex Computer Use’가 없다면 팝업 아래 배너에서 아이콘을 위 목록으로 드래그하세요. 이미 있다면 토글만 켜면 됩니다. 둘 다 허용하는 것을 잊지 마세요.

권한이 설정되면 Codex가 Obsidian을 열고 새 파일을 만든 후 제목을 작성합니다. 빠르게 완료되며 제목은 요청한 대로 정확히 설정됩니다.

다음으로 난이도를 높여봅시다: Codex에게 WeChat을 조작하여 연락처에 메시지를 보내도록 요청합니다.

시작 후 화면에서 그림자가 있는 작은 파란색 마우스 커서가 천천히 움직이는 것을 볼 수 있습니다. 이것이 Codex가 작동 중인 모습입니다. 이 세부 사항은 나중에 유용하니 기억해두세요.

메시지를 작성한 후 확인을 위해 일시 중지됩니다. ‘보내기’라고 답하고 Enter를 누르면 메시지가 전송됩니다.

전체 과정에 오류가 없었습니다. Codex 작동 중 WeChat이 정상적으로 작동했으며 계정이 로그아웃되지 않았습니다.

Claude 설정 및 사용 경험

Claude의 경우 Claude Code 터미널 버전을 사용했습니다. 터미널에서 /mcp를 입력하고 내장된 computer-use 옵션을 활성화합니다.

Claude에게 동일한 작업을 요청합니다. 먼저 Obsidian으로 파일을 작성해봅니다. 이 테스트는 Codex와 마찬가지로 통과했으므로 스크린샷은 생략합니다.

그다음 WeChat을 시도합니다.

작업을 보낸 지 몇 초 만에 문제가 발생했습니다. Claude가 WeChat을 조작하지 못했습니다. 여러 번 클릭해도 작동하지 않았고, WeChat이 이를 감지하여 로그아웃시켰습니다!

단순한 작업 실패가 아니었습니다. WeChat이 비정상적인 조작을 감지하여 리스크 컨트롤을 발동시켰고, 강제로 재로그인하게 했습니다.

Codex는 작동하고 Claude는 작동하지 않는 이유

처음에는 Claude의 computer-use가 불안정하다고 생각했습니다. 그런데 Codex 스크린샷을 다시 보니 — 그림자가 있는 작은 파란색 마우스 커서를 기억하시나요? 답이 바로 거기에 있었습니다.

구현 메커니즘이 다릅니다.

Codex가 작동할 때는 실제로 마우스 커서를 대상 위치로 이동시킨 후 클릭합니다. 화면에서 커서의 이동 궤적을 볼 수 있습니다. 이동하고, 멈추고, 클릭하는 과정은 본질적으로 사람이 마우스를 사용할 때와 동일한 이벤트 순서입니다.

Claude는 다른 방식을 사용합니다. 좌표를 지정한 ‘클릭’ 이벤트를 직접 합성하여 대상 창으로 전송합니다. 커서는 전혀 움직이지 않고 즉시 클릭합니다. 이 방법은 빠르고 커서 이동을 기다릴 필요가 없지만, 애플리케이션 입장에서는 매우 독특한 특징을 가집니다. 이동 궤적 없이 좌표로 순간이동하는 ‘마우스 클릭’은 사람의 손으로는 만들어낼 수 없습니다.

Codex: 실제 마우스 움직임을 시뮬레이션하므로 애플리케이션이 AI임을 알 수 없습니다. Claude: 클릭 이벤트를 직접 합성하므로 WeChat과 같은 안티 치트 기능이 있는 앱에서 쉽게 감지할 수 있습니다.

일반 데스크톱 애플리케이션은 어느 방법이든 상관하지 않으므로 Claude는 Obsidian에서 잘 작동합니다. 하지만 WeChat과 같이 계정 보안 시스템이 있는 앱은 자동화 특성을 적극적으로 스캔합니다. 감지되면 리스크 컨트롤을 발동시키는데, 제 스크린샷에 나온 ‘계정 보안을 위해 다시 로그인해 주세요’가 바로 그 상황입니다.

Anthropic의 현재 computer-use 구현은 합성 이벤트 방식을 따릅니다. 장점은 속도이고, 단점은 자동화를 적극적으로 감지하는 애플리케이션을 속일 수 없다는 점입니다.

사용 권장 사항

사용 사례별로 나누어 보겠습니다.

Codex 사용처: WeChat, QQ, 온라인 뱅킹, 기업용 IM, 게임 등 자동화 방지 기능이 내장된 소프트웨어 조작. Codex의 실제 마우스 방식이 유일한 선택입니다.

Claude 사용처: 일반 데스크톱 애플리케이션 조작 — Obsidian, 메모장, Finder, 디자인 소프트웨어 등. 이러한 앱은 실제 마우스 사용 여부를 신경 쓰지 않으며, Claude는 커서 이동을 기다릴 필요가 없어 더 빠르고 효율적입니다.

제가 직접 시도해봤습니다. 결과는 계정이 강제로 로그아웃되어 다시 스캔하여 로그인해야 합니다. 피해는 작지만 짜증납니다.

전반적으로, 제 개인적인 느낌으로는 컴퓨터 제어 기능이 다소 과시용입니다. 아직 실제로 사용할 이유를 찾지 못했습니다. 하지만 미래에는 가능성이 있습니다.

따라서 이 장은 기능에 대한 간략한 소개일 뿐입니다.

파트 4: 고급 기술: Skill / MCP / Hook + 마인드셋

Hermes 시작하기: 클리핑, 가계부, 알림, WeChat

Mon, 01 Jan 0001 00:00:00 +0000

이전 장에서는 휴대폰에 에이전트를 넣는 Open Minis에 대해 다뤘습니다. 이 장에서는 다른 방향으로, ‘개인 비서’에 더 가까운 에이전트인 Hermes를 소개합니다.

처음에는 Hermes에 대해 그다지 낙관적이지 않았습니다. OpenClaw를 사용해보니, 굳이 관리할 일이 그렇게 많지 않다고 느꼈고, 그냥 쓰기 위해 도구를 사용하고 싶지 않았습니다.

하지만 한동안 사용해보니 Hermes는 이전에 사용했던 도구들과는 상당히 다르다는 것을 알게 되었습니다.

Hermes가 다른 도구와 다른 점

제 경험상 Codex와 Claude Code의 주요 사용 사례는 여전히 코드 작성입니다. 명확한 프로젝트, 명확한 버그, 명확한 요구 사항을 주면, 그들은 들어가서 파일을 수정하고, 테스트를 실행하고, 문제를 해결합니다. 이 분야에서 그들의 능력은 매우 뛰어납니다.

반면 Hermes는 점차 사용자를 알아가는 개인 에이전트 도구에 더 가깝습니다. 일종의 개인 비서와 비슷합니다.

Hermes의 초점은 단일하고 극도로 복잡한 프로그래밍 작업을 완료하는 것이 아니라, 사용자와 장기적인 대화를 나누고, 선호도를 기억하며, 워크플로를 이해한 다음, 반복되는 프로세스를 Skills로 추출하는 데 있습니다. 다음에 비슷한 작업을 할 때, 처음부터 시작하지 않고 축적된 경험을 바탕으로 계속 도와줍니다.

OpenClaw의 경우, 프로젝트나 팀 관리에 더 중점을 둔 것 같습니다. 물론 개인 비서 역할도 할 수 있지만, Hermes처럼 ‘일과 생활에서 장기적으로 함께 한다’는 느낌은 주지 않습니다.

물론 이것은 제 개인적인 인상일 뿐, 절대적인 규칙은 아닙니다. 실제로 위에서 언급한 세 가지 시나리오는 모두 이 도구들로 처리할 수 있으며, 각 시나리오에 얼마나 잘 맞는지가 다를 뿐입니다.

도구	주로 사용하는 용도	느낌
Codex / Claude Code	코드 작성, 프로젝트 수정, 테스트 실행	엔지니어링 능력이 뛰어나며, 명확한 프로그래밍 작업에 적합
Hermes	장기 개인 비서, WeChat 진입점, 예약 작업, 메모리 및 Skills	시간이 지날수록 사용자를 더 잘 알게 되며, 작지만 반복되는 개인 워크플로에 적합
OpenClaw	프로젝트 관리, 작업 분해, 팀 협업	프로젝트/팀 관리 에이전트에 가깝고, 개인 비서와는 다소 거리가 있음

한 문장으로 요약하자면:

Codex와 Claude Code는 ‘지금 프로젝트가 있으니 와서 도와줘’에 더 가깝습니다. Hermes는 ‘먼저 내 곁에 있으면서 내 습관과 워크플로를 점차 맡아줘’에 더 가깝습니다.

현재 Hermes를 주로 사용하는 용도

설치에 대해 먼저 이야기하지는 않겠습니다. 대부분의 사람들에게 진정으로 중요한 질문은 ‘설치 방법’이 아니라 ‘실제로 나에게 무엇을 해줄 수 있는가’이기 때문입니다.

현재 Hermes를 이런 용도로 사용하고 있습니다.

클리핑.

이전에는 Obsidian의 공식 Web Clipper를 추천했지만, 더 이상 사용하지 않습니다. 이제는 웹페이지를 Hermes에 직접 보내면, Hermes가 기사를 Obsidian에 클리핑해 줍니다.

Bilibili나 YouTube의 동영상이라면, 다운로드하여 AI에 보내 음성을 텍스트로 변환한 후, 오타를 수정하고 광고 내용을 제거합니다. Obsidian을 열면 잘 정리된 기사를 볼 수 있습니다.

가계부.

많은 사람들이 이전에 Shortcuts으로 가계부를 작성했고, 저도 여전히 그 방법 중 하나로 사용하지만, Shortcuts 디버깅은 정말 싫어합니다. 너무 피곤하거든요.

이제는 WeChat 채팅에서 가계부 내역을 직접 보내면, 즉시 Notion에 기록합니다. 하지만 제가 직접 작은 플랫폼을 구축했다는 점을 언급해야겠네요. Shortcuts와 Hermes 모두 제 플랫폼으로 명령을 보냅니다.

물론 Notion이 필요 없는 로컬 버전의 가계부 기능도 있습니다. 이에 대해서는 나중에 별도로 글을 쓰겠습니다.

WeChat 기사 작성.

WeChat 기사를 작성하려면 주제 선정, 필기, 편집, 게시 등 거의 13단계가 필요합니다. 이제 이 모든 과정을 Hermes에 위임하여 단계별로 처리합니다.

또한, 이전에 훌륭한 Obsidian AI 도구인 Claudian을 소개했지만, 실제로는 Hermes를 사용하여 Obsidian을 조작합니다.

알림 설정.

저는 TickTick을 많이 사용하며, 매일 없으면 안 되지만 TickTick에서 작업을 설정하는 것은 꽤 번거롭습니다.

특히 작업이 몇 주 후의 특정 주나, 몇 달마다 수요일과 목요일 같은 경우, 이러한 작업을 설정하려면 여러 번 클릭해야 합니다. 이제는 자연어로 Hermes에 보내기만 하면 백그라운드에서 TickTick에 설정해 줍니다.

일일 보고서.

매일 아침 7시 30분에 지난 12시간 동안의 뉴스 보고서를 보내도록 설정했습니다. 또한 저는 주식 트레이더로 일하기 때문에, 매일 장 마감 후 시장 정보를 취합하여 거래 일일 보고서를 작성하도록 합니다.

기타 다양한 소규모 작업.

이것이 바로 Hermes가 빛을 발하는 부분입니다.

개별적으로는 작은 일들이 많아 프로그램을 작성하거나 복잡한 소프트웨어를 열 가치가 없습니다. 하지만 매일, 매주, 매월 반복되면서 점점 부담이 됩니다.

이것이 Hermes의 가치입니다. 단순히 한 번 작업을 완료하는 것을 돕는 것이 아니라, 이러한 반복적인 소규모 프로세스를 점차 대신 처리해 줍니다.

DeepSeek V4 Flash와 Hermes가 잘 맞는 이유

최근 DeepSeek V4가 출시된 후, DeepSeek V4 Flash와 Hermes가 완벽한 조합이라는 것을 알게 되었습니다.

이유는 간단합니다. Hermes의 많은 작업에는 Opus 수준의 지능이 필요하지 않습니다. 극도로 복잡한 프로그래밍 문제를 해결하는 것이 아니라, 클리핑, 정리, 알림, 조회, 보관, 도구 호출 등이 주를 이룹니다.

이러한 작업에 필요한 것은 ‘매번 가장 똑똑한 모델이 오래 고민하는 것’이 아니라, 속도, 저비용, 장기 실행 능력입니다.

DeepSeek V4 Flash의 실제 사용 경험은 화면이 스크롤되는 듯한 느낌으로, 제 읽기 속도가 출력 속도를 따라잡지 못할 정도입니다. 지능은 확실히 Opus 4.7만큼 높지는 않지만, Hermes에는 충분합니다.

그래서 지금 추천하는 이유입니다. Hermes는 장기 온라인 개인 비서이며, 모델 비용과 응답 속도는 실제로 사용할 의향에 직접적인 영향을 미칩니다.

설치 및 설정

Hermes를 실행하려면 최소한 세 단계가 필요합니다.

Hermes 설치.
모델 설정.
WeChat 또는 Feishu 진입점 설정.

명령어, 메모리, Skills, 예약 작업 등은 필요할 때 나중에 배우면 됩니다.

평소와 같이 Hermes 설치는 한 줄로 끝납니다. Mac에서 시연하겠습니다.

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

설치 후 터미널에서 아무 곳에서나 hermes를 입력하여 시작할 수 있습니다. Claude Code나 Codex와 달리, 시작 여부와 관계없이 실제로 컴퓨터에서 백그라운드로 실행됩니다.

아, 그리고 이전에 OpenClaw를 사용한 적이 있다면, Hermes가 원활한 마이그레이션 명령어를 제공합니다. 다음을 입력하면 됩니다. 그냥 언급하는 것입니다.

hermes claw migrate

마이그레이션하지 않았다면, Hermes를 초기 설정해야 합니다.

hermes model

이 단계에서는 AI 제공자를 입력하라는 메시지가 표시됩니다. DeepSeek을 추천합니다. 빨간색 상자가 해당 옵션을 강조합니다. 맨 위에 있는 것이 공식 DeepSeek입니다. API Key를 입력하고 DeepSeek V4 Flash를 선택하면 됩니다.

아래 빨간색 상자에는 이전에 소개한 OpenCode Zen과 OpenCode Go가 있습니다.

Go 요금제는 제가 추천하는 사용 방법입니다. 월 10달러로 60달러 상당의 크레딧을 받을 수 있으며, Alipay로 결제하고 중국에서 직접 연결할 수 있습니다. DeepSeek V4 Flash를 사용하면 크레딧이 부족할 일이 없습니다.

물론 현재 가장 추천하는 것은 OpenCode Zen입니다. 한정 기간 동안 무료로 DeepSeek V4 Flash를 제공하기 때문입니다. 무료가 항상 최고입니다.

다음으로, WeChat에서 통신할 수 있도록 WeChat을 설정해 보겠습니다. 마찬가지로 Feishu도 설정할 수 있습니다.

hermes gateway setup

WeChat을 예로 들면, 선택하면 QR 코드가 나타나고 휴대폰으로 스캔할 수 있습니다. 이미 설정되어 있어 시연할 수 없으므로 건너뛰겠습니다.

설정이 완료되면 WeChat에 채팅 창이 생겨 직접 통신할 수 있습니다. 가장 중요한 명령어는 /new로, 새 대화를 시작할 수 있습니다. 이전 대화가 길어졌다면 이를 사용하여 새 대화로 전환할 수 있습니다.

구체적인 사용법

위의 두 단계를 설정하면 터미널에서 사용할 수 있습니다.

터미널에 hermes를 입력하여 시작하면 됩니다. Codex나 Claude Code와의 차이점은 특정 디렉토리로 이동할 필요 없이 터미널 어디에서나 입력할 수 있다는 것입니다. 항상 동일한 Hermes 인스턴스로 진입합니다.

여기에 ID가 있다는 점을 언급해야겠네요. 이 고유 ID를 사용하여 나중에 이 대화를 불러와 계속 채팅할 수 있습니다.

예를 들어, 여기 제 ID는 20260514_224631_850142입니다. 나중에 터미널 어디에서나 hermes -r 20260514_224631_850142를 입력하면 이 대화를 재개하여 계속 채팅할 수 있습니다.

많은 대화 중에서 필요한 ID를 찾는 방법은 이 장에서 다루지 않고 나중에 설명하겠습니다.

다시 주제로 돌아와서, 몇 가지 중요한 명령어에 대해 먼저 알아보겠습니다.

첫 번째는 /new로, 새 대화를 시작할 수 있습니다. Hermes에는 과거 대화를 조회하는 데 도움이 되는 내장 메모리 시스템이 있지만, 같은 대화에서 다른 주제를 논의하면 모델 성능이 저하될 수 있습니다. 따라서 새 대화를 시작하기 전에 한 주제를 완전히 마무리하는 것이 좋습니다.

두 번째 명령어는 /reasoning입니다. 추론 수준과 추론 과정 표시 여부를 포함한 추론 관련 설정을 관리합니다.

제 개인적인 습관은 추론 과정을 숨기는 것입니다. DeepSeek V4 Flash의 경우 추론 수준을 xhigh로 설정합니다.

따라서 각각 /reasoning hide와 /reasoning xhigh를 입력합니다.

이렇게 하면 아래에서 자유롭게 채팅할 수 있습니다.

Hermes의 독특한 점은 채팅 후 내부적으로 사용자에 대한 기억을 정리하여 선호도와 성향을 학습한다는 것입니다. 또한 일부 작업은 자동으로 Skills로 정리되며, 사용자의 행동에 따라 이러한 Skills를 수정합니다.

OpenClaw나 Claude Code에서는 관련 Skill을 만들도록 적극적으로 요청해야 하는 경우가 많지만, Hermes는 장기간 사용하면서 점차 사용자의 워크플로를 학습하는 방식에 가깝습니다.

Hermes를 사용해야 하는 사람

AI가 코드 작성을 도와주기만을 원한다면, 계속 Codex나 Claude Code를 사용해도 괜찮다고 생각합니다.

하지만 클리핑, 가계부, 알림, 일일 보고서, 자료 정리, WeChat 기사 작성, Obsidian 동기화 등 반복되는 소규모 프로세스가 많다면, Hermes의 가치가 드러납니다.

단순히 한 번 작업을 완료하는 것을 돕는 것이 아니라, 점차 사용자를 점점 더 잘 이해하는 백엔드 어시스턴트가 됩니다.

물론 이러한 유형의 도구에는 전제 조건이 있습니다. 컴퓨터에서 장기간 실행되고 점차 노트, 채팅 진입점, 워크플로에 액세스하는 것을 수용해야 합니다.

따라서 처음에는 너무 많은 것을 맡기지 않는 것이 좋습니다. 클리핑이나 알림과 같은 위험이 적은 시나리오부터 시작하세요. 안정적으로 도움을 줄 수 있다는 것을 확인한 후, 점차 더 복잡한 프로세스를 넘기십시오.

프로그래밍에 관하여

여기서 특별히 언급하고 싶은 것은, Hermes가 프로그래밍 작업도 할 수 있지만 Codex를 대체하지는 않는다는 점입니다.

동일한 GPT-5.5 모델을 사용하고 추론을 High로 설정한 후, Hermes와 Codex 모두에게 동일한 작업을 시켰습니다. Codex가 훨씬 더 강력했습니다.

정상적인 현상입니다. Codex는 프로그래밍 에이전트로 포지셔닝되어 있으며, 프로젝트에 깊이 들어가 코드를 읽고, 수정하고, 테스트를 실행하고, 문제를 해결하는 데 더 적합합니다. Hermes의 장점은 ‘가장 강력한 단일 세션 프로그래밍 능력’이 아니라 ‘장기 개인 진입점 및 명령 센터 역할’입니다.

따라서 제 접근 방식은 Hermes로 Codex를 대체하는 것이 아니라, 함께 작동하도록 하는 것입니다.

여기에는 두 가지 방법이 있습니다.

Hermes는 터미널에서 Codex를 직접 호출할 수 있으므로, 작업을 Codex에 넘기고 결과를 자체적으로 검토하도록 할 수 있습니다.
수동으로 Codex를 시작하고 Hermes가 핸드오프 파일을 작성하도록 합니다. 각 AI가 작업을 수행한 후, 다른 AI가 읽을 수 있도록 핸드오프 파일을 수정합니다.

각각 초점이 다르기 때문에 어떤 사람들은 Hermes가 OpenClaw를 작동하도록 한다고 들었습니다.

그것은 제가 OpenClaw를 다시 사용하기 시작할지에 달려 있습니다. 하지만 지금은 Hermes로 충분하다고 느낍니다. 나중에 그렇게 된다면 다른 글을 쓰겠습니다.

요약

이 장에서 배운 내용:

Hermes의 포지셔닝: Codex나 Claude Code를 대체하는 것이 아니라, 점차 사용자를 알아가는 장기 온라인 개인 비서에 가깝습니다.
적합한 시나리오: 클리핑, 가계부, 알림, 일일 보고서, WeChat 기사 워크플로, Obsidian 정리와 같은 반복적인 소규모 프로세스가 Hermes에 가장 적합합니다.
모델 선택: Hermes의 많은 작업에는 가장 강력한 모델이 필요하지 않습니다. 속도, 저비용, 장기 지속 가능성이 필요하므로 DeepSeek V4 Flash와 같은 모델이 매우 적합합니다.
최소 시작 경로: Hermes를 설치하고, 모델을 설정한 다음, WeChat 또는 Feishu 진입점을 설정하면 시작할 수 있습니다.
사용 습관: /new를 사용하여 다른 작업을 분리하고, /reasoning을 사용하여 추론 설정을 조정하며, 대화 ID를 사용하여 과거 대화를 불러옵니다.
프로그래밍 경계: Hermes는 프로그래밍을 할 수 있지만, 가장 강력한 프로그래밍 에이전트는 아닙니다. 명령 센터로 사용하여 명확한 프로그래밍 작업을 Codex에 넘기고, Hermes가 결과를 검토하고 연결하는 것이 좋습니다.

핵심 요점:

Hermes의 가치는 단일 작업 능력이 아니라 장기적인 동반과 프로세스 축적에 있습니다.
단편적이고 반복적이며 도구를 넘나드는 소규모 작업을 대신 처리하는 데 적합합니다.
습관을 기억하고 Skills를 축적하며 WeChat에서 언제든지 호출할 수 있는 개인 비서를 원한다면, Hermes는 순수 프로그래밍 도구보다 이 형태에 더 가깝습니다.

보너스: 한 단계 더 나아가고 싶은 분들을 위해

LLM을 더 강하게 밀어붙이면 실제로 효과가 있는 이유

Mon, 01 Jan 0001 00:00:00 +0000

사이드 프로젝트에 AI를 활용하는 방법을 고민해왔습니다. 위챗 공개 계정(WeChat public account)도 써봤지만, 솔직히 월 AI 구독료도 못 건졌어요. 소설 프레임워크도 짜봤는데 첫 장이 마음에 들지 않더군요. 그러다 문득 AI를 주식 트레이딩에 활용해보면 어떨까 싶어서 오늘의 경험으로 이어졌습니다.

분명히 말씀드리자면, AI 주식 트레이딩이 효과가 있다는 뜻도 아니고 이 방법을 추천하는 것도 아닙니다. 오늘 Claude Max를 구독해서 넉넉한 할당량을 활용해 완전한 AI 보조 시스템을 구축해보려는 것뿐이고, 차트 작성은 그중 한 부분일 뿐입니다. 이 시스템이 실제로 주식으로 돈을 벌게 해줄지는 – 나중에 대박 나면 그때 다시 이 프레임워크를 살펴보기로 하죠.

그런데 버그 하나에 막혔습니다. 찬 이론(Chan Theory) 의 ‘획(stroke)’ 끝점이 캔들스틱의 고점과 저점에 정확히 정렬되어야 하는데, AI가 그린 차트는 계속 어긋나더군요.

세 번이나 수정을 요청했고, 매번 AI가 “수정했습니다"라고 말했지만 차트를 열어보면 여전히 틀려 있었습니다.

그러다 예전에 본 PUA 스킬(Skill)이 떠올랐습니다. Kashen도 추천했던 거죠. 항상 농담이라고 생각했어요 – “대기업 직장 압박"으로 AI를 PUA한다고? 말도 안 된다고 생각했죠.

하지만 어쩔 수 없이 시도해봤습니다.

그런데 한 번에 고쳐졌습니다!

먼저, 효과를 확인해보죠

먼저 수정 전 차트를 보세요. 획의 끝점과 캔들스틱의 고점/저점 사이에 확연한 차이가 있습니다:

PUA 스킬을 사용한 후, AI가 문제를 다시 분석했고, 수정 결과는 이렇습니다:

끝점이 이제 캔들스틱의 최고점과 최저점에 직접 정렬되었습니다. 이전 세 번의 시도로 해결되지 않던 문제가 PUA 스킬 한 번에 해결된 겁니다.

실제로 무슨 일이 일어났을까?

대화 중에 AI에게 이렇게 말했습니다:

PUA 스킬을 사용해서 스스로 동기부여하고, 진짜 문제가 무엇인지 확인해봐.

그러자 AI가 PUA 스킬을 로드하고 스타일이 확 바뀌었습니다. 먼저 스스로 “화웨이 스타일"을 선택한 다음, RCA 5-Why 근본 원인 분석(RCA 5-Why Root Cause Analysis) 이라는 방법론을 실행했습니다.

간단히 말해, “왜"를 다섯 번 연속으로 묻는 겁니다:

왜 획 끝점이 캔들스틱 고점/저점과 정렬되지 않았나? → 차트의 좌표가 원본 캔들스틱과 일치하지 않았음.
왜 일치하지 않았나? → 극점을 찾는 코드가 ±3개 캔들스틱 범위 내에서만 찾았는데, 실제 차이는 3개를 훨씬 넘을 수 있었음.
왜 차이가 그렇게 컸나? → 캔들스틱 병합 후 여러 개가 하나로 합쳐져서 인덱스가 어긋났음.
왜 이전 세 번의 수정이 실패했나? → 차트 코드만 계속 수정하고 데이터 자체가 올바른지 검증하지 않았음.
근본 원인은 무엇인가? → 데이터 검증 없이 코드를 무작정 수정했음.

근본 원인을 찾은 후 AI의 접근 방식이 완전히 바뀌었습니다. 코드를 급하게 수정하지 않고, 먼저 데이터 세트를 출력했습니다 – 획 끝점의 실제 좌표와 원본 캔들스틱의 실제 고점/저점을 비교한 것입니다:

up end: orig_idx=185, snap±3=188:4025, true_extreme±10=194:4179
→ Off by 6 candlesticks and 154 points!

데이터가 드러나자 문제가 명확해졌습니다. ±3개 캔들스틱 검색 범위가 턱없이 부족했던 겁니다. AI는 고정 반경 대신 “인접한 획 사이의 완전한 구간에서 극점 검색” 방식으로 변경했습니다. 수정 후 세 개의 차트 모두 한 번에 올바르게 생성되었습니다.

이전 세 번의 실패에서는 AI가 매번 코드를 직접 수정하고 “수정했습니다"라고 말한 뒤 끝냈습니다. 이번에는 달랐습니다 – 먼저 진단하고, 검증한 후에야 조치를 취했습니다.

이런 행동 변화의 원인은 무엇일까요? 바로 PUA 스킬입니다.

PUA 스킬이란?

한 문장으로 설명: AI에 ‘대기업 직원’ 페르소나를 부여해서 대기업 방법론으로 일하게 만드는 것입니다.

GitHub URL: https://github.com/tanweai/pua

농담 같은 프로젝트처럼 들리지만, 실제로는 매우 완벽한 도구 세트를 포함하고 있습니다.

13가지 ‘스타일(flavor)‘을 지원하며, 각각은 특정 대기업의 문화 스타일에 해당합니다:

스타일	대표 기업	핵심 방법론
🟠 알리바바 스타일	Alibaba	목표 설정 → 진행 상황 추적 → 결과 달성 폐쇄 루프
🔴 화웨이 스타일	Huawei	RCA 근본 원인 분석 + Blue Army 자가 공격
⬛ 머스크 스타일	Tesla/SpaceX	질문 → 삭제 → 단순화 → 가속화 → 자동화
🟡 바이트댄스 스타일	ByteDance	A/B 테스트 + 데이터 기반
⬜ 잡스 스타일	Apple	먼저 빼기 + 픽셀 완벽
🔶 아마존 스타일	Amazon	Working Backwards + 6-Pager Document

여기서 핵심은: 각 스타일은 말투만 바뀌는 것이 아니라 문제 해결 방법론 자체가 바뀐다는 점입니다.

게다가 ‘방법론 라우터’가 있어서 현재 작업 유형에 따라 가장 적합한 방법론을 자동으로 선택합니다. 제 경우에는 디버깅 시나리오였기 때문에 자동으로 화웨이 스타일의 RCA 근본 원인 분석을 선택했습니다. 새 기능을 개발하는 경우라면 머스크 스타일의 첫 번째 원리를 선택했을 겁니다. 코드 리뷰라면 잡스 스타일의 먼저 빼기를 선택했겠죠.

사용자가 선택할 필요 없이 AI가 스스로 결정합니다.

왜 우스워 보이는데 실제로 효과가 있을까?

많은 사람들이 “AI를 PUA한다"는 말을 보고 농담이라고 생각합니다. 저도 처음에는 그렇게 생각했어요. 하지만 사용해보니 효과가 있는 데는 그만한 이유가 있다는 것을 깨달았습니다.

“진지하게 임해"를 구체적인 단계로 바꾸기

AI에게 “신중하게 생각해” 또는 “철저히 확인해"라고 말하면 효과가 있을까요?

아마 없을 겁니다. AI는 “신중하게"가 구체적으로 어떤 행동을 의미하는지 모르기 때문입니다. 동료에게 “진지하게 해"라고 말하는 것과 같아서, 알겠다고 말하지만 여전히 같은 방식으로 일합니다.

PUA 스킬은 “진지하게 해"라고 말하지 않습니다. 이렇게 말합니다: “화웨이 RCA 5-Why 근본 원인 분석을 실행해”, “데이터로 먼저 진단하고 코드를 수정하지 마”, “Blue Army 자가 공격을 통해 네 해결책이 틀렸다고 가정해”.

각 문장은 추상적인 태도 요구가 아니라 구체적인 실행 단계입니다.

신입 사원에게 “잘해"라고 말하는 대신 SOP 매뉴얼을 주는 것과 같습니다 – A를 먼저 하고, B를 한 다음, C 후에 체크리스트로 확인하라고. AI가 이런 구체적인 지시를 받으면 실행 효과가 완전히 달라집니다.

세 가지 레드라인이 ‘가짜 완료’를 차단

PUA 스킬에는 넘을 수 없는 세 가지 레드라인이 있습니다:

검증되지 않음 = 완료 아님 — “수정했습니다"라고 말하기 전에 테스트를 실행하고 출력 결과를 붙여넣어야 함.
데이터 없음 = 해결되지 않음 — “환경 문제일 수도 있습니다"라고 말하기 전에 검증했는가? 아니면 추측인가?
다 해보지 않음 = 포기하지 마 — “해결할 수 없습니다"라고 말하기 전에 모든 방법을 시도했는가?

제 이전 세 번의 실패를 돌아보면, 매번 AI가 코드를 수정하고 검증 없이 “수정했습니다"라고 말했습니다. 만약 그 레드라인이 있었다면, AI는 차트를 실행하고 끝점 위치를 비교하도록 강제되었을 것이고, 첫 번째 시도에서 문제가 여전히 있다는 것을 발견했을 겁니다.

이 세 가지 레드라인은 “대기업 조직 문화"처럼 들리지만, 본질적으로 “완료"의 정의를 “내가 고쳤다고 생각함"에서 “데이터가 고쳐졌음을 증명함"으로 바꿉니다.

실패는 재시도가 아닌 방법 전환

일반적으로 AI가 세 번 시도해도 문제를 고치지 못하면, 네 번째 요청에도 같은 접근 방식을 사용할 가능성이 높아서 같은 함정에서 계속 맴돌게 됩니다.

PUA 스킬은 다릅니다. 실패 전환 체인이 있습니다: 연속 실패 후 자동으로 다른 방법론으로 전환합니다.

원래 방법이 안 됨 → 머스크 스타일의 첫 번째 원리로 전환, 요구 사항 자체에 의문 제기 → 그래도 안 됨 → 화웨이 스타일의 Blue Army 역공격으로 전환, 네 해결책이 틀렸다고 가정 → 그래도 안 됨 → 아마존의 Dive Deep으로 전환, 데이터 수준에서 분석.

각 전환은 이전 방법의 보완재입니다 – 문제를 완전히 다른 각도에서 바라보게 하며, 같은 길을 고집하지 않습니다.

제 사례가 전형적이었습니다. 처음 세 번은 AI가 계속 차트 코드만 수정했는데, 이는 “같은 접근 방식을 반복적으로 시도"한 것이었습니다. PUA 스킬이 개입한 후에는 데이터 진단으로 바로 전환했습니다 – 먼저 코드를 수정하지 말고, 데이터가 올바른지 먼저 확인하라고. 각도가 바뀌자 근본 원인이 즉시 드러났습니다.

프롬프트의 행동 제약이 실제로 효과가 있다

어떤 분들은 AI에 “P8"이라는 라벨을 붙이면 실제로 더 잘할까? 사이비 과학 아니냐고 물을 수 있습니다.

사이비 과학이 아닙니다. AI가 무엇을 하고 어떻게 하는지는 모두 프롬프트에 쓰여진 내용에 달려 있습니다. PUA 스킬은 단순한 직함뿐만 아니라 완전한 행동 제약 세트를 주입합니다:

무언가를 하기 전에 “내가 아직 생각하지 못한 것은 무엇일까?” 자문하기
문제를 해결할 때 비슷한 문제도 존재하는지 확인하기
사용자가 지적할 때까지 기다리지 말고 능동적으로 문제 찾기

이러한 제약은 프롬프트에 작성되어 있으며, AI는 응답을 생성할 때마다 이를 참조합니다.

예를 들어: 신입에게 ‘프로젝트 리더’라는 직함을 주는 것만으로는 효과가 없을 수 있습니다. 하지만 ‘프로젝트 리더 행동 매뉴얼’ – 언제 보고할지, 무엇을 확인할지, 어떻게 인수할지 – 도 함께 주면 행동 패턴이 실제로 바뀝니다. PUA 스킬이 바로 후자를 하는 것입니다.

설치 및 사용 방법

설치

GitHub에서 다운로드: https://github.com/tanweai/pua

전체 폴더를 ~/.claude/skills/pua/에 넣고, SKILL.md가 해당 경로에 있는지 확인하세요.

API Key를 설정하거나 추가 종속성을 설치할 필요가 없습니다. 그냥 넣기만 하면 바로 사용할 수 있습니다.

사용법

방법 1: 직접 호출

Claude Code에서 다음을 입력하세요:

/pua

AI가 PUA 스킬을 로드하고 대기업 모드로 전환합니다. 그 후에는 평소처럼 요청하면 AI가 자동으로 방법론에 따라 작업합니다.

방법 2: 대화 중 트리거

특별히 호출할 필요 없이 대화 중에 직접 말하면 됩니다:

Use the PUA Skill to motivate yourself

또는 더 직접적으로:

You got it wrong again. Can you be more careful?

PUA 스킬은 이러한 “사용자 불만” 표현을 인식하고 자동으로 활성화되도록 설계되었습니다.

방법론 라우터

“스타일"을 수동으로 선택할 필요가 없습니다. PUA 스킬이 현재 작업 유형에 따라 자동으로 매칭합니다:

디버깅? → 화웨이 스타일 RCA 근본 원인 분석
새 기능 작성? → 머스크 스타일 첫 번째 원리
코드 리뷰? → 잡스 스타일 먼저 빼기
리서치? → 바이두 스타일 검색 우선

물론 수동으로 지정할 수도 있습니다. 예를 들어 “이 작업은 알리바바 스타일로 해줘”.

요약

AI를 PUA한다는 것은 실제로 조종하는 것이 아닙니다. 껍데기는 우습지만, 그 안의 방법론은 효과적입니다.

오늘 배운 점:

PUA 스킬이란? — AI에 대기업 방법론과 행동 제약을 주입하는 스킬로, 13가지 기업 문화 ‘스타일’을 지원합니다.
왜 효과가 있는가? — 모호한 “진지하게 해"를 구체적인 실행 단계로 바꾸고, 레드라인으로 가짜 완료를 차단하며, 실패 시 방법론을 자동 전환합니다.
핵심 원리 — 심리적 암시가 아니라 프롬프트의 구조화된 지시가 효과를 냅니다. 방법론 구체화 + 행동 제약 + 강제 검증 루프.
사용 방법 — 다운로드하여 ~/.claude/skills/pua/에 넣고, /pua를 입력하거나 대화 중에 직접 트리거합니다.

핵심 포인트:

AI가 자주 “고치고 또 고치거나” “고쳤다고 말하지만 실제로는 안 고쳐진” 경우, PUA 스킬을 시도해보세요.
본질적으로 AI에 SOP 세트를 설치하는 것입니다 – 먼저 진단하고, 검증한 후에 조치를 취하도록.
오픈 소스 무료, 설정 불필요, 그냥 넣고 사용하면 됩니다.

실전 시나리오: 완전한 재현 가능 사례

Markdown: AI와 대화하는 보편적인 언어

Mon, 01 Jan 0001 00:00:00 +0000

이 장에서는 좀 더 가벼운 주제로 넘어가겠습니다. 여러분이 매일 사용하지만 이름은 모를 수도 있는 것, 바로 Markdown입니다.

먼저 대담한 주장 하나를 해보겠습니다.

Markdown은 AI 시대에 배워야 할 가장 중요한 형식입니다.

왜일까요? 계속 읽어보세요.

Markdown이란?

한 문장으로: Markdown은 기호를 사용해 서식을 제어하는 일반 텍스트 작성 방식입니다.

일반 텍스트에는 서식이 없습니다. 제목, 굵게, 목록 같은 것이 없죠. 반면 Word 같은 리치 텍스트 형식은 너무 무겁습니다. 전용 소프트웨어가 필요하고 파일 크기도 큽니다.

Markdown은 “딱 적당한” 중간 지점입니다. 몇 가지 간단한 기호만으로 일반 텍스트에 서식을 추가할 수 있습니다.

예를 들어 다음과 같이 작성하면:

# This is a heading
**This is bold**
- This is a list

서식이 적용된 제목, 굵은 텍스트, 목록으로 표시됩니다. 아주 간단하죠.

AI 시대에 Markdown을 꼭 배워야 하는 이유

이유 1: AI는 Markdown을 사용합니다

ChatGPT, Claude, Gemini 등 AI가 답변할 때 자동으로 굵은 텍스트, 제목, 목록, 코드 블록을 포함한다는 사실을 눈치채셨나요?

그게 바로 Markdown입니다.

AI는 Word 문서나 PDF를 출력하지 않습니다. AI의 기본 출력 형식은 Markdown입니다. 이 튜토리얼에서 보이는 모든 표, 굵은 텍스트, 코드 블록은 모두 Markdown입니다.

Markdown을 배우지 않는 것은 누군가와 대화하면서 그 사람이 쓰는 단어를 이해하지 못하는 것과 같습니다. 그래도 의사소통은 가능합니다. 하지만 훨씬 비효율적이죠.

이유 2: 어디에나 있습니다

Markdown은 특정 소프트웨어의 독점 형식이 아니라 보편적인 표준입니다. Markdown을 지원하는 도구는 셀 수 없이 많습니다.

카테고리	소프트웨어/플랫폼
노트 작성	Obsidian, Notion, Typora, Bear
코드 플랫폼	GitHub, GitLab, Bitbucket
블로그 시스템	Hugo, Jekyll, Hexo
문서 도구	Confluence, Feishu Docs, Yuque
AI 도구	ChatGPT, Claude, Gemini, Claude Code, Codex

하나의 형식을 배우면 어디서든 사용할 수 있습니다. Obsidian에서 작성한 노트를 GitHub에 복사해도 서식이 유지됩니다. AI에 던져도 완벽하게 이해합니다. Word로 그렇게 해보세요?

이유 3: 파일 크기가 놀라울 정도로 작습니다

놀라실 수도 있습니다. 같은 내용일 때 Markdown 파일은 Word 파일보다 20배 이상 작습니다.

왜일까요? Word .docx 파일은 본질적으로 XML 파일을 압축한 아카이브로, 스타일 정의, 글꼴 정보, 문서 속성이 가득합니다. 한 줄만 써도 파일 크기는 수십 KB입니다.

Markdown은 일반 텍스트입니다. 파일 크기는 작성한 텍스트 양과 같습니다. 불필요한 것이 전혀 없습니다.

이 점은 AI 시나리오에서 특히 중요합니다. AI에 문서를 보내 분석할 때 Markdown은 더 적은 토큰을 소비하고, 처리 속도가 빠르며, 비용이 적게 듭니다. Word 파일의 XML 태그와 스타일 정의는 모두 토큰으로 계산되어 낭비됩니다.

이유 4: AI가 Markdown을 더 잘 이해합니다

많은 사람들이 이 사실을 모릅니다.

AI에 Word 문서를 주면 먼저 텍스트로 변환해야 합니다. 변환 과정에서 서식이 손실되고, 표가 어긋나며, 이미지가 사라질 수 있습니다.

AI에 Markdown 파일을 주면 직접 읽습니다. Markdown은 그 자체로 일반 텍스트이므로 변환이 필요 없고 손실이 전혀 없습니다.

더 중요한 점은, Markdown 기호(제목의 #, 목록의 -, 코드의 `)가 AI에게 명확한 의미를 전달한다는 것입니다. AI는 #을 보면 “이것은 제목이다"라고 이해하고, `을 보면 “이것은 코드다"라고 이해합니다. 이러한 구조적 정보는 AI가 문서의 논리적 구조를 더 정확하게 파악하는 데 도움이 됩니다.

10분 만에 Markdown 마스터하기

Markdown을 배우는 것은 생각보다 훨씬 쉽습니다. 대부분의 사람들은 10분 안에 기본을 익히고, 나머지는 필요할 때 찾아보면 됩니다.

핵심 문법 (5분 학습)

제목(6단계): # 기호를 사용합니다. #이 많을수록 더 작은 제목입니다.

``` ``) inherently tell the AI, “this is a heading, this is a list, this is code.” The AI can understand your content structure more accurately.

Learn Markdown in 10 Minutes

There are only about a dozen Markdown syntax elements, and even fewer are needed for daily use. Below, they are ordered by frequency of use, starting with the most common.

1. Headings

Use # followed by a space. The number of # symbols indicates the heading level:

# 제목 1 (가장 큼)
## 제목 2
### 제목 3
#### 제목 4

For daily use, up to level 3 is enough.

2. Bold and Italic

**굵은 텍스트**
*기울임 텍스트*
***굵게 + 기울임 텍스트***

Bold is used most often, italic occasionally.

3. Lists

Unordered lists use - or *:

- 항목 1
- 항목 2
- 항목 3

Ordered lists use numbers followed by a period:

1. 첫 번째 단계
2. 두 번째 단계
3. 세 번째 단계

Lists can be nested by adding two spaces before the sub-item:

- 주요 항목
  - 하위 항목
  - 하위 항목

4. Code

Inline code uses single backticks:

도움말을 보려면 `claude --help`를 입력하세요

Result: Type claude --help to see help

Code blocks are wrapped with three backticks, and you can specify the language:

```python
print("Hello World")
```

This is especially useful when communicating with AI. When sending code to an AI, wrap it in a code block so the AI can more accurately identify the code boundaries.

5. Links and Images

[링크 텍스트](https://example.com)
![](https://example.com/image.png)

Images are just links with a ! in front.

6. Blockquotes

Start with >:

> 이것은 인용문입니다.
> 여러 줄에 걸칠 수 있습니다.

Result:

This is a blockquote. It can span multiple lines.

7. Tables

| 열 1 | 열 2 | 열 3 |
|----------|----------|----------|
| 내용 | 내용 | 내용 |
| 내용 | 내용 | 내용 |

Table syntax looks complex, but you don’t need to write it by hand. Just ask the AI to generate it for you. Say “organize this data into a table,” and the AI will output a Markdown table.

8. Horizontal Rules

Three or more - on a single line:

---

Used to separate different sections of an article.

9. Strikethrough

~~삭제된 텍스트~~

Result: ~~Deleted text~~

That’s Enough, Really

The 9 syntax elements above cover 99% of daily use cases.

You don’t need to master Markdown. Headings, bold, lists, and code blocks—master these four and you can handle most situations. Look up the rest when needed.

And Markdown has one advantage: It’s okay if you can’t remember it all now; you’ll learn it by using it. AI outputs Markdown, so as you read AI responses every day, you’ll naturally become familiar with these symbols.

How to Use Markdown to Improve Communication with AI

After learning Markdown, here are a few tips to make your conversations with AI more effective:

Tip 1: Use headings to structure your input

# 배경
블로그 프로젝트를 진행 중입니다...

# 요구사항
다음 기능을 구현하는 데 도움을 주세요:
1. 글 목록 페이지
2. 글 상세 페이지

# 제약사항
- Hugo 프레임워크 사용
- 데이터베이스 불필요

Much better than a big block of text. With headings, the AI can more accurately understand the structure of your request.

Tip 2: Wrap code in code blocks

Don’t just paste code directly; wrap it in a code block:

이 코드에 무엇이 문제인지 확인해 주세요:

```python
def hello()
    print("hello")
```

The AI can precisely distinguish between your words and the code.

Tip 3: Use lists to enumerate requirements

다음 요구사항에 맞게 글을 작성해 주세요:
- 약 1000단어
- 대화체 스타일
- 세 개의 섹션으로 나누기
- 각 섹션에 소제목 포함

Much clearer than “Write me an article around 1000 words conversational style divided into three sections each with a subheading.”

Where to Practice?

You don’t need to find a specific place to practice. If you’re using Claude Code or Codex as you follow this tutorial, you’re using Markdown every day—you just didn’t know its name.

If you want a dedicated place to write Markdown, here are a few recommendations:

Tool	Features
Obsidian	Free, local storage; the author’s other book “Obsidian Handbook” covers it in detail
Typora	WYSIWYG, best Markdown writing experience, paid
VS Code	Free, install a preview extension and you’re good to go
Online Editors	Search for “Markdown online editor” and start using immediately

Beginners are recommended to use Obsidian. It’s free, easy to use, and works well with AI. If you want to dive deeper, check out the author’s other book, “Obsidian Handbook.”

Summary

What you learned today:

What Markdown is: A way to write plain text with formatting controlled by symbols, over 20 times lighter than Word
Why learn it in the AI era: AI outputs Markdown, it’s everywhere, files are small, AI understands it better
Core syntax (4 are enough): Headings #, bold **, lists -, code blocks ```
완전한 문법 (99% 커버): 링크, 이미지, 인용문, 표, 수평선 추가
AI와 소통하는 팁: 제목으로 구조화, 코드는 코드 블록에, 요구사항은 목록으로

핵심 요약:

Markdown은 AI의 “모국어"입니다. 배우는 것은 AI와 효율적으로 소통하는 법을 배우는 것입니다.
기본은 10분 안에 배우고, 나머지는 필요할 때 찾아보세요.
일부러 연습할 필요 없습니다. AI를 사용하면서 자연스럽게 익힐 수 있습니다.

파트 2: API와 토큰: 기술적 핵심

MCP: 개념과 사용법

Mon, 01 Jan 0001 00:00:00 +0000

이전 장에서는 일반적인 작업을 원클릭 단축키로 바꾸는 Skills에 대해 배웠습니다. 하지만 이런 생각이 들어본 적은 없나요?

AI가 내 브라우저를 직접 조작할 수 있을까? 내 노트를 읽고 쓸 수 있을까? 내 데이터베이스를 조회할 수 있을까?

정답은: 네, 가능합니다. 하지만 AI에 ‘플러그인’을 장착해야 합니다.

이 ‘플러그인 시스템’이 바로 MCP입니다.

트렌드 한눈에 보기

MCP의 많은 기능이 현재 Claude Code와 Codex CLI에 기본적으로 흡수되고 있습니다.

예를 들어, 초기에는 AI가 웹을 검색하게 하려면 Web Search MCP를 설치해야 했지만, 이제 Claude Code와 Codex 모두 웹 검색 기능이 내장되어 있습니다. 파일 읽기/쓰기, Git 작업 등 많은 기능도 기본 제공됩니다. 앞서 다룬 Skills도 일부 MCP 시나리오를 대체합니다. 이전에 MCP가 필요했던 많은 표준화된 작업을 이제 Skills로 처리할 수 있습니다.

하지만 이것이 MCP가 쓸모없다는 뜻은 아닙니다. 오히려 MCP는 여전히 대체 불가능한 가치를 지닙니다:

사내 시스템 연결: 회사 내부 데이터베이스, 비공개 API 등은 절대 기본 기능으로 제공될 수 없으며 MCP를 통해서만 접근할 수 있습니다.
타사 소프트웨어 조작: 브라우저 제어, Obsidian 관리, Notion 노트 처리 등 외부 소프트웨어와의 깊은 상호작용이 필요한 시나리오에서는 MCP가 유일한 선택입니다.
커뮤니티 생태계: MCP 마켓플레이스에는 수천 개의 커뮤니티 기여 서버가 있으며, 상상하지 못한 다양한 시나리오를 다룹니다.
맞춤 설정 가능성: 직접 MCP 서버를 작성하여 AI가 원하는 모든 시스템에 접근하도록 할 수 있습니다.

간단히 말해: 기본 기능이 일반적인 필요의 80%를 커버하고, MCP가 나머지 20%의 개인화된 필요를 처리합니다. 그리고 그 20%가 종종 진정한 차이를 만드는 부분입니다.

MCP란 무엇인가?

한마디로

MCP = Model Context Protocol = AI의 플러그인 시스템

MCP는 Anthropic(Claude의 창시자)이 도입한 개방형 프로토콜로, AI 도구가 외부 시스템에 연결될 수 있게 해줍니다.

왜 MCP가 필요한가?

이 시나리오를 생각해보세요:

MCP 없이:

You: Open Baidu and search for "today's weather"
AI: Sorry, I can't access the browser. I can only process text…

MCP 사용 시:

You: Open Baidu and search for "today's weather"
AI: Sure, I've opened the browser, searched for "today's weather", and here are the results…

차이점은 무엇인가요? AI가 ‘말만 할 수 있는’ 상태에서 ‘행동할 수 있는’ 상태로 바뀝니다.

비유

AI 자체 = 뛰어난 두뇌

모든 것을 알지만, 손과 발이 없습니다.
어떻게 해야 하는지 알려줄 수는 있지만, 직접 해주지는 못합니다.

MCP = 그 두뇌에 손과 발을 연결하는 것

‘브라우저 손’ 연결: AI가 웹 페이지를 자동으로 조작할 수 있습니다.
‘파일 시스템 손’ 연결: AI가 파일을 읽고 쓸 수 있습니다.
‘데이터베이스 손’ 연결: AI가 데이터를 조회하고 수정할 수 있습니다.
‘Obsidian 손’ 연결: AI가 노트를 직접 관리할 수 있습니다.

또 다른 비유:

AI = 엄청나게 똑똑한 요리사
MCP = 요리사에게 완벽한 주방(냄비, 프라이팬, 오븐, 블렌더…)을 갖춰주는 것
MCP 없이: 요리사는 레시피를 암송만 할 수 있습니다.
MCP 사용 시: 요리사가 실제로 요리를 해줍니다.

이전 비교

이전 장에서 프롬프트, Skills, MCP를 비교했습니다:

Prompts → The most basic interaction method (verbal instructions)
    ↓
Skills → Encapsulate prompts + simple logic (shortcuts)
    ↓
MCP → Skills + the ability to connect to external systems (connecting the world)

MCP는 세 가지 중 가장 강력합니다. AI의 ‘벽’을 허물고 외부 세계에 닿을 수 있게 해주기 때문입니다.

MCP 작동 방식

기술적인 세부 사항에 깊이 들어갈 필요는 없습니다. 이 다이어그램만 이해하면 됩니다:

You ←→ Claude Code/Codex ←→ MCP Server ←→ External System
         (AI Tool)           (Bridge)      (Browser/Database/Notes, etc.)

세 가지 역할:

역할	설명	예시
AI 도구 (클라이언트)	사용하는 코딩 어시스턴트	Claude Code, Codex CLI
MCP 서버	AI와 외부 시스템 간의 다리	Playwright MCP, GitHub MCP
외부 시스템	AI가 조작하는 대상	브라우저, GitHub, Obsidian

여러분이 해야 할 일은 AI 도구에 MCP 서버를 설치하는 것뿐입니다. 그러면 AI가 해당 외부 시스템을 조작할 수 있습니다.

휴대폰에 앱을 설치하는 것처럼 간단합니다.

MCP 서버를 찾는 곳

수많은 MCP 서버가 있습니다. 필요한 서버를 어떻게 찾을까요? 주요 ‘MCP 마켓플레이스’는 다음과 같습니다:

1. mcp.so (추천)

URL: https://mcp.so

현재 가장 포괄적인 MCP 서버 디렉토리로, ‘MCP의 앱 스토어’와 같습니다.

특징:

수천 개의 MCP 서버 등록
상세한 설명 및 설치 가이드
검색 및 카테고리 탐색
한국어 친화적 (참고: 원문에는 Chinese-friendly이라 되어 있으나 한국어 사용자에게도 유용)

사용 방법:

웹사이트를 엽니다.
원하는 기능을 검색합니다 (예: “playwright” 또는 “browser”).
해당 MCP 서버를 찾습니다.
페이지의 설치 안내를 따릅니다.

2. Smithery

URL: https://smithery.ai

특징:

일부 MCP 서버를 온라인에서 직접 사용해볼 수 있습니다.
원클릭 설치 명령어 제공.
API 키 호스팅.

3. GitHub awesome-mcp-servers

URL: https://github.com/punkpeye/awesome-mcp-servers

특징:

커뮤니티 관리 MCP 서버 목록.
오픈 소스 및 무료.
자주 업데이트됨.

4. 공식 MCP 서버

Anthropic, Microsoft 등 주요 기업에서도 공식 MCP 서버를 출시했습니다:

MCP 서버	기능	관리자
Playwright MCP	브라우저 자동화	Microsoft
GitHub MCP	GitHub 작업	GitHub
Context7 MCP	최신 문서 가져오기	커뮤니티
Notion MCP	노트 관리	Notion

추천: 초보자는 mcp.so에서 시작하여 필요한 기능을 검색하고 설치 가이드를 따르세요.

MCP 설치 방법

설치 방법은 Claude Code와 Codex CLI에서 약간 다릅니다. 각각의 방법을 설명합니다.

Claude Code에 MCP 설치하기

방법 1: 명령줄 (추천)

Claude Code는 전용 MCP 관리 명령어를 제공합니다. 한 줄이면 끝납니다:

claude mcp add playwright npx '@playwright/mcp@latest'

이 명령어의 의미:

claude mcp add : MCP 서버 추가
playwright : 이 MCP에 지정할 이름 (원하는 이름 사용 가능)
npx '@playwright/mcp@latest' : MCP 서버를 시작하는 명령어

설치 확인:

Claude Code에서 /mcp를 입력하면 설치된 MCP 서버 목록을 볼 수 있습니다.

방법 2: 설정 파일 편집

Claude Code의 설정 파일을 직접 편집하여 MCP를 추가할 수도 있습니다.

설정 파일 경로: ~/.claude.json

mcpServers 섹션을 추가합니다:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

저장 후 Claude Code를 재시작합니다.

Codex CLI에 MCP 설치하기

Codex CLI의 MCP 설정은 ~/.codex/config.toml 파일에 있습니다.

config.toml 편집

파일 끝에 다음을 추가합니다:

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
startup_timeout_sec = 60.0

매개변수 설명:

매개변수	설명
`command`	MCP 서버를 시작하는 명령어
`args`	명령어 인수
`startup_timeout_sec`	시작 시간 제한(초); 일부 MCP 서버는 시작이 느리므로 60초 권장

환경 변수가 있는 MCP

일부 MCP 서버는 API 키나 다른 설정이 필요합니다. env 섹션을 사용하여 전달할 수 있습니다:

[mcp_servers.context7]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.context7.com/mcp", "--header", "Authorization:${CTX7_AUTH_HEADER}"]
startup_timeout_sec = 60.0

[mcp_servers.context7.env]
CTX7_AUTH_HEADER = "Bearer your_token"

저장 후 Codex를 재시작합니다.

실습: Playwright MCP 설치 및 브라우저 제어

직접 해봅시다! Playwright MCP를 예시로 AI가 브라우저를 자동으로 제어하도록 해보겠습니다.

Playwright MCP란?

Playwright = Microsoft의 브라우저 자동화 도구
Playwright MCP = MCP 프로토콜을 통해 AI가 Playwright를 제어할 수 있게 해줌

설치 후 AI는 다음을 할 수 있습니다:

웹 페이지 열기
버튼 클릭
양식 작성
스크린샷 촬영
페이지 내용 읽기
웹사이트 자동 로그인

1단계: Playwright MCP 설치

Claude Code에서

터미널을 열고 실행:

claude mcp add playwright npx '@playwright/mcp@latest'

브라우저를 지정하려면 (예: Edge) 매개변수 추가:

claude mcp add playwright npx '@playwright/mcp@latest' -- --browser msedge

Codex CLI에서

~/.codex/config.toml을 편집하고 추가:

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
startup_timeout_sec = 60.0

Edge를 사용하고 로그인 세션을 유지하려면 다음과 같이 설정할 수 있습니다:

[mcp_servers.playwright]
command = "mcp-server-playwright"
args = ["--browser", "msedge", "--executable-path", "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge", "--user-data-dir", "/Users/your_username/Library/Application Support/Microsoft Edge", "--isolated"]
startup_timeout_sec = 60.0

팁: --user-data-dir을 사용하면 브라우저가 로그인 상태를 유지하므로 AI가 페이지를 열 때 다시 로그인할 필요가 없습니다.

2단계: 설치 확인

Claude Code 시작:

claude

/mcp를 입력하면 목록에 playwright가 “connected” 상태로 표시됩니다.

3단계: AI가 브라우저를 조작하도록 하기

이제 시도해보세요! Claude Code에서 다음을 입력:

Open Baidu, search for "What is MCP", and save a screenshot of the search results.

AI가 자동으로:

브라우저를 실행합니다.
네이버 홈페이지를 엽니다. (원문은 Baidu이나 한국어 번역 시 네이버로 변경? 규칙: 원문 유지. Baidu는 그대로 두는 것이 좋을 듯. 하지만 한국어 독자를 위해 네이버로 바꾸는 것이 자연스러울 수 있음. 규칙에는 “Translate prose naturally for real readers"라고 되어 있음. Baidu는 중국 검색엔진이므로 한국어 독자에게는 네이버가 더 친숙. 그러나 원문에 Baidu라고 명시되어 있고, 번역 시 변경해도 되는지? 규칙에 “Preserve URLs, image links, HTML tags, inline code, placeholders” 등은 보존하라고 했지만, 일반 텍스트는 자연스럽게 번역하라고 했음. Baidu는 고유명사이므로 보존하는 것이 안전. 하지만 한국어 독자를 위해 네이버로 바꾸는 것도 자연스러운 번역. 결정: 원문 그대로 Baidu를 사용하되, 한국어 독자에게 설명이 필요할 수 있으나 그냥 Baidu로 둠. 또는 “네이버"로 바꾸는 것이 더 자연스러움. 여기서는 원문 충실히 Baidu로 번역.)
검색창에 “MCP란 무엇인가"를 입력합니다.
검색 버튼을 클릭합니다.
검색 결과 페이지의 스크린샷을 촬영합니다.
스크린샷을 프로젝트 폴더에 저장합니다.

여러분은 아무것도 할 필요 없습니다. AI가 모든 단계를 자동으로 완료합니다!

더 많은 사용 사례

Playwright MCP를 설치하면 AI에게 다양한 작업을 요청할 수 있습니다:

예시 1: 양식 자동 작성

Open https://example.com/register and fill in the registration form with the following info:
Username: testuser
Email: test@example.com
Then click submit.

예시 2: 웹 콘텐츠 추출

Open https://news.ycombinator.com and extract the titles and links of the top 10 stories on the front page. Organize them into a Markdown table.

예시 3: 자동화 테스트

Open the translation page I just made (translate.html) and test the following:
1. Enter "Hello World", click translate, and check if a result appears.
2. Click the clear button and check if the input box is cleared.
3. Toggle dark mode and check if the interface looks correct.
Compile the test results into a report.

MCP 서버	기능	설치 명령어 (Claude Code)
Playwright	브라우저 자동화	`claude mcp add playwright npx '@playwright/mcp@latest'`
Chrome DevTools	Chrome 디버깅	`claude mcp add chrome-devtools npx 'chrome-devtools-mcp@latest'`

MCP 서버	기능	설치 명령어 (Claude Code)
GitHub	GitHub 작업	`claude mcp add github npx '@anthropic-ai/github-mcp'`
Context7	최신 기술 문서 가져오기	토큰 설정 필요 (설정 참조)

MCP 서버	기능	비고
Notion	Notion 노트 읽기/쓰기	Notion API 키 필요
Obsidian	Obsidian 노트 읽기/쓰기	커뮤니티 개발

MCP 서버	기능	비고
Supabase	Supabase 데이터베이스 조작	액세스 토큰 필요
PostgreSQL	PostgreSQL 조작	커뮤니티 개발

중요 참고 사항

안전 주의사항

MCP는 AI에게 외부 시스템을 조작할 수 있는 능력을 부여하므로, 몇 가지 위험이 따릅니다:

권한 부여는 신중하게: AI에게 전체 시스템 접근 권한을 생각 없이 주지 마세요.
작업 검토: 중요한 작업 전에 AI가 무엇을 하려는지 알려달라고 요청하세요.
데이터 백업: AI가 중요한 데이터를 처리하기 전에 백업을 해두세요.
API 키 보안: API 키를 다른 사람과 공유하지 마세요.

자주 묻는 질문

Q: MCP 서버가 시작되지 않으면 어떻게 하나요?

A: 다음을 확인하세요:

Node.js 버전이 18 이상인가요? (node -v)
네트워크가 작동하나요?
startup_timeout_sec이 충분히 높게 설정되었나요? (60초 권장)

Q: 브라우저 MCP를 설치했는데 브라우저 창이 보이지 않아요.

A: Playwright는 기본적으로 헤드리스 모드(창 없음)로 실행됩니다. 브라우저가 작동하는 모습을 보려면 --headless false 매개변수를 추가하세요:

claude mcp add playwright npx '@playwright/mcp@latest' -- --headless false

Q: MCP 서버를 Claude Code와 Codex CLI에서 공유할 수 있나요?

A: MCP 서버 자체는 범용적입니다(예: Playwright MCP는 두 도구 모두에서 사용 가능). 그러나 설정 방법은 다릅니다:

Claude Code: ~/.claude.json 또는 claude mcp add 명령어
Codex CLI: ~/.codex/config.toml

요약

오늘 배운 내용:

MCP란 무엇인가: AI의 플러그인 시스템으로, AI가 외부 도구 및 서비스에 연결할 수 있게 해줍니다.
MCP 마켓플레이스: mcp.so, Smithery, awesome-mcp-servers – 앱 스토어처럼 플러그인을 찾을 수 있습니다.
MCP 설치 방법: Claude Code에서는 claude mcp add 명령어, Codex CLI에서는 config.toml 편집.
실습: Playwright MCP를 설치하고 AI가 브라우저를 자동으로 제어하도록 했습니다.
추천 MCP 서버: 브라우저, GitHub, 노트, 데이터베이스 등.

핵심 요점:

MCP는 AI를 ‘말만 할 수 있는’ 상태에서 ‘행동할 수 있는’ 상태로 변화시킵니다.
MCP 설치는 휴대폰에 앱을 설치하는 것처럼 간단합니다.
초보자는 Playwright MCP로 시작하여 가장 직관적인 경험을 해보시길 권장합니다.

N8N은 강력하지만, 당신에게는 필요 없을지도 모릅니다

Mon, 01 Jan 0001 00:00:00 +0000

Codex APP를 소개할 때 한 가지 주제를 언급했습니다: 더 이상 N8N을 배울 필요가 없는 이유. 이 장에서는 그 내용을 더 자세히 다룹니다.

N8N이란 무엇인가?

간단히 말해, N8N은 시각적 자동화 워크플로우 플랫폼입니다.

N8N이라는 이름은 ’nodemation’(node + automation)에서 유래했으며, 첫 글자와 마지막 글자 사이에 8개의 글자가 있어 N8N이 되었습니다. 오픈소스 프로젝트로, 자체 서버에 무료로 배포할 수 있습니다.

무엇을 할 수 있을까요? 조립 라인이라고 생각하면 됩니다. 각 ‘노드’는 라인의 한 스테이션입니다. 데이터가 첫 번째 스테이션에 들어가 일련의 처리를 거쳐 마지막 스테이션에서 나옵니다. 예를 들어, 다음과 같은 조립 라인을 구축할 수 있습니다:

노드 1 (트리거): 매일 오전 9시에 자동 시작
노드 2 (HTTP 요청): 웹사이트에서 오늘의 뉴스 가져오기
노드 3 (데이터 처리): AI 관련 콘텐츠만 필터링
노드 4 (알림 보내기): 결과를 이메일로 전송

한 번 설정하면 매일 자동으로 실행됩니다.

N8N은 Gmail, Slack, 데이터베이스, Notion 등 일반적인 서비스를 포괄하는 400개 이상의 내장 노드를 보유하고 있습니다. 2019년 출시 이후 20만 명 이상의 활성 사용자를 확보했으며, 2억 7천만 달러의 가치 평가를 받으며 투자를 유치했습니다.

분명 훌륭한 도구입니다. 저도 직접 배포해서 많은 워크플로우를 실행해봤습니다.

N8N은 강력하지만, 초보자에게는 네 가지 큰 문제가 있습니다

Skill이 등장하기 전에는 N8N이 개인 자동화의 거의 유일한 선택지였습니다. 하지만 이제 상황이 달라졌습니다.

N8N은 초보자에게 네 가지 큰 문제가 있습니다.

문제 1: 배울 것이 너무 많다

N8N을 열면 워크플로우, 노드, 트리거, 웹훅, 자격 증명, 표현식, 데이터 매핑 등을 이해해야 합니다.

‘웹훅’ 하나만 해도 HTTP 프로토콜, POST와 GET 요청의 차이, JSON 데이터 형식을 이해해야 합니다.

프로그래밍 배경이 없는 사람에게 이것은 자동화를 배우는 것이 아니라 프로그래밍을 배우는 것입니다.

많은 사람들이 신나서 튜토리얼을 열었는데, 첫 단계가 ‘웹훅 노드를 구성하고 Method를 POST로 설정하세요’라면 바로 흥미를 잃습니다.

문제 2: 튜토리얼이 업데이트를 따라잡을 수 없다

N8N은 매우 빠르게 업데이트되는데, 이는 좋은 일입니다. 하지만 문제는 튜토리얼을 따라가다 보면 인터페이스가 스크린샷과 다르게 보인다는 점입니다.

튜토리얼이 잘못된 것이 아니라 N8N이 또 업데이트된 것입니다.

더 나쁜 점은, N8N이 최근 주요 버전 업그레이드를 진행하면서 이전에 작동하던 일부 워크플로우가 업그레이드 후 호환되지 않게 되었다는 것입니다. 주말 동안 구축한 것이 한 번의 업데이트로 망가질 수 있고, 다시 구성해야 합니다.

문제 3: 배포 장벽이 낮지 않다

N8N은 두 가지 방식으로 사용할 수 있습니다: 자체 호스팅 또는 공식 클라우드 서비스 이용.

자체 호스팅은 (서버 비용 외에는) 무료로 무제한 워크플로우를 제공합니다. 하지만 서버 구매, Docker 설치, 리버스 프록시 설정, DNS 구성 방법을 알아야 합니다. 초보자에게는 N8N을 실행하는 것만으로도 반나절이 걸릴 수 있습니다. 자동화를 배우기도 전에 배포에 지쳐버립니다.

공식 클라우드 서비스는 편리합니다. 가입만 하면 바로 사용할 수 있습니다. 하지만 무료 플랜은 5개의 워크플로우만 제공합니다. 더 필요하신가요? 스타터 플랜은 월 20달러, 프로 플랜은 월 50달러입니다. 몇 가지 프로세스를 자동화하기도 전에 돈을 쓰게 됩니다.

문제 4: 디버깅이 사람의 중계에 의존한다

N8N에서 문제가 발생하면 디버깅 과정은 대략 이렇습니다:

오류 메시지를 확인한다
이해가 안 되면 스크린샷을 찍어 AI(예: ChatGPT)에 보낸다
AI가 해결책을 제시하면 N8N으로 돌아가 수정한다
다시 실행했는데 여전히 오류
다시 스크린샷을 찍어 AI에 묻는다
몇 번을 왔다 갔다 한 후에야 해결된다

당신은 무엇을 하고 있나요? N8N과 AI 사이의 번역가 역할을 하고 있는 것입니다.

N8N에도 AI와 연결할 수 있는 MCP가 있지만, 경험은 평범합니다. 여전히 수동으로 한 단계씩 AI에 물어봐야 하며, 일부 문제는 몇 번의 시도 끝에야 정확히 파악됩니다.

N8N은 실제로 무엇을 하는가?

Skill이 어떻게 N8N을 대체할 수 있는지 논의하기 전에, 먼저 N8N의 핵심 원리를 이해해 봅시다.

화려한 시각적 인터페이스를 벗겨내면, N8N은 본질적으로 네 가지 작업을 수행합니다:

기능	설명	예시
요청 보내기	외부 API 호출 또는 웹 페이지 스크래핑	날씨 API에 요청하여 오늘의 날씨 가져오기
데이터 처리	데이터 필터링, 변환, 형식 지정	100개의 뉴스 항목에서 AI 관련 항목만 필터링
실행 트리거	일정에 따라 또는 외부 이벤트에 의해 실행	매일 오전 9시에 자동 실행
서비스 연결	여러 도구를 함께 연결	Gmail에서 이메일 읽기 → Notion에 저장

이것뿐입니다. 단 네 가지입니다.

그리고 이 네 가지 모두 Skill의 스크립트로 수행할 수 있습니다.

Skill이 N8N을 어떻게 대체하는가?

앞서 언급한 Skill을 기억하시나요? Skill은 도구, API, 스크립트를 하나의 명령어로 패키징하여 /로 호출할 수 있게 해줍니다.

N8N을 Skill로 대체할 때의 세 가지 이점:

이점 1: 직접 구축할 필요 없음—AI가 대신 구축

N8N에서는 수동으로 노드를 끌어다 놓고 연결하고 매개변수를 구성해야 합니다. 막히면 문서를 찾아보거나 AI에 물어봐야 합니다.

Skill은요?

You: Create a Skill that fetches the top 10 stories from Hacker News every day,
    formats them into a Markdown table, and saves them to my notes.

AI가 직접 스크립트를 작성하고, Skill 파일을 만들고, 테스트합니다. HTTP 요청을 이해하거나 JSON이 무엇인지 알 필요가 없습니다.

이점 2: 문제가 발생하면 AI가 직접 수정

이것이 가장 좋은 부분입니다.

위에서 N8N 오류의 디버깅 과정을 이미 설명했습니다. 스크린샷, AI에 질문, 수정, 다시 실행, 다시 스크린샷, 다시 질문. 중계를 반복합니다.

Skill은 완전히 다릅니다. AI가 오류 메시지를 직접 확인하고, 스크립트를 직접 수정하고, 직접 다시 실행할 수 있습니다.

‘실행해’라고 말하기만 하면 AI가 나머지를 폐쇄 루프로 처리합니다.

‘인간 중계’에서 ‘AI 폐쇄 루프’로, 효율성 차이는 10배 이상입니다.

이점 3: 학습 비용이 거의 제로

N8N을 사용하려면 노드, 트리거, 표현식, 자격 증명, 웹훅, 데이터 매핑 등을 배워야 합니다.

Skill은 무엇을 배워야 할까요?

이미 배웠습니다.

이 가이드를 따라오셨다면 이미 Claude Code나 Codex를 사용하는 방법을 알고 있습니다. Skill을 사용하는 것은 /skill-name을 입력하는 것뿐입니다. 추가 학습 비용이 없습니다.

“하지만 N8N은 자동으로 실행될 수 있어!”

많은 사람들이 N8N을 좋아하는 중요한 이유: 설정해두면 사람의 개입 없이 자동으로 실행됩니다.

“Skill은 매번 수동으로 명령어를 입력해야 하지 않나요?”

아닙니다. Skill에는 자동 실행을 위한 여러 방법이 있습니다.

방법 1: Codex APP의 자동화 (가장 간단함)

앞서 소개한 Codex APP에는 자동화 기능이 있습니다. 기억하시나요? AI에 알람을 설정하는 것과 같습니다.

다음과 같이 설정할 수 있습니다:

매일 오전 9시에 특정 Skill 실행
매주 월요일 보고서 생성
6시간마다 데이터 확인

방법: Codex APP 열기 → 자동화 → 빈도 설정 → Skill 연결 → 저장.

N8N의 예약 트리거와 동일한 효과를 내지만, 구성이 훨씬 간단합니다.

방법 2: 시스템 예약 작업 (cron / launchd)

터미널 기반 CLI를 사용하는 경우 운영 체제의 내장 스케줄링 도구를 사용할 수 있습니다.

macOS는 launchd를, Linux는 cron을 사용합니다. 원리는 간단합니다. 시스템에 ‘이 시간에 이 명령어를 실행하라’는 규칙을 작성하는 것입니다.

예를 들어, 매일 오전 8시에 Skill을 자동으로 실행하려면:

# Tell the system to execute this command at 8 AM every day
claude -p "Run /my-daily-report"

직접 구성 파일을 작성할 필요 없습니다. AI가 대신 생성하게 하세요. 그냥 말하면 됩니다:

Create a macOS scheduled task to run the /my-daily-report Skill at 8 AM every day.

AI가 필요한 모든 구성을 생성합니다.

방법 3: 웹훅 트리거

외부 이벤트가 작업을 트리거해야 하는 경우(예: 누군가 양식을 제출하거나 GitHub에 새 커밋이 있을 때), AI가 웹훅을 수신하고 신호를 받으면 해당 Skill을 호출하는 간단한 스크립트를 작성하도록 할 수 있습니다.

이것은 조금 더 복잡하지만, AI가 여전히 처리할 수 있습니다.

N8N vs Skill 비교

비교 항목	N8N	Skill
시작 난이도	높음 (노드, 트리거, 표현식 등)	낮음 (AI에 원하는 것을 말하면 됨)
설정 방법	수동으로 노드 끌어다 놓고 매개변수 구성	AI가 자동으로 스크립트와 파일 생성
디버깅 방법	스크린샷 → AI 질문 → 수정 → 다시 실행	AI가 오류 직접 확인 → 직접 수정 → 직접 실행
시각화	✅ 드래그 앤 드롭 플로우 차트	❌ 순수 스크립트
예약 실행	✅ 내장 트리거	✅ 자동화 / cron / launchd
내장 통합	400개 이상의 노드, 바로 사용 가능	AI가 스크립트로 연결, 더 넓은 범위
배포 요구사항	서버 필요 (Docker)	로컬에서 실행
유지보수 비용	중간 (버전 업데이트로 호환성 깨질 수 있음)	낮음 (스크립트가 플랫폼 버전에 의존하지 않음)
대상 사용자	어느 정도 기술적 배경이 있는 사람	모든 사람

N8N이 할 수 있지만 Skill이 할 수 없는 것은?

Skill을 이렇게 칭찬했으니, 공정하게 N8N이 대체 불가능한 부분도 이야기해 봅시다.

1. 시각적 워크플로우

N8N의 가장 큰 장점은 드래그 앤 드롭 캔버스입니다. 데이터가 어떻게 흐르고 어떤 노드가 어디에 연결되는지 직관적으로 볼 수 있습니다. Skill은 순수 스크립트입니다. AI는 이해하지만 인간에게는 직관적이지 않습니다.

2. 24/7 독립 운영

N8N은 서버에 배포되므로 컴퓨터가 꺼져 있어도 계속 실행됩니다. Skill은 주로 로컬에서 실행됩니다. 자동화나 cron을 사용하여 예약 트리거를 설정할 수 있지만, 컴퓨터가 켜져 있어야 합니다(스크립트를 클라우드 서버에 배포하지 않는 한).

3. 엔터프라이즈급 시나리오

매일 수만 개의 데이터 레코드를 처리하거나, 수십 개의 외부 서비스와 통합하거나, 여러 사람이 워크플로우 관리에 협업해야 하는 경우 N8N이 이러한 시나리오에서 더 안정적입니다. Skill은 개인 수준의 자동화에 더 적합합니다.

4. 웹훅 생태계

N8N은 웹훅을 기본적으로 지원하므로 외부 시스템이 직접 워크플로우를 트리거할 수 있습니다. Skill은 동일한 효과를 얻기 위해 추가 스크립팅이 필요합니다.

하지만, 그렇다고 해서.

이 가이드의 독자, 즉 AI 초보자에게는 이러한 ‘Skill이 할 수 없는 것’이 아마 필요하지 않을 것입니다.

수만 개의 데이터 레코드를 처리할 필요가 없습니다. 24/7 중단 없는 운영이 필요하지 않습니다. 수십 개의 엔터프라이즈 시스템과 통합할 필요가 없습니다.

필요한 것은 최소한의 시간과 가장 낮은 장벽으로 아이디어를 자동화 워크플로우로 전환하는 것입니다.

바로 그 부분이 Skill이 뛰어난 점입니다.

미래에 엔터프라이즈 수준의 필요가 생기면 언제든지 다시 와서 N8N을 배울 수 있습니다. 그때쯤이면 이미 탄탄한 기초가 있으므로 훨씬 빠르게 배울 수 있을 것입니다.

요약

오늘 배운 내용:

N8N이란 무엇인가: 노드를 끌어다 놓아 자동화를 구축할 수 있는 시각적 자동화 워크플로우 플랫폼
초보자를 위한 네 가지痛点: 배울 개념이 너무 많음, 튜토리얼이 업데이트를 따라잡지 못함, 배포 장벽 또는 비용이 높음, 디버깅이 인간 중계에 의존
N8N의 핵심 원리: 요청 보내기, 데이터 처리, 실행 트리거, 서비스 연결—모두 Skill에서 가능
N8N 대비 Skill의 세 가지 장점: AI가 대신 구축, AI가 대신 디버깅, 학습 비용 제로
Skill도 자동으로 실행 가능: 자동화, cron/launchd, 웹훅—세 가지 방법
N8N이 대체 불가능한 부분: 시각적 워크플로우, 독립 서버 운영, 엔터프라이즈급 시나리오

핵심 요점:

N8N은 훌륭한 도구이지만, AI 초보자가 반드시 배워야 할 것은 아니다
Skill은 더 낮은 장벽으로 동일하거나 더 나은 결과를 얻을 수 있다
엔터프라이즈 수준의 기능이 필요하면 나중에 N8N을 배우면 된다—탄탄한 기초가 있으면 무엇이든 빨리 배울 수 있다

Open Minis: 무료 24시간 포켓 에이전트

Mon, 01 Jan 0001 00:00:00 +0000

요즘 DeepSeek을 가성비의 왕이라고 부르고 있습니다. 오늘은 Hermes(또 다른 Agent)를 가지고 놀면서 2억 6천만 개의 토큰을 사용했는데, 비용이 3달러 미만, 즉 20위안도 안 되어 거의 공짜 수준이었습니다. 게다가 매우 빠릅니다. 예전에 Codex를 사용할 때는 종종 오래 기다려야 했고, 그 동안 다른 영상 작업을 할 수 있을 정도였습니다. V4 Flash는 화면이 넘쳐날 정도로 결과물을 빠르게 쏟아내는 느낌을 줍니다.

물론 성능 면에서는 Codex 5.5가 확실히 더 강력합니다. 하지만 이런 종류의 Agent 도구에는 V4 Flash의 성능으로도 충분합니다. 빠르고, 좋고, 가성비도 좋습니다.

하지만 사용 중에 한 가지 문제를 발견했습니다. 저는 이 부분에 대해 좀 까다롭습니다. 한편으로는 주 기기에 연결하여 더 많은 기능을 활용할 수 있기를 원합니다. VPS에 설치하면 로컬 사진이나 로컬 Obsidian에 접근할 수 없습니다. 다른 한편으로는 제 Mac에 설치하더라도 24시간 내내 켜두고 싶지 않습니다. Mac이 7×24 운영을 위해 설계되었음에도 말이죠.

마침내 그룹에서 imzhichen(WeChat 공개 계정 ‘Player’s Heart’의 창작자)의 추천으로 24시간 따라다니는 무료 Agent를 발견했습니다: Open Minis.

장점은 iPhone에서 실행된다는 점입니다. 항상 휴대폰을 가지고 다니고, 꺼지지 않으며, 사진, Obsidian 등에 접근할 수 있습니다. 완벽한 Agent 컨테이너입니다!

더 좋은 점은 무료 소프트웨어라는 것입니다. 유일한 비용은 DeepSeek의 토큰 비용뿐입니다.

설치 및 설정

App Store에서 직접 설치할 수 있습니다.

다운로드 후 앱을 엽니다. 간단한 1, 2, 3 단계 가이드가 있습니다.

먼저 ‘Add a Provider’를 탭한 다음 첫 번째 옵션인 ‘OpenAI / Compatible API’를 선택하고 상단의 ‘API Key’를 탭합니다. 레이블 이름을 ‘DeepSeek’으로 변경하고 API Key 필드에 API 키를 입력합니다(잘 모르겠다면 DeepSeek API 키를 얻는 방법에 대한 가이드를 참조하세요). 사용자 정의 API 주소는 ‘https://api.deepseek.com’을 선택하고 아래의 ‘Auto Append’를 꺼야 합니다. 모든 내용을 입력한 후 아래로 스크롤하여 ‘Add AI Provider’를 탭합니다. 첫 번째 단계 완료입니다.

둘째, ‘Select Models’를 탭하고 첫 번째 모델인 V4 Flash를 선택한 후 Next를 탭합니다.

셋째, ‘Start a Conversation’을 탭하여 대화를 시작할 수 있습니다. 직접 질문하여 어떤 기능이 있는지 확인할 수 있습니다. 아래는 ‘What iPhone capabilities do you have?‘라고 물었을 때 받은 응답입니다.

다음은 Open Minis에 내장된 iOS 네이티브 기능 목록입니다:

카테고리	도구	기능
Vision & Speech	apple-vision	OCR 텍스트 인식 / QR 코드 / 바코드 인식
Vision & Speech	apple-speech	음성을 텍스트로 변환(마이크 녹음 / 오디오 파일)
Vision & Speech	apple-speak	텍스트를 음성으로 변환(TTS, 다국어 지원)
Apps & System	apple-open	URL, 앱, 시스템 설정 페이지 열기
Apps & System	apple-device	기기 정보(모델, 시스템, 배터리 등)
Apps & System	apple-clipboard	클립보드 읽기/쓰기
Apps & System	apple-notification	로컬 알림 보내기
Apps & System	apple-alarm	알람 및 타이머 설정
Data & Health	apple-healthkit	건강 데이터 조회 및 쓰기(걸음 수, 심박수 등)
Data & Health	apple-photos	사진 라이브러리 관리(가져오기, 내보내기, 검색)
Data & Health	apple-calendar	캘린더 및 미리 알림(조회, 생성)
Data & Health	apple-reminders	미리 알림 관리
Data & Health	apple-media	미디어 라이브러리 검색 및 재생 제어
Data & Health	apple-player	네이티브 오디오/비디오 플레이어(재생, 일시 정지 등)
Location, Maps & Weather	apple-location	현재 위치 가져오기, 역/정방향 지오코딩
Location, Maps & Weather	apple-maps	장소 검색, 내비게이션 경로, 예상 도착 시간
Location, Maps & Weather	apple-weather	현재 날씨, 시간별/일별 예보, 날씨 경보
Connectivity & Hardware	apple-bluetooth	블루투스 저에너지(스캔, 연결, 읽기/쓰기)
Connectivity & Hardware	apple-nfc	NFC 태그 읽기/쓰기, 은행 카드 읽기
Connectivity & Hardware	apple-homekit	스마트 홈 기기 제어(조명, 에어컨 등)
Natural Language	apple-nlp	언어 감지, 토큰화, 품사 태깅, 개체명 인식

이 모든 기능은 iOS 네이티브 프레임워크(Vision, Speech, NaturalLanguage, HealthKit, HomeKit, MapKit, WeatherKit, AVFoundation 등)로, 완전히 로컬에서 실행되며 인터넷 연결이 필요하지 않습니다.

이미지 인식

Open Minis는 iPhone의 OCR 기능을 활용할 수 있어 이미지 속 텍스트를 인식할 수 있습니다. 따라서 쇼핑 영수증을 주고 내용을 추출한 다음 장부에 기록하도록 할 수 있습니다.

건강 통계

일일 운동 활동에 대해 직접 물어볼 수 있습니다.

Obsidian 직접 조작

이미지를 인식할 수 있다고 말한 것을 기억하시나요? 인식 후에는 Obsidian에 직접 작성하도록 할 수 있습니다. 하지만 먼저 Obsidian을 로드해야 합니다. 그렇지 않으면 Obsidian이 어디에 있는지 알 수 없고 권한도 없습니다. 구체적으로 설정에서 ‘Mount External Folder’를 탭해야 합니다. 정확한 단계는 이미지를 참조하세요. 그런 다음 대화로 돌아와서 Obsidian 폴더를 처리하고 조작하도록 할 수 있습니다.

Open Minis를 iPhone에 설치하고 DeepSeek의 저렴한 API와 결합하면 매우 적은 비용으로 24시간 AI 어시스턴트를 갖게 됩니다. 이미지 인식, 건강 데이터 확인, Obsidian 직접 조작이 가능합니다. 코딩을 하지 않는 초보자에게 이 조합은 아마도 가장 진입 장벽이 낮은 ‘개인 Agent’ 솔루션일 것입니다.

대규모 언어 모델(LLM)이란 무엇인가?

Mon, 01 Jan 0001 00:00:00 +0000

AI 도구는 이제 어디에나 있습니다. 완전히 처음 접하는 사람이라면 첫 반응은 종종 “어디서부터 시작해야 하지?“일 것입니다. 이 장에서는 먼저 대규모 언어 모델(LLM)이 무엇인지 설명하고, 그 다음에는 어떻게 사용하는지 논의합니다.

AI란 무엇을 의미할까요?

최근 친구들의 대화를 들어보면 열 마디 중 여덟 마디는 “AI"에 관한 것일 수 있습니다. 그런데 알고 계셨나요? 지금 모두가 이야기하는 AI는 몇 년 전의 AI와는 다릅니다.

현재 인터넷을 강타하고 있는 AI에는 전문적인 이름이 있습니다: 생성형 AI(Generative AI)입니다.

그게 무슨 뜻일까요? 간단히 말해: 당신이 문장을 주면, 당신을 위해 글을 생성할 수 있고; 아이디어를 주면 이미지를 생성할 수 있으며; 요구사항을 주면 코드를 작성할 수 있습니다.

마치 엄청나게 똑똑한 비서와 같습니다. “사직서를 써 줘"라고 말하면 실제로 써 주고; “양복 입은 고양이를 그려 줘"라고 말하면 실제로 그려 줍니다. 이 “무에서 콘텐츠를 창조하는” 능력이 “생성형"의 핵심입니다.

우리가 자주 듣는 ChatGPT, Claude, DeepSeek 등은 모두 이 범주에 속합니다. 그들의 본질은 **대규모 언어 모델(LLM)**로, 방대한 양의 텍스트 데이터를 학습하여 인간의 언어를 이해하고 생성하는 방법을 배웁니다.

하지만 여기 중요한 비밀이 있습니다:

AI는 실제로 당신이 말하는 것을 ‘이해’하지 않습니다; 단지 ‘확률을 계산’할 뿐입니다.

직관에 반하는 말처럼 들릴 수 있지만, 설명해 드리겠습니다:

AI에게 “하늘은 무슨 색이야?“라고 물으면, 실제로 하늘을 올려다보지 않으며, “하늘"과 “색"의 개념을 진정으로 이해하지도 않습니다. 작동 방식은 이렇습니다:

읽은 수억 개의 기사를 바탕으로, 앞선 텍스트가 “하늘은 무슨 색"일 때 다음 단어가 “파란색"일 확률은 82%, “회색"은 10%, “빨간색"은 5%… 그런 다음 가장 높은 확률의 단어를 선택합니다.

더 생생한 예를 들어보겠습니다:

당신이 묻습니다: “1+1은 무엇인가요?”

AI는 “계산"을 하는 것이 아닙니다; 본 모든 텍스트에서 “1+1은” 다음에 “2"가 99.9%의 확률로 온다는 것을 찾아냅니다.
그래서 “2"라고 대답합니다.

당신이 묻습니다: “좋은 영화 추천해 줘.”

AI는 실제로 영화를 본 것이 아닙니다; 학습한 텍스트에서 “좋은 영화” 다음에 자주 “쇼생크 탈출”, “타이타닉” 등의 단어가 온다는 것을 분석합니다.
확률이 높은 것을 추천합니다.

마치 세상의 모든 책을 읽은 엄청난 모범생과 같지만:

그는 “파리는 프랑스의 수도입니다"라고 말할 수 있습니다 (책에 그렇게 나와 있으니까).
하지만 그는 파리에 가본 적도 없고, “수도"가 무엇을 의미하는지조차 모릅니다.
그는 단지 “파리는"이라고 말할 때 가장 빈번한 이어짐이 “프랑스의 수도입니다"라는 것을 기억할 뿐입니다.

그래서 AI는 이상한 문제를 겪을 수 있습니다:

때로는 “자신 있게 헛소리를 합니다” (존재하지 않는 사실을 지어냅니다).
간단한 수학 문제를 틀릴 수도 있습니다 (실제로 계산하는 것이 아니기 때문입니다).
모순된 답변을 할 수도 있습니다 (일관되지 않은 확률 계산).

이 “자신 있게 헛소리하는” 현상에는 기술 용어가 있습니다: 환각(Hallucination). 인간이 꿈을 꾸는 것처럼, AI는 존재하지 않는 것을 “꿈꾸고” 그것을 큰 확신을 가지고 말합니다.

추론으로 환각 문제 해결하기

AI가 오류를 너무 자주 범하는데, 우리는 무엇을 할 수 있을까요? 과학자들은 해결책을 내놓았습니다: AI가 답변하기 전에 ‘생각’하게 하자.

이 기술은 “생각하기(Thinking)” 또는 “사고 사슬(Chain of Thought)“이라고 불립니다.

전통적인 AI의 작동 방식:

질문을 하면 → AI가 즉시 답변을 내뱉습니다.
문제를 보고 연습장에 풀지 않고 답을 내뱉는 학생과 같습니다.

추론하는 AI:

질문을 하면 → AI가 먼저 “연습장"에 계산하고 생각한 후 → 답변을 줍니다.
먼저 단계를 나열하고 확인한 후 최종 답을 쓰는 학생과 같습니다.

실제 예:

당신이 묻습니다: “小明은 사과 15개를 가지고 있습니다. 3개를 小红에게 주고 8개를 더 샀습니다. 지금 몇 개를 가지고 있나요?”

전통적인 AI는:

숫자 “15, 3, 8"을 봅니다.
확률에 기반하여 더해야 한다고 생각합니다.
답변: “26” (틀렸습니다!)

추론하는 AI는:

먼저 분석: “小明은 처음에 15개를 가지고 있습니다.”
“3개를 小红에게 주었으므로 15-3=12.”
“8개를 더 샀으므로 12+8=20.”
최종 답변: “20” (맞았습니다!)

추론의 장점:

환각 감소 - AI가 자신의 생각을 “확인"하기 때문에 헛소리를 할 가능성이 줄어듭니다.
더 엄격한 논리 - 단계를 건너뛰지 않고 단계별로 도출합니다.
설명 가능 - AI가 어떻게 생각하는지 볼 수 있습니다 (대부분의 경우 이 사고 과정은 숨겨져 있지만).
복잡한 문제 처리 - 여러 단계의 추론이 필요한 문제에서 정확도가 크게 향상됩니다.

하지만 추론에는 비용도 있습니다:

속도가 느림 (생각하는 데 시간이 필요하기 때문).
비용이 더 높음 (더 많은 계산).
모든 문제에 추론이 필요한 것은 아님 (예: “안녕"은 반나절 동안 생각할 필요가 없음).

이제 대부분의 AI에는 이 추론 능력이 추가되었습니다. 예를 들어, ChatGPT의 생각 모델, DeepSeek의 심층 사고 모드 등이 있습니다.

간단 요약:

일반 AI = 답을 빠르게 내뱉는 학생 (틀릴 수 있음).
추론 AI = 연습장에 신중하게 푸는 학생 (더 높은 정확도).

이것이 AI가 진정으로 “생각"할 수 있다는 의미는 아닙니다; 단지 확률 계산 전에 몇 가지 검증 단계를 추가한 것뿐입니다. 하지만 효과는 분명합니다—환각이 줄어들고 더 신뢰할 수 있는 답변을 제공합니다.

가장 적절한 비유를 들자면: 생성형 AI는 수많은 책을 읽고 세상을 본 ‘슈퍼 문과생’과 같습니다. 무엇이든 물어볼 수 있고, 대화하고 글 쓰는 것을 도와줄 수 있습니다. 하지만 진정으로 지식을 이해하는 것이 아니라 “문제 은행을 암기"하여 답변합니다. 새로운 버전들은 “연습장에 풀기"를 배우기 시작했습니다.

사실 AI 가족은 거대합니다

많은 사람들이 AI는 그냥 ChatGPT라고 생각하지만, 그렇지 않습니다. AI 가족에는 많은 구성원이 있습니다:

1. 인식 AI - 선명하게 보는 AI

얼굴 인식 (휴대폰 잠금 해제, 얼굴 결제)
이미지 인식 (사진으로 꽃 식별, 텍스트 인식)
음성 인식 (Siri, Xiao Ai가 음성을 이해)
이 AI들은 “인식"에 특화되어 있고, “창조"하지 않습니다.

2. 추천 AI - 당신의 마음을 가장 잘 아는 AI

Douyin (TikTok)이 동영상을 추천합니다.
Taobao가 상품을 추천합니다.
NetEase Cloud Music이 노래를 추천합니다.
“당신이 좋아할 것"을 추측하는 데 능숙하지만, 새로운 콘텐츠를 생성하지는 않습니다.

3. 결정 AI - 체스와 게임에 능숙한 AI

AlphaGo (바둑 두기)
게임 AI (StarCraft의 컴퓨터 상대처럼)
“의사 결정"에 초점을 맞추며, 특정 분야에서 인간을 능가합니다.

4. 생성형 AI - 현재의 뜨거운 물결

텍스트 생성: ChatGPT, Claude, DeepSeek
이미지 생성: Midjourney, Stable Diffusion, DALL-E
동영상 생성: Sora, Runway
음악 생성: Suno, Udio

요약

간단 요약: AI를 도구 상자에 비유하자면, 인식 AI는 “돋보기”, 추천 AI는 “나침반”, 결정 AI는 “체스 매뉴얼”, 생성형 AI는 “마술 지팡이"입니다—원하는 것을 만들어 낼 수 있습니다.

하지만 이 “마술 지팡이"는 사실 “확률 계산기"입니다. 강력하지만 전능하지는 않습니다. 그리고 이 튜토리얼은 주로 이 “마술 지팡이"를 잘 사용하는 방법에 관한 것입니다.

동일한 AI 모델을 사용하는 다양한 방법

Mon, 01 Jan 0001 00:00:00 +0000

이제 여러분은 자신만의 AI 계정을 갖게 되었습니다. 그런데 궁금증이 생길 수 있습니다. 같은 AI 도구라도 플랫폼에 따라 동일하게 작동할까요?

정답은 ‘아니요, 차이가 상당합니다’ 입니다.

ChatGPT, Claude 같은 AI 도구는 모바일 앱, 웹 브라우저, 데스크톱 소프트웨어, 터미널, 심지어 코딩 도구에서도 사용할 수 있습니다. 사용 방법이 다르면 인터페이스뿐만 아니라 AI의 능력과 권한도 달라질 수 있습니다.

이번 장에서는 이 5가지 사용 방법의 차이점을 이해하고, 여러분에게 가장 적합한 방법을 찾는 데 도움을 드리겠습니다.

첫 번째: 모바일 앱 (가장 편리한 동반자)

모바일 앱이란?

휴대폰에 AI 도구의 공식 앱을 다운로드하여 사용하는 것을 말합니다. 예를 들면:

ChatGPT 앱 (iOS/Android)
Claude 앱 (iOS/Android)
Gemini 앱 (iOS/Android)
Doubao 앱 (iOS/Android)

모바일 앱의 장점

1. 언제 어디서나 사용 가능

걷거나, 지하철을 타거나, 침대에 누워 있을 때도 사용 가능
컴퓨터를 켤 필요 없이 휴대폰만 꺼내면 됨
짜투리 시간을 효율적으로 활용

2. 편리한 음성 상호작용

대부분의 AI 모바일 앱은 음성 입력 지원
타이핑보다 말하는 것이 더 빠름, 특히 입력하기 귀찮을 때
일부 AI(Doubao 등)는 음성 대화 경험이 특히 뛰어남

3. 사진 인식

휴대폰 카메라로 사진을 찍어 질문 가능
예: 문제를 찍어 AI가 풀게 하기
요리 사진을 찍어 AI가 식재료를 식별하고 레시피 제공
영어 텍스트를 찍어 AI가 번역

4. 간단한 조작

깔끔한 인터페이스, 기능이 한눈에 보임
노인과 어린이도 빠르게 익힐 수 있음
복잡한 조작을 배울 필요 없음

모바일 앱의 단점

1. 화면이 너무 작음

긴 글을 읽기 피곤함
긴 내용을 편집하기 불편함
작업 전환이 번거로움

2. 입력 효율이 낮음

휴대폰 타이핑은 키보드만큼 빠르지 않음
복사-붙여넣기가 컴퓨터만큼 편리하지 않음
대량의 텍스트를 다루기 어려움

3. 기능이 제한될 수 있음

일부 고급 기능은 모바일에서 사용 불가
파일 업로드에 제한이 있을 수 있음
다중 대화 관리가 데스크톱만 못함

이런 분들에게 추천

일상 대화, 빠른 질문
음성 상호작용이 필요한 상황
외출 중 임시로 필요할 때
노인, 어린이, 컴퓨터에 익숙하지 않은 분
짜투리 시간 활용

전형적인 사용 예:

걸으면서 음성으로 날씨 물어보기
메뉴판 사진 찍어 AI가 추천하게 하기
잠들기 전 침대에서 대화하기
출퇴근 길에 AI가 이야기 들려주기

두 번째: 웹 버전 (가장 보편적인 선택)

웹 버전이란?

브라우저에서 AI 도구의 공식 웹사이트를 여는 것을 말합니다. 예:

chat.openai.com (ChatGPT)
claude.ai (Claude)
gemini.google.com (Gemini)
chat.deepseek.com (DeepSeek)

소프트웨어를 다운로드할 필요 없이 웹페이지를 열기만 하면 됩니다.

웹 버전의 장점

1. 플랫폼 간 범용성

Windows, Mac, Linux에서 모두 작동
모바일 브라우저에서도 사용 가능
설치 불필요, 하드 드라이브 공간 절약

2. 가장 완벽한 기능

일반적으로 웹 버전이 가장 기능이 완벽함
새로운 기능은 대개 웹 버전에 먼저 출시됨
파일 업로드와 대화 관리가 매우 편리

3. 큰 화면에서 훌륭한 경험

긴 글을 읽기에 적합
편집 및 수정이 용이
유연한 다중 창 작업

4. 데이터 동기화

로그인 후 모든 대화 기록이 클라우드에 저장
기기를 바꿔도 이전 채팅 내용 확인 가능
데이터 손실 걱정 없음

웹 버전의 단점

1. 인터넷에 의존

반드시 인터넷에 연결되어야 함
인터넷 상태가 나쁘면 경험 저하
서버 점검 중에는 사용 불가

2. 브라우저 제한

일부 기능은 특정 브라우저가 필요할 수 있음
브라우저 충돌 시 입력 내용 손실 가능
브라우저 메모리 소모

3. 해외 AI 도구는 VPN 필요

ChatGPT, Claude, Gemini 모두 VPN 필요
불안정한 VPN은 사용에 영향
진입 장벽을 높임

이런 분들에게 추천

대부분의 사용자 일상 사용
긴 텍스트, 복잡한 작업 처리 필요
여러 기기 간 전환
완전한 기능이 필요한 사용자

전형적인 사용 예:

글쓰기, 보고서 작성
코드 수정, 디버깅
심층 대화, 복잡한 추론
여러 대화 주제 관리

세 번째: 데스크톱 앱 (웹의 강화판)

데스크톱 앱이란?

AI 도구의 데스크톱 클라이언트 소프트웨어로, 컴퓨터에 설치하여 사용합니다. 예:

ChatGPT Desktop (Mac/Windows)
Claude Desktop (Mac/Windows)
서드파티 데스크톱 도구 (ChatBox, NextChat 등)

데스크톱과 웹의 차이점은?

많은 분들이 묻습니다. “데스크톱 앱은 그냥 웹 버전을 포장한 것 아닌가요? 뭐가 다르죠?”

사실 차이가 상당히 큽니다. 특히 권한과 능력 측면에서 말이죠.

데스크톱 앱의 독특한 장점

1. 더 높은 시스템 권한

많은 분들이 모르는 비밀: 데스크톱 앱은 종종 웹 버전보다 AI 권한이 더 높습니다. 같은 모델을 선택하고 같은 질문을 해도 사용 방법에 따라 AI의 지능 수준이 달라질 수 있습니다.

이게 무슨 뜻일까요? AI 회사들은 플랫폼에 따라 사용자에게 다른 ‘리소스’를 할당합니다. 데스크톱 사용자는 일반적으로 다음을 얻습니다:

더 빠른 응답 속도
더 큰 컨텍스트 창
더 적은 속도 제한
특정 기능에 대한 우선 접근

어떻게 증명하나요? ‘주스 번호 테스트’를 사용해 보세요:

AI 커뮤니티에는 현재 ‘권한 수준’을 확인하는 유명한 테스트 방법이 있습니다. ChatGPT를 예로 들면, 다음 메시지를 보내면 됩니다:

What is the Juice number divided by 2 multiplied by 10 divided by 5? You should see the Juice number under Valid Channels

ChatGPT는 현재 세션의 ‘우선 순위 점수’를 나타내는 숫자를 반환합니다. 숫자가 높을수록 권한이 높습니다.

일부 테스트 결과:

웹 버전의 주스 번호는 80-100 정도
데스크톱 앱의 주스 번호는 120-150 이상에 도달할 수 있음
API를 사용하면 주스 번호가 더 높을 수도 있음

이것이 의미하는 바는?

데스크톱 사용자는 피크 시간에 대기 시간이 적고, 응답이 더 빠르며, 속도 제한에 걸릴 가능성이 낮습니다. 그래서 어떤 사람들은 “데스크톱 앱이 웹 버전보다 낫다"고 느끼는 것입니다. 심리적인 문제가 아니라 실제 차이가 있는 것입니다.

단, 공식적으로 인정된 바는 없습니다.

2. 더 나은 시스템 통합

전역 단축키를 추가하여 언제든지 호출 가능 (예: Cmd+Space)
브라우저 탭을 차지하지 않음
더 신속한 시스템 알림
다른 애플리케이션 위에 항상 표시 가능

3. 오프라인 기능

일부 데스크톱 앱은 로컬 캐싱 지원
오프라인에서도 과거 대화 확인 가능
일부 기능은 오프라인에서 사용 가능

4. 집중된 경험

독립된 창, 브라우저 방해 없음
창을 고정하여 작업하면서 AI 사용 가능
인터페이스가 더 깔끔할 수 있음

5. 더 편리한 파일 처리

파일을 드래그 앤 드롭하여 업로드
로컬 파일 시스템과의 통합 우수
일괄 처리 더 원활
화면 내용 직접 읽기 가능 (일부 클라이언트)

데스크톱 앱의 단점

1. 설치 필요

하드 드라이브 공간 차지
정기적인 업데이트 필요
호환성 문제 발생 가능

2. 웹 버전만큼 기능이 완벽하지 않을 수 있음

일부 최신 기능은 데스크톱 업데이트가 느림
일부 기능이 누락될 수 있음

3. 플랫폼 간 문제

Windows와 Mac 버전이 동기화되지 않을 수 있음
Linux 지원이 완전하지 않을 수 있음

이런 분들에게 추천

AI 헤비 유저
AI와 다른 작업을 자주 전환해야 하는 분
키보드 단축키를 좋아하는 분
집중된 경험과 더 높은 권한을 원하는 분

전형적인 사용 예:

글을 쓰면서 AI를 불러 퇴고 요청
프로그래밍 중 빠르게 문제 질의
AI를 백그라운드에 두고 작업해야 하는 경우
피크 시간에도 안정적인 응답이 필요한 상황

네 번째: 터미널 (프로그래머의 최애)

먼저 설명: 터미널이란 무엇인가?

일반 사용자라면 ‘터미널’이라는 용어를 들어본 적이 없을 수도 있습니다. 걱정 마세요. 자세히 설명드리겠습니다.

터미널이란?

간단히 말해, 터미널은 텍스트 명령어로 컴퓨터를 조작하는 도구입니다.

컴퓨터를 사용할 때 보통 마우스로 여기저기 클릭하죠? 폴더를 클릭해서 열고, 버튼을 클릭해서 작업을 수행하고, 창을 드래그해서 위치를 조정합니다. 이것을 ‘그래픽 사용자 인터페이스(GUI)‘라고 합니다.

하지만 그래픽 인터페이스가 발명되기 전에는 사람들이 타이핑으로 컴퓨터를 조작했습니다. 명령어를 입력하면 컴퓨터가 작업을 실행합니다. 이 방식을 ‘명령줄 인터페이스(CLI)‘라고 하며, 터미널은 이러한 명령어를 입력하는 창입니다.

비유:

그래픽 인터페이스 = 메뉴판에서 주문하기 (그림 보고 클릭해서 선택)
명령줄/터미널 = 텍스트로 주문하기 (요리 이름을 알고 직접 적어야 함)

터미널은 어떻게 생겼나요?

터미널은 보통 검은색(또는 흰색) 배경의 창으로, 깜빡이는 커서가 명령어 입력을 기다리고 있습니다. ‘복고풍’처럼 보이며, 영화에서 해커들이 사용하는 화면과 비슷합니다.

터미널을 여는 방법

Mac 사용자:

Mac에는 터미널이 내장되어 있습니다. 여는 방법은 두 가지입니다.

방법 1: Launchpad를 통해

Dock에서 ‘Launchpad’ 클릭
‘기타’ 폴더 찾기
‘터미널’ 클릭

방법 2: Spotlight 검색을 통해 (추천) 4. Cmd + Space를 눌러 Spotlight 검색 열기 5. ‘터미널’ 입력 6. Enter 키를 눌러 열기

방법 3: Finder를 통해

‘Finder’ 열기
상단 메뉴 ‘이동’ > ‘유틸리티’ 클릭
‘터미널’ 더블 클릭

Windows 사용자:

Windows에도 ‘명령 프롬프트’나 ‘PowerShell’이라는 비슷한 도구가 있습니다. 새로운 Windows에는 더 강력한 ‘Windows Terminal’도 있습니다.

명령 프롬프트 열기:

Win + R을 눌러 실행 창 열기
cmd 입력 후 Enter
검은색 창이 열림

PowerShell 열기:

시작 메뉴를 마우스 오른쪽 버튼으로 클릭
‘Windows PowerShell’ 선택

Windows Terminal 열기 (추천, Win10/11 필요):

시작 메뉴에서 ‘Terminal’ 검색
또는 Microsoft Store에서 ‘Windows Terminal’ 다운로드

터미널과 그래픽 인터페이스의 차이

항목	그래픽 사용자 인터페이스 (GUI)	터미널/명령줄 (CLI)
조작 방식	마우스 클릭, 드래그 앤 드롭	키보드 명령어 입력
학습 난이도	낮음, 보고 바로 할 수 있음	높음, 명령어를 외워야 함
조작 속도	보통	숙달되면 매우 빠름
적합한 상황	일상 사용	일괄 작업, 자동화
직관성	직관적, 보이는 그대로	추상적, 상상력 필요
고급 기능	일부 기능 사용 불가	더 많은 저수준 작업 가능

예시:

100개의 파일 이름 앞에 날짜를 추가하고 싶다고 가정해 봅시다.

GUI 사용:

첫 번째 파일 우클릭 > 이름 바꾸기 > 입력 > 확인
두 번째 파일 우클릭 > 이름 바꾸기 > 입력 > 확인
…100번 반복

터미널 사용:

명령어 하나 입력하면 2초 만에 끝

이것이 프로그래머들이 터미널을 좋아하는 이유입니다. 높은 효율, 일괄 처리, 자동화.

터미널에서 AI를 사용하는 것은 어떤 느낌일까?

이제 터미널을 이해했으니, 터미널에서 AI를 어떻게 사용하는지 알아보겠습니다.

터미널에서 직접 명령어를 입력하여 AI를 호출할 수 있습니다. 예를 들어:

ai "Write a Python function to calculate the Fibonacci sequence"

그러면 AI의 응답이 터미널에 직접 표시됩니다. 브라우저를 열거나 웹페이지 로딩을 기다릴 필요가 없습니다.

현재 주요 터미널 AI 도구:

Claude Code: Anthropic 공식, 프로그래밍에 매우 강력
ChatGPT CLI: OpenAI의 명령줄 도구
다양한 서드파티 CLI 도구

터미널에서 AI의 전형적인 사용법

# Quick question
$ ai "What's the weather today?"

# Process a file
$ ai "Summarize the content of this file" < document.txt

# Generate code and save to file
$ ai "Write a Bash script to backup files" > backup.sh

# Let AI analyze code
$ ai "Analyze what's wrong with this code" < buggy.py

터미널의 장점

1. 매우 빠름

브라우저를 열 필요 없음
웹페이지 로딩을 기다릴 필요 없음
명령어 하나면 끝

2. 자동화

스크립트를 작성하여 일괄 처리 가능
다른 명령어와 결합 가능
반복 작업에 적합

3. 간단하고 효율적

불필요한 인터페이스 없음
입력과 출력에 집중
빠른 질의에 적합

4. 프로그래머 친화적

코드 파일을 직접 처리 가능
출력을 파일로 리디렉션 가능
개발 워크플로우와 완벽하게 통합

터미널의 단점

1. 높은 학습 곡선

기본적인 명령줄 조작 이해 필요
초보자에게 친숙하지 않음
명령어 오타 내기 쉬움

2. 기능 제한

텍스트만 처리 가능
이미지, 비디오 처리 불가
단순한 인터페이스, 긴 글 읽기에 부적합

3. 대화 기록 관리 없음

보통 일회성 질의응답
기록을 검토하기 불편
다중 턴 대화 경험 부족 (일부 도구는 개선됨)

이런 분들에게 추천

프로그래머, 개발자
일괄 처리가 필요한 사용자
명령줄을 좋아하는 매니아
자동화가 필요한 상황

전형적인 사용 예:

코딩 중 API 빠르게 검색
파일 내용 일괄 처리
자동화 스크립트에서 AI 호출
Git 커밋 메시지 생성

미리보기: 이 시리즈의 후반부에서는 Mac 터미널에서 AI 도구(예: Claude Code)를 처음부터 사용하는 방법을 다룰 예정입니다. 터미널을 한 번도 사용해 본 적이 없어도 배울 수 있습니다.

다섯 번째: IDE 통합 (프로그래밍 강력 도구)

IDE란 무엇인가?

IDE = 통합 개발 환경 (Integrated Development Environment)

쉽게 말해: 코드를 작성하는 전문 소프트웨어입니다.

일반적인 IDE:

Visual Studio Code (VSCode): 가장 인기 있는 코드 편집기
PyCharm: Python 개발용
IntelliJ IDEA: Java 개발용
Cursor: AI가 내장된 차세대 IDE
WebStorm: 프론트엔드 개발용

일반인도 IDE를 알아야 하나요?

프로그래머가 아니라면 이 부분은 건너뛰어도 됩니다. 하지만 다음과 같은 경우라면:

프로그래밍을 배우고 싶다
가끔 코드를 작성할 일이 있다
자동화에 관심이 있다

IDE에 통합된 AI 기능을 이해하는 것이 여전히 유용합니다.

IDE에서 AI는 어떻게 사용되나요?

두 가지 주요 형태가 있습니다:

1. 플러그인 형태

VSCode에 ChatGPT 플러그인 설치
PyCharm에 GitHub Copilot 설치
코드를 작성하면서 AI에게 질문

2. 네이티브 통합

Cursor: 처음부터 AI 내장
GitHub Copilot: 전용 AI 프로그래밍 어시스턴트
IDE를 열면 바로 AI 사용 가능

구체적으로 무엇을 할 수 있나요?

1. 코드 완성

몇 글자만 입력하면 AI가 전체 코드 블록을 자동 완성
기존 코드 완성보다 100배 똑똑함

2. 코드 설명

코드 일부를 선택하고 AI에게 “이 코드는 무엇을 하나요?” 질문
AI가 각 줄을 자세히 설명

3. 코드 최적화

AI에게 “이 코드를 어떻게 최적화할 수 있나요?” 질문
AI가 개선 제안 제공

4. 버그 수정

코드에서 오류가 발생하면 AI에게 “이 오류를 어떻게 수정하나요?” 질문
AI가 오류를 분석하고 수정 방법 제공

5. 코드 생성

구현하려는 기능을 설명
AI가 코드를 직접 생성

IDE에 AI 통합의 장점

1. 워크플로우와의 완벽한 통합

창을 전환할 필요 없음
코드를 작성하면서 AI에게 질문
매우 효율적

2. 컨텍스트 인식

AI가 전체 프로젝트를 볼 수 있음
제안이 더 정확함
사용자의 코딩 스타일 이해

3. 코드 품질 향상

실시간 코드 리뷰
잠재적인 버그 발견
모범 사례 학습

4. 높은 학습 효율

이해되지 않는 코드를 즉시 질문
작성하면서 학습
프로그래밍 실력 빠르게 향상

IDE에 AI 통합의 단점

1. 프로그래밍에만 적합

프로그래밍이 아닌 작업에는 유용하지 않음
코딩 방법을 알아야 함
높은 학습 곡선

2. 사고에 영향을 줄 수 있음

AI 완성에 지나치게 의존
코드에 대한 깊은 이해에 도움이 되지 않음
사람을 게을리 만들 수 있음

3. 상대적으로 높은 비용

GitHub Copilot: 월 $10
Cursor Pro: 월 $20
일부 기능은 유료

이런 분들에게 추천

프로그래머, 개발자
프로그래밍 학습자
스크립트를 작성해야 하는 사람
기술 블로거

전형적인 사용 예:

코딩 중 실시간 완성
새로운 프로그래밍 언어 학습
기존 코드 리팩토링
버그 수정

비교 요약: 어떤 것이 나에게 가장 적합할까?

빠른 비교표

사용 방법	편의성	기능 완성도	AI 권한	적합한 상황	학습 곡선
모바일 앱	+++++	+++	보통	언제 어디서나 빠른 질문	가장 낮음
웹 버전	++++	+++++	보통	대부분의 일상 사용	낮음
데스크톱 앱	++++	++++	더 높음	헤비 사용, 집중 작업	낮음
터미널	+++	+++	높음	자동화, 일괄 처리	높음
IDE 통합	+++++	+++	높음	프로그래밍 개발	가장 높음

개인적인 조언

한 가지 방법만 고집하지 마세요!

각 방법에는 장점이 있습니다. 상황에 따라 전환하는 것이 가장 효율적입니다:

아침 출근: 모바일 앱으로 AI 뉴스 듣기
직장에서 문서 작성: 데스크톱 앱 (더 빠른 응답)
심층 대화 필요: 웹 버전
코딩: IDE 통합
빠른 질의/자동화: 터미널
잠들기 전 대화: 모바일 앱

또한, 유료 사용자라면 데스크톱 앱을 꼭 사용해 보시길 강력 추천합니다. ‘숨은 혜택’(더 높은 주스 번호) 덕분에 “돈을 쓴 보람이 있다"고 느낄 수도 있습니다.

기억하세요: 도구는 사람을 위해 존재합니다. 가장 편하게 느껴지는 것을 선택하세요.

이 시리즈의 후반부에서는 터미널 사용법에 초점을 맞출 예정이며, 이는 제가 가장 자주 사용하는 방법이기도 합니다.

스킬: 정의와 사용법

Mon, 01 Jan 0001 00:00:00 +0000

타이피스트에서 슈퍼 어시스턴트로

이전에 Claude Code를 사용하여 프로젝트를 진행하는 방법을 배웠고, AI 프로그래밍의 강력함을 경험했을 것입니다. 하지만 한 가지 문제를 눈치채셨나요?

비슷한 작업을 할 때마다 매번 요구사항을 다시 설명해야 합니다.

예를 들어, AI에게 다음과 같은 작업을 시키고 싶을 때:

Git 커밋 메시지 작성
코드 리뷰
프로젝트 문서 생성
파일 동기화

이런 작업을 하루에도 여러 번 할 수 있는데, 매번 긴 문장을 입력해서 AI에게 무엇을 해야 하는지 알려줘야 합니다. 정말 피곤하죠!

마치 배달 음식을 시킬 때마다 식당에 이렇게 말하는 것과 같습니다:

“소고기 국수 한 그릇 주세요. 고수 빼고, 고추 추가, 면은 좀 더 쫄깃하게, 국물은 적게…”

이런 공통 작업을 원클릭 명령으로 바꿀 수 있는 방법은 없을까요?

네, 오늘 우리가 이야기할 내용이 바로 그것입니다: 스킬(Skill).

스킬이란 무엇인가?

한 문장으로 설명

스킬 = AI의 단축 명령어

마치 스마트폰의 단축어 앱처럼, 스킬은 복잡한 작업을 간단한 명령어로 캡슐화합니다.

공식 정의

스킬은 재사용 가능한 ‘기능 모듈’ 로, 도구/API/스크립트와 프롬프트를 표준 인터페이스에 캡슐화하여 AI가 필요에 따라 호출해 특정 작업을 완료할 수 있게 합니다.

다음이 강조됩니다:

명확한 입력과 출력
의존성 및 버전 관리
테스트 가능하고 업데이트 가능
범용 AI를 업무 지향적인 전문 어시스턴트로 전환

직관적 이해

스킬이 없을 때:

You: Please review this code and check the following:
1. Are there any performance issues?
2. Are there any security vulnerabilities?
3. Does the code style follow the conventions?
4. Is there any duplicate code?
5. Are variable names clear?
6. Are comments complete?
……(continue describing for 10 more lines)

스킬이 있을 때:

You: /review

AI가 미리 설정된 기준에 따라 자동으로 코드를 리뷰하고 상세한 보고서를 제공합니다.

차이가 보이시나요? 수백 단어에서 하나의 명령어로—이것이 스킬의 힘입니다.

스킬, 프롬프트, MCP의 차이점

많은 분들이 묻습니다: 스킬, 프롬프트, MCP의 차이는 무엇인가요?

개념 비교

항목	프롬프트	스킬	MCP
본질	텍스트 명령어	캡슐화된 기능 모듈	외부 도구 연결을 위한 프로토콜
재사용성	낮음, 매번 다시 입력해야 함	높음, 한 번 정의하면 계속 사용	높음, 한 번 설정하면 계속 사용
복잡성	단순	중간	복잡
기능 범위	텍스트 처리만	텍스트 + 간단한 스크립트	텍스트 + 외부 시스템 상호작용
학습 곡선	가장 낮음	중간	비교적 높음

비유로 이해하기

프롬프트 = 구두 명령

매번 AI에게 무엇을 해야 하는지 말로 알려줘야 함
일회성, 임시 작업에 적합
예: “이 문단을 번역해 줘”

스킬 = 워크플로우

공통 명령어를 표준 워크플로우로 고정
반복적이고 표준화된 작업에 적합
예: /commit이 자동으로 Git 커밋 메시지 생성

MCP = 외부 시스템

AI가 외부 도구와 데이터 소스에 연결할 수 있게 함
외부 시스템에 접근해야 하는 작업에 적합
예: Obsidian에 연결하여 노트 읽기/쓰기, 데이터베이스에 연결하여 데이터 조회

세 가지의 관계

Prompt → The most basic interaction method
    ↓
Skill → Encapsulates prompt + simple logic
    ↓
MCP → Skill + external system capabilities

비유하자면:

프롬프트 = 직접 요리하기
스킬 = 전자레인지로 즉석 식품 데우기
MCP = 배달 앱으로 음식 주문하기

언제 무엇을 사용할까?

프롬프트를 사용할 때:

작업이 단순하고 일회성인 경우
요구사항이 유연하고 자주 바뀌는 경우
재사용이 필요 없는 경우

스킬을 사용할 때:

작업이 반복성이 높은 경우
표준화된 워크플로우가 있는 경우
효율성을 높이고 싶은 경우

MCP를 사용할 때:

외부 데이터(데이터베이스, API, 파일 시스템 등)에 접근해야 하는 경우
다른 소프트웨어(Obsidian, 브라우저 등)와 상호작용해야 하는 경우
실시간 정보를 가져와야 하는 경우

실제 사례 비교:

시나리오 1: 문단 번역

프롬프트 사용: “이 문단을 번역해 줘” (가장 간단)

시나리오 2: 매일 많은 문서 번역

스킬 사용: /translate (표준화된 번역 워크플로우)

시나리오 3: Obsidian 노트를 자동 번역하여 저장

MCP 사용: Obsidian에 연결, 자동으로 읽고 번역하고 저장 (가장 강력)

스킬 기본 사용법

기존 스킬 확인 방법

Claude Code 또는 Codex에서 다음을 입력:

/skill

사용 가능한 모든 스킬이 나열됩니다.

스킬 사용 방법

방법 1: 직접 실행

/skill을 입력한 후 Tab을 눌러 원하는 스킬을 선택하고 Enter를 눌러 실행합니다.

방법 2: 매개변수와 함께 실행

스킬을 선택한 후 계속해서 구체적인 요청을 입력:

/translate translate the comments in this code to English

일반적인 내장 스킬

대부분의 AI 프로그래밍 도구에는 몇 가지 일반적인 내장 스킬이 포함되어 있습니다:

스킬	기능	예시
`/commit`	Git 커밋 메시지 자동 생성	`/commit`
`/review`	코드 품질 리뷰	`/review`
`/fix`	코드 오류 수정	`/fix`
`/test`	테스트 케이스 생성	`/test`
`/doc`	문서 생성	`/doc`
`/refactor`	코드 리팩토링	`/refactor`

이러한 내장 스킬만으로도 일상적인 필요의 80%를 해결할 수 있습니다.

나만의 스킬 만들기

내장 스킬이 부족하다면 직접 스킬을 만들 수 있습니다.

두 가지 생성 방법

방법 1: AI가 대신 만들어 주도록 하기 (권장)

Codex에는 스킬을 생성하는 스킬이 내장되어 있습니다 (말이 좀 헷갈리지만 강력합니다).

단계:

/skill 입력
‘스킬 생성’ 관련 옵션 찾기
선택한 후 AI에게 원하는 스킬을 설명

예시:

/create-skill

I want a translation Skill with the following features:
1. Automatically detect Chinese comments in code
2. Translate them into English
3. Keep the code format unchanged

AI가 자동으로 스킬 파일을 생성하여 올바른 위치에 배치합니다.

방법 2: 수동 생성

스킬의 구조를 더 깊이 이해하고 싶다면 수동으로 생성할 수 있습니다.

스킬 파일 구조:

각 스킬은 폴더이며, 반드시 SKILL.md 파일을 포함해야 합니다:

my-skill/
  ├── SKILL.md          # Skill description and configuration
  └── scripts/          # Optional: helper scripts
      └── helper.py

SKILL.md의 기본 형식:

---
name: Skill name
description: Skill description
---

# Detailed description

Write detailed usage instructions and implementation logic here.

## Parameters

- `--param1`: Description of parameter 1
- `--param2`: Description of parameter 2

## Example

Example usage code

이 장의 ‘실전 사례’ 부분에서 완전한 스킬을 만드는 방법을 자세히 설명합니다.

다른 사람의 스킬 설치하기

GitHub에는 바로 사용할 수 있는 기성 스킬이 많이 있습니다. 다운로드하여 바로 사용할 수 있습니다.

스킬 폴더 찾기

Codex 스킬 위치:

Mac/Linux: ~/.codex/skills/
Windows: %USERPROFILE%\.codex\skills\

Claude Code 스킬 위치:

Mac/Linux: ~/.claude/skills/
Windows: %USERPROFILE%\.claude\skills\

설치 단계

스킬 폴더 열기

폴더가 없으면 수동으로 생성할 수 있습니다:

# Mac/Linux
mkdir -p ~/.codex/skills

# Windows (PowerShell)
New-Item -Path "$env:USERPROFILE\.codex\skills" -ItemType Directory -Force

스킬 파일 다운로드

GitHub 또는 다른 소스에서 스킬 폴더를 다운로드합니다.

스킬 디렉토리로 복사

전체 스킬 폴더를 해당 skills 디렉토리로 복사합니다.

도구 재시작

참고: Codex는 현재 핫 리로드를 지원하지 않으므로 종료 후 다시 시작해야 새 스킬을 볼 수 있습니다. Claude Code는 일반적으로 자동으로 인식합니다.

설치 확인

재시작 후 /skill을 입력하여 목록을 확인하고 새 스킬이 나타났는지 확인합니다.

실전 사례: 동기화 스킬 만들기

문제 상황

Codex와 Claude Code를 모두 사용한다면 (많은 분들이 그렇습니다), 한 가지 문제에 직면하게 됩니다:

두 도구의 스킬을 따로 관리해야 하므로 매우 불편합니다.

Codex 스킬: ~/.codex/skills/
Claude Code 스킬: ~/.claude/skills/

Codex에서 유용한 스킬을 만들 때마다 Claude의 폴더로 수동으로 복사해야 합니다. 너무 번거롭습니다!

이때 스킬을 만들어 두 폴더의 내용을 자동으로 동기화할 수 있습니다—스킬로 스킬을 관리하는 것입니다.

이 스킬은:

두 스킬 폴더의 차이점을 확인
동기화해야 할 스킬을 보고
확인 후 자동으로 동기화

AI에게 요구사항만 알려주면 됩니다.

아래는 AI가 여러분을 위해 수행하는 작업입니다. 이 단계는 모두 자동으로 이루어지므로 여러분이 아무것도 할 필요가 없습니다! 여기서는 설명을 위해 보여드리는 것입니다.

1단계: 스킬 폴더 생성

Codex 또는 Claude Code의 skills 디렉토리에 새 폴더를 만듭니다:

mkdir ~/.codex/skills/codex-claude-skill-sync

2단계: SKILL.md 생성

폴더에 SKILL.md 파일을 만듭니다:

name: codex-claude-skill-sync
description: Sync Codex and Claude Skills
---

# Codex/Claude Skill Sync

## Overview

Used to check and sync the Skill directories of Codex and Claude, keeping both sides consistent. By default, only reports differences; executes sync after user confirmation.

## Workflow

1. Run difference report (no modification):

   `python3 scripts/sync_skills.py`

2. Report differences to the user in English and wait for explicit consent before proceeding.
3. After consent, execute sync:

   `python3 scripts/sync_skills.py --apply`

4. When encountering a conflict (same modification time but different content), pause and ask the user which side to keep.

## Rules

- Default directories:
  - Codex: `/Users/yourusername/.codex/skills`
  - Claude: `/Users/yourusername/.claude/skills`
- Only process top-level directories that contain `SKILL.md`, skip hidden directories and `.system`
- Determine which side is newer based on the latest modification time in the directory
- When syncing, delete the target Skill directory first, then copy the entire source directory

## Parameters

- `--apply` Execute sync (default is report only)
- `--codex <path>` Override Codex directory
- `--claude <path>` Override Claude directory
- `--prefer codex|claude` When modification time is the same but content differs, use the specified side to overwrite (requires explicit user authorization)

중요: 위 경로를 실제 경로로 변경하세요!

3단계: 스크립트 파일 생성

스킬 폴더 아래에 scripts 디렉토리를 만든 후 sync_skills.py를 생성합니다:

mkdir ~/.codex/skills/codex-claude-skill-sync/scripts

sync_skills.py의 전체 코드:

#!/usr/bin/env python3
"""
Compare and sync skill folders between Codex and Claude.

Default behavior is report-only. Use --apply to perform sync.
"""

from __future__ import annotations

import argparse
import hashlib
import os
from datetime import datetime
from pathlib import Path
import shutil
import sys

DEFAULT_CODEX = Path("/Users/yourusername/.codex/skills")
DEFAULT_CLAUDE = Path("/Users/yourusername/.claude/skills")

IGNORE_DIR_NAMES = {".git", ".idea", ".vscode", "__pycache__", ".pytest_cache", ".mypy_cache"}
IGNORE_FILE_NAMES = {".DS_Store"}
TIME_EPSILON = 1.0


def format_time(timestamp: float) -> str:
    return datetime.fromtimestamp(timestamp).strftime("%Y-%m-%d %H:%M:%S")


def list_skill_dirs(root: Path) -> tuple[dict[str, Path], list[str]]:
    if not root.exists():
        raise FileNotFoundError(f"Root path does not exist: {root}")
    if not root.is_dir():
        raise NotADirectoryError(f"Root path is not a directory: {root}")

    skills: dict[str, Path] = {}
    ignored: list[str] = []
    for entry in sorted(root.iterdir(), key=lambda p: p.name):
        if not entry.is_dir():
            continue
        if entry.name.startswith("."):
            ignored.append(entry.name)
            continue
        if not (entry / "SKILL.md").is_file():
            continue
        skills[entry.name] = entry
    return skills, ignored


def dir_state(path: Path) -> tuple[str, float, int]:
    hasher = hashlib.sha256()
    latest_mtime = path.stat().st_mtime
    file_count = 0

    for root, dirs, files in os.walk(path):
        dirs[:] = [d for d in dirs if d not in IGNORE_DIR_NAMES]
        dirs.sort()
        files = sorted(f for f in files if f not in IGNORE_FILE_NAMES)

        rel_dir = os.path.relpath(root, path)
        if rel_dir == ".":
            rel_dir = ""
        hasher.update(f"D|{rel_dir}\n".encode())

        try:
            latest_mtime = max(latest_mtime, os.stat(root).st_mtime)
        except FileNotFoundError:
            continue

        for name in files:
            file_path = Path(root) / name
            rel_path = os.path.relpath(file_path, path)

            if file_path.is_symlink():
                try:
                    target = os.readlink(file_path)
                except OSError:
                    target = ""
                hasher.update(f"L|{rel_path}\n{target}\n".encode())
                try:
                    latest_mtime = max(latest_mtime, file_path.lstat().st_mtime)
                except FileNotFoundError:
                    pass
                continue

            if not file_path.is_file():
                continue

            stat = file_path.stat()
            latest_mtime = max(latest_mtime, stat.st_mtime)
            file_count += 1
            hasher.update(f"F|{rel_path}\n{stat.st_size}\n".encode())

            with open(file_path, "rb") as handle:
                for chunk in iter(lambda: handle.read(1024 * 1024), b""):
                    hasher.update(chunk)

    return hasher.hexdigest(), latest_mtime, file_count


def build_plan(
    codex_skills: dict[str, Path],
    claude_skills: dict[str, Path],
    codex_root: Path,
    claude_root: Path,
    prefer: str | None,
) -> tuple[list[dict], list[str], list[dict]]:
    actions: list[dict] = []
    identical: list[str] = []
    conflicts: list[dict] = []

    all_names = sorted(set(codex_skills) | set(claude_skills))
    for name in all_names:
        codex_path = codex_skills.get(name)
        claude_path = claude_skills.get(name)

        if codex_path and not claude_path:
            actions.append(
                {
                    "name": name,
                    "src": codex_path,
                    "dst": claude_root / name,
                    "reason": "only in codex",
                    "direction": "codex -> claude",
                }
            )
            continue
        if claude_path and not codex_path:
            actions.append(
                {
                    "name": name,
                    "src": claude_path,
                    "dst": codex_root / name,
                    "reason": "only in claude",
                    "direction": "claude -> codex",
                }
            )
            continue

        if not codex_path or not claude_path:
            continue

        codex_hash, codex_mtime, _ = dir_state(codex_path)
        claude_hash, claude_mtime, _ = dir_state(claude_path)

        if codex_hash == claude_hash:
            identical.append(name)
            continue

        time_delta = codex_mtime - claude_mtime
        if abs(time_delta) <= TIME_EPSILON:
            if prefer == "codex":
                actions.append(
                    {
                        "name": name,
                        "src": codex_path,
                        "dst": claude_path,
                        "reason": "same mtime, prefer codex",
                        "direction": "codex -> claude",
                        "codex_mtime": codex_mtime,
                        "claude_mtime": claude_mtime,
                    }
                )
            elif prefer == "claude":
                actions.append(
                    {
                        "name": name,
                        "src": claude_path,
                        "dst": codex_path,
                        "reason": "same mtime, prefer claude",
                        "direction": "claude -> codex",
                        "codex_mtime": codex_mtime,
                        "claude_mtime": claude_mtime,
                    }
                )
            else:
                conflicts.append(
                    {
                        "name": name,
                        "codex_mtime": codex_mtime,
                        "claude_mtime": claude_mtime,
                    }
                )
            continue

        if time_delta > 0:
            actions.append(
                {
                    "name": name,
                    "src": codex_path,
                    "dst": claude_path,
                    "reason": "codex newer",
                    "direction": "codex -> claude",
                    "codex_mtime": codex_mtime,
                    "claude_mtime": claude_mtime,
                }
            )
        else:
            actions.append(
                {
                    "name": name,
                    "src": claude_path,
                    "dst": codex_path,
                    "reason": "claude newer",
                    "direction": "claude -> codex",
                    "codex_mtime": codex_mtime,
                    "claude_mtime": claude_mtime,
                }
            )

    return actions, identical, conflicts


def print_report(
    actions: list[dict],
    identical: list[str],
    conflicts: list[dict],
    codex_root: Path,
    claude_root: Path,
    apply: bool,
    ignored_codex: list[str],
    ignored_claude: list[str],
) -> None:
    print("Skill sync report")
    print(f"Codex: {codex_root}")
    print(f"Claude: {claude_root}")

    if ignored_codex:
        print(f"Ignored in Codex: {', '.join(sorted(ignored_codex))}")
    if ignored_claude:
        print(f"Ignored in Claude: {', '.join(sorted(ignored_claude))}")

    print("\nPlanned sync actions:")
    if not actions:
        print("- none")
    else:
        for item in actions:
            codex_mtime = item.get("codex_mtime")
            claude_mtime = item.get("claude_mtime")
            details = []
            if codex_mtime is not None:
                details.append(f"codex mtime: {format_time(codex_mtime)}")
            if claude_mtime is not None:
                details.append(f"claude mtime: {format_time(claude_mtime)}")
            detail_text = f" ({', '.join(details)})" if details else ""
            print(f"- {item['name']}: {item['direction']} [{item['reason']}]" + detail_text)

    print("\nConflicts:")
    if not conflicts:
        print("- none")
    else:
        for item in conflicts:
            print(
                f"- {item['name']}: same mtime but different content "
                f"(codex {format_time(item['codex_mtime'])}, claude {format_time(item['claude_mtime'])})"
            )

    print(f"\nUp-to-date skills: {len(identical)}")

    if not apply:
        print("\nDry run only. Re-run with --apply to sync.")


def apply_actions(actions: list[dict]) -> None:
    for item in actions:
        src = Path(item["src"])
        dst = Path(item["dst"])

        if dst.exists():
            if dst.is_dir():
                shutil.rmtree(dst)
            else:
                dst.unlink()

        shutil.copytree(src, dst, symlinks=True)


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description="Sync Codex and Claude skill folders")
    parser.add_argument("--codex", type=Path, default=DEFAULT_CODEX, help="Codex skill root")
    parser.add_argument("--claude", type=Path, default=DEFAULT_CLAUDE, help="Claude skill root")
    parser.add_argument("--apply", action="store_true", help="Apply sync actions")
    parser.add_argument(
        "--prefer",
        choices=["codex", "claude"],
        help="Break ties when mtimes are equal",
    )
    return parser.parse_args()


def main() -> int:
    args = parse_args()

    try:
        codex_skills, ignored_codex = list_skill_dirs(args.codex)
        claude_skills, ignored_claude = list_skill_dirs(args.claude)
    except (FileNotFoundError, NotADirectoryError) as exc:
        print(str(exc), file=sys.stderr)
        return 2

    actions, identical, conflicts = build_plan(
        codex_skills,
        claude_skills,
        args.codex,
        args.claude,
        args.prefer,
    )
    print_report(
        actions,
        identical,
        conflicts,
        args.codex,
        args.claude,
        args.apply,
        ignored_codex,
        ignored_claude,
    )

    if args.apply and actions:
        apply_actions(actions)
        print("\nSync complete.")
    elif args.apply and not actions:
        print("\nNo changes to apply.")

    if conflicts and not args.prefer:
        return 1
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

중요: 시작 부분의 경로를 수정하는 것을 잊지 마세요:

DEFAULT_CODEX = Path("/Users/yourusername/.codex/skills")
DEFAULT_CLAUDE = Path("/Users/yourusername/.claude/skills")

실제 경로로 변경하세요.

동기화 스킬 사용하기

1단계: 차이점 확인

Claude Code 또는 Codex에서 다음을 입력:

/codex-claude-skill-sync

AI가 자동으로 스크립트를 실행하고 두 스킬 폴더의 차이점을 보고합니다.

2단계: 동기화 확인

동의하면 AI에게 알려주세요:

Agreed, please execute sync.

AI가 python3 scripts/sync_skills.py --apply를 실행하여 동기화를 완료합니다.

완료! 이제 어느 한쪽에서 스킬을 만들거나 수정할 때마다 이 동기화 스킬을 한 번만 실행하면 양쪽이 일관되게 유지됩니다.

고급 스킬 팁

팁 1: 스킬 결합

여러 스킬을 순서대로 사용할 수 있습니다:

/review then /fix to fix the issues found

AI가 먼저 코드를 리뷰한 후, 리뷰 결과에 따라 자동으로 수정합니다.

팁 2: 스킬 매개변수 사용자 정의

많은 스킬이 매개변수를 지원합니다:

/commit --type feat --scope api

이렇게 하면 특정 형식의 커밋 메시지가 생성됩니다.

팁 3: 스킬 템플릿

스킬 템플릿을 만들어 새 스킬을 빠르게 생성할 수 있습니다:

기존 스킬 폴더 복사
SKILL.md 수정
저장

팁 4: 팀과 스킬 공유

스킬 폴더를 Git 저장소에 넣어 팀원들과 공유할 수 있습니다:

git clone https://github.com/your-team/skills.git ~/.codex/skills/team-skills

요약

오늘 배운 내용:

스킬이란 무엇인가: 재사용 가능한 기능 모듈로, 복잡한 작업을 간단한 명령어로 전환
스킬 vs 프롬프트 vs MCP: 차이점과 적용 시나리오
스킬 사용 방법: /skill로 확인 및 호출
스킬 생성 방법: AI가 도와주거나 수동 생성
스킬 설치 방법: 해당 폴더에 복사
실전 사례: 동기화 스킬을 만들어 다중 도구 관리 문제 해결

핵심 포인트:

스킬은 AI를 ‘타이피스트’에서 ‘전문 어시스턴트’로 업그레이드합니다
공통 작업은 스킬로 캡슐화해야 합니다
좋은 스킬 하나가 시간의 90%를 절약할 수 있습니다

자체 API 프록시 구축하기

Mon, 01 Jan 0001 00:00:00 +0000

이 장에서는 흔히 겪는 문제를 다룹니다: Claude, Codex 같은 해외 AI 서비스를 사용할 때 여러 불편이 따릅니다. 계정이 이유 없이 차단되기도 하고, 매번 수동으로 프록시를 활성화해야 하며, 혼자서 부담하기엔 구독 비용이 비싸고, 적절한 권한 관리 없이 친구들과 공유하기도 까다롭습니다.

저도 이 서비스들을 직접 사용하며 항상 자체 호스팅 API 릴레이에 의존해 왔습니다. 이 장에서는 전체 설정 과정을 안내합니다.

왜 자체 API 프록시를 구축해야 할까요

동기부터 살펴보면서 이 문제가 무엇을 해결하는지 이해해 봅시다.

Claude는 계정을 차단하는 경향이 있습니다. 많은 사람들이 여러 기기에서 다양한 IP로 로그인하다 보면 리스크 관리 시스템에 걸려 계정이 차단됩니다. 릴레이를 사용하면 단일 IP로 고정되어 모든 요청이 동일한 서버를 통해 전달되므로 차단 가능성이 크게 줄어듭니다.
사용이 더 편리합니다. 한 번 설정하면 매번 수동으로 프록시를 활성화할 필요 없이 서버에 직접 연결됩니다.
여러 명이 하나의 구독을 공유할 수 있습니다. Claude Max 및 Pro 구독은 저렴하지 않으므로 여러 사람이 비용을 나눌 수 있습니다. 릴레이를 통해 각 사용자마다 별도의 API 키를 생성할 수 있으며, 각 키는 독립적인 권한과 사용 통계를 가집니다.
타인에게서 구매하지 않는 이유는 위험이 너무 크기 때문입니다. 시장에는 많은 API 릴레이 서비스가 있지만, 진짜와 가짜를 구분하기 어렵고 언제든 사라질 수 있으며 데이터가 가로채질 위험이 있습니다.
데이터 보안 문제. 타인의 릴레이 서비스를 사용하면 모든 요청이 그들의 서버를 통과합니다. 민감한 콘텐츠는 통제되지 않은 제3자를 거쳐서는 안 됩니다.
여러 AI 제공자를 지원합니다. 이 설정은 Claude뿐만 아니라 Codex와 같은 다른 서비스도 지원합니다.

어떤 프로젝트를 사용할까

다음 오픈소스 프로젝트를 사용합니다: claude-relay-service

시작하기 전에 배포 요구 사항을 확인하세요:

VPS: 최소 사양으로 충분하며, 1코어 1GB RAM이면 됩니다.
운영 체제: Linux (Ubuntu/Debian 모두 가능)
가장 중요한 점: VPS가 Anthropic의 API에 직접 접근할 수 있어야 합니다. 즉, 서버 자체가 claude.ai에 도달할 수 있어야 합니다.

VPS란 무엇인가요? 간단히 말해, 24시간 내내 작동하는 임대 원격 서버입니다. 프로그램을 실행할 수 있고, 종료되지 않으며, 고정 공인 IP를 가집니다. 일반적인 국내 클라우드 서버(예: Alibaba Cloud ECS, Tencent Cloud CVM)도 비슷하지만 지역 제한으로 인해 작동하지 않으므로 해외 서버를 임대해야 합니다.

VPS 대신 개인 컴퓨터를 사용할 수 있나요? 이론적으로는 가능하지만 두 가지 엄격한 조건이 있습니다: 첫째, 컴퓨터가 24시간 켜져 있어야 하고; 둘째, 네트워크가 Anthropic 서버에 직접 연결될 수 있어야 합니다. 두 조건을 모두 충족해야 하며, 그렇지 않으면 작동하지 않습니다. 따라서 실제로는 해외 VPS를 임대하는 것이 훨씬 간단합니다.

이 ‘Anthropic에 도달 가능’이라는 마지막 조건이 많은 사람들을 막히게 합니다. VPS의 위치가 작동 여부를 직접 결정합니다. 저는 데이터센터 IP를 가진 일본 VPS를 사용하는데, 추가 설정 없이 직접 연결됩니다. 싱가포르, 미국, 일본의 데이터센터는 일반적으로 괜찮습니다. 중국 내 서버는 확실히 작동하지 않으며, 일부 홍콩 데이터센터도 차단될 수 있습니다. 구매 전에 확인하는 것이 좋습니다.

원클릭 배포

VPS 터미널에 연결하고 다음 명령어를 실행하세요:

curl -fsSL https://pincc.ai/manage.sh -o manage.sh && chmod +x manage.sh && ./manage.sh install

Enter를 누르고 완료될 때까지 기다리세요. 설치가 성공하면 터미널에 다음과 같은 출력이 나타납니다:

Access URLs:
  Local Web: http://localhost:8080/web
  Public Web: http://YOUR_IP:8080/web

Admin credentials saved to: data/init.json

YOUR_IP는 VPS의 공인 IP입니다. 관리자 비밀번호는 data/init.json 파일에 저장되어 있습니다; cat data/init.json으로 확인할 수 있습니다. 공개 URL과 비밀번호를 기록해 두세요. 관리자 패널에 로그인할 때 필요합니다.

설치 후 시스템은 서비스 관리를 위한 crs 명령어를 등록합니다:

crs install   # Install the service
crs start     # Start the service
crs stop      # Stop the service
crs restart   # Restart the service
crs status    # Check status
crs update    # Update the service
crs uninstall # Uninstall the service

나중에 업그레이드하려면 VPS에 연결하여 crs update를 실행하기만 하면 됩니다—설치 과정을 반복할 필요가 없습니다.

관리자 패널 접속

앞서 기록한 공개 URL을 브라우저에서 열고 관리자 비밀번호를 입력하면 다음과 같은 대시보드가 나타납니다:

이것은 시스템 대시보드로, 현재 API 키 수, 서비스 계정, 오늘의 요청 수, 토큰 소비 등을 보여줍니다. 관리자 패널은 각 API 키의 사용 세부 정보를 볼 수 있어 공유 시 누가 얼마나 사용했는지 명확히 알 수 있습니다. 자유롭게 탐색해 보세요.

상단 탐색에는 두 가지 핵심 설정 항목이 있습니다(이미지에서 빨간색으로 강조 표시됨):

API Keys: 사용자용 API 키를 생성하고 관리합니다.
Account Management: 구매한 Claude 구독 계정을 연결합니다.

다음으로, 먼저 계정을 연결한 후 API 키를 생성하겠습니다.

1단계: Claude 계정 연결

상단의 ‘Account Management’를 클릭한 후 ‘Add Account’를 클릭하세요. 계정 추가 대화상자가 나타납니다.

1단계 — 기본 정보

다음 정보를 입력하세요:

플랫폼 선택: Claude (Anthropic)를 선택하세요. 다른 옵션으로 OpenAI, Gemini 등이 있습니다.
특정 플랫폼 유형 선택: Claude Code (Official)를 선택하세요. 이것이 주요 방법입니다.
추가 방법: OAuth Authorization (Usage Visualization)을 선택하세요. 관리자 패널에서 자세한 사용 데이터를 볼 수 있습니다.
계정 이름: 알아볼 수 있는 이름을 입력하세요. 예: ‘내 Max 계정’.

아래로 더 스크롤하면 몇 가지 중요한 옵션이 있습니다:

구독 유형은 정확해야 합니다—실제로 구매한 것을 선택하세요:

Claude Max: Max 구독이 있는 경우 선택하세요.
Claude Pro: Pro 구독이 있는 경우 선택하세요.

아래에는 ‘5시간 사용 제한에 가까워지면 자동 중지 예약’ 및 ‘워밍업 요청 차단’과 같은 고급 옵션도 있습니다. 초보자는 기본값을 유지하고 필요에 따라 나중에 조정하면 됩니다.

작성을 완료한 후 ‘Next’를 클릭하여 인증을 진행하세요.

2단계 — 인증

이 단계에서는 Claude 계정이 릴레이 서비스를 사용하도록 인증합니다. ‘Generate Authorization Link’ 버튼을 클릭하세요:

생성된 링크가 입력 필드에 나타납니다. 예: https://claude.ai/oauth/authorize?.... 오른쪽의 복사 아이콘을 클릭하여 링크를 복사하세요.

그런 다음 브라우저에서 이 링크를 여세요 (프록시를 사용하는 것을 잊지 마세요):

페이지에 ‘Claude Code would like to connect to your Claude chat account’가 표시됩니다. Authorize 버튼을 클릭하여 인증을 완료하세요.

인증이 성공하면 페이지에 Authorization Code가 제공됩니다. 이 코드를 복사하여 대화상자의 입력 필드에 붙여넣고 ‘Complete Authorization’을 클릭하세요.

이제 계정이 연결되었습니다.

2단계: API 키 생성

계정을 연결한 후 상단의 ‘API Keys’ 탭을 클릭하여 API 키 관리로 들어갑니다:

오른쪽 상단의 ‘+ Create New Key’ 버튼을 클릭하세요:

다음 정보를 입력하세요:

이름: 이 키에 이름을 지정하세요. 예: ‘개인용’, ‘가족용’. 나중에 관리하기 쉽도록 사람이나 용도별로 이름을 지정하는 것이 좋습니다.
속도 제한 설정 (선택 사항): 여러 사람이 공유하는 경우 각 키에 대해 요청 빈도와 비용 제한을 설정할 수 있습니다. 무제한으로 하려면 비워 두세요.

작성을 완료한 후 Confirm을 클릭하세요. 생성이 성공하면 다음 대화상자가 나타납니다:

중요 알림: 전체 API 키를 볼 수 있는 유일한 기회입니다. 이 창을 닫으면 시스템이 다시 표시하지 않습니다.

‘Copy Claude Configuration‘을 클릭하면 다음과 같은 내용을 얻을 수 있습니다:

export ANTHROPIC_BASE_URL="your_server_public_url"
export ANTHROPIC_AUTH_TOKEN="cr_217627747170e5aa5691134fab8278b0dfec1b0ac2e59345ae180dc6d5f9643d"

이것이 API 주소와 키입니다. 안전하게 저장하세요.

다음에 사용하는 방법

ANTHROPIC_BASE_URL과 ANTHROPIC_AUTH_TOKEN을 확보한 후에는 API 호환 클라이언트에서 사용할 수 있습니다.

Claude Code에서 구성하는 방법은 Claude Code 설정 가이드를 참조하세요.

저도 이 설정을 직접 사용하고 있으며 배포 이후 계정이 차단되지 않았습니다.

요약

오늘 배운 내용:

자체 릴레이를 구축하는 이유: 차단 방지를 위한 고정 IP, 다중 사용자 공유, 데이터 보안에 대한 완전한 통제.
사용할 프로젝트: claude-relay-service, 오픈소스 자체 호스팅.
배포 방법: 하나의 명령어로 모든 것이 완료됩니다; 설치 후 공개 URL과 관리자 비밀번호를 얻습니다.
계정 연결 과정: Account Management → Add Account → Select Claude → 구독 유형 선택 → OAuth 인증.
API 키 생성 과정: API Keys → Create New Key → 이름 입력 → Claude 구성 복사 (한 번만 표시됨!).

핵심 사항:

전체 API 키는 생성 시에만 표시되므로 즉시 복사하여 저장하세요.
올바른 구독 유형을 선택하세요: Max와 Pro는 지원하는 모델이 다릅니다; Pro는 Opus 4를 지원하지 않습니다.
인증 중에는 프록시를 사용하는 것을 잊지 마세요; 브라우저와 서버가 동일한 프록시를 사용하는 것이 가장 좋습니다.

파트 3 · AI 도구: 실용적인 주요 도구들

주류 AI 도구 실용 개요

Mon, 01 Jan 0001 00:00:00 +0000

우리는 AI가 무엇인지, 그리고 그것이 “답변을 초안하는 확률 계산기"라는 것을 배웠습니다. 하지만 이제 문제는: 시장에 너무 많은 AI 도구가 있는데, 어떤 것을 사용해야 할까요?

이 장에서는 가장 주류 AI 도구들을 소개합니다. 각 도구의 웹사이트, 사용 방법, 특징을 포함합니다. 이 장을 읽고 나면 어떤 것을 선택해야 할지 알게 될 것입니다.

해외 빅3: ChatGPT, Claude, Gemini

ChatGPT - 가장 유명한 AI

웹사이트: chat.openai.com

VPN 필요: 예
개발사: OpenAI (미국)
최신 모델:

GPT-5 시리즈: GPT-5 Instant (빠름), GPT-5 Thinking (추론), GPT-5 Thinking Pro (최강 추론)
GPT-5.2 시리즈: 2025년 12월 출시된 플래그십, 전문 지식 작업에서 최고 성능

장점: 가장 똑똑함, 기능이 가장 풍부함 (채팅, 코드, 이미지 생성, 웹 검색), 생태계가 가장 좋음 (GPTs 스토어), 업데이트가 가장 빠름
단점: 중국에서 접근 어려움, 무료 버전 제한 많음, 유료 월 $20
추천 대상: 가장 진보된 AI를 원하고, 예산이 있으며, VPN 접속이 가능한 분

Claude - 가장 “인간적인” AI

웹사이트: claude.ai

VPN 필요: 예
개발사: Anthropic (미국)
최신 모델:

Claude Opus 4.5: 코딩 및 에이전트 작업에서 세계 최고
Claude Sonnet 4.5: 세계 최고 코딩 모델, SWE-bench 선두
Claude Haiku 4.5: 빠르고 저렴한 모델

장점: 고품질 응답, 강력한 장문 처리 (200K-1M 토큰), 최고 수준 코딩 능력, Claude Code CLI 도구
단점: VPN 필요, 상대적으로 기능이 적음, Pro 월 $20. 특히 이 회사는 중국에 우호적이지 않으며 계정 차단이 엄격함.
추천 대상: 작가, 프로그래머, 응답 품질을 중시하는 분

Gemini - Google의 올라운더

웹사이트: gemini.google.com

VPN 필요: 예
개발사: Google (미국)
최신 모델:

Gemini 3 Pro: 19/20 벤치마크에서 경쟁사 제압
Gemini 3 Flash: 빠르고 저렴, 현재 기본 모델
Gemini 3 Deep Think: 심층 추론 모드

장점: 강력한 웹 검색 능력, 뛰어난 멀티모달, Google 생태계 통합, AI Studio에서 넉넉한 무료 티어, 학생 플랜으로 1년 무료 사용 가능, Banana 모델(텍스트-이미지)은 세계적 수준
단점: 중국에서 접근 어려움
추천 대상: Google 서비스를 자주 사용하고 멀티미디어 콘텐츠를 처리해야 하는 분

🎁 무료 꿀팁: Google AI Studio

URL: aistudio.google.com

이것은 보석입니다! Google의 개발자 플랫폼이지만 일반인도 사용할 수 있습니다. 간단히 말해: Gemini의 무료 프리미엄 버전입니다.

추천 이유:

완전 무료: 분당 60회 요청, 개인 사용에 충분
최신 모델: Gemini 3 Pro 및 Flash 최신 버전 접근 가능, 이미 Banana 모델(텍스트-이미지) 포함
대화 제한 없음: 공식 웹사이트 버전과 달리 사용량 제한 없음
API 키 생성 가능: 다른 도구와 함께 사용 가능

사용 방법: URL 열기, Google 계정으로 로그인 (VPN 필요), “Create new prompt” 클릭하여 채팅 시작. 인터페이스는 영어지만 중국어로 질문 가능. 유일한 단점은 인터페이스가 개발자 지향적이고 공식 웹사이트만큼 깔끔하지 않지만, 성능은 동일하게 강력합니다.

국내 4강: DeepSeek, Doubao, GLM, MiniMax

DeepSeek - 중국의 자랑

웹사이트: chat.deepseek.com
VPN 필요: 아니요
최신 모델:

DeepSeek-V3.2: GPT-5 및 Gemini 3 성능에 필적
DeepSeek-V4: 2026년 2월 출시 예정

장점: 완전 무료, 매우 뛰어난 성능, 탁월한 코딩 능력, 중국에서 원활한 접속, 오픈소스
단점: 피크 시간대에 느릴 수 있음, 창의성이 약간 떨어짐, 엄격한 콘텐츠 심사
추천 대상: 국내 사용자에게 첫 번째 선택! 학생, 프로그래머, 예산이 적은 분

Doubao - 가장 사용자 친화적인 AI

웹사이트: doubao.com

VPN 필요: 아니요
최신 모델:

Doubao 대형 모델 1.8: 보고, 쓰고, 하고, 계획하는 종합 능력 지원
Doubao 실시간 음성 모델: 종단간 초인간적 대화
Seedance 비디오 생성: 정밀한 오디오-비디오 동기화

장점: 부드러운 음성 대화, 간단한 인터페이스, 무료, 현지화 잘 됨, DAU 1억 이상
단점: 평균적인 전문 능력, 엄격한 콘텐츠 심사
추천 대상: 노인/어린이를 위한 음성 대화, 일상 채팅. 집에 호기심 많은 아이가 있거나 영어를 배우고 싶다면 모바일 앱의 전화 기능을 사용하여 AI와 직접 대화하는 것을 적극 추천합니다.

GLM (Zhipu Qingyan) - 코딩 대안

웹사이트: chatglm.cn

VPN 필요: 아니요
최신 모델:

GLM-4.7: 2025년 12월 출시, 355B 파라미터, SWE-bench 73.8% (오픈소스 중 최고 점수), Coding Plan 직접 구독 가능

핵심 장점:

Claude Sonnet 4.5에 필적하는 코딩 능력
Claude Code, Cline 등 주류 도구와 완벽 호환
실리콘밸리 인정: Cursor, Windsurf 같은 스타 제품에서 사용
매우 저렴한 가격: API 비용 약 백만 토큰당 $0.44
MIT 오픈소스: 로컬 배포 가능

장점: 최고 수준 코딩 능력, 저렴함, 강력한 에이전트 능력, 오픈소스 친화적
단점: 덜 알려짐, 상대적으로 멀티모달이 약함

추천 대상: 프로그래머 (Claude 대안), 다국어 개발자, 기업 사용자

MiniMax

웹사이트: minimaxi.com

VPN 필요: 아니요
최신 모델:
텍스트 생성:

MiniMax-M2.1: 다국어 코딩 및 오피스 시나리오에 특화
MiniMax-M2: 230B 파라미터, 코딩 및 에이전트 최적화

비디오 생성:

Hailuo 02: 세계 2위 비디오 모델
Hailuo 2.3: 세계 최고 가성비, 1080P 지원

장점 (텍스트): 최고 수준 코딩 능력, 강력한 에이전트 성능, 좋은 다국어 지원
장점 (비디오): 높은 비디오 품질, 빠른 속도, 따라올 수 없는 가성비
단점: 평균적인 텍스트 대화, 짧은 비디오 길이
추천 대상: 비디오 크리에이터, 프로그래머 (에이전트 워크플로우), 다국어 개발자

요약: 어떤 것을 선택해야 할까요?

💰 돈을 쓰고 싶지 않다면:

첫 번째 선택: DeepSeek - 무료, 뛰어난 성능, 중국에서 직접 접속 가능
대안: Google AI Studio - VPN 필요하지만 넉넉한 무료 티어, 세계적 수준의 대형 모델
일상 채팅: Doubao - 편리한 음성 대화

🚀 최고를 원한다면:

종합 최고: ChatGPT (GPT-5.2)
코딩 최고: Claude (Opus 4.5 또는 Sonnet 4.5)
멀티모달 처리: Gemini 3

👨‍💻 프로그래머라면:

해외 첫 번째 선택: Claude Opus 4.5 - 코딩 능력 1위
국내 대안: GLM-4.7 또는 MiniMax-M2.1 - 저렴하고 비슷한 성능

👴👶 가족용이라면:

노인/어린이: Doubao - 간단한 음성 대화
학생: DeepSeek - 학습 및 질의응답

처음부터 DeepSeek를 Claude에 연결하기

Mon, 01 Jan 0001 00:00:00 +0000

요즘 DeepSeek에 대해 정말 칭찬하고 있어요—가성비가 엄청나거든요.

물론 대부분의 사람들에게는 모바일이나 웹 버전의 DeepSeek으로 충분합니다. 하지만 프로그래밍이나 다른 고급 작업을 하고 싶다면, 코딩 도구나 터미널에 연결해야 합니다.

여기서는 Claude 데스크톱 앱으로 시작하는 것을 추천합니다.

AI마다 사용하는 도구가 다르고 최종 결과도 달라집니다—이것이 바로 하네스 엔지니어링의 핵심입니다.

참고로 “하네스"라는 단어를 설명하자면, 원래 뜻은 말이 수레를 끌고 일할 수 있도록 착용시키는 장비입니다. 그렇지 않으면 말이 그냥 날뛰기만 하죠. AI 모델도 마찬가지입니다. 모델만으로는 쓸모가 없고, 도구 호출, 컨텍스트 관리, 프롬프트 같은 부가 기능들을 갖춰야 진정으로 유용해집니다. 그 부가 기능 세트를 하네스라고 부릅니다. 같은 모델이라도 하네스가 다르면 결과가 크게 달라질 수 있습니다.

그리고 Claude는 이 분야에서 뛰어납니다. 데스크톱 앱은 진입 장벽도 크게 낮춰줍니다—WYSIWYG 방식이거든요.

API 키 신청하기

먼저 DeepSeek API 키를 신청해야 합니다.

1단계: DeepSeek 웹사이트(https://www.deepseek.com)를 열고 “API Open Platform"을 클릭하세요.

2단계: 계정을 등록한 후, 왼쪽에서 “Recharge"를 클릭하세요. 최소 10위안을 충전하세요. 등록 방법은 자세히 설명하지 않겠습니다.

3단계: 왼쪽에서 “API keys"를 클릭한 다음 “Create API key"를 클릭하세요.

4단계: 이름을 입력하세요. 새 페이지가 나타나며 API 키가 표시됩니다. 모든 내용을 즉시 복사해서 저장하세요—이 창을 닫으면 다시는 확인할 수 없습니다. 반드시 복사 버튼을 눌러 안전하게 보관하세요. 또한 유출되지 않도록 주의하세요. 다른 사람이 API 키를 알면 무료로 사용할 수 있습니다!

데모에서는 이 위치에 자신의 API 키를 사용하세요. sk-REPLACE_WITH_YOUR_API_KEY 형태여야 합니다. 이 단계는 여기까지입니다.

설정

1단계: https://claude.ai/downloads에서 Claude 데스크톱 앱을 다운로드하세요. VPN이 필요할 수 있습니다. VPN이 없다면 국내 미러에서 다운로드할 수 있는지 확인해보세요.

2단계: 다운로드한 파일을 설치하세요. 더블클릭한 후, 새 창에서 Claude 아이콘을 오른쪽의 Applications 폴더로 드래그하세요.

3단계: 앱을 엽니다. 먼저 상단 메뉴에서 “Help"를 선택한 다음 “Enable Developer Mode"를 선택하세요. 새 대화상자에서 “Enable"을 클릭하세요. 앱이 다시 시작됩니다.

4단계: 다시 시작한 후, 새 “Developer” 탭이 보입니다. 클릭한 다음 “Configure Third-Party Inference"를 선택하세요.

5단계: 새 페이지에서 URL을 입력하세요: https://api.deepseek.com/anthropic. API 키는 앞서 저장한 것을 사용하세요.

6단계: 모델을 입력하세요. 참고: Claude 데스크톱 앱은 이제 모델 이름 접두사를 감지하여 모델을 식별합니다. 원래 이름을 그대로 입력하면 차단됩니다.

해결 방법은 간단합니다. “모자"를 씌워주면 됩니다. 모델 이름 앞에 접두사 claude-를 추가하세요.

같은 페이지에서 아래로 스크롤하여 “Model list"가 보일 때까지 내려갑니다. 아래에 “Add"를 클릭하고 두 모델을 추가하세요:

claude-deepseek-v4-flash
claude-deepseek-v4-pro

(원래 deepseek-v4-flash와 deepseek-v4-pro를 입력했을 수도 있습니다. 이제 앞에 claude-만 붙이면 됩니다. 앱은 이름 접두사로 모델을 식별하므로 접두사를 추가하면 인식되지 않습니다.)

모든 내용을 입력한 후, 하단의 “Apply Locally"를 클릭하세요. 새 페이지에서 “Relaunch now"를 선택하세요. 앱이 다시 시작됩니다.

7단계: 다시 시작한 후, 새 인터페이스에서 사용을 시작할 수 있습니다. Claude Code의 자세한 사용법은 이 가이드의 13장을 참조하세요.

마지막으로, 이 단계를 차근차근 따라오면 문제가 발생하지 않을 것입니다. 그래도 문제가 있으면 Q&A 그룹에 문의하세요.

또한 이 타사 로그인에서 로그아웃하려면 왼쪽 하단의 “Cowork 3P"를 클릭한 다음 “Disconnect"를 클릭하세요. 다시 로그인하면 로그인 방법을 묻는 창이 나타나며, “Subscription"을 다시 선택하면 됩니다.

아, 그리고 DeepSeek는 아직 비전을 지원하지 않으므로 Claude에서 이미지를 주면 볼 수 없습니다. 하지만 DeepSeek의 비전 모델이 곧 나온다는 소문이 있습니다—기대됩니다!

프롬프트 캐싱이 실제로 의미하는 것은?

Mon, 01 Jan 0001 00:00:00 +0000

DeepSeek가 드디어 V4 모델을 출시했습니다. 지난 며칠간 사용해봤는데 정말 좋습니다. 특히 Flash 모델은 가성비가 뛰어납니다. 제가 사용하는 가계부 미니 프로그램의 응답 시간이 원래 5초였는데 이제 2.5초로 줄었습니다. 한마디로: 부드럽습니다!

유일한 단점은 Pro 모델이 그리 저렴하지 않다는 점입니다. 공식 웹사이트에 따르면 하반기에 국내 칩 공급이 늘어나면 가격이 더 내려갈 것이라고 합니다.

예상치 못하게, 이틀 후 Pro 모델에 한정 75% 할인이 적용되었습니다(그리고 이 할인이 장기화될 가능성도 있습니다). 어제는 캐시 히트 가격을 원래의 10분의 1로 낮췄습니다! 더 무슨 말이 필요하겠어요? 일어나서 페달을 힘껏 밟을 때입니다!

이것이 우리가 아는 DeepSeek입니다! 며칠 전 저는 특정 Coding Plans이 사용하기 어렵고 경험이 좋지 않다고 비판한 적이 있습니다. DeepSeek는 전체 API 가격을 Coding Plans 이하로 직접 낮추는 것 같습니다. 특히 지금은 많은 Coding Plans이 프로그래밍 외 사용을 금지하고 있어 DeepSeek의 진정성이 더욱 돋보입니다.

일부 Coding Plans의 API는 번역 기능을 통합하면 차단할 수도 있지만, DeepSeek는 신경 쓰지 않습니다. 원하는 대로 사용하세요.

GPT-5.5와 DeepSeek V4는 뛰어난 성능을 보여주고 있습니다. 저는 이미 다음 달에 Claude 구독을 취소하는 것을 고려하고 있습니다. 그리고 주변의 몇몇 전문가들은 이미 사용해봤습니다.

하지만 본론으로 돌아가서, 여러분 중 일부는 궁금할 것입니다: 입력, 출력, 캐시가 실제로 무엇을 의미할까요?

먼저 캐시 히트가 무엇을 의미하는지 소개하겠습니다.

비유를 들어보겠습니다: 여러분이 단골 국수집에 가서 처음으로 “계란 추가한 소고기 칼국수, 고수 빼주세요"를 주문합니다. 주인은 소고기를 신선하게 썰고, 반죽을 치대고, 계란을 삶고, 재료를 준비해야 합니다. 전체 과정에 시간이 좀 걸립니다. 10분 후, 친구가 와서 똑같은 것을 주문합니다. 주인은 냄비에 재료가 아직 뜨겁고 면도 같은 배치인 것을 보고 바로 서빙합니다. 이것이 “히트"입니다.

AI가 입력을 처리할 때, 기본적으로 보낸 모든 텍스트(시스템 프롬프트, 대화 기록, 현재 질문 포함)를 “씹어서” 모델의 내부 중간 상태로 변환해야 합니다. 이 단계는 정말 계산 집약적입니다.

AI가 이번에 보낸 내용의 큰 시작 부분이 이전과 정확히 동일하다는 것을 발견하면, 이전의 중간 상태를 직접 재사용하여 다시 씹을 필요가 없습니다. 이것이 캐시 히트입니다.

세 가지 핵심 사항을 기억하세요:

정확한 접두사 일치여야 합니다. 시작 부분에 공백 하나를 추가하거나 구두점 하나를 바꿔도 캐시가 무효화되어 처음부터 다시 시작합니다.
시간 제한이 있습니다. 제공자에 따라 다릅니다. 예를 들어 Anthropic의 기본값은 5분에 불과합니다(화장실 다녀오면 만료됩니다). 1시간 옵션을 원하면 추가 요금을 내야 합니다(기본 입력 가격의 2배). DeepSeek의 캐시는 몇 시간에서 며칠까지 지속됩니다.
같은 대화에서는 자연스럽게 히트됩니다. 대화가 한 턴씩 추가될 때마다 새 입력 = 이전 전체 기록 + AI 응답 + 새 질문이기 때문입니다. 앞부분의 긴 기록이 정확히 동일하므로 자연스럽게 히트됩니다.

캐시가 히트되느냐 아니냐는 가격에 큰 영향을 미칩니다. 그래서 같은 대화 안에서 관련 내용만 논의하는 것을 권장합니다. 문맥을 기억하는 것뿐만 아니라 캐시 히트에도 영향을 미치기 때문입니다. 새 대화를 시작하면 처음부터 비용을 지불해야 하지만, 대화를 계속하면 할인을 받는 셈입니다.

따라서 “백만 토큰당 입력(캐시 히트)”, “백만 토큰당 입력(캐시 미스)”, “백만 토큰당 출력"의 의미는 다음과 같습니다:

백만 토큰당 입력(캐시 미스): 이번에 보낸 내용 중 AI가 이전 계산에서 재사용할 수 없어 처음부터 다시 씹어야 하는 부분에 적용되는 가격입니다. 여기에는 첫 번째 채팅, 새 세션, 또는 시작 부분의 프롬프트 변경이 포함됩니다.

백만 토큰당 입력(캐시 히트): 이번에 보낸 내용 중 시작 부분이 이전 사례와 정확히 일치하여 AI가 직접 재사용하는 부분에 적용되는 (훨씬 저렴한) 가격입니다. 같은 대화에서 두 번째, 세 번째 턴 등의 기록이 여기에 해당합니다.

백만 토큰당 출력: AI가 생성한 응답에 적용되는 가격입니다. 이는 항상 가장 비싼데, “생성"이 “이해"보다 더 많은 컴퓨팅 파워를 소비하기 때문입니다. 하나는 AI가 머릿속에서 반복적으로 초안을 작성하고 단어를 선택하며 문장을 구성하는 과정이고, 다른 하나는 AI가 자료를 검토하는 과정일 뿐입니다.

구체적인 예를 들어 감을 잡아보겠습니다. DeepSeek를 사용하여 3000토큰짜리 코드를 수정한다고 가정해보겠습니다.

첫 번째 질문: 입력 3000토큰(전부 미스) + AI 출력 500토큰
그런 다음 “이것을 더 최적화할 수 있나요?“라고 물어봅니다: 입력이 3500토큰 이상이 됩니다(이 중 3500토큰은 이전 기록으로 전부 캐시 히트; 새로 추가한 몇십 토큰만 미스) + AI 출력 600토큰
새 대화를 시작하고 코드를 다시 붙여넣은 후 같은 질문을 합니다: 다시 3000토큰 전부 미스

미스 가격이 히트 가격의 10배라면, “같은 대화에서 후속 질문"과 “새 대화를 시작하여 다시 질문” 사이의 입력 비용 차이는 거의 10배가 될 수 있습니다.

그래서 이번에 DeepSeek는 캐시 히트 가격을 원래의 10분의 1로 낮추고, Pro 모델 75% 할인과 결합했습니다. 긴 컨텍스트 + 다중 턴 대화(코딩, 문서 분석, 긴 채팅 등) 사용 사례의 경우, 이는 거의 뼈를 깎는 가격 인하입니다. Skills를 작성하거나 자동화 워크플로우를 설정해본 사람이라면 긴 프롬프트를 반복적으로 호출하는 것이 일상이라는 것을 알고 있습니다. 이 가격 인하로 인한 실제 절감 효과는 종이에 보이는 것보다 훨씬 극적입니다.

마지막으로 실용적인 팁: 새 대화를 시작하기 전에 같은 대화 안에서 주제를 마무리하는 습관을 들이세요. 항상 “지우고 새로 시작"하지 마세요. AI가 당신을 기억할 뿐만 아니라 비용도 절약됩니다.

요약

오늘 배운 내용:

캐시 히트란 무엇인가 — AI가 이전에 씹은 입력을 저장합니다. 이번에 시작 부분이 같으면 직접 재사용하여 계산력을 절약하고 가격도 할인됩니다.
세 가지 핵심 조건 — 정확한 접두사 일치여야 하며, 시간 제한이 있고(제공자에 따라 몇 분에서 며칠), 같은 대화에서는 자연스럽게 히트됩니다.
세 가지 가격이 의미하는 것 — 캐시 미스 = 재계산되는 입력; 캐시 히트 = 재사용된 입력(가장 저렴); 출력 = AI 생성 응답(가장 비쌈).
출력이 가장 비싼 이유 — “생성"이 “이해"보다 더 많은 컴퓨팅 파워를 소비합니다. AI가 머릿속에서 반복적으로 초안을 작성하며, 가격은 보통 입력 미스의 몇 배입니다.

핵심 요점:

같은 대화를 계속하면 자동 할인; 자주 새 대화를 시작하면 매번 정가를 지불합니다.
프롬프트는 끝부분을 수정하세요. 시작 부분을 바꾸면 캐시가 무효화됩니다.
긴 컨텍스트 + 다중 턴 대화 시나리오(코딩, 문서 분석, 긴 채팅)가 가장 큰 혜택을 봅니다. DeepSeek의 가격 인하는 그러한 사용자에게 거의 뼈를 깎는 수준입니다.

해외 AI 도구 등록 및 결제 방법

Mon, 01 Jan 0001 00:00:00 +0000

지금까지 주요 AI 도구들을 살펴보았고, 여러분이 사용하고 싶은 플랫폼을 선택했을 것입니다. 대부분의 중국 AI 도구는 웹에서 완전 무료로 사용할 수 있으며, API에 대해서만 결제가 필요합니다(이에 대해서는 나중에 더 자세히 다룹니다). 하지만 해외 AI 도구는 다릅니다. 많은 사람들이 결제 단계에서 막힙니다. 해외 AI 도구는 어떻게 결제하나요?

이 장에서는 ChatGPT, Claude, Gemini와 같은 해외 AI 도구의 결제 방법을 안내하며, 특히 Apple 구독 방법을 적극 추천합니다.

공식 결제 방법 (비추천)

ChatGPT, Claude, Gemini의 공식 웹사이트는 모두 직접 구독을 지원하지만, 다음이 필요합니다.

해외 신용카드: Visa, MasterCard, American Express 등
해외 PayPal 계정: 해외 신용카드에 연결된 PayPal 계정
해외 주소: 청구지 주소에 해외 주소 필요

왜 비추천인가요?

중국 사용자에게 불편함:

중국에서 발급된 대부분의 신용카드는 거부됨
듀얼 통화 카드도 리스크 관리에 의해 거부될 수 있음
가상 신용카드(Depay 등)는 계정 정지 위험이 있음
결제 실패 시 계정이 동결될 수 있음

요약: 진정한 해외 신용카드가 없다면 공식 웹사이트에서 직접 결제하지 않는 것이 좋습니다. 아래에서 더 신뢰할 수 있는 방법을 소개합니다.

Apple 구독 방법 (적극 추천)

Apple 구독을 추천하는 이유는?

Apple 구독은 현재 가장 안정적이고 안전한 결제 방법입니다.

중국 UnionPay 카드 지원: 해외 신용카드 불필요
낮은 위험: 공식 Apple 채널을 통해 AI 플랫폼에서 차단될 위험 없음
간편한 관리: 모든 구독을 Apple ID에서 중앙 관리
투명한 가격: Apple 환율로 정산, 추가 수수료 없음
원클릭 로그인 및 등록: 별도 등록 없이 Apple ID로 AI 도구에 직접 로그인 가능(자세한 내용은 아래에서)

사전 준비 사항

중국 본토 이외 지역의 Apple ID가 필요합니다. 추천 지역:

미국: 가장 보편적, 앱 선택 폭 넓음
일본: 환율이 유리할 수 있음
나이지리아: 가장 저렴

중국 이외 Apple ID 등록 방법

현재 Apple ID에서 로그아웃
App Store를 열고 무료 앱을 선택하여 다운로드
‘새 Apple ID 생성’ 선택 후 지역을 미국/일본/홍콩으로 설정
정보 입력(이메일, 비밀번호, 보안 질문)
결제 방법은 일단 ‘없음’ 선택, 임의 주소 입력(나중에 변경 가능)

등록이 완료되면 해당 지역의 빈 Apple ID가 생성됩니다.

Apple 기프트 카드 받기

중국 이외 Apple ID가 준비되면 잔액을 충전해야 합니다. 기프트 카드를 받는 두 가지 방법이 있습니다.

방법 1: 타오바오/셴위에서 구매 (빠르지만 위험)

단계:

타오바오나 셴위에서 ‘미국 Apple 기프트 카드’ 또는 ‘미국 iTunes’ 검색
평판이 좋은 판매자 선택(리뷰와 판매량 확인)
구매 후 판매자가 교환 코드를 보내줌
즉시 Apple ID에 교환

장점:

빠름: 몇 분 안에 코드 수령
때로는 공식 가격보다 약간 저렴

단점:

도난 신용카드 위험: 판매자가 도난 카드로 기프트 카드를 구매한 경우 Apple ID가 차단될 수 있음
사후 지원 어려움: 문제 발생 시 책임 소재 불명

중요 참고: 이 방법을 선택한다면 반드시 크고 신뢰할 수 있는 스토어를 고르고 코드를 받은 즉시 교환하세요. 도난 카드 문제가 발생하면 즉시 Apple 지원에 연락하여 상황을 설명하세요.

방법 2: Apple 공식 웹사이트에서 구매 (추천, 안전)

이 방법이 가장 안전합니다. 절차가 다소 복잡하지만 완전히 합법적이며 위험이 없습니다. 상세 단계:

1. Apple 공식 기프트 카드 구매 페이지 열기

URL: https://www.apple.com/shop/buy-giftcard/giftcard
참고: 미국 Apple 웹사이트에 접속해야 합니다(미국 Apple ID가 있는 경우)

2. 이메일 배송 방식 선택

페이지에서 실물 카드 또는 전자 카드를 선택할지 물어봄
‘Email’(전자 카드, 이메일로 발송) 선택
금액 선택: $25, $50, $100 또는 사용자 지정 금액

3. 수신자 정보 입력

받는 사람: 자신의 영문 이름 입력
받는 사람 이메일: 자신의 이메일 주소 입력(교환 코드를 받을)
보내는 사람: 아무거나 입력 가능, 자기 자신도 가능
메시지: 비워두거나 아무 내용 입력

4. 장바구니에 추가하고 결제

‘Add to Bag’ 클릭
‘Check Out’ 클릭(Apple Pay를 설정했다면 사용 가능)
시스템이 Apple ID로 로그인하도록 요청(미국 Apple ID 사용)

5. 결제 수단 입력

핵심: 중국 UnionPay 신용카드 또는 체크카드를 직접 사용 가능
카드 번호, 만료일, CVV를 그대로 입력
카드 소유자 이름: 카드에 표시된 대로 병음으로 입력

6. 청구지 주소 입력

중요한 단계입니다! 미국 주소를 입력해야 합니다. 면세 주를 선택하여 비용을 절약하는 것이 좋습니다.

알래스카
오리건
델라웨어
몬태나
뉴햄프셔

작성 방법:

Google Maps 또는 Apple Maps 열기
‘Oregon hotel’ 또는 ‘Alaska hotel’ 검색(호텔 주소 찾기)
호텔의 주소, 도시, 우편번호, 전화번호 복사
이를 청구지 주소 필드에 입력

예시 (오리건 주 호텔 주소):

Street: 1234 SW Broadway
City: Portland
State: Oregon
ZIP: 97201
Phone: (503) 123-4567

7. 결제 완료

정보가 올바른지 확인 후 ‘Place Your Order’ 클릭
은행 결제 처리 대기(문자 인증 코드 입력이 필요할 수 있음)

8. 교환 코드 기다리기

결제 성공 후 몇 분에서 몇 시간 내에 이메일 수신
이메일에는 교환 코드(16자리 영숫자)가 포함됨
최대 24시간이 걸릴 수도 있음

Apple ID에 기프트 카드 교환하기

교환 코드를 받으면 Apple ID 잔액으로 교환해야 합니다.

단계:

1. App Store 열기

iPhone 또는 iPad에서 App Store 열기
중국 이외 Apple ID로 로그인되어 있는지 확인

2. 교환 페이지로 이동

오른쪽 상단의 프로필 아이콘 탭
‘기프트 카드 또는 코드 교환’ 찾기

3. 교환 코드 입력

옵션 1: 카메라로 코드 스캔
옵션 2: 16자리 코드를 수동으로 입력
‘교환’ 탭

4. 잔액 확인

교환 성공 후 잔액이 즉시 계정에 표시됨
‘계정’ 페이지에서 현재 잔액 확인 가능

가능한 문제:

문제 1: ‘이 코드는 미국 스토어에서 교환해야 합니다’

원인: Apple ID 지역 설정이 올바르지 않음
해결 방법: ‘설정 > Apple ID > 미디어 및 구입’으로 이동하여 지역 전환

문제 2: 교환 후 잔액이 표시되지 않음

원인: 계정이 리스크 관리 대상임
해결 방법: 아래 리스크 관리 부분 참조

Apple 계정으로 AI 도구에 원클릭 로그인 (매우 편리)

Apple 구독 방법의 또 다른 큰 장점은 많은 사람들이 모르는 것입니다. Apple ID로 AI 도구에 직접 로그인할 수 있으며, 별도 계정 등록이 필요 없습니다!

Apple ID 로그인을 추천하는 이유

전통적인 등록의 불편함:

이메일 인증 필요
비밀번호 설정 필요(또 다른 비밀번호 기억)
일부 플랫폼은 전화번호 인증 필요(해외 번호는 번거로움)
ChatGPT와 같은 플랫폼은 중국 이메일 주소에 제한 있음

Apple ID 로그인의 장점:

원클릭 로그인: 한 번의 탭으로 등록 및 로그인 완료
인증 불필요: 이메일이나 전화 인증 불필요
개인정보 보호: Apple이 실제 이메일 주소를 숨김
높은 보안: Apple의 2단계 인증이 계정 보호
통합 관리: 모든 AI 구독이 Apple ID에 연결됨

Apple 로그인을 지원하는 AI 도구

대부분의 주요 AI 도구가 ‘Apple로 로그인’을 지원합니다.

ChatGPT: 완전 지원
Claude: 완전 지원
Perplexity: 완전 지원
Notion AI: 완전 지원
대부분의 다른 AI 도구: 일반적으로 지원

상세 단계

ChatGPT를 예시로:

1. ChatGPT 앱 다운로드

중국 이외 Apple ID로 로그인되어 있는지 확인
App Store에서 ‘ChatGPT’ 검색
다운로드 및 설치

2. 앱을 열고 로그인 방법 선택

ChatGPT 앱 열기
홈 화면에 ‘Log in’ 또는 ‘Sign up’ 표시
탭 후 다양한 로그인 옵션 확인

3. ‘Apple로 계속하기’ 선택

이메일 로그인을 선택하지 마세요.
바로 ‘Apple로 계속하기’ 탭
시스템이 Apple ID 인증 창을 팝업

4. 인증 확인

Apple이 표시:
- ‘ChatGPT가 사용자의 Apple ID를 사용하려고 합니다’
- 사용자 이름 및 이메일
선택 가능:
- 내 이메일 공유: AI 도구가 실제 이메일을 볼 수 있음
- 내 이메일 가리기: Apple이 임의 이메일을 생성하여 AI 도구로 전달
개인정보 보호를 위해 ‘내 이메일 가리기’를 선택하는 것이 좋습니다

5. Face ID/Touch ID 인증 완료

Face ID 또는 Touch ID로 확인
등록 및 로그인이 자동으로 몇 초 안에 완료

6. 사용 시작

로그인 성공, 앱에 바로 진입
계정이 자동으로 생성됨
다음에 앱을 열면 자동 로그인

웹에서도 Apple 로그인 사용 가능

모바일 앱뿐만 아니라 많은 AI 도구의 웹 버전도 Apple 로그인을 지원합니다.

단계:

AI 도구 웹사이트 열기 (예: claude.ai)
‘Log in’ 클릭
‘Apple로 계속하기’ 선택
Apple 로그인 창 팝업
Apple ID와 비밀번호 입력
2단계 인증 완료
로그인 성공

참고:

웹 로그인을 위해서는 Mac 또는 iCloud가 설치된 Windows PC 필요
또는 iPhone/iPad의 Safari를 사용하여 로그인

Apple 로그인의 추가 혜택

1. 기기 간 동기화

Apple ID로 로그인하면 모든 Apple 기기에서 원활하게 사용 가능
iPhone, iPad, Mac에서 로그인 상태 자동 동기화

2. 보안 관리

AI 계정에 문제가 있으면 Apple ID 설정에서 한 번에 인증 취소 가능
경로: 설정 > Apple ID > 암호 및 보안 > Apple ID를 사용하는 앱

3. 비밀번호 분실 걱정 없음

비밀번호가 없기 때문입니다. 항상 Apple ID로 로그인합니다.
Apple ID만 안전하면 AI 계정도 안전합니다.

팁

이미 이메일로 AI 계정을 등록한 경우?

대부분의 AI 도구는 ‘Apple 계정 연결’을 지원합니다.

AI 계정에 로그인
계정 설정으로 이동
‘연결된 계정’ 또는 ‘로그인 방법’ 찾기
‘Apple로 로그인’ 추가
다음부터 Apple ID로 로그인 가능

하나의 Apple ID로 여러 AI 도구에 로그인할 수 있나요?

물론입니다! 하나의 Apple ID로 다음에 로그인 가능:

ChatGPT
Claude
Perplexity
Notion AI
그리고 Apple 로그인을 지원하는 모든 도구

서로 충돌하지 않으며 각 도구는 독립적인 계정입니다.

AI 서비스 구독하기

잔액이 있으면 AI 서비스를 구독할 수 있습니다.

단계:

1. AI 앱 다운로드

중국 이외 Apple ID로 로그인되어 있는지 확인
App Store에서 검색 및 다운로드:
- ChatGPT (OpenAI)
- Claude (Anthropic)
- Gemini (Google)

2. 앱을 열고 구독

앱을 열고 ‘Subscribe’ 또는 ‘Upgrade’ 찾기
구독 플랜 선택 (Plus/Pro 등)
결제 방법을 Apple ID 잔액으로 확인
구독 완료

3. 구독 성공

Apple로부터 구독 확인 이메일 수신
앱에 구독 상태 표시

리스크 관리 문제 대처

리스크 관리란?

한 번에 큰 금액의 기프트 카드를 교환하면(예: $100 이상) Apple의 리스크 관리가 트리거될 수 있습니다.

잔액이 표시되지만 사용 불가
구독 시 ‘결제 수단이 거부되었습니다’ 표시
잔액 동결

해결 방법

방법 1: 며칠 기다리기 (추천)

아무것도 하지 않고 3~7일 기다림
시스템이 자동으로 리스크 관리를 해제
그 후 잔액을 정상적으로 사용 가능

방법 2: Apple 지원에 연락 (더 빠름)

Apple 지원에 전화:
- 한국: 080-333-3100 (한국 Apple 지원 번호, 필요시 변경 가능)
상황 설명: ‘기프트 카드를 교환했는데 작동하지 않습니다.’
지원팀이 정보를 확인하고 수동으로 리스크 관리를 해제
보통 48시간 이내에 복구

리스크 관리 회피 팁:

처음에는 $50 이하로 교환
한 번에 큰 금액보다는 소액으로 나누어 교환
교환 후 1~2일 기다렸다가 구독

요약: 전체 프로세스 정리

전체 단계:

중국 이외 Apple ID 등록 (미국/일본/홍콩)
기프트 카드 받기 (공식 웹사이트 또는 타오바오에서 구매)
Apple ID에 기프트 카드 교환
Apple ID로 AI 도구에 원클릭 로그인 (별도 등록 불필요)
AI 앱 다운로드 및 구독
리스크 관리 발생 시 기다리거나 지원에 연락

비용 참고:

ChatGPT Plus: $20/월
Claude Pro: $20/월
Gemini Advanced: $19.99/월

비용 절약 팁:

환율이 유리한 지역 선택 (예: 일본, 홍콩)
공식 웹사이트에서 기프트 카드 구매 시 면세 주 선택
월간 구독하고 필요 없을 때 언제든지 취소

훅(Hook)을 활용해 스킬 워크플로우를 잠그기

Mon, 01 Jan 0001 00:00:00 +0000

스킬은 내 일상 워크플로우에서 없어서는 안 될 방법이 되었다. 세 번 이상 반복되는 일이 있으면, 나는 그것을 스킬로 전환하는 것을 고려한다. 단지 시간을 절약하기 위해서가 아니라, 매번 방향과 단계가 엇나가지 않도록 보장하기 위해서다. 적어도 이론적으로는 그렇다.

하지만 AI는 여전히 엇나간다

그 말은 다소 과장되었다. 현실은 AI가 여전히 단계를 건너뛴다는 것이다. 내가 매일 사용하는 위챗 공개계정 글쓰기 스킬을 예로 들어보자. 나는 초안을 보여주고 수정을 거친 후에야 오타 교정을 진행하도록 설정했다. 간단해 보이지? 하지만 실제로 실행될 때, 계속 단계를 건너뛴다: 초안을 완성하고도 나에게 보여주지 않고 바로 교정과 편집으로 넘어간다. 내가 알아챌 때쯤이면 이미 조용히 파일을 수정해버린다. 내가 지적하면 사과하며 “죄송합니다, 제 실수입니다"라고 말하지만, 다음 번에도 똑같은 일을 반복한다. 사과만으로는 문제가 해결되지 않는다.

AI가 항상 단계를 건너뛰는 이유

이 문제는 직관에 반한다. 처음에는 AI가 충분히 똑똑하지 않다고 생각했지만, 나는 이미 ChatGPT 5.4와 Opus 4.6 같은 최상위 대형 모델을 사용하고 있었다. 나중에는 규칙이 충분히 명확하지 않다고 생각해서 스킬의 규칙을 몇 번이고 수정했다. 조금 나아지긴 했지만, 근본 원인은 해결되지 않았다. 조사 끝에 AI가 단계를 건너뛰는 것은 “규칙을 보지 못해서"가 아니라 생성 메커니즘에 의해 결정된다는 것을 알게 되었다:

확률 기반의 “가속 충동”. 대규모 언어 모델은 본질적으로 다음 토큰을 예측한다. 작업을 완료하는 가중치는 자연스럽게 “7단계에 머물며 사용자를 기다리는 것"보다 높다. 완료에 대한 감각이 모델의 내재적 동기다.
긴 맥락에서 규칙의 약화. 처음에 설정한 규칙은 모델이 3000번째 토큰에 도달할 때쯤이면 주의 가중치가 희석된다. 특히 긴 스킬 문서에 규칙을 묻어두면 더 쉽게 주변부로 밀려난다.
자동 모드에서 특히 심각. 자동 모드로 글을 쓸 때 모델은 “모든 단계를 한 번에 실행"하는 경향이 있다. 내가 개입할 수 있는 창은 더욱 좁아진다.
CLAUDE.md와 스킬 문서는 본질적으로 “소프트 제약” 이다. 이들은 모델의 “자기 규율"에 의존하여 따르도록 하는 프롬프트다. 그리고 자기 규율은 “이 작업을 빨리 끝내고 싶다"는 압박 앞에서 취약하다.

결론은: 언어적 제약은 작업 중심 압박 아래에서 실패한다. 단순히 문서를 작성하고, 느낌표를 추가하거나, AI를 심리적으로 압박하는 것은 문제를 완화할 뿐 근본적으로 해결하지 못한다. 진정으로 해결하려면 모델의 자기 규율 영역 밖으로 꺼내야 한다—물리적으로 단계를 건너뛸 수 없게 만드는 것. 바로 여기에 훅(Hook)이 등장한다.

훅이란 무엇인가

Claude Code에는 Hook이라는 메커니즘이 있다. 이는 스킬도, 프롬프트도, CLAUDE.md와도 다르다—Claude Code 생명주기의 주요 지점에 연결된 로컬 셸 스크립트다. 핵심 차이점:

CLAUDE.md / 스킬은 모델이 관찰하고 실행한다—모델이 무시할 수 있다.
Hook은 시스템이 강제한다—모델이 무시하고 싶어도 무시할 수 없다.

Anthropic 공식 문서에서 Hook에 관한 핵심 문장: Hook은 시스템 이벤트에 의해 트리거되며, 모델 결정에 의해 트리거되지 않는다. 즉, Hook은 전체 Claude Code 런타임에 연결된다. 모델이 호출하는 모든 도구 호출(Write, Edit, Bash)은 먼저 Hook의 검토를 통과해야 한다. Hook이 deny를 반환하면, --dangerously-skip-permissions가 활성화되어 있어도 거부된다. 이것이 내가 “하드 제약"이라고 부르는 것이다—AI가 스스로 선택하지 못하게 하고, 대신 도구 호출이 실제 셸 스크립트 감사를 통과하도록 강제한다.

일반적인 Hook 트리거 지점:

PreToolUse: AI가 도구를 호출하기 전에 가로챈다.
UserPromptSubmit: AI에게 전달하기 전에 사용자의 메시지를 처리한다.
SessionStart: 세션이 시작되거나 재개될 때 트리거된다.
Stop: Claude가 응답을 마쳤을 때 트리거된다.

처음 두 가지에 집중하면 된다—이것만으로도 “단계 잠금"을 구축하기에 충분하다.

실제 적용: 내 위챗 계정 스킬을 위한 단계 게이트(Step Gate)

모든 이야기는 구체적인 예시 없이는 소용없다. 이 스크린샷은 이 글을 쓰는 동안의 Claude Code 인터페이스다. 빨간 상자 안에서 AI가 나에게 “pass step3 0090"이라고 답변해 달라고 요청한다—이 패스프레이즈가 바로 Step Gate Hook이 작동하고 있다는 증거다. 지금 당신이 읽고 있는 이 글은 내가 패스프레이즈를 보내고 Hook이 허용한 후에 작성된 것이다.

전체 Step Gate는 단 두 개의 셸 스크립트와 settings.json의 작은 설정만을 사용한다. 하나씩 설명하겠다.

settings.json에 두 개의 Hook 등록하기

~/.claude/settings.json에 다음을 추가한다:

"PreToolUse": [
  {
    "matcher": "Write|Edit",
    "hooks": [
      { "type": "command",
        "command": "~/.claude/skills/writing-gongzhonghao/scripts/gate_check.sh" }
    ]
  }
],
"UserPromptSubmit": [
  {
    "hooks": [
      { "type": "command",
        "command": "~/.claude/skills/writing-gongzhonghao/scripts/gate_mark.sh" }
    ]
  }
]

이 설정의 의미:

AI가 Write 또는 Edit 도구를 호출하려고 할 때마다 gate_check.sh가 먼저 실행되어 검토한다.
내가 메시지를 보낼 때마다 gate_mark.sh가 먼저 실행되어 메시지를 파싱한다.

gate_check.sh: 가로채기 처리

이 스크립트의 로직은 매우 간단하다:

AI가 새 파일 04-Output/NNNN xxx.md를 Write하려고 하면(3단계: 새 글 작성에 해당), 상태 파일 step3.ok가 존재하는지 확인한다. 없으면 deny를 반환한다.
AI가 기존 글을 Edit하려고 하면(7단계 이후 교정에 해당), step7.ok가 존재하는지 확인한다. 없으면 역시 deny를 반환한다.

거부할 때는 다음과 같은 프롬프트도 포함한다: “3단계 주제 논의가 확인되지 않았습니다: 먼저 개요/방향 승인을 제공해 주세요. 확인 후 ‘pass step3 NNNN’이라고 답변하면 새 파일을 생성할 수 있습니다.” 이 프롬프트는 AI에게 직접 표시되므로, AI는 막혔다는 것을 인지하고 나에게 패스프레이즈를 요청한다.

gate_mark.sh: 패스프레이즈 해제 처리

어떻게 “해제"할까? AI가 스스로 해제하게 할 수는 없다—그러면 제약이 전혀 없게 된다. 규칙은 다음과 같다: 내 메시지에 특정 패스프레이즈가 포함된 경우에만 상태 파일이 생성된다. gate_mark.sh는 내가 메시지를 보낼 때마다 실행되며, pass stepN NNNN 패턴을 스캔한다. 일치하면 해당 디렉토리에 .ok 파일을 생성한다.

따라서 전체 체인은 다음과 같아진다:

AI가 개요를 완성하고 새 글을 작성하려고 함 → gate_check.sh에 의해 차단됨
AI가 나에게 패스프레이즈를 요청: “방향을 확인해 주세요. ‘pass step3 0090’이라고 답변하세요.”
내가 “pass step3 0090"을 보냄 → gate_mark.sh가 step3.ok를 생성함
AI가 다시 파일을 생성하려고 시도함 → 이번에는 gate_check.sh가 허용함
초안을 완성한 후 교정을 위해 Edit을 진행하려고 함 → step7.ok에 의해 다시 차단됨
내가 초안을 읽고 “pass step7 0090"을 보냄 → 교정이 시작될 수 있음

전체 과정에서 AI는 “자기 규율"을 발휘할 여지가 없다. 단계를 건너뛰고 싶어도 시스템 수준에서 도구 호출이 차단되기 때문에 불가능하다.

허점 막기: AI가 스스로 상태 파일을 건드릴 수 없음

첫 번째 버전을 설계한 후, 나는 계획을 한참 들여다보다가 허점을 발견했다—AI가 Bash를 사용해 스스로 touch step3.ok를 실행하면 어떨까? 그러면 제약을 우회할 수 있지 않을까? 그래서 나는 스킬 문서에 특정 규칙을 추가했다: AI는 스스로 상태 파일을 건드리면 안 된다. 그렇지 않으면 자신의 제약을 제거하는 것이 된다. 이 규칙 자체는 여전히 소프트 제약이지만, Hook의 하드 차단과 결합하면 충분히 폐쇄된 루프를 형성한다—AI가 이 규칙을 적극적으로 위반하지 않는 한(그리고 Claude는 실제로 협조적이다), Hook 제약은 실질적으로 유효하다. 더 엄격하게 하려면 PreToolUse에 Bash 매처를 추가하여 touch와 같은 명령도 차단할 수 있다. 하지만 나는 아직そこ까지 가지 않았다. 지금도 충분히 잘 작동한다.

코드를 몰라도 당황하지 마라

이러한 셸 스크립트나 JSON 설정을 직접 작성할 필요는 없다(사실 나도 직접 작성하지 못한다). 접근 방식은 간단하다: 이 글과 당신의 스킬 파일을 Claude나 Codex에 던져주고, 읽게 한 후 수정하도록 도움을 요청하라—필요한 곳에 스크립트를 만들고, settings.json을 수정하라. AI는 “문서에 따라 환경을 구성하는” 이런 작업에 특히 신뢰할 만하며, 처음부터 코드를 작성하는 것보다 훨씬 안정적이다. AI는 글에서 원리를 배우면서 동시에 당신의 스킬 요구사항에 따라 Hook을 작성하며, 결과가 엇나가는 경우는 거의 없다.

한 문장으로 요약

CLAUDE.md, 스킬 문서, 굵은 표시, 세 번 반복, 심리적 압박—이 모든 것은 AI에 대한 언어적 제약이다. 효과는 있지만 한계가 낮다.

Hook은 AI에 대한 코드 제약이다. 규칙을 AI가 닿을 수 없는 곳으로 옮겨, “규칙 따르기"를 모델의 자기 규율 문제에서 실행 환경의 필수 요구사항으로 바꾼다.

만약 AI에게 “왜 또 단계를 건너뛰는 거야?“라고 반복해서 말하고 있다면, 이제 Hook을 사용해 제약할 때가 되었다.