個人ブログの運営やWeb開発において、「日常のメモやアイデア出し、手順書はObsidianを使ってスマホ・PC間で手軽に同期したい。しかし、WebサイトのビルドやCLIスクリプト、AIによる自動化は本格的なローカル環境で動かしたい」という要望は非常に多くあります。
しかし、この2つを素朴に両立させようとすると、フォルダのルートが分断されたり、同期トラブルが発生したりと、さまざまな壁に突き当たります。
この記事では、MacとWindowsの両対応を見据えながら、「Obsidian（iCloud同期）」と「Web開発（ローカル環境）」を最も美しく、破綻なく共存させるためのアーキテクチャと構築手順 をまとめます。
※本記事では、Google Antigravity、Gemini CLI、Claude Code、Cursorなど、プロジェクト直下の指示書（GEMINI.md や CLAUDE.md）やスキル定義（.agents/skills/）を自律的に読み込んで作業する最新のAIコーディングエージェント環境を前提としています。
1. 抱えていた課題とジレンマ#
なぜ開発ファイルをiCloudに置いてはいけないのか？#
「スマホでもコードや設定を見たいから」と、Web開発のリポジトリ（Hugo、Node.js、Wranglerなど）ごとiCloud Driveに置くのは、エンジニア界隈では最大のタブー（アンチパターン） とされています。
開発ファイルをiCloudに置いたときに起きる3大事故
node_modulesの同期地獄: 数万個の微小なJSファイルをiCloudが1つずつクラウドへ同期しようとし、MacのCPUとメモリが100%に張り付き、ファンが爆音で回り続けます。- ビルド時のファイルロックとクラッシュ:
hugo serverなどのローカルプレビュー中、ファイル生成とiCloudの同期ロックが衝突し、「Permission denied」などのエラーでプレビューが頻繁に落ちます。 - ストレージ最適化によるファイル消失: OSの空き容量確保機能によって、ソースコードや画像が勝手にクラウド退避（雲マーク）され、ビルド時に「ファイルが見つかりません」と失敗します。
👉 鉄則：開発系は絶対に「ローカル環境（~/Sites）」、メモや手順書は「iCloud」に物理的に分ける必要があります。
ルートが分断されると、CLI自動化やAIへの指示が困難になる#
しかし、開発系（~/Sites/site-a.com）と手順書（~/Library/.../blog）でフォルダのルートが完全に分かれると、次の問題が生じます：
- スクリプト内で長いiCloudパスを扱うことになり、環境依存やパス解決エラーが多発する。
- AIエージェントに「手順書に従って記事を書いて」と指示するとき、フォルダを跨ぐオーバーヘッドが発生する。
- 別のMacやWindowsマシンへ移行したときに、パス構造が崩れてスクリプトが動かなくなる。
2. 【重要】iCloudでのGit管理：.git をローカルに完全分離するテクニック#
ObsidianのVaultをiCloudで管理しつつ、バージョン管理のためにGitを使いたい場合、もうひとつの大きな罠があります。
iCloud内に .git を置くとリポジトリが破損する#
.git ディレクトリの中には、数千〜数万個のコミットオブジェクトやインデックスファイルが存在します。
これをiCloud Driveがバックグラウンドで非同期同期すると、Gitが書き込みを行っている最中にiCloudがファイルを同期・ロックしてしまい、.git の内部データが破損する（Corrupted repository） 事故が多発します。
解決策：Gitのメタデータ（.git）だけをローカルに分離する#
この問題は、Git標準の gitdir 参照機能 を使って、.git ディレクトリの実体をiCloudの外（ローカル専用ディレクトリ）へ逃がすことで完全に防げます。
【ローカル非同期領域】
~/.git-roots/blog-vault.git/ ← ★実際の .git（巨大な履歴データ）をここに置く！
【iCloud Drive】
~/Library/.../Documents/blog/
├── .git ← ★たった1行「gitdir: ...」と書かれたテキストファイル
├── 01_構成方針.md
└── drafts/設定手順（既存のVaultで .git を分離する）#
# 1. ローカル専用のGit退避フォルダを作成
mkdir -p "$HOME/.git-roots"
# 2. iCloud内の .git ディレクトリをローカルへ移動
mv "$HOME/Library/Mobile Documents/iCloud~md~obsidian/Documents/blog/.git" \
"$HOME/.git-roots/blog-vault.git"
# 3. iCloud側のVault直下に、ローカルの .git を指すポインタファイルを作成
echo "gitdir: $HOME/.git-roots/blog-vault.git" > \
"$HOME/Library/Mobile Documents/iCloud~md~obsidian/Documents/blog/.git"これにより、iCloud上には たった1行のテキストファイル（.git） しか同期されないため、同期遅延やファイル競合、Gitリポジトリの破損リスクが100%消滅します。日常の git status や git commit は今まで通り全く同じように実行できます。
MacとWindowsを両用する場合のワンポイント注意
なお、MacとWindowsの両方で同じiCloud Vaultを開いて作業する場合、.git に書き込まれるパスがOS固有の絶対パス（Mac: /Users/...、Windows: C:\Users\...）になるため、Gitコミットを行うメインPC（例: Mac）での運用を想定しています。もしWindows側でもGit操作を行いたい場合は、端末ごとにローカルパスを合わせる等の工夫が必要です。
3. 検討した手法とプロコン比較#
フォルダのルート分断問題を解消するために検討した選択肢の比較です。
| 選択肢 | メリット | デメリット・落とし穴 | 判定 |
|---|---|---|---|
| ① Gitサブモジュール | リポジトリ内に手順書が物理的に配置される | ・Privateリポジトリの場合、Cloudflare等のCI/CDデプロイで認証エラーになる ・メモを直すたびに親・子の二重コミットが必要 ・コミット巻き戻り（先祖返り）事故が多発 | ❌ 非推奨 |
| ② シンボリックリンク直貼り | Mac上で手軽に繋げる | ・Windowsでは管理者権限や「開発者モード」が必要になり、標準の環境でトラブルになりやすい | 🔺 要注意 |
| ③ 完全な並列配置（ローカル） | 相対パス ../blog-vault で綺麗に繋がる | ・ObsidianのiCloud同期が使えなくなる（スマホ閲覧を諦める必要あり） | 🔺 スマホ同期不可 |
| ④ 親フォルダへのリンク＋擬似並列 | iCloud同期を維持しつつ、全サイトから相対パスで統一可能 | ・親フォルダに1回だけリンク（ジャンクション）を作る作業が必要 | ⭕️ 最適解 |
4. 最適解：「親フォルダにリンクを1本置く」擬似並列アーキテクチャ#
すべての課題をクリアした結論が、「開発親フォルダ（~/Sites）の中に、iCloudへのリンク（ジャンクション）を1本だけ生やす」 という手法です。
全体アーキテクチャ図#
【iCloud Drive】
~/Library/.../Documents/blog/ ← [実体] スマホ・iPadと手軽に同期！
│ ├── .git (gitdirポインタ)
│ ├── drafts/ ← スマホから書く記事アイデア・下書き
│ └── 04_ブログ運営手順.md
│
│ (リンク・ジャンクション)
▼
【ローカル開発環境】
~/Sites/ (Windowsなら C:\Sites\)
├── blog-vault/ ← ★iCloud実体へのショートカット
│ └── .agents/ ← ★AIの共通頭脳（スキル・ルール）
│ └── skills/blowfish/
│
├── site-a.com/ ← WebサイトA（Hugo + Blowfish）
│ ├── .agents -> ../blog-vault/.agents (共通AIをリンク)
│ ├── content/posts/ ← 本番記事（Page Bundle形式）
│ └── GEMINI.md ← サイト個別設定
│
└── site-b.com/ ← 将来のWebサイトB
└── .agents -> ../blog-vault/.agentsなぜこの構成が優れているのか？#
- iCloud同期を一切犠牲にしない: 実体はiCloudにあるため、外出先からスマホで手順書や下書きを閲覧・編集できます。
- すべてのサイトから「相対パス（
../blog-vault）」で統一: どのブログサイトからも、真横を見るだけで共通ナレッジに届きます。 - AIの共通頭脳（
.agents）を一元管理: PC全体（Global）を汚さず、~/Sites配下のブログだけで「Blowfishスキル」や「執筆ルール」を共有できます。 - MacとWindowsで100%同じ構造を再現可能: Macは
ln -s、Windowsはmklink /Jを1回打つだけで全く同じ世界が作れます。
5. 【読者の疑問を解消】実際の記事執筆フローはどう回すのか？#
「思考や下書きはObsidianで、実際の記事コードはローカルの content/posts/ にあるなら、日常の執筆フローはどうなるのか？」という疑問に対する、実際の運用シナリオです。
flowchart LR
A["① スマホ/PCのObsidian
(iCloud: drafts/)
アイデア・箇条書き下書き"] --> B["② PCローカル
(~/Sites/site-a.com)
AIエージェントに清書指示"]
B --> C["③ Hugo Page Bundle
(content/posts/slug/)
自動生成・整形"]
C --> D["④ ローカルプレビュー
hugo server -D
ブラウザ確認"]
D --> E["⑤ git push
Cloudflare自動デプロイ"]
日常の3ステップ#
- 出先・スマホで下書き（Obsidian）:
blog-vault/drafts/new-idea.mdに、思いついた構成案やメモを箇条書きでラフに書きます。iCloud経由でPCへ即座に同期されます。
- PCでAIエージェントに指示（ローカル開発環境）:
- PCのターミナルで
cd ~/Sites/site-a.comに入り、AIにこう指示します：
「
../blog-vault/drafts/new-idea.mdの下書きを元に、../blog-vault/04_ブログ運営手順.mdのルールに従って、Blowfish形式でcontent/posts/my-slug/index.mdに清書して配置して」 - PCのターミナルで
- AIが記事化 → プレビュー確認して公開:
- AIがフロントマター（タイトル、タグ、カテゴリ、slug）を整え、適切なショートコードを配置してくれます。
- 手元で
hugo server -Dで確認し、アイキャッチ画像を配置してgit pushすれば公開完了です。
下書きをHugoの複雑なPage Bundle構造で直接書く必要がなく、Obsidianの身軽さと静的サイトジェネレーターの堅牢性を両立できます。
6. 【完全作業手順書】環境構築ステップ#
実際の環境構築や、別PCへの移行時にそのまま使える手順です。
ステップ1：開発親フォルダの準備とリンク作成#
【Macの場合】#
# 1. 親フォルダが存在しない場合は作成
mkdir -p ~/Sites
# 2. iCloudへのシンボリックリンクを作成
ln -s "$HOME/Library/Mobile Documents/iCloud~md~obsidian/Documents/blog" ~/Sites/blog-vault【Windowsの場合】#
コマンドプロンプト（cmd）を起動して実行します（ジャンクション mklink /J は管理者権限不要です）：
:: 1. 親フォルダを作成
mkdir C:\Sites
:: 2. iCloudへのジャンクションを作成（※絶対パスで指定）
mklink /J "C:\Sites\blog-vault" "%USERPROFILE%\iCloudDrive\iCloud~md~obsidian\Documents\blog"Windows版iCloudの注意点
- フォルダ名の揺れ: Microsoft Store版などの環境により、パスが
%USERPROFILE%\iCloud Drive\...（半角スペース入り）になる場合があります。エクスプローラーのアドレスバーで実際のパスを確認してください。 - オフラインエラー（0x8007016A）対策: エクスプローラーで
blogフォルダを右クリックし、「常にこのデバイスに保持する」を選択してください。未ダウンロード状態のファイルがあると、CLIから読み込んだ際にエラーになります。
ステップ2：共通VaultにAIスキル・ルールを集約する#
blog-vault の中に、全サイト共通で使うAI設定フォルダ（.agents）を用意します。
# blog-vault 内に .agents/skills を作成
mkdir -p ~/Sites/blog-vault/.agents/skills
# テーマ同梱のAIスキル（例: Blowfish）を共通置き場へコピー
cp -r ~/Sites/site-a.com/themes/blowfish/.claude/skills/blowfish ~/Sites/blog-vault/.agents/skills/ステップ3：各Webサイトから .agents をリンクする#
各ブログサイトから、共通のAI頭脳へリンクを繋ぎます。
【Macの場合】#
cd ~/Sites/site-a.com
# 共通 .agents へのリンクを作成
ln -s ../blog-vault/.agents .agents
# リンクをGitで追跡しないよう .gitignore に追加
echo ".agents" >> .gitignore【Windowsの場合】#
cd C:\Sites\site-a.com
:: ※mklink /J は相対パス不可のため、絶対パスで指定します
mklink /J "C:\Sites\site-a.com\.agents" "C:\Sites\blog-vault\.agents"
:: .gitignore に追加
echo .agents >> .gitignoreステップ4：サイト固有設定とルール参照（GEMINI.md）#
各サイトのルート（~/Sites/site-a.com/GEMINI.md）に、共通ナレッジへの参照と個別設定を記載します：
# site-a.com プロジェクト設定
## 共通ルール参照
記事執筆やサイト運用のルールは、以下の共通ナレッジを参照すること：
- 運営・執筆手順: ../blog-vault/04_ブログ運営手順.md
- 構成方針: ../blog-vault/01_ブログ構成方針.md
## このサイト固有の設定
- 公開ドメイン: https://site-a.com
- Cloudflare Worker名: site-a-com
- メインカテゴリ: AI活用, デジタルツール7. まとめ#
- 「Web開発＝ローカル＋GitHub」「思考・手順書＝iCloud＋Obsidian」 と割り切り、開発親フォルダにリンクを1本置くことで、両者のいいとこ取りが実現できます。
- iCloudでのGit運用は、
.gitをローカルへ分離退避する ことでリポジトリ破損を完全に回避できます。 - サブモジュールや複雑な同期ツールに頼らず、「並列配置＋相対パス」 を採用することで、GitのトラブルやCI/CDの認証地獄から解放されます。
.agents/フォルダごとリンクすることで、複数サイト展開時もAIスキル・ルールを1箇所でメンテナンスできます。
日常の作業時は、常に cd ~/Sites/site-a.com に入って作業するだけ。
これで、MacでもWindowsでも、CLI自動化でもAIペアプログラミングでも、迷いなく高速にブログ運営を回せる最強の基盤が整います。
