자주 막히는 자리
첫 발행까지 가는 동안 흔히 부딪히는 자리를 모았습니다. 증상으로 찾아 해당 항목만 보면 됩니다. 여기에 없는 증상은 에러 메시지를 그대로 복사해 Claude Code에 붙여 넣고 물어보는 편이 빠릅니다.
Python과 설치
섹션 제목: “Python과 설치””command not found: python3”
섹션 제목: “”command not found: python3””Python 3가 안 깔린 상태입니다. macOS는 brew install python3, Linux와 WSL2는 sudo apt install -y python3 python3-pip. 설치 후 python3 --version으로 확인합니다.
”command not found: pip”
섹션 제목: “”command not found: pip””pip 대신 pip3을 써 봅니다.
pip3 install -r scripts/requirements.txt그래도 안 되면 python3 -m pip install -r scripts/requirements.txt로 부릅니다. 권한 에러가 뜨면 --user를 붙입니다.
OAuth와 자격증명
섹션 제목: “OAuth와 자격증명”발행이 dry-run에서 멈추고 파일이 없다고 나옴
섹션 제목: “발행이 dry-run에서 멈추고 파일이 없다고 나옴”scripts/credentials.json이 없는 상태입니다. Google Cloud 콘솔에서 Blogger API를 켜고 OAuth 클라이언트 ID를 데스크톱 앱 유형으로 발급해 scripts/credentials.json으로 저장합니다. 자세한 화면 순서는 scripts/README.md에 있습니다.
첫 발행 때 동의 화면이 안 뜸
섹션 제목: “첫 발행 때 동의 화면이 안 뜸”token.json은 첫 발행 때 브라우저 동의로 자동 생성됩니다. 동의 창이 안 뜨면 credentials.json이 제자리(scripts/ 아래)에 있는지, 데스크톱 앱 유형으로 발급됐는지 봅니다. 웹 앱 유형으로 발급하면 동의 흐름이 다릅니다.
”invalid_grant” 또는 토큰 만료
섹션 제목: “”invalid_grant” 또는 토큰 만료”token.json이 만료됐거나 권한이 바뀐 상태입니다. scripts/token.json을 지우고 발행을 다시 부르면 동의 화면이 새로 떠서 토큰을 재발급합니다.
블로그 ID
섹션 제목: “블로그 ID”어느 블로그에 올라갈지 모르겠음
섹션 제목: “어느 블로그에 올라갈지 모르겠음”list-blogs 명령으로 본인 Google 계정의 블로그 목록과 ID를 확인합니다. 한글본이 갈 블로그 ID를 .env의 BLOG_ID_KO에, 영문본이 갈 블로그 ID를 BLOG_ID_EN에 적습니다.
글이 엉뚱한 블로그에 올라감
섹션 제목: “글이 엉뚱한 블로그에 올라감”.env의 BLOG_ID_KO와 BLOG_ID_EN이 바뀌어 박혔을 수 있습니다. 두 ID를 다시 확인하고, 한글 블로그와 영문 블로그 ID가 제자리인지 봅니다.
게이트
섹션 제목: “게이트”AI-smell 게이트 불합격으로 발행이 안 됨
섹션 제목: “AI-smell 게이트 불합격으로 발행이 안 됨”글의 AI 티 점수가 60점을 넘은 상태입니다. 발행이 일부러 막히는 자리입니다. 글을 한 번 읽고 도입부, 문단 길이, 1인칭 경험 유무를 봅니다. 빠져나오는 자세한 길은 when-ai-gets-stuck에 있습니다.
AdSense 게이트에서 글이 표시됨
섹션 제목: “AdSense 게이트에서 글이 표시됨”광고 정책에 걸릴 신호가 잡힌 상태입니다. 게이트가 짚어 준 자리를 고치거나, 광고를 안 붙일 글이면 그대로 진행할지 판단합니다.
한영 정합
섹션 제목: “한영 정합”한글본만 있고 영문본이 없음
섹션 제목: “한글본만 있고 영문본이 없음”번역을 안 돌렸거나 slug가 어긋난 상태입니다. “방금 글 영문본 만들어줘”로 번역을 부르고, find _workspace/posts/new -iname "*{slug}*"로 두 파일이 같은 slug로 짝지어졌는지 확인합니다.
발행이 한영 정합에서 막힘
섹션 제목: “발행이 한영 정합에서 막힘”품질 게이트가 한글본과 영문본의 hreflang 상호 참조나 구조 대응이 어긋났다고 본 상태입니다. “한영 정합 다시 맞춰줘”라고 하면 게이트가 짚은 자리를 고칩니다.
발행 스크립트
섹션 제목: “발행 스크립트””Permission denied: ./scripts/deploy.sh”
섹션 제목: “”Permission denied: ./scripts/deploy.sh””스크립트에 실행 권한이 없는 상태입니다.
chmod +x scripts/deploy.sh의도 안 한 글까지 같이 올라감
섹션 제목: “의도 안 한 글까지 같이 올라감”publish-new를 slug 없이 불렀을 때입니다. staging의 모든 글이 대상이 됩니다. 한 편만 올리려면 --slug {slug}로 좁혀 부릅니다.
그래도 안 풀리면
섹션 제목: “그래도 안 풀리면”GitHub 이슈를 열거나 팀 Slack에 올립니다. 세 가지를 같이 적습니다.
- 어디서 막혔는지 (어느 단계, 어느 명령)
- 에러 메시지 전체
- 환경 정보 (운영체제, Python 버전)