자주 막히는 자리

책을 쓰는 동안 흔히 부딪히는 자리를 모았습니다. 증상으로 찾아 해당 항목만 보면 됩니다. 여기에 없는 증상은 에러 메시지를 그대로 복사해 Claude Code에 붙여 넣고 물어보는 편이 빠릅니다.

git

”command not found: git”

git이 안 깔린 상태입니다. macOS는 xcode-select --install, Linux와 WSL2는 sudo apt install -y git. 설치 후 git --version으로 확인합니다.

챕터 commit이 충돌함

여러 챕터를 한꺼번에 commit하려다 충돌이 나는 경우가 있습니다. book-studio는 한 챕터가 한 commit이 원칙입니다. 챕터를 하나씩 commit하면 충돌이 줄고, 되돌리기도 챕터 단위로 깔끔합니다. 이미 충돌이 났으면 에러를 복사해 Claude Code에 붙여 넣고 “이 충돌 어떻게 풀어?”라고 물어봅니다.

책 전환

엉뚱한 책의 챕터를 쓰고 있음

활성 책(active_slug)이 의도와 다른 책을 가리키는 상태입니다. “지금 어느 책 작업 중이야?”로 활성 책을 확인하고, “X 책으로 이어서”로 옮깁니다. 여러 권을 굴릴 때 가끔 활성 책이 헷갈리는 자리입니다.

책 목록에 없는 책을 찾음

books.json에 등록 안 된 책이거나 슬러그가 어긋난 상태입니다. “책 목록 보여줘”로 등록된 책을 확인합니다. 새 책이면 “새 책 — 슬러그 X로”로 다시 등록합니다.

게이트

챕터 게이트가 계속 불합격

챕터의 AI 티 점수가 61점을 넘은 상태입니다. 챕터를 읽고 도입부가 결과부터 던지는지, 구체적 수치나 실패담이 없는지, 템플릿 표현이 박혔는지를 봅니다. 빠져나오는 자세한 길은 when-ai-gets-stuck에 있습니다.

연속성 보고서에 어긋남이 잡힘

continuity-check가 챕터를 인덱스와 대조하다 설정 불일치를 잡은 상태입니다. 의도된 변화면 인덱스를 갱신하고, 실수면 챕터를 고칩니다. continuity를 봅니다.

산출물

markdown이 깨져 보임

챕터 파일에 frontmatter나 코드 블록이 잘못 닫혔을 수 있습니다. markdown 뷰어로 열어 어디서 깨지는지 보고, “이 챕터 markdown 고쳐줘”라고 하면 정리합니다.

챕터가 git에 커밋이 안 됨

_workspace/는 .gitignore에 들어가 git 추적에서 빠지는 자리입니다. 챕터 산출물은 원래 커밋 대상이 아닙니다. 챕터를 따로 백업하고 싶으면 _workspace/ 바깥으로 복사하거나, git 추적 자리를 따로 만듭니다. pre-commit 훅이 _workspace/ 커밋을 막는 건 의도된 동작입니다.

그래도 안 풀리면

GitHub 이슈를 열거나 팀 Slack에 올립니다. 세 가지를 같이 적습니다.

• 어디서 막혔는지 (어느 책, 어느 챕터, 어느 단계)
• 에러 메시지 전체
• 환경 정보 (운영체제)