技術書をGitHubとCI/CDで書く方法――Zenn Bookを2冊公開してわかったこと

2026 年 7 月、Zenn で『Zig 言語で学ぶブロックチェイン』と『自分で作るクラウド競技』の 2 冊を公開しました。

ありがたいことに、2 冊とも Zenn 公式アカウントで紹介され、Book Store の「注目の一冊」に掲載されました。

• Zig言語で学ぶブロックチェイン
  • Zenn 公式による紹介（2026 年 7 月 14 日）
• 自分で作るクラウド競技
  • Zenn 公式による紹介（2026 年 7 月 29 日）

ただし、2 冊の作り方は大きく異なります。

『Zig 言語で学ぶブロックチェイン』は、2025 年 2 月に書き始め、公開まで約 1 年半かかりました。原稿ディレクトリだけで 128 コミットあり、実装の変更、章の再構成、EVM 章の追加、公開前レビューを何度も繰り返しています。

一方、『自分で作るクラウド競技』は、企画 Issue を作ってから短期間で公開しました。ただし、最初の原稿をそのまま磨いたのではありません。題材そのものを途中で捨て、11 本の Pull Request を通して初見読者向けに作り直しました。

期間もテーマも異なる 2 冊でしたが、最後まで書き切るために必要だった工程は共通していました。

それは、技術書を文章ではなく、テスト可能で継続的に改善できる「もう 1 つのソフトウェア」として扱うことです。

公式に選ばれた理由は公開されていないため、「この方法なら紹介される」とは言えません。この記事では、紹介される方法ではなく、技術書を最後まで書き切り、公開後も直し続けるために実際に使った工程を紹介します。

最初に全体像をまとめると、次のようになります。

• 読者と、読了後にできることを 1 文で決める
• 動作するサンプルを先に用意する
• GitHub で原稿と目次を管理する
• Pull Request ごとに CI と人のレビューを通す
• Zenn の下書きで実際の表示を確認する
• 公開設定だけを変更し、公開後のページを確認する

書き始める前に、出版方法とメディアを選ぶ

最初から「Zenn で本を書く」と決めるのではなく、誰に何を届けたいかを先に決めます。

形式	向いている内容
個人ブログ	執筆の動機、迷い、失敗など、自分の経験を伝える
Zenn 記事	1 つの技術的な問いや手順を、1 ページで完結させる
Zenn Book	複数の章を順番に進み、最後に 1 つの成果物を完成させる

判断するときは、次の点を考えます。

• 読者は誰か
• 1 ページで完結するか
• 読了後に何ができるようになるか
• 内容を今後も更新するか
• 原稿の正本をどこに置くか

今回の 2 冊は、前の章で作ったものを次の章で使い、最後に動く成果物を完成させる構成です。そのため、単発の記事ではなく Zenn Book を選びました。

執筆の工夫

目次より先に「読者の変化」を決める

最初から章立てを考えると、書きたいことを並べただけの本になりがちです。先に、次の 1 文を作ります。

この本は、誰が、何を一から作り、最後にどの方法で動作確認できる本なのか。

たとえば『自分で作るクラウド競技』では、企画 Issue に次の項目を書きました。

• 想定読者
• 読了後に作れるもの
• 全章を通して使う題材
• この本では扱わないこと
• コードと原稿の正本
• 公開前の確認方法
• 完成と判断する条件

最初の目次は、完成版と大きく変わってもかまいません。企画の役割は目次を固定することではなく、内容を変えるときに「読者の到達点を守れているか」を判断できるようにすることです。

ChatGPT Pro で広げ、人が決め、Codex で現実に合わせる

今回の執筆では、ChatGPT Pro と Codex を同じ用途には使いませんでした。

担当	主な役割
ChatGPT Pro	テーマの候補、想定読者、タイトル、章立て、文章の初稿を作る
人	採用する案、章の順番、削る内容、最終的な主張を決める
Codex	リポジトリを調べ、原稿と実装を照合し、修正と検証を行う

企画の初期段階では、採用しない案も含めて広く考える必要があります。ここは ChatGPT Pro との対話で進めました。

案が決まった後は、人が読者の立場でストーリーを組み直します。そのうえで Codex へ、対象読者、読後の状態、変更すること、変更しないこと、検証方法を渡します。

AI にすべてを任せるのではなく、発散、判断、実物との照合を分けたことがポイントです。

本文より先に、動作するサンプルを作る

技術書で危険なのは、説明しやすい架空のコードや実行結果を書いてしまうことです。文章として自然でも、読者の環境では動かないことがあります。

そこで、本文を書く前に次を用意します。

• 読者が使うコード
• 実行コマンド
• 期待する結果
• 対象バージョン
• 失敗したときの戻し方

Zig 本では、本文とは別のBlockChain リポジトリに、章ごとの開始地点と完成地点を置きました。公開前には、本文で案内する経路を実際に実行し直しました。

クラウド競技本では、説明用に考えた複雑な題材を途中で捨て、TenkaCloudChallengeに存在する、動作確認済みの Hello World を題材にしました。

原則は単純です。

本文に合わせてコードを想像するのではなく、動いたコードと検証結果に本文を合わせる。

実装が未完成なら、本文にも未完成と書きます。将来やりたいことを、現在使える機能のように書かないことも重要です。

Zenn Book を GitHub で管理する

Zenn には、1 ページで完結する「記事」と、複数の章を順番に読む「本」があります。

前の章で作ったものを次の章で育てる、用語を順番に説明する、最後に 1 つの成果物を完成させる、といった内容は本に向いています。

GitHub 連携で Zenn Book を管理する場合、1 冊の原稿は次のような構成になります。

books/
└── cloud-competition/
    ├── config.yaml
    ├── cover.png
    ├── chapter1.md
    ├── good-problems.md
    ├── chapter2.md
    └── ...

config.yamlには、タイトル、紹介文、公開状態、章の順番などを書きます。

title: "自分で作るクラウド競技"
summary: "実践型クラウド競技を設計・実装・開催する本です。"
topics: ["AWS", "SRE", "GameDay", "CTF", "TenkaCloud"]
published: false
price: 0
chapters:
  - chapter1
  - good-problems
  - chapter2

各章は Markdown ファイルです。

---
title: "クラウド競技とは何か"
---

ここから本文を書きます。

chaptersに書いた順番が、そのまま本の目次になります。ファイルが存在していても、chaptersに含まれていなければ本には表示されません。

原稿、目次、表紙を同じリポジトリに置くことで、次のことができます。

• Issue で企画する
• Pull Request で文章と章構成をレビューする
• 変更履歴を残す
• CI で章をまたぐ不整合を止める
• 公開時点のコミットを特定する

詳しいファイル仕様は、Zenn 公式の CLI ガイドで確認できます。

章ごとではなく、読者が通る経路を確認する

技術記事では、読者が必要な箇所だけ読むこともあります。技術書では、前の章で作った状態を次の章が引き継ぎます。

そのため、章単体では正しくても、通読すると次のような問題が起きます。

• 前の章とファイル名が違う
• 執筆中に API が変わり、古い説明が残る
• 初めて出る用語の説明が後の章にある
• コード断片を組み合わせると動かない
• 第 3 章の小さな誤りが、第 10 章でエラーになる

Pull Request では、変更した章だけでなく、読者が最初から最後まで進む経路への影響を確認します。

Codex へ修正を依頼するときも、「分かりやすく直して」だけではなく、次のように完了条件を渡します。

対象読者:
  製品を知らないが、AWS の基本操作はできる人

読後の状態:
  ローカル環境から AWS 上の演習までを順番に作れる

変更すること:
  第 1 章を前提知識の説明から始める
  簡単な題材から難しい題材へ並べ替える

変更しないこと:
  未実装機能を追加しない
  架空のログや API を書かない

検証:
  make before_commit
  Zenn の PC・モバイルプレビュー

これなら、文章を増やすことではなく、読者の到達点を守ることが作業の基準になります。

原稿の CI/CD とは何か

ソフトウェア開発では、変更のたびにテストを実行する仕組みを CI、利用者へ届ける工程を CD と呼びます。

技術書にも同じ考え方を使えます。

• CI: 原稿を変更するたびに、表記、目次、文字数、図の構文などを自動検査する
• CD: レビュー済みの原稿を Zenn へ同期し、公開する

文章の良し悪きをすべて自動判定するわけではありません。機械が見つけられる失敗を CI へ任せ、人は読者の理解やストーリーに集中します。

私の原稿は、次の流れで公開しています。

企画 Issue
  ↓
原稿用ブランチ
  ↓
本文とサンプルを編集
  ↓
ローカルプレビュー
  ↓
Pull Request
  ↓
GitHub Actions で検査
  ↓
main へ merge
  ↓
Zenn へ同期

機械で確認できる失敗を CI へ移す

原稿リポジトリでは、公開前の共通ゲートとして次のコマンドを実行しています。

make before_commit

現在は、主に次の項目を検査しています。

textlint
  ├─ 日本語技術文書の表記
  ├─ 技術用語のスペル
  └─ 不自然な文章パターン

Zenn Book validation
  ├─ config.yaml の形式
  ├─ 目次に書かれた章が存在するか
  └─ 章の並びに問題がないか

chapter length validation
  └─ 各章が Zenn の文字数上限以内か

Mermaid parser
  └─ 図の構文を Mermaid 本体で解析できるか

GitHub Actions でも、push と Pull Request のたびに同じ項目を検査します。ローカルと GitHub で品質基準を分けないことがポイントです。

検査項目は、最初から完璧にそろえたわけではありません。実際に失敗したら、次の順番で増やしました。

1. 原稿の問題を見つける
2. その場で直す
3. 同じ種類の問題を検出するテストを追加する

たとえば Zig 本では、公開直前に 3 章が Zenn の 1 章あたりの文字数上限を超えていることが分かりました。章を意味の切れ目で分割した後、同じ失敗を繰り返さないよう、文字数検査を CI へ追加しました。

Mermaid 図では、構文エラーと、ダークテーマで読みにくい配色の問題が見つかりました。構文は Mermaid 本体で自動検査し、配色は人がライト・ダークの両方で確認するようにしました。

原稿の CI も、ソフトウェアの回帰テストと同じように、実際の失敗から育てられます。

CI で分からないことは、人がプレビューする

CI が緑でも、読者にとって良い本とは限りません。CI が保証するのは、定義した検査を通ったことだけです。

人は、次の項目を確認します。

• 想定読者に説明していない用語を突然使っていないか
• 前提知識を置きすぎていないか
• 簡単な内容から難しい内容へ進んでいるか
• コードと期待結果の対応が分かるか
• 「現在できること」と「将来やりたいこと」が混ざっていないか
• 費用や削除手順など、安全上必要な説明が先にあるか
• PC とモバイルで読みやすいか
• ライト・ダークテーマで図が読めるか

クラウド競技本の初稿は、構文上は問題がなくても、製品を知っている読者を前提にしていました。また、複数の概念を同時に説明していたため、初見の読者には進む順番が分かりませんでした。

そこで公開直前に、次のように組み直しました。

• 第 1 章を「クラウド競技とは何か」から始める
• 製品名より先に、読者が取り組む問題を説明する
• ローカル環境から始め、簡単な順番で AWS へ進む
• 複雑な題材を捨て、実在する最小問題へ置き換える
• 課金が始まる前に、費用と削除手順を説明する

CI は編集者の代わりではありません。編集者が毎回確認しなくてよい機械的な失敗を引き受ける仕組みです。

下書きで確認してから、公開だけの Pull Request を作る

Zenn Book は、published: falseのまま GitHub から同期できます。公開前に、Zenn 上の実物で次を確認します。

• 表紙、タイトル、紹介文
• 章の順番
• PC とモバイルの表示
• ライト・ダークテーマ
• 図とコードブロック
• 内部リンクと外部リンク

問題がなくなったら、本文修正とは別の Pull Request で公開設定だけを変更します。

-published: false
+published: true

差分を 1 行に分けることで、何を公開する操作なのか、どのコミットが公開版なのかが明確になります。

merge しただけで完了にはしません。公開後に、ログアウトした状態で次を確認します。

• 公開 URL へアクセスできるか
• 表紙と目次が正しいか
• すべての章へ移動できるか
• GitHub 上の公開コミットと内容が一致しているか

Zenn への同期には時間がかかる場合があります。ダッシュボードのデプロイ状態と公開ページの両方を確認します。

2 冊を作って分かったこと

『Zig 言語で学ぶブロックチェイン』は、2025 年 2 月に書き始め、2026 年 7 月に公開できる状態になりました。原稿ディレクトリだけで 128 コミットあり、実装の変更、章の再構成、EVM 章の追加、公開前レビューを重ねた長期の執筆でした。

一方、『自分で作るクラウド競技』は、企画 Issue #270から短期間で作りました。ただし、初稿をそのまま磨いたわけではありません。題材が複雑すぎると判断して Hello World へ変更し、初見読者が簡単な順番で進める構成へ、公開までに 11 本の Pull Request で組み直しました。

期間も題材も異なりますが、必要だった条件は共通していました。

• 読者の出発点と、読了後にできることが明確になっている
• 本文のコード、コマンド、ログが実物と一致している
• 最初から順番に進めれば、同じ結果を再現できる
• 機械で検査できる失敗を CI で止める
• 機械で判断できない読者体験を、人が確認する

本は、長い記事ではありません。順序と状態を持ち、変更すると別の章にも影響するという意味で、もう 1 つのソフトウェアに近いものです。

まとめ

私が技術書を書くときに行っていることは、次のとおりです。

• 読者と、読了後にできることを 1 文で決める
• 動作するコードと検証結果を先に用意する
• 原稿、目次、表紙を GitHub で管理する
• Pull Request ごとに、章をまたぐ影響を確認する
• 実際に起きた失敗を CI の検査へ変える
• 読者の理解や表示は、人がプレビューする
• 公開設定の変更を独立した小さな Pull Request にする
• merge 後は、公開されたページを確認する

1 本の記事では説明しきれないテーマがあれば、まず 3 章の小さな本として設計してみるのがおすすめです。

参考リンク

• 原稿リポジトリ
• Zenn 公式: CLI で記事・本を管理する方法
• Zenn 公式: GitHub リポジトリ連携
• Zig 本の完成 Pull Request #256
• 章ごとに実行可能にした Pull Request #258
• 章の文字数制限を CI 化した Pull Request #261
• クラウド競技本の企画 Issue #270
• Hello World 基準で全面改稿した Pull Request #278
• 初見読者向けに再構成した Pull Request #280
• 公開 Pull Request #284