AI Session Notes - 2026-02-25

Docker マルチステージビルドの仕組み

学んだこと

Dockerfile に FROM を複数書くことでステージを分けられる。各ステージは AS で名前を付ける
docker build . は最後の FROM ステージを最終イメージとして使う。だから本番用ステージを最後に置くのが慣習
docker build --target <name> や docker-compose の target: で任意のステージを指定できる
Docker は指定されたステージとその依存元だけを実行する。無関係なステージは実行されない
COPY --from=<ステージ名> で他ステージの成果物だけを持ってこれる。途中のステージは最終イメージに含まれないため、イメージが軽量になる

詳細

ステージ間の依存関係と実行範囲

base ← dev
base ← deps ← builder ← runner

runner をビルドするとき dev は実行されない。dev をビルドするとき deps/builder/runner は実行されない。「止める」のではなく「ゴールに必要なステージだけ実行する」が正確な表現。

deps ステージを分離する理由（キャッシュ最適化）

Docker は各命令の結果をキャッシュし、入力が変わっていない命令はスキップする。依存定義ファイル（package.json, lock ファイル）だけを先にコピーしてインストールすることで、ソースコード変更時に依存インストールをスキップできる。

# deps ステージ: 依存定義だけコピー
COPY package.json pnpm-lock.yaml ./
RUN pnpm install

# builder ステージ: ソースコードをコピーしてビルド
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN pnpm build

このパターンは Node.js に限らず Go (go.mod/go.sum) や Python (requirements.txt) でも同様に使われる定番パターン。

フレームワーク公式の Dockerfile サンプル

マルチステージビルドで「何をコピーすればいいか」はフレームワークが決めており、公式サンプルが提供されている。ゼロから考える必要はほぼない。Next.js の場合は vercel/next.js の examples/with-docker にサンプルがある。

本番用 docker-compose の要否

学んだこと

Fly.io / Railway / Cloud Run 等のクラウドサービスは Dockerfile だけ渡せばビルド・実行してくれるので、本番用 docker-compose は不要
自前の VPS にデプロイする場合は、docker run のオプションをまとめられるので docker-compose があると便利
開発用と本番用で docker-compose を分けるときは docker-compose.prod.yml のように別ファイルにし、-f オプションで指定する

MkDocs Material で Markdown リポジトリを検索可能なサイトにする

学んだこと

MkDocs Material は Markdown ファイルから全文検索付きの静的 HTML サイトを生成できる
検索はクライアントサイド JavaScript で動作する。ビルド時に全ファイルの検索インデックス（JSON）を事前生成し、ブラウザ側の lunr ライブラリで検索する。サーバーサイドの処理は一切不要
GitHub Actions で mkdocs gh-deploy --force を実行すれば、gh-pages ブランチに自動デプロイされ、GitHub Pages でそのまま公開できる
MkDocs はすべてのコンテンツを docs/ ディレクトリ配下に置く必要がある。シンボリックリンクやルート直接参照は非サポート
日本語検索には jieba パッケージをインストールすると MkDocs Material が自動検出して使用する（中国語向けだが日本語にも応用可能）

詳細

最小構成

必要なファイルは3つだけ：

mkdocs.yml — サイト設定（テーマ、ナビゲーション、検索プラグイン）
requirements.txt — mkdocs-material と jieba
.github/workflows/deploy.yml — push 時に自動ビルド・デプロイ

MkDocs 2.0 と Material の互換性

MkDocs 2.0 は Material for MkDocs と非互換。Material チームは MkDocs 1.x を 2026年11月までサポート予定で、後継として「Zensical」という独自ツールを開発中。現時点では MkDocs 1.x + Material の組み合わせで問題なく使える。

ナレッジベースの検索性を高める手段の比較

学んだこと

Git + Markdown のワークフローをそのまま活かすなら MkDocs や Obsidian が自然な選択肢
Obsidian はローカルアプリのインストールが必要だが、双方向リンクやグラフビューが強力
Notion は検索・データベースビュー・フィルタリングが強力だが、Git/Markdown との二重管理になる
判断基準は「既存ワークフローとの親和性」「検索機能の充実度」「導入コスト」の3軸

GitHub Actions の仕組みと料金

学んだこと

GitHub Actions は「特定のイベント（push 等）をトリガーに、GitHub のサーバー上で処理を自動実行する仕組み」
runs-on: ubuntu-latest は毎回まっさらな Linux VM が用意される。前回の状態は残らないので、依存インストールは毎回やり直す
uses: actions/xxxxx は公開されている再利用可能なアクション（コードの checkout、言語のセットアップ等）。run: は生のシェルコマンド
パブリックリポジトリなら完全無料。プライベートリポジトリでも無料プランで月2,000分の実行時間が付く
ランナーの選択肢は ubuntu / windows / macos の3種。Docker のように Alpine 等の軽量イメージは指定できない。ubuntu が最安（1x）で、windows は 2x、macos は 10x の料金レート

リポジトリ構成変更時の影響範囲チェック

学んだこと

ディレクトリ構成を変更したとき、リポジトリ内のファイル（README、設定ファイル）だけでなく、外部リポジトリにあるスキルやコマンド定義のパス参照も更新が必要
grep で旧パスを横断検索して影響範囲を洗い出すのが確実
シンボリックリンクで別リポジトリの設定を参照している場合、そちら側のコミット・プッシュも忘れずに行う

メタ情報

ツール: Claude Code
関連技術: Docker, Dockerfile, マルチステージビルド, Docker Compose, キャッシュ最適化, デプロイ, MkDocs, Material for MkDocs, GitHub Pages, GitHub Actions, 静的サイト生成, 全文検索