Obsidian（iCloud）とWeb開発（ローカル）を美しく共存させる！Mac・Windows両対応のブログ運用・AI開発環境の構築法

個人ブログの運営やWeb開発において、「日常のメモやアイデア出し、ブログの運営手順書や開発ルールはObsidianにまとめ、スマホ・タブレット・PC間で手軽に同期したい」と考える方は多いはずです。これを最も手軽に、かつ無料で実現できるのが iCloud Drive によるVault同期です。

しかし、いざWebサイトのビルドやCLIスクリプト、AIによる開発自動化を本格的に動かそうとすると、「開発系のファイルはローカルに置かなければならない」 という絶対の制約にぶつかります。

その結果、「iCloudにあるルールや思考メモ」と「ローカルにある開発ファイル」で物理的な位置が完全にズレてしまい、開発の設計やパス解決、AIエージェントへの指示が途端に大変になる というジレンマが発生します。

この位置ズレを解消する運用手段はいくつか存在しますが、それぞれ一長一短があります。この記事では、検討したアプローチを比較・整理した上で、MacとWindowsの両対応を見据えた「最も美しく破綻しない共存アーキテクチャと構築手順」 をまとめました。

※本記事では、Google Antigravity、Gemini CLI、Claude Code、Cursorなど、プロジェクト直下の指示書（AGENTS.md や GEMINI.md、CLAUDE.md）やスキル定義（.agents/skills/）を自律的に読み込んで作業する最新のAIコーディングエージェント環境を前提としています。

1. 抱えていたジレンマ：iCloudとローカルの「位置ズレ」問題

#

やりたかったこと：Obsidianに思考と開発ルールを集約したい

#

思考メモやブログの下書きはもちろん、「ブログの執筆ルール」「運営手順」「AIへの指示スキル（.agents）」 もすべてObsidianのVault（blog）に一元管理したいと考えました。実体がiCloud Drive上にあれば、出先のiPhoneから手順書を手軽に見返したり、下書きを書き留めたりできるからです。

直面した壁：開発ファイルは絶対にiCloudに置いてはいけない

#

一方、HugoやNode.js、WranglerなどのWeb開発リポジトリは、「絶対にiCloudに置いてはいけない（ローカルに置くべき）」 というのがエンジニア界隈の鉄則です。

👉 結論：開発系は絶対に「ローカル環境（~/Sites）」、メモやルールは「iCloud」に物理的に分ける必要があります。

結果として生じる「位置ズレ」問題

#

しかし、開発系（~/Sites/site-a.com）と手順書・ルール（~/Library/.../blog）でフォルダのルートが完全に分かれてしまうと、次のような問題が噴出します：

• スクリプト内で長いiCloudの絶対パスを扱うことになり、環境依存やパス解決エラーが多発する。
• AIエージェントに「手順書に従って記事を書いて」と指示するとき、フォルダを跨ぐオーバーヘッドが発生する。
• MacとWindowsでiCloudの保存場所が全く異なるため、別のマシンへ移行したときにパス構造が崩れて動かなくなる。

2. 検討した解決策とプロコン（一長一短）

#

この「位置ズレ」を埋めて両者をスムーズに連携させるために、いくつかの運用手法を検討しました。しかし、それぞれに一長一短（メリットと落とし穴）が存在します。

それぞれの課題を検証した結果、たどり着いたのが ④の「親フォルダにリンクを1本置く」擬似並列アーキテクチャ です。

3. 最適解：「親フォルダにリンクを1本置く」擬似並列アーキテクチャ

#

すべての課題をクリアした構造がこちらです。 「開発親フォルダ（~/Sites）の中に、iCloudへのリンク（ジャンクション）を1本だけ生やす」 ことで、実体はiCloudに置いたまま、ローカルからは完全に並列なフォルダとして見せかけます。

全体アーキテクチャ図

#

【iCloud Drive】
~/Library/.../Documents/blog/      ← [実体] スマホ・iPadと手軽に同期！
        │   ├── drafts/            ← スマホから書く記事アイデア・下書き
        │   ├── AGENTS.md
        │   └── guides/
        │       └── 03_ブログ運営手順.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形式）
│   └── AGENTS.md                  ← サイト個別設定・AI指示書
│
└── site-b.com/                    ← 将来のWebサイトB
    └── .agents -> ../blog-vault/.agents

なぜこの構成が優れているのか？

#

1. iCloud同期を一切犠牲にしない: 実体はiCloudにあるため、外出先からスマホで手順書や下書きを閲覧・編集できます。
2. すべてのサイトから「相対パス（../blog-vault）」で統一: どのブログサイトからも、真横を見るだけで共通ルールに届きます。
3. AIの共通頭脳（.agents）を一元管理: PC全体（Global）を汚さず、~/Sites 配下のブログだけで「Blowfishスキル」や「執筆ルール」を共有できます。
4. MacとWindowsで100%同じ構造を再現可能: Macは ln -s、Windowsは mklink /J を1回打つだけで全く同じ世界が作れます。

4. 日常の執筆・運用フロー（Obsidian × ローカル開発 × AI）

#

「位置ズレ」を解消したことで、日常の執筆フローは驚くほどシンプルになります。

flowchart LR
    A["① スマホ/PCのObsidian
(iCloud: drafts/)
アイデア・箇条書き下書き"] --> B["② PCローカル
(~/Sites/site-a.com)
AIエージェントに清書指示"]
    B --> C["③ Hugo Page Bundle
(content/posts/slug/)
自動生成・整形"]
    C --> D["④ ローカル確認
npm run dev
ブラウザで表示確認"]
    D --> E["⑤ 本番ビルド検証
npm run build
エラー・下書き残存防止"]
    E --> F["⑥ git push
Cloudflare自動デプロイ"]

日常の3ステップ

#

1. 出先・スマホで下書き（Obsidian）:
   • blog-vault/drafts/new-idea.md に、思いついた構成案やメモを箇条書きでラフに書きます。iCloud経由でPCへ即座に同期されます。
2. PCでAIエージェントに指示（ローカル開発環境）:
   • PCのターミナルで cd ~/Sites/site-a.com に入り、AIにこう指示します：

   「../blog-vault/drafts/new-idea.md の下書きを元に、../blog-vault/AGENTS.md の参照ルールに従って、Blowfish形式で content/posts/my-slug/index.md に清書して配置して」

3. AIが記事化 → プレビュー確認して公開:
   • AIがフロントマター（タイトル、タグ、カテゴリ、slug）を整え、適切なショートコードを配置してくれます。
   • 手元で npm run dev（内部で hugo server を起動）で確認し、アイキャッチ画像を配置します。公開前には npm run build で本番ビルドを検証し、下書き残存ファイルやエラーがないことを確認してから git push すれば安全に公開完了です。

下書きをHugoの複雑なPage Bundle構造で直接書く必要がなく、Obsidianの身軽さと静的サイトジェネレーターの堅牢性を両立できます。

5. 【完全作業手順書】ゼロから作る環境構築ステップ

#

実際の環境構築や、別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"

ステップ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：サイト固有設定とルール参照（AGENTS.md）

#

各サイトのルート（~/Sites/site-a.com/AGENTS.md）に、共通ナレッジへの参照と個別設定、AIが安全に動くためのガードレールを記載します（※利用するAIツールに応じて GEMINI.md や CLAUDE.md としても同様に機能します）：

# site-a.com AIエージェント指示書

## 資料の参照順序
1. `../blog-vault/AGENTS.md` の「AIが資料を読む順序」を参照の正本とし、作業に応じて該当手順を確認する。全資料を一括で読み込まない。
2. 過去のレビュー履歴や完了判定を、現在の作業指示として直接適用しない。

## 状態確認ファースト（二重適用防止）
- 指示された内容が既に反映されているかを必ず最初に確認し、反映済みであれば重複して再実行しない。

## ガードレール（絶対変更禁止事項）
- テーマ本体（`themes/blowfish/`）を直接編集しない（サイト側でオーバーライドする）。
- 既存記事のファイル名・画像名・slugを一括置換・リネームしない。
- `package.json` のビルドスクリプトから `--cleanDestinationDir` を外さない。

## このサイト固有の設定
- 公開ドメイン: https://site-a.com
- Cloudflare Worker名: site-a-com
- メインカテゴリ: AI活用, デジタルツール, ブログ運営

6. 【おまけ】iCloud内のVaultをGit（GitHub）で無料バックアップする小技

#

最後に、ちょっとした発展テクニックとしてのオマケです。

なぜiCloud管理なのにGitを使うのか？（同期 vs バックアップ）

#

ObsidianのVaultをiCloudで運用していると、「同期はしてくれるけれど、誤って重要なメモを上書き・削除してしまったときの過去履歴バックアップがない」 という不安が残ります。

そこで、無料かつ最も堅牢なバックアップ手段の1つとしてGit（GitHubのプライベートリポジトリ）を併用する のがおすすめです。

• 端末間のリアルタイム同期: iCloud Drive に任せる（スマホ・PC間で手軽に同期）
• 念のための過去履歴・誤削除バックアップ: Git に任せる（GitHub等へ定期保存）

落とし穴：iCloud内に .git を置くとリポジトリが破損する

#

ただし、Vault直下でそのまま git init してはいけません。 .git ディレクトリ内にある数千〜数万個の細かなGitオブジェクトをiCloudが同期しようとすると、同期ロックが衝突して Gitリポジトリが破損する（Corrupted repository） 事故が多発します。

解決策：.git（履歴実体）だけをローカル非同期領域に逃がす

#

この問題は、Git標準の gitdir 参照機能 を使い、履歴実体だけをiCloudの外へ退避させることで完全に防げます。

【ローカル非同期領域】
~/.git-roots/blog-vault.git/      ← ★実際の .git（巨大な履歴データ）をここに置く！

【iCloud Drive】
~/Library/.../Documents/blog/
├── .git                          ← ★たった1行「gitdir: ...」と書かれたテキストファイル
├── AGENTS.md
└── drafts/

設定手順（Macの場合）

#

# 1. ローカル専用のGit退避フォルダを作成
mkdir -p "$HOME/.git-roots"

# 2. 既存の .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） しか同期されないため、同期遅延やリポジトリ破損のリスクがゼロになります。

7. まとめ

#

• 「Web開発＝ローカル＋GitHub」「思考・ルール＝iCloud＋Obsidian」 と割り切り、開発親フォルダにリンクを1本置くことで、両者のいいとこ取りが実現できます。
• 物理的な「位置ズレ」を解消することで、すべてのサイトから 「相対パス（../blog-vault）」 で共通ルールや下書きを参照できるようになります。
• AI設定フォルダ（.agents/）を共通化することで、複数サイト展開時もAIスキルや執筆ルールを1箇所でメンテナンスできます。
• ObsidianのバックアップにGitを使う場合は、.git をローカルへ逃がし、メイン機1台でバックアップ用として割り切る ことで、破損やコンフリクトを回避できます。

日常の作業時は、常に cd ~/Sites/site-a.com に入って作業するだけ。 これで、MacでもWindowsでも、CLI自動化でもAIペアプログラミングでも、迷いなく高速にブログ運営を回せる最強の基盤が整います。