기술 서적 초안을 하루 만에 — Claude Code로 bkit 가이드북 쓰기

📝 한 줄 요약

bkit 바이브코딩 가이드북(3챕터, 100페이지 분량)을 Claude Code와 함께 하루 만에 초안까지 완성했습니다. AI로 ebook을 쓸 수 있다는 걸 직접 검험해보고, 동시에 "결과물이 나왔다고 내 것이 된 건 아니다"는 것도 배웠습니다.

🎯 이런 분들께 도움이 됩니다

• Claude Code로 바이브코딩을 하고 있고, 더 체계적인 워크플로우를 찾는 분

• bkit 플러그인이 무엇인지 감을 잡고 싶은 분

• AI로 기술 문서나 ebook을 써보고 싶은 분

😫 문제 상황

bkit은 Claude Code에 설치하는 플러그인입니다. PDCA 사이클로 설계-구현-검증 루프를 자동화하고, 에이전트 팀을 조율하는 등 꽤 복잡한 기능을 갖추고 있습니다. 그런데 막상 "bkit이 뭐야?"라는 질문을 받으면 머릿속에 있는 것을 꺼내 설명하기가 쉽지 않았습니다.

두 가지를 동시에 해결하고 싶었습니다.

• bkit의 개념과 구조를 체계적으로 정리하고 싶다

• AI로 ebook을 집필하는 경험 자체를 해보고 싶다

마침 두 목표가 딱 맞아떨어지는 주제가 bkit 가이드북이었습니다.

🛠️ 사용한 도구

🔧 작업 과정

1단계: 집필 계획 수립 — workflow 설계

무작정 "책 써줘"가 아니라, 집필 워크플로우를 먼저 설계했습니다. bkit 소스코드 위치와 가이드북 구성을 알려주고, 집필 계획 파일을 만들어달라고 했습니다.

bkit agentic workflow 에 대하여 가이드북을 작성하고자 한다.
- '~/vibepipe/bkit-claude-code' 에 코드가 존재한다.
- 가이드북 구성: 1. 설명(개념,구조), 2. 주요 사용처, 3. 핸즈온
가이드북을 작성하는 workflow 작성해줘

Claude Code는 bkit 소스코드를 직접 읽고 분석한 뒤, workflow.md(집필 순서, 품질 기준, 검토 절차)를 생성했습니다. 집필을 시작하기 전에 "어떻게 쓸 것인가"를 정의한 셈입니다.

이 단계가 초반에 가장 힘들었습니다. 책의 방향과 구성을 정하는 일 — AI가 도와주더라도 결국 "이 책이 무엇을 위한 책인가"는 제가 직접 판단해야 했습니다.

2단계: autopilot 모드로 3챕터 초안 생성

계획 파일이 완성되자, 한 줄짜리 명령으로 본격 집필을 시작했습니다.

"workflow.md를 따라 가이드북 작성 시작"

workflow.md를 스스로 읽고 순서에 따라 작업을 진행합니다. 자리를 비운 사이에 챕터 3개가 완성되었습니다.

• ch01-concept.md — 왜 bkit인가, PDCA 사이클, Context Engineering 3계층, Hook 시스템, 프로젝트 레벨

• ch02-usecases.md — 부트스트래핑, PDCA 기능 개발, 에이전트 팀, QA, 커스터마이징

• ch03-handson.md — Starter/Dynamic/Enterprise 레벨 실습 3개

• index.md — 전체 목차, 서문, 빠른 참조 카드

명령 하나에 챕터 4개가 만들어졌습니다. 분량보다 더 인상적인 건 그 다음 단계였습니다.

3단계: 에이전트 팀 검토 — 초안이 책이 되는 순간

생성한 초안이 실제 bkit과 일치하는지, 독자가 이해할 수 있는지 검토가 필요했습니다.

agent team(lead + 전문가 teammate 3)에서 작성된 bkit 가이드북에 대한 내용 및 편집 검토를 진행한다.

에이전트 팀 4명(lead + 전문가 teammate 3)이 각자 다른 역할로 검토했습니다. 기술 정확성 에이전트는 bkit 소스코드와 가이드북 내용을 교차 확인했고, 편집 에이전트는 문체 일관성을, 독자 관점 에이전트는 "처음 읽는 사람이 이해할 수 있는가"를 점검했습니다.

workflow.md 가 책의 뼈대를 세웠다면, agent team 검토가 살을 붙이는 과정이었습니다. 이 두 단계가 맞물리면서 "책의 내용이 정리되는 느낌"이 실제로 들었습니다.

4단계: 다이어그램과 레이아웃 마무리

다이어그램 변환

책에 ASCII 문자로 그린 다이어그램이 여러 개 있었는데, PDF에서 보기 좋지 않았습니다.

'bkit Context Engineering 3계층' 다이어그램을 Mermaid 다이어그램으로 변경해줘

Claude Code가 PDCA 사이클, Context Engineering 3계층, Hook 아키텍처, 레벨 감지 로직 — 4개 다이어그램을 Mermaid 형식으로 변환했습니다. 중간에 PlantUML을 시도했다가 렌더링 품질이 마음에 들지 않아 Mermaid로 돌아왔는데, AI와 "이건 별로야, 원래대로 돌려줘" 식의 대화가 자연스럽게 이어졌습니다.

PDF 레이아웃 버그

표 컬럼 너비가 의도대로 나오지 않는 문제가 있었습니다. 직접 비율을 지정해도 무시되는 상황이었는데, Claude Code가 PDF 변환 코드를 분석해 근본 원인을 찾아냈습니다. pandoc이 colgroup을 먼저 생성하면 나중에 삽입한 설정이 무시된다는 문제였습니다. 글쓰기 외의 도구 수준 디버깅까지 같은 대화에서 해결된다는 점이 인상적이었습니다.

✅ 결과

Before vs After

산출물

• bkit-guidebook.pdf — 188×257mm 기술 서적 레이아웃, Mermaid 다이어그램 4개 포함

• bkit-guidebook.md — 통합 Markdown 원본 (110KB)

• 챕터 파일 3개 (ch01~ch03)

💬 AI 활용 팁

효과적이었던 것

1. 계획부터 AI와 함께 — 무작정 "써줘"가 아니라, 워크플로우 파일을 먼저 만들고 그 파일을 따라가게 하면 결과가 훨씬 일관됩니다.

2. 검토 순서 — 초안 생성과 검토를 분리하면 각 단계에서 집중할 수 있습니다. 동시에 진행하면 둘 다 엉성해집니다.

3. 롤백을 두려워하지 않기 — PlantUML이 마음에 안 들면 "원래대로 돌려줘"가 됩니다. AI와의 작업에서 실험과 롤백 비용은 거의 없습니다.

4. 도구 수준 문제도 함께 — 레이아웃 버그처럼 글쓰기 외의 기술적 문제도 같은 대화에서 해결됩니다.

주의할 점

1. 결과물이 나왔다고 내 것이 되는 건 아닙니다 — 책은 나왔지만, "bkit이 뭐야?" 질문을 받으면 여전히 더듬게 됩니다. 결과물을 직접 읽고 소화하는 시간이 반드시 필요합니다.

2. 구성을 정하지 않고 시작하면 안 됩니다 — 초반에 "어떤 책을 쓸 것인가"를 AI에게 맡기면 방향이 계속 흔들립니다. 챕터 구성과 핵심 독자는 사람이 먼저 정해야 합니다.