사전 준비

이 단계는 한 번만 하면 됩니다. 이미 갖춘 항목은 건너뛰면 됩니다.

처음 보는 명령이 절반 이상이라면 비개발자용 시작의 “어떤 분을 염두에 두고 썼나” 단락을 한 번 보고 와 주세요. 매뉴얼이 가정하는 학습 수준이 거기에 적혀 있습니다.

운영체제별 차이

항목	macOS	Windows	Linux
사용하는 터미널	`Terminal.app` 또는 iTerm2	WSL2 위의 Ubuntu를 권합니다	배포판이 제공하는 셸
검증 상태	검증됨	WSL2를 먼저 설치한 다음 그 안에서 모든 명령을 실행합니다	검증됨

Windows에서는 WSL2 설치 안내를 먼저 끝낸 다음 이쪽으로 돌아오세요. 이 매뉴얼의 모든 명령은 WSL2 위 Ubuntu 셸 안에서 실행한다고 가정합니다.

1) Python 3

발행 스크립트(scripts/deploy_to_blogger.py)가 Python 3로 동작합니다. 대부분의 macOS와 Linux에는 이미 설치돼 있습니다.

python3 --version    # Python 3.11.x 비슷한 줄이 뜨면 정상입니다

아무것도 안 뜨거나 “command not found”가 뜨면 설치합니다.

# macOS
brew install python3

# Linux와 WSL2
sudo apt update && sudo apt install -y python3 python3-pip

2) git

macOS

xcode-select --install

작은 대화 상자가 떠서 동의를 받고 설치가 시작됩니다. git이 이미 설치돼 있으면 안내 메시지만 한 줄 띄우고 끝납니다.

Linux와 WSL2

sudo apt update && sudo apt install -y git

설치 검증과 본인 정보 등록

git --version    # git version 2.x.x
git config --global user.name "Your Name"
git config --global user.email "your@example.com"

3) Claude Code

공식 설치 안내는 docs.claude.com/ko/docs/claude-code/quickstart에 있습니다. 설치한 뒤에 claude를 한 번 실행해 로그인하거나 API 키를 등록합니다.

claude --version    # 버전 번호가 뜨면 준비가 끝난 것입니다

Claude Code 대신 OpenAI Codex CLI를 써도 됩니다. 그 경우 진입점은 저장소 루트의 AGENTS.md이고 같은 흐름이 그대로 적용됩니다. 처음이라면 Claude Code를 권합니다.

4) Google 계정과 Blogger 블로그

blogger.com에 Google 계정으로 로그인해 블로그를 하나 만듭니다. 한국어 블로그와 영어 블로그를 따로 운영할 생각이라면 두 개를 만듭니다. blog-studio는 한글본을 BLOG_ID_KO 블로그에 올리고, 영문본을 BLOG_ID_EN 블로그에 올립니다.

블로그를 만들었으면 일단 여기까지입니다. 블로그 ID를 .env에 적는 방법은 first-run과 publish 단계에서 안내합니다.

5) OAuth 자격증명 발급

Blogger에 자동으로 글을 올리려면 Google이 발급하는 자격증명이 필요합니다. 두 파일입니다.

scripts/credentials.json: Google Cloud 콘솔에서 받는 OAuth 클라이언트입니다 (데스크톱 앱 유형).
scripts/token.json: 첫 발행 때 동의 화면을 거치면 자동으로 생성되는 토큰입니다.

credentials.json을 받는 절차는 Google Cloud 콘솔에서 프로젝트를 만들고, Blogger API를 켜고, OAuth 클라이언트 ID를 데스크톱 앱 유형으로 발급해 내려받는 흐름입니다. 화면 순서와 버튼 위치는 저장소의 scripts/README.md에 정리돼 있습니다. Google 콘솔 화면은 종종 바뀌니 공식 문서도 같이 봅니다.

token.json은 지금 만들 필요가 없습니다. 첫 발행 때 브라우저에서 동의를 한 번 하면 자동으로 생깁니다.

6) 선택 사항: 코드 에디터

글이 어떻게 저장되는지 들여다보고 싶다면 VS Code가 무난합니다. AI가 글을 다 써 주기 때문에 꼭 필요하지는 않습니다.

항목이 모두 갖춰졌다면 clone-and-install로 갑니다.