🔥

LLMとの協働開発で1日427ファイル爆発！？ - AI時代の情報管理術

に公開
AI
効率化
プロジェクト管理
LLM
開発管理
idea

LLMとの協働開発で1日427ファイル爆発！？ - AI時代の情報管理術

はじめに - 笑えない現実

「今日も順調にAIと開発してるな〜」と思っていたら、気づけば1日で427個のマークダウンファイルが生成されていました。

$ find . -name "*.md" | wc -l
427

AI駆動開発あるあるですね...笑

最近いくつかのプロジェクトでエージェント型AI駆動開発を続けてきましたが、毎回この「情報爆発問題」に悩まされてきました。
この記事ではその対策メモを残します。

この記事も、基本的にClaudeCodeに書いてもらってます🤖
（なので、一部ワイのことディスってんなwという表現があります）

AI協働開発の光と影

The Good - AIのスーパーパワー

  • 生成速度: 人間の数十倍の文書・コード生成
  • 網羅性: 漏れのない分析・設計
  • 一貫性: 論理的で構造化された出力
  • 創造性: 人間では思いつかない解決策

The Bad - 制御不能の副作用

  • 情報洪水: 427ファイル/1日の爆発的生成
  • 記憶断絶: セッションリセットによる車輪の再発明
  • 善意の破壊: 動作確認済みコードの「最適化」書き換え
  • 判断困難: 何が重要で何が陳腐化かの区別不能

実例：あるWebアプリケーションプロジェクトでの爆発現場

私が開発していたWebアプリケーションプロジェクトで実際に発生した状況を見てみましょう：

爆発前の状況

プロジェクト開始: 2025-09-16 朝
初期ファイル数: 約10個のmdファイル
開発方針: 「AIと一緒に効率的に開発しよう！」

1日後の惨状

# プロジェクトルート
$ ls *.md | wc -l
32

# 全体
$ find . -name "*.md" | wc -l
427

ファイル名の一例：

  • SYSTEM_ARCHITECTURE.md
  • PHASE2_IMPLEMENTATION_PLAN.md
  • DATABASE_DESIGN.md
  • TEST_STRATEGY.md
  • DEVELOPMENT_PRINCIPLES.md
  • API_SPECIFICATION.md
  • ...（以下421個省略）

何が起きたのか？

  1. 問題発生 → AIが解決策文書生成
  2. 解決策実装 → 関連文書・マニュアル生成
  3. 新機能追加 → 仕様書・設計書生成
  4. テスト実行 → 結果レポート・分析書生成
  5. 振り返り → 改善提案・計画書生成

各ステップで5-10個のファイルが生成され、指数関数的に爆発していきました。

根本原因の分析

1. LLMの本質的特性

  • コンテキスト忘却: セッションごとに記憶リセット
  • 網羅性志向: 「念のため」の文書大量生成
  • 個別最適: 全体最適を考慮しない独立生成

2. 人間側の問題

  • 制御意識不足: 「AIが勝手にやってくれる」の過信
  • 整理後回し: 「後でまとめよう」の先延ばし
  • 判断基準不明: どれが重要かの明確な指針なし

3. プロジェクト構造の問題

  • フラット構造: すべてが同じ階層に混在
  • 分類基準なし: ファイルの役割・重要度が不明
  • ライフサイクル管理なし: 作りっぱなしで放置

解決策：5段階分類システム

爆発現場から学んだ教訓を元に、以下の分類システムを確立しました：

ディレクトリ構造

project/
├── docs/
│   ├── core/           # 🔴 CORE: 削除禁止・最重要
│   ├── active/         # 🟡 ACTIVE: 現在進行中
│   ├── reference/      # 🟢 REFERENCE: 参考資料
│   ├── obsolete/       # 🗑️ OBSOLETE: 陳腐化・削除候補
│   └── archive/        # 📦 ARCHIVE: 成功記録保存
├── PROJECT_MASTER_SPECIFICATION.md  # 中央仕様書
└── SESSION_CONTEXT.md              # 継続性管理

分類基準

🔴 CORE（6個）：プロジェクトの核心

  • マスター仕様書
  • 設計原則
  • 重要な機能仕様書
  • セッション管理ファイル

🟡 ACTIVE（3個）：現在進行中

  • README.md
  • 現在開発中の機能設計
  • 解決中の問題分析

🟢 REFERENCE（9個）：参考資料

  • 技術マニュアル
  • 開発ガイド
  • ベストプラクティス集

🗑️ OBSOLETE（11個）：陳腐化

  • 古い計画書
  • 重複した設計書
  • 使われなくなったガイド

📦 ARCHIVE（3個）：成功記録

  • 実装完了ログ
  • 成功事例記録
  • 学習成果保存

実践：427→32個への劇的削減

Step 1: 現状把握

# 全体状況確認
$ find . -name "*.md" | wc -l
427

# ルートディレクトリの惨状
$ ls *.md | wc -l
32

Step 2: 分類実行

# ディレクトリ作成
$ mkdir -p docs/{core,active,reference,obsolete,archive/$(date +%Y-%m-%d)}

# CORE文書移動（最重要・削除禁止）
$ mv MASTER_SPECIFICATION.md docs/core/
$ mv SYSTEM_ARCHITECTURE.md docs/core/
$ mv DEVELOPMENT_PRINCIPLES.md docs/core/

# その他も分類基準に従って移動...

Step 3: 結果確認

=== CLASSIFICATION RESULTS ===
CORE: 6個（削除禁止・最重要）
ACTIVE: 3個（現在進行中）
REFERENCE: 9個（参考資料）
OBSOLETE: 11個（陳腐化・削除候補）
ARCHIVE: 3個（成功記録保存）

# ルートディレクトリクリーンアップ完了！
$ ls *.md 2>/dev/null || echo "No markdown files in root - cleanup successful!"

93%削減達成！ 🎉　（AIってこの手の表現好きですね笑 by にんげん）

制御技術：AIの暴走を防ぐ仕組み

1. Single Source of Truth パターン

# PROJECT_MASTER_SPECIFICATION.md
> THE SINGLE SOURCE OF TRUTH
> すべての作業はここから開始

## プロジェクト全体状況
- 技術仕様
- 実装状況
- 困った記録・解決策
- 次のアクション

2. セッション継続性の確保

# SESSION_CONTEXT.md
## 前回セッションの成果
- 実装: ユーザー認証機能完成
- 修正: APIレスポンス解析バグ修正
- テスト: データベース統合テスト完了

## 保護対象（絶対変更禁止）
- .user-login-form # 動作確認済みセレクタ
- user_profile schema # テスト通過済み

## 今回の目標
- データエクスポート機能実装

3. 防御プログラミング

# 保護メカニズム
PROTECTION_RULES:
  - VERIFIED/LOCKED/PROTECTED マーカー
  - 重要ファイル変更の自動検出
  - AI指示での明示的制約
  - 変更前の自動バックアップ

自動化：爆発予防スクリプト

ファイル数監視

#!/bin/bash
# プロジェクト健全性チェック

FILE_COUNT=$(find . -name "*.md" | wc -l)
if [ $FILE_COUNT -gt 50 ]; then
    echo "⚠️ WARNING: $FILE_COUNT md files (threshold: 50)"
    echo "Consider running cleanup procedure"
fi

陳腐化検出

# 30日以上更新されていないファイル検出
find . -name "*.md" -mtime +30 -exec echo "📅 STALE: {}" \;

実証結果と効果

定量的成果

  • ファイル削減: 427→32個（93%削減）
  • 作業時間: 約30分で完全整理
  • 維持コスト: 週1回・10分の定期清掃
  • 検索効率: 必要情報への即座アクセス

定性的効果

  • 制御感回復: 「プロジェクト全体を把握している」安心感
  • 生産性向上: 情報探しの時間削減
  • 品質向上: 重要情報の保護・継承
  • ストレス軽減: 「どれが最新？」の迷いが解消

AI駆動開発の新しい標準

プロジェクト開始テンプレート

ANY_PROJECT/
├── docs/
│   ├── core/
│   ├── active/
│   ├── reference/
│   ├── obsolete/
│   └── archive/
├── PROJECT_MASTER_SPECIFICATION.md
├── SESSION_CONTEXT.md
└── AI_COLLABORATION_RULES.md

AI協働の基本原則

  1. 制御第一: AIは強力な道具、人間が制御権保持
  2. 中央集約: Single Source of Truthの確立
  3. 防御設計: 重要資産の自動保護
  4. 定期清掃: 情報の新陳代謝促進

おわりに

427個のファイル爆発は、決して失敗ではありませんでした。

この経験から生まれた管理手法は：

  • ✅ 実証済み: 実際の爆発現場で93%削減達成
  • ✅ 再現可能: 明確な手順・基準・ツール
  • ✅ 汎用性: あらゆるAI協働プロジェクトに適用可能
  • ✅ 継続可能: 自動化・習慣化による持続的効果

AI時代の開発では、生成力の活用と制御力の確保の両立が重要です。

この記事の手法が、AI協働開発に取り組む皆さんの役に立てば幸いです。そして、もし今「ファイル爆発中」で困っている方がいらっしゃれば、ぜひお気軽にコメントでご相談ください！

一緒に、AI時代の新しい開発スタイルを確立していきましょう 🚀

（AIらしく締めてくれたということで..😇 私にはお気軽にご相談しないでくださいねw あなたのAIにご相談ください🙇）

Discussion