Tech Notebook のシステム構成と自動化の仕組み

本プロジェクト「Tech Notebook」は、AI（Gemini）を活用して開発プロセスにおける疑問や調査結果を自動的にドキュメント化する技術ノートシステムです。本システムは、ローカル開発環境から直接指示を出す「Antigravity（AIアシスタント）ルート」と、スマートフォンなど外出先から手軽に起票できる「GitHub Issues（サーバーレス）ルート」の2つのワークフローで運用されており、いつでもシームレスに記事を追加・公開できます。

1. 2つの投稿ルートと全体フロー

Tech Notebookは、状況に合わせて使い分けられる2つの投稿ルートを用意しています。

【1. チャット（Antigravity）ルート (PCローカル)】
[開発チャット] 「〇〇について調べて」と指示 ➔ [Antigravity] 調査、HTMLファイル生成 ➔ 自動コミット・プッシュ

【2. GitHub Issuesルート (スマホ/外出先)】
[スマートフォン] GitHubのIssueを作成（タイトルに調査テーマ）
  ↓
[GitHub Actions] 許可された起票ユーザーを検知してワークフロー起動
  ↓
[generate-article.js] Gemini 3.5 Flash APIを呼び出し、構造化された記事データを取得
  ↓
[generate-article.js] HTMLファイル生成、index.json更新、sitemap.xml更新
  ↓
[GitHub Actions] 自動コミット＆プッシュ、Issueに完了コメントを追加して自動クローズ
  ↓
[GitHub Actions] サイトデプロイ（GitHub Pages）➔ 記事が公開される

2. AIコーディングアシスタント「Antigravity」によるローカル自動化

PCで作業している際は、AIコーディングアシスタント「Antigravity」を活用して技術調査と記事のパブリッシュを自動化できます。開発チャットで指示を出すだけで、Antigravityは以下のタスクを自律的に完了させます。

技術調査の実施: Web検索や関連ドキュメントの参照により、信頼性の高い情報を収集します。
HTMLファイルの生成: 定義された共通テンプレート（template.html）を基に、意味の通ったセマンティックなHTML構造の記事ファイルを作成します。
インデックス登録: 記事一覧データベースである index.json に新規記事のメタデータ（タイトル、概要、カテゴリ、日付）を追記します。
コミットとプッシュ: Gitのステージング、コミットメッセージ作成、リモートリポジトリへのプッシュを代行します。

3. 外出先からの投稿を実現する GitHub Issues ルート

開発PCが手元にない外出先やスマートフォンからでも、GitHubのIssueを作成することで自動的に記事を追加できます。GitHub ActionsとGemini API（`gemini-3.5-flash` モデル）がバックエンドで連携し、サーバーレス環境で動作します。

安全な実行制限: スパムや無駄なAPI呼び出しを防ぐため、特定の許可されたGitHubアカウントからの起票のみを処理対象とするトリガー制限を設けています。
自動パブリッシュパイプライン: Actionsが完了すると自動的にIssueへ完了コメントが書き込まれてクローズされ、デプロイ用ワークフローが連携して数分でサイトが更新されます。

4. 競合（コンフリクト）の自動回避

ローカル（Antigravity）とリモート（GitHub Issues）の2つのルートから非同期に記事が追加されるため、データの競合を防止する仕組みを設けています。Antigravityがローカルで作業を開始する直前に、必ず自動で git pull を実行してリモートの変更を取得する運用ルールをAIに設定しています。これにより、Gitコンフリクトを回避してシームレスに記事を追加し続けることができます。

5. 静的サイトにおける技術的工夫とUX設計

静的サイトとしてのパフォーマンスを極限まで保ちながら、SEO効果を高め、快適な表示速度を両立するための様々な仕組みが導入されています。

① クライアントサイドでの動的カード描画 (main.js)

ポータル（トップページ）は、静的なHTMLを毎回AIが修正するのではなく、記事全体のメタデータを管理する notes/index.json を非同期フェッチ（fetch）し、カード要素を動的に構築します。これにより、デザインの変更や記事データの管理が完全に分離され、リポジトリが破綻しません。

② 「もっと見る」ボタン（ページネーション機能）

記事数が多くなった際にページ読み込みが重くならないよう、1ページあたり初期表示を 12件 に制限しています。フィルタリングや検索が行われた際にも動的に計算され、制限を超える記事がある場合のみ「もっと見る」ボタンがアニメーション表示されます。ボタンを押すと12件ずつ段階的にフェードイン描画されます。

③ キャッシュバスター（二重キャッシュの完全回避）

静的ホスティングであるGitHub Pages特有の強力なブラウザキャッシュ対策として、以下の仕組みを組み込んでいます。

データキャッシュ回避: index.json をフェッチする際に、末尾にタイムスタンプ（?t=Date.now()）をクエリパラメータとして動的付与。
プログラムキャッシュ回避: index.html から main.js や site.css をロードする際に、バージョン（?v=1.0.1）を付与し、新しいロジック（キャッシュバスター処理）がブラウザで即座に動作するように強制更新します。

④ 収益化に向けた高度なSEO対策

構造化データ (JSON-LD) の埋め込み: 検索エンジン（Google等）が記事構造をより深く解釈できるよう、各HTMLの <head> 内に `TechArticle` スキーマ を動的に自動埋め込みしています（投稿日、更新日、著者名 hondasan などがマークアップされます）。
クローラー最適化: 検索エンジンのクローラーを適切に誘導する robots.txt および sitemap.xml を配備し、新しい記事が追加されるたびにAIが自動でXMLサイトマップにURLブロックを追記するフローを構築しています。

6. まとめ

本システムは、最新のAIモデル（Gemini 3.5 Flash）とGitHubの自動化パイプライン（Actions）を組み合わせることで、「疑問の発生」から「学習成果のパブリッシュ」までの時間と手間を限りなくゼロに近づけた、究極の個人向けナレッジ蓄積ツールです。