コンテンツにスキップ

フォルダ構成の設計意図

作成日: 2026-02-06 目的: Claude Code が効率的に動作できるプロジェクト構造の構築

設計原則

1. 明確な責任分離 (Separation of Concerns)

各ディレクトリは単一の明確な責任を持つべきです。これにより： - Claude Code がファイルの場所を推測しやすくなる - 開発者が直感的にナビゲートできる - 依存関係が明確になる

2. 浅い階層構造

過度に深い階層は避け、2〜3階層に抑えます。理由： - ファイルパスが短く、コマンド入力が簡単 - Claude Code のコンテキストウィンドウを節約 - 全体構造の把握が容易

3. 予測可能な命名

標準的な命名規則を使用します： - scripts/ - 実行可能なスクリプト - docs/ - ドキュメント - projects/ - サブプロジェクト - vault/ - データストレージ

ディレクトリ構成

MyLab/
├── .agent/                     # エージェント設定とスキル定義
│   └── skills/                 # Claude Code用のスキルスクリプト
│
├── projects/                   # サブプロジェクト（独立性の高いもの）
│   └── buzz-collector/         # Xからバズツイート収集
│       ├── src/                # プロジェクト専用のソースコード
│       ├── config/             # プロジェクト専用の設定
│       ├── logs/               # プロジェクト専用のログ
│       └── README.md           # プロジェクト個別のドキュメント
│
├── scripts/                    # 汎用スクリプト（ツール・ユーティリティ）
│   ├── conversation/           # 会話ログ保存
│   ├── browser/                # ブラウザ設定支援
│   └── utils/                  # その他汎用ツール
│
├── vault/                      # ナレッジベース（Obsidian）
│   ├── .obsidian/              # Obsidian設定
│   └── Resources/              # 生成コンテンツ
│       ├── ConversationLogs/   # 会話記録
│       └── WebArticles/        # Web記事要約
│
├── docs/                       # プロジェクト全体のドキュメント
├── logs/                       # プロジェクト全体の実行ログ
└── archive/                    # 非アクティブなコード・実験用コード

各ディレクトリの意図

.agent/skills/

目的: Claude Code が実行可能なスキル定義 理由: - エージェント関連の設定を一箇所に集約 - スキルの検索・実行が高速化 - バージョン管理が容易

projects/

目的: 独立性の高いサブプロジェクトの格納 理由: - 大規模な機能は独自の構造を持つべき - 依存関係を明確に分離 - 将来的に別リポジトリへの分離が容易 - 例: buzz-collector は独自のスクレイピング、データベース、設定を持つ

プロジェクト判定基準: - 5ファイル以上のソースコード - 独自の設定ファイルが必要 - 独立したREADMEが必要 - 他の部分と依存関係が少ない

scripts/

目的: プロジェクト横断的に使用する実行可能なスクリプト 理由: - 「実行するもの」を一箇所に集約 - Claude Code が「何かを実行する」タスクで探しやすい - 従来の src/ と scripts/ の重複を解消

サブディレクトリ分類: - conversation/ - 会話ログ管理（.agent/skills/ と連携） - browser/ - ブラウザ・環境設定 - utils/ - その他汎用ツール

vault/（旧 ObsidianVault/）

目的: 知識・データの永続化 理由: - より短く覚えやすい名前 - .obsidian/ 設定を一箇所に統合（ルートから削除） - 「データストレージ」の役割を明確化

docs/

目的: プロジェクト全体のドキュメント 配置するもの: - 設計書・仕様書 - セットアップガイド - アーキテクチャ説明 - このファイル自身

logs/

目的: プロジェクト全体の実行ログ 理由: - 一時的なログと永続的なログ（vault）を分離 - デバッグ時にすぐアクセス可能 - .gitignore で除外しやすい

archive/

目的: 非アクティブなコード・実験的なコードの保管 理由: - メインの作業領域をクリーンに保つ - 過去のコードも参照可能 - 削除する前の「一時保管場所」

削除・統合したもの

❌ ルートの .obsidian/

削除理由: vault/.obsidian/ と重複 影響: Obsidianは vault/ をワークスペースとして開く

❌ src/

統合先: scripts/ または projects/*/src/ 理由: 「src」は曖昧すぎる。スクリプトなのかライブラリなのか不明確

❌ config/vscode/

統合先: .vscode/ 理由: VSCodeは .vscode/ を標準で参照するため、分離する必要がない

❌ Credentials/

代替: .env + .env.example 理由: - 標準的な環境変数管理の方が広く理解される - .gitignore での管理が容易 - 注: 既存の Credentials/ は .gitignore されているため、一旦残す

Claude Code にとってのメリット

1. 高速なファイル検索

質問: 「会話ログを保存するスクリプトはどこ?」
答え: scripts/conversation/ を探せばOK（迷わない）

2. コンテキストの効率化

  • 浅い階層 → 短いパス → トークン節約
  • 明確な命名 → 推論の必要性が減る

3. スキル実行の信頼性

  • スクリプトパスが一貫している
  • .agent/skills/*.md の更新が最小限

4. プロジェクト理解の速度向上

projects/buzz-collector/  ← サブプロジェクト
scripts/conversation/     ← ツール
vault/Resources/          ← データ
→ ディレクトリ名だけで役割がわかる

移行ガイド

スキルファイルの更新が必要な箇所

# 旧
src/save_conversation_log.py

# 新
scripts/conversation/save_conversation_log.py

Obsidian Vaultの再設定

  1. Obsidianで vault/ フォルダを開き直す
  2. .obsidian/ 設定は自動的に認識される

環境変数の移行（任意）

# Credentials/ 内の情報を .env に移行する場合
# .env.example をコピーして .env を作成
cp .env.example .env
# Credentials/ の内容を .env に手動で移行

今後の拡張ポイント

プロジェクトの追加

新しいサブプロジェクトは projects/ に追加: 

projects/
├── buzz-collector/
├── new-project/          ← 新規追加
│   ├── src/
│   ├── config/
│   └── README.md

スクリプトカテゴリの追加

新しいカテゴリは scripts/ に追加: 

scripts/
├── conversation/
├── browser/
├── utils/
└── analytics/            ← 新規追加

バージョン履歴

  • v1.0 (2026-02-06): 初回リストラクチャリング
  • projects/ の導入
  • scripts/ への統合
  • vault/ への改名
  • .obsidian/ の統合

次の見直し推奨日: 2026-08-06（半年後） プロジェクトの成長に応じて構造を再評価してください。