AI Dev Toolkit

• 統合アーキテクチャ：すべての機能を 1 つの AI Librarian サーバーに集約 (安定：Code、プレベータ：Desktop)
• 簡単なセットアップ：Claude Desktop／Code にワンステップでインストール (安定：Code、ベータ：Desktop)
• パフォーマンスの最適化：オーバーヘッドを削減し、応答時間を短縮 (安定)
• MCP への完全準拠：Model Context Protocol 標準を完全に実装 (安定：Desktop)
• ツールインデックスとの統合：AI に最適化されたツールの選択と使用方法のガイダンス (安定)

• コードの理解：コンポーネントの追跡機能を備えた、包括的なコードベースのインデックス作成 (安定)
• 永続的なコンテキスト：会話をまたいでコード構造の認識を維持 (安定)
• コンポーネント関係の分析：依存関係と関連性を自動的に検出 (安定)
• ドキュメントの生成：ドキュメント文字列を抽出してドキュメントを作成 (安定)
• リアルタイム更新：プロジェクトの変更を自動的に監視して最新の状態を維持 (安定)
• Mini-Librarian：大規模なコードベースを専門的な知識単位に分割して処理 (安定：Code、ベータ：Desktop)

• 自動統合：手動設定は不要です。初期化するだけで、すべてが機能します (安定)
• コードとツールの連携：コードコンポーネントを関連するツールにインテリジェントに接続 (安定)
• 双方向参照：コンポーネントからツールへ、またツールからコンポーネントへ移動可能 (安定)
• コンテキスト認識：特定のコードに最も役立つツールを理解 (安定)
• バックグラウンドでの保守：コードの進化に合わせて相互参照を継続的に更新 (安定)

• 安全なプロジェクトアクセス：開発ファイルへのアクセスを制御します (安定版)
• ディレクトリのナビゲーション：直感的にディレクトリを移動、探索できます (安定版)
• コード操作：適切なエラー処理を行いながら、コードの読み取り、書き込み、変更を行います (安定版)
• 強化されたファイル編集：エラー処理とプレビューが改善されたファイル編集機能です (安定版)
• 編集ブックマーク：複雑なコードセクションの編集用にブックマークを作成、編集、適用できます (安定版)
• ブックマーク管理：複数箇所にわたる編集用のブックマークを一覧表示、取得、更新できます (安定版)
• ファイル操作：包括的なファイル管理機能を提供します (安定版)
• 検索とインデックス作成：強力な検索ツールでファイルやコンテンツを見つけられます (安定版)
• Git リポジトリの追跡：Git リポジトリとその履歴を分析、追跡します (安定版)

• 非同期処理：時間のかかる操作をバックグラウンドで実行します (安定版)
• 優先度付きタスクキュー：自動タイムアウト機能を備え、優先度に応じて操作を管理します (安定版)
• バックグラウンドワーカー：並列タスク実行のためのワーカースレッドプールを提供します (安定版)
• タスクの永続化：サーバーを再起動しても操作が保持され、自動的に復旧します (安定版)
• 思考ツール：複雑な問題に対する高度な分析的推論機能を提供します (安定版)
• 進行状況の追跡：タスクの状態、結果、実行指標を監視します (安定版)
• コンポーネント間の統合：すべてのサブシステムでタスク処理を統合します (安定版)

• 永続的な To-Do 追跡：タスクは会話をまたいで保持されます (安定版)
• 多階層のタスク構造：タスク、サブタスク、依存関係に対応します (安定版)
• 優先度とステータスの追跡：重要度と完了状況に応じて作業を整理します (安定版)
• コードコンテキストの関連付け：タスクを特定のコードコンポーネントに関連付けます (安定版)
• タスクの自動推定：会話から潜在的なタスクを抽出します (安定版：Code、ベータ版：Desktop)

• 脆弱性評価：コードベースをプロフェッショナルレベルでセキュリティ分析します (安定版)
• パターンベースのスキャン：一般的なセキュリティ脆弱性を検出します (安定版)
• AST ベースの分析：セキュリティ上の問題を高度なコード分析で特定します (安定版)
• 重大度の分類：問題を深刻度別に分類します（Critical から Info まで） (安定版)
• 標準化されたレポート：CWE ID と脆弱性の詳細な説明を提供します (安定版)
• AI Toolkit 固有のパターン：AI Dev Toolkit のコンポーネント向けにカスタムルールを用意しています (安定版)
• Sanity Check との統合：コード品質とセキュリティを組み合わせて評価します (安定版)
• 独立したセキュリティツール：security_analyze() 関数を使って単独で使用できます (安定版)

• AI ミニライブラリアン：特定の分析タスクを処理する専門 AI エージェント (安定版)
• 非同期処理：複雑な操作のバックグラウンドタスク処理 (安定版)
• タスクキュー管理：タイムアウト処理を備えた優先順位付きタスク実行 (安定版)
• 回復力の高い操作：障害やタイムアウトからの自動復旧 (安定版)
• AI に最適化された省略形式：AI 間の効率的な通信を実現する圧縮形式 (安定版：Code、ベータ版：Desktop)
• 高度なコンテキスト認識：タスクとコードを関連付ける豊富なコンテキスト情報 (安定版)
• 分散型ナレッジシステム：専門エージェント間で知識を分散 (安定版：Code、ベータ版：Desktop)

• 構造化されたリフレクション：複雑な問題を推論するための Claude のスクラッチパッド (安定版)
• 要件の検証：必要な情報がすべて収集されているか確認 (安定版)
• ルール遵守の確認：計画されたアクションがポリシーに準拠しているか検証 (安定版)
• 詳細な計画：複雑なタスクを管理しやすいステップに分割 (安定版)
• 結果の分析：他のツールの結果を処理して検証 (安定版)
• 明確な分離：内部の思考プロセスをユーザーとの会話から分離 (安定版)
• 意思決定の支援：アプローチを比較して最適な選択肢を選択 (安定版)

• MCP プロンプト：一般的なタスク用の事前定義済み会話テンプレート (安定版)
  • analyze-codebase：プロジェクトの包括的な分析
  • debug-issue：デバッグ支援ワークフロー
  • refactor-code：コードのリファクタリングに関するガイダンス
  • add-feature：機能実装ワークフロー
• 動的リソース：MCP リソースを通じてプロジェクトのメタデータにアクセス (ベータ版)
  • librarian://projects/*：プロジェクトのメタデータと AI ライブラリアンのデータ
  • librarian://bookmarks/*：ブックマーク情報を編集
  • librarian://diagnostics/*：診断情報
• プロンプトツール：複雑なタスク向けの動的ガイダンス生成ツール (安定版)
  • get_debugging_guide：コンテキストを考慮したデバッグ支援
  • get_refactoring_guide：型に応じたリファクタリング戦略
  • get_feature_implementation_guide：機能開発ワークフロー
  • get_analysis_guide：コードベースの分析アプローチ

重要：以下のコード例はすべて、Claude が内部でこれらのツールをどのように使用するかを示すものです。実行する必要のあるコマンドではありません。すべて Claude が自動的に処理します！

タイムアウトを回避するためのツール使用の最適化

最適なパフォーマンスを確保し、タイムアウトを防ぐため、Claude は次の階層的なツール選択ガイドラインに従います。

階層的なツール選択

Claude は次の順序でツールを優先します。

1. 最初にコンポーネントレジストリ：ファイルシステムを操作する前に .ai_reference/component_registry.json を確認します
2. 次にスクリプトインデックス：特定のファイルを見つけるには .ai_reference/script_index.json を使用します
3. 最後に直接ファイルを操作：インデックス化されたデータが利用できない場合の最終手段としてのみ使用します

# PREFERRED: Query component registry directly (fastest)
registry_path = f"{project_path}/.ai_reference/component_registry.json"
with open(registry_path, 'r') as f:
    registry = json.load(f)
component = registry["components"].get(component_name)

# If found, do targeted file reading
if component:
    file_path = component["primary_file"]
    # Now read just this specific file

コード検索の場合

# PREFERRED: Use script index to identify exact files to check
index_path = f"{project_path}/.ai_reference/script_index.json"
with open(index_path, 'r') as f:
    script_index = json.load(f)

# Find files containing target class/function
matches = []
for file_path, info in script_index["files"].items():
    if target_name in info["classes"] or target_name in info["functions"]:
        matches.append(file_path)
        
# Read only those specific files

実行時間の長い操作の場合

# Use TaskBoard for operations that might time out
task_id = submit_background_task(
    task_type="search",
    target_path=project_path,
    pattern=search_pattern
)
# Check status and get results when ready
task_result = get_task_result(task_id)

AI ライブラリアンと統合コンテキスト

コードベースの理解、分析、またはナビゲーションを Claude に依頼すると、内部ではこれらの関数が使用されます。

# Initialize AI Librarian for a project
# This one command sets up everything - AI Librarian, Unified Context, and Tool References
initialize_enhanced_librarian("path/to/your/project")

# Search for code implementations
find_implementation("path/to/your/project", "login function")

# Query components
query_component("path/to/your/project", "MyClass")

# Find tools related to a specific component
find_related_tools("path/to/your/project", "AuthenticationManager")

# Find components related to a specific tool
find_related_components("path/to/your/project", "edit_file")

# Get a unified view of your project
get_unified_context("path/to/your/project")

大規模なコードベースのサポート

大規模なコードベースでは、効率的なナビゲーションと理解を支援するため、Claude はミニライブラリアンを使用します。

# Access mini-librarians directly (Claude Code)
read_file(".ai_reference/scripts/___aitoolkit_librarian_ai_dev_toolkit_py.json")

# Get component information from mini-librarians
get_component_details("path/to/project", "ComponentName") 

# Search across mini-librarians
search_mini_librarians("path/to/project", "function_name")

タスク管理

タスクの追跡を Claude に依頼すると、内部ではこれらの関数が使用されます。

# Add a task
add_todo("path/to/project", "Implement login feature", priority="high")

# List tasks
list_todos("path/to/project")

# Update task status
update_todo_status("path/to/project", "todo-123", "completed")

高度な AI タスク管理

より高度なタスク追跡には、Claude はこれらの高度な関数を使用します。

# Create an AI-optimized task
add_ai_task("path/to/project", "Authentication system refactoring", "Improve security and performance", "refactor", 2)

# List AI tasks
list_ai_tasks("path/to/project", status="active", priority=1)

# Add detailed code context to a task
add_task_context(task_id, "code_snippet", "Task relates to authentication system")

Think ツール

複雑な推論タスクを処理するとき、Claude は Think ツールをプライベートなスクラッチパッドとして使用します。

# Use the think tool as a scratchpad for reflection
think("""
User wants to implement a new authentication feature.
- Required information:
  * User roles and permissions structure
  * Current authentication flow
  * Security requirements
- Implementation approach options:
  * Extend existing AuthManager
  * Create new specialized AuthProvider
  * Use third-party authentication library
- Considerations:
  * Performance impact
  * Security implications
  * Maintenance complexity
- Decision:
  * Extending existing AuthManager seems most appropriate
  * Need to add role validation logic
  * Will require unit tests for new functionality
""")

# For deeper, time-consuming analysis, use deep_analysis from the TaskBoard system
task_id = deep_analysis(project_path, "I need to understand how the authentication system works and its dependencies")
get_task_status(project_path, task_id)
get_task_result(project_path, task_id)

ファイルシステム操作

Claude はプロジェクトファイルを操作するために、これらの関数を使用します。

# Read a file
read_file("path/to/your/file.py")

# Write to a file
write_file("path/to/your/file.py", "file content")

# Edit bookmarks for complex code changes
bookmark_id = create_edit_bookmark("path/to/project", "path/to/file.py", 10, 25)
update_bookmark("path/to/project", bookmark_id, "new content for lines 10-25")
apply_bookmark("path/to/project", bookmark_id)

# List directory contents
list_directory("path/to/your/directory")

# Search for files
search_files("path/to/your/project", "pattern")

# Git repository tracking
git_info = get_git_info("path/to/your/project")
update_git_history("path/to/your/project", ".git_history")

# Project upgrading and analysis
from aitoolkit.utils.upgrade_manager import UpgradeManager

# Check if a project needs an upgrade
needs_upgrade, current, latest = UpgradeManager.needs_upgrade("path/to/project")

# Analyze a project structure and get recommendations
analysis = UpgradeManager.analyze_project("path/to/project")
recommendations = analysis["recommendations"]["recommendations"]

# Upgrade a project to the latest version
results = UpgradeManager.upgrade("path/to/project", backup=True)

# Or use the command-line tool
# python scripts/upgrade_ai_toolkit.py --analyze /path/to/project
# python scripts/upgrade_ai_toolkit.py /path/to/project

Claude Code とデスクトップ版の機能の比較

Claude Code は、ミニライブラリアンとアダプターパターンを通じて、ツールキットの機能をシミュレートできます。

Claude Code アダプターパターン

Claude Code は、.ai_reference ディレクトリに保存されたアダプターパターンを通じて、ツールキットの機能をシミュレートします。

# Example: Instead of direct toolkit call like:
result = create_edit_bookmark("path/to/project", "path/to/file.py", 10, 25)

# Claude Code reads the adapter pattern and executes:
file_content = read_file("path/to/file.py")
content_to_edit = file_content.splitlines()[10:25]
# Store in memory for later application
session_bookmarks["bookmark1"] = {"file": "path/to/file.py", "start": 10, "end": 25, "content": content_to_edit}

セキュリティ分析

セキュリティ分析タスクでは、Claude は内部でこれらの関数を使用します。

# Run a comprehensive security analysis on your project
security_report = security_analyze("path/to/your/project")

# Enhanced sanity check with security analysis included
check_report = enhanced_sanity_check("path/to/your/project", include_security=True)

パフォーマンスの最適化とタイムアウトへの対処

Claude はこれらの最適化戦略を自動的に実装します。

# Initialize with robustness features automatically applied
# This is the recommended all-in-one initialization method
initialize_ai_dev_toolkit("path/to/your/project")

# For other long-running operations, robustness decorators are used
from aitoolkit.utils.tool_wrappers import make_robust

@make_robust(timeout=60.0, max_retries=2)
def my_search_function(query):
    # Implementation here

よくある問題と解決方法：

• ⚠️ MCP が見つからない - Claude Desktop に接続できない：「Claude Desktop に接続されていないため、機能制限モードで実行しています」などのメッセージが表示される場合、MCP パッケージがインストールされていません。次のコマンドで解決できます：

  pip install mcp[cli]
  

  その後、サーバーを再起動してください。詳しい手順については、MCP_INSTALLATION.mdを参照してください。

• サーバーは実行されているが Claude Desktop に接続できない：次の点を確認してください。

  1. MCP パッケージがインストールされている（pip list | grep mcp）
  2. サーバーが適切に MCP を初期化して実行されている
  3. Claude Desktop の設定で正しいサーバーのパスが指定されている
  4. タイムアウト設定が正しい（MCP_INSTALLATION.md を参照）

• Claude にツールキットが表示されない：設定が正しく保存されていることを確認し、Claude Desktop を再起動してください。

• 権限エラー：設定で許可されているディレクトリを確認してください。

• 接続の問題：Claude Desktop が正しく設定されていることを確認し、サーバーを再起動してください。

• インポートエラー：すべての依存関係がインストールされていることを確認してください。

• ファイルアクセスの問題：サーバーにファイルへのアクセスに必要な権限があることを確認してください。

• サニティチェックの問題：sanity_check ツールで問題が発生した場合は、代替手段として find_implementation() や query_component() などの個別の診断ツールを使用してください。

• レガシーファイル：以前のバージョンに戻す際に、追跡されていないファイルがすべて削除されるように、git reset --hard の後に git clean -fd を実行してください。

• 重複ファイル：クリーンアップの過程で、.old、.backup、.fixed などの拡張子が付いた重複ファイルが見つかることがあります。これらは今後のリリースで対処する予定です。

• find_related_files ツールのエラー：このツールには既知の問題があり、今後のリリースで修正される予定です。

• タイムアウトエラー：バージョン 0.5.4 では、より信頼性の高いスレッドベースの仕組みと、検索および書き込み操作のタイムアウト延長により、タイムアウト処理を改善しました。また、サーバーの切断を防ぐため、MCP プロトコルのタイムアウトを 30s から 120s に延長しました。それでもタイムアウトが発生する場合は、python install_for_claude_code.py を実行してプロジェクトを最新バージョンにアップグレードしてください。

• 古い .ai_reference 形式：古い形式の .ai_reference ディレクトリを使用しているプロジェクトでは、python install_for_claude_code.py を実行してインストーラーを起動してください。これらのディレクトリは自動的に検出され、アップグレードを提案します。

• ツールのタイムアウトによるパフォーマンスの問題：ツールの処理に時間がかかり、タイムアウトする場合は、上記の「ツールの使用の最適化」セクションで説明した階層的なツール選択方法を使用してください。ファイルシステムを直接操作する前に、必ずコンポーネントレジストリとスクリプトインデックスを照会してください。

追加のドキュメントはdocsディレクトリにあります。

• AI ライブラリアンガイド
• タスクシステムのドキュメント
• MCP サーバーテンプレート
• プロジェクト構造
• ツールリファレンス
• AI Reference のアップグレード
• アップグレードマネージャー
• Think ツールガイド

今後のリリース

• ベータリリース：高度な GUI インターフェースの改善を近日公開
• コードベースのクリーンアップ：重複ファイルとレガシーコードの統合
• サニティチェックの改善：診断機能とレポート機能の強化
• GUI の改善：クリーンアップユーティリティを備えた設定インターフェースの強化
• プロジェクトテンプレート：一般的なプロジェクトタイプ向けのスターターテンプレート

最近のリリース

• [0.5.8] GUI の改善（現行）：カラーモードの選択、フォントのカスタマイズ、文字サイズの調整に対応した、より現代的なインターフェースを強化しました。専用の「ヘルプとトラブルシューティング」タブ、ターミナル機能を備えた「開発者」タブ、フィルタリング機能付きのオンデマンドログエクスプローラーを追加し、Claude Desktop への干渉を防ぐため、サーバーの状態監視を削除しました。
• [0.5.7] GUI の機能強化：再起動機能を備えた Claude Desktop のプロセス管理、ログフィルタリングシステム、より直感的なボタン配置によるダッシュボードの構成改善を追加しました。
• [0.5.6] アップグレードマネージャー：GUI 統合によるプロジェクト分析・アップグレードシステム、リクエストキューの明確な消去機能、Think Tool の再分類を追加しました。
• [0.5.5] Git 統合：Git リポジトリの追跡・分析機能を追加し、Git 情報の取得や Claude 用の履歴ファイル生成を行う新しい MCP ツールを追加しました。

今後の計画

• IDE 統合：VS Code などの IDE 向け拡張機能
• 高度なコード分析：より深い意味的なコード理解
• チームワークフローツール：プロジェクト管理との統合

現在進行中の作業

• ツールインデックスの改善：最近、パフォーマンスを大幅に向上させるシンプルなツールインデックスシステムを実装しました。

  • 複雑な多段階処理を、単一パスのアーキテクチャに置き換えました。
  • サブプロセス処理を行わずに、関数を直接検出します。
  • 実行速度が最大 10 倍向上しました（従来は 60 秒以上かかっていた処理が 5 秒未満になりました）。
  • 障害発生箇所を減らし、信頼性を高めました。
  • 保守性を高めるため、出力形式を簡素化しました。

• 健全性チェックとセキュリティ分析：sanity_check ツールを大幅に改善しました。

  • 包括的な評価を行うため、Security Analyzer と統合しました。
  • 重大度レベル（critical、warning、info）に対応しました。
  • エラー処理とエンコーディングの問題を改善しました。
  • CWE ID を含む、専門的なセキュリティ評価を実現しました。
  • より深くコードを理解するため、AST ベースの分析を追加しました。
  • 構造化された出力によって、レポートを改善しました。

• ディレクトリ構成の整理：重複する機能の統合を進めています。

  • librarian ディレクトリ内の重複ファイルを統合しています。
    • 強化されたファイル編集機能を統合しています。
    • モジュール間の命名規則を統一しています。
    • 非推奨の機能を削除しています（基本インデクサーは enhanced_indexer に置き換えられています）。
  • gui ディレクトリを整理しています。
    • メインの GUI 実装を configurator_new.py に統一しています。
    • レガシーファイルやバックアップファイルを削除しています。
    • レガシーファイルを整理する GUI ボタンを追加しています。

• ファイルシステム操作：ファイルの編集・操作機能を強化しました。

• 堅牢性の向上：タイムアウト処理と再試行処理を強化しています。

  • 時間のかかる処理に対する自動再試行メカニズム
  • リクエストの衝突を防ぐキュー管理の改善
  • ボトルネックの特定に役立つパフォーマンス指標
  • 設定可能なしきい値を用いた、よりスマートなタイムアウト処理