GitHubオーガニゼーションを模したローカルディレクトリ構造管理術：AI時代の開発環境
きっかけは「またパスがわからなくなった」
「あのリポジトリ、どこに clone したっけ？」
個人開発を続けていると、この問いかけに何度も悩まされました。/workspace/dev/ だったか、/workspace/projects/ だったか、はたまた /workspace/documents/work/ だったか。
特に痛感したのは、AI ツールを使い始めてからです。Claude Code に「さっき編集したファイル、もう一度開いて」と頼んでも、「パスがわかりません」と返される。仕方なく find ~ -name "repo-name" を打つのですが、候補が3つも出てきて「どれだっけ...」となる。VS Code の履歴を漁っても、似たような名前のリポジトリが並んでいて判別できない。
「あれ、このリポジトリ、Mac の方に clone したんだっけ？ Windows の方だっけ？」という状況も頻発しました。複数マシンを使っていると、マシンごとにディレクトリ構造がバラバラになっていて、毎回「このマシンでは /workspace/dev/、あっちのマシンでは /workspace/projects/」と頭の中で切り替える必要がありました。
正直、自分の記憶力のなさにうんざりしていました。
そこで試してみたのが、GitHub のオーガニゼーション構造をそのままローカルに持ち込む方法です。「どうせ GitHub と同じ構造にすれば迷わないだろう」という単純な発想でした。
基本的な考え方
GitHub では、リポジトリを「オーガニゼーション」という単位でグループ化できます。この構造をそのままローカルにも持ち込んでみようと考えました。
例えば、GitHub 上で https://github.com/your-org/your-repo というリポジトリがあるなら、ローカルでも /workspace/your-org/your-repo のように配置する、という具合です。
URL構造とパス構造を一致させておけば、「このリポジトリはどこにあるか」を考える必要がなくなります。GitHub の URL を見れば、ローカルのパスがすぐわかる。
なぜURL構造とパス構造を一致させるのか
実は、Git のリモートURL（https://github.com/your-org/your-repo）とローカルパス（/workspace/your-org/your-repo）を対応させると、いくつかの副次的な利点があります。
まず、git clone の際にディレクトリを指定し忘れても、オーガニゼーション単位で配置されるため「どこに置いたっけ？」が起きません。cd /workspace/your-org/ してから git clone すれば、自然と正しい場所に配置されます。
次に、複数マシン間でパス構造が統一されるため、スクリプトやドキュメントで相対パス（../another-repo）を書いても、どのマシンでも同じように動きます。
そして、AI ツールがリポジトリの関連性を推測しやすくなります。同一オーガニゼーション内のリポジトリは物理的に近い場所に配置されるため、AI が「この設定ファイルは隣のリポジトリにあるかも」と推論しやすくなるのです。
単純ですが、これが思いのほか効果的でした。
この構造にして変わったこと
AIツールが関連ドキュメントを見つけてくれるようになった
Claude Code などの AI ツールは、現在開いているディレクトリをコンテキストとして読み込みます。プロジェクトが巨大すぎるとトークンを浪費し、小さすぎると関連ドキュメントにアクセスできません。
オーガニゼーション単位でディレクトリを分けておくと、AI が余計なファイル（別のプロジェクトのソース等）を読まずに済みます。同一オーガニゼーション内の共通ドキュメントは自然と参照してくれるようになりました。
以前は「このドキュメント読んでほしいんだけど」と明示的に指示しないと見つけてくれなかったのが、今では勝手に見つけて参照してくれます。地味に嬉しい変化でした。
相対パスで迷わなくなった
../another-repo のような参照が、どのマシン（Mac/Windows）でも同じ構造になります。特に「ドキュメント専用リポジトリ」と「コードリポジトリ」を分けている場合、パスの解決が楽になりました。
以前は「あれ、このマシンでは ../docs でいいんだっけ？」と毎回確認していたのが、今ではパスを見ればすぐわかります。
誤操作が減った
git commit -a や rm -rf 等の操作をする際、パスを見れば「今どのオーガニゼーションのどのプロジェクトにいるか」が明示されます。
以前は誤って別のプロジェクトで git commit してしまい、コミット履歴を汚したことがありました。今ではパスを見れば一目瞭然なので、そういうミスが激減しました。
移行のハマりポイント
既存のディレクトリから移行する際、私が実際にハマった点を共有します。
絶対パスが壊れて冷や汗をかいた話
移行を始めた初日、いきなり問題が発生しました。
古いプロジェクトの設定ファイルに /workspace/dev/my-project/data/config.json のような絶対パスがハードコードされていたのです。ディレクトリを移動した瞬間、アプリケーションが「ファイルが見つかりません」とエラーを吐き始めました。
「これ、本番環境のスクリプトでも同じパス使ってる…」と気づいた時の焦りは今でも覚えています。
これを機に、パスは環境変数（$PROJECT_ROOT 等）で管理するように改めました。
シンボリックリンクで凌いだ泥臭い対応
とはいえ、すべての絶対パスを一度に直すのは現実的ではありませんでした。依存関係が複雑に絡み合っていて、どこを直せば何が壊れるかわからない状態。
「全部直してから動作確認しよう」という選択肢もありました。でも、それは怖い。もし直し漏れがあったら、どこが原因かわからなくなる。かといって、旧パスのまま放置するのも気持ち悪い。
そこで使ったのがシンボリックリンクです。
# 旧パスから新パスへのシンボリックリンクを作成
ln -s /workspace/your-org/your-repo /workspace/old-location/your-repo
「動くならヨシ」の精神で、旧パスへのアクセスを新パスに転送するリンクを張りまくりました。これなら、旧パスを参照しているコードがあっても、とりあえず動く。動作確認しながら、少しずつ絶対パスを修正していけばいい。
正直、美しい解決策ではありません。エレガントなリファクタリングを期待していた人には申し訳ない。でも、この泥臭いやり方のおかげで「一度に全部直す」というリスクを避けながら、徐々に移行を進められました。今でも数本のシンボリックリンクが残っていますが、動いているので見て見ぬふりをしています。
.gitignore はリポジトリ単位が無難
オーガニゼーション層に共通の .gitignore を置けば便利だろうと考えた時期がありました。結論から言うと、やめておいた方がいいです。
理由は単純で、Git はオーガニゼーション層の .gitignore を認識しないから。リポジトリごとに設定が必要になり、中途半端に共通化しようとした分だけ混乱が増えました。
「共通化できるものは共通化したい」という気持ちはわかりますが、Git の仕様に逆らっても良いことはありません。素直にリポジトリごとに設定するのが無難です。
結局どうだったか
「GitHub の構造をローカルに模倣する」というシンプルなルールを導入して数ヶ月。正直なところ、最初は「面倒だな」と思っていました。でも今では、この構造なしでの開発は考えられなくなっています。
Before（導入前）:
- リポジトリの場所を探すのに毎回 30秒程度
-
findコマンドで候補が複数出て、さらに迷う - AI に「パスがわかりません」と言われる頻度が高い
After（導入後）:
- GitHub の URL を見れば即座にパスがわかる
- 複数マシン間でもパス構造が統一されている
- AI が関連ドキュメントを自動で見つけてくれる
「あのリポジトリどこだっけ？」という時間が消えたのは大きいです。GitHub の URL を見れば、ローカルのパスがすぐわかる。考える時間が減ると、開発に集中できます。
特に AI とペアプログラミングをする場面で効果を実感しています。ディレクトリ構造は、AI へのコンテキスト提供の一部。パス構造が整っていると、AI が「このプロジェクトは何をするものか」「関連リポジトリはどこにあるか」を自然と理解してくれるようになりました。
移行作業は地味に大変でしたが、一度整えてしまえば後が楽です。「どこに何があるか」で悩む時間が減ると、開発に集中できるようになります。
Discussion