本ドキュメントは、コーディングエージェント（coding_agent）プロジェクトの全体仕様を統合したものです。各機能の詳細については、それぞれの仕様書を参照してください。
本プロジェクトは、GitHub Copilot Coding Agentのようなコーディングエージェントを構築することを目的としています。GitHubやGitLabのIssue、Pull Request、Merge Requestに対して、LLM（大規模言語モデル）を活用して自動的にコード変更や対応を行います。
- タスク取得: GitHub/GitLabから特定ラベルが付与されたIssue/PR/MRをタスクとして取得
- LLM対話: OpenAI、Ollama、LM Studio等のLLMプロバイダーと連携
- MCP連携: Model Context Protocol（MCP）サーバーを通じてGitHub/GitLabの操作を実行
- コンテキスト管理: 会話履歴の管理と自動圧縮
- 一時停止・再開: タスク処理の一時停止と状態保存からの再開
- タスク停止: アサイン解除によるタスクの停止
- 継続動作モード: Docker Composeによる継続的なタスク処理
- ユーザー設定管理: ユーザーごとのLLM設定の管理
→ 詳細は spec.md を参照
本システムは以下のコンポーネントで構成されています：
- main.py: メインエントリーポイント、Producer/Consumerモードの制御
- TaskGetter: GitHub/GitLabからタスクを取得する抽象クラスと具象クラス
- Task: タスクを表現する抽象クラスと具象クラス（Issue/PR/MR対応）
- TaskHandler: タスク処理のオーケストレーション
- LLMClient: 各LLMプロバイダーへのインターフェース
- MCPToolClient: MCPサーバーとの通信クライアント
- TaskQueue: タスクキュー管理（インメモリまたはRabbitMQ）
- Producerモードでタスク一覧を取得し、キューに投入
- Consumerモードでキューからタスクを取得
- タスクに対してLLMとMCPサーバーを用いて処理を実行
- 処理完了後、タスクの状態を更新
→ 詳細は class_spec.md を参照
LLMとの会話履歴（コンテキスト）を効率的に管理するための仕組みです。メモリ消費を抑えながら、長時間の処理に対応します。
- ファイルベース管理: 会話履歴をJSONL形式でファイルに保存
- コンテキスト圧縮: トークン数が閾値を超えた場合に要約を生成
- 状態管理: SQLiteデータベースでタスク状態を一元管理
- UUID管理: 各タスクに一意のUUIDを割り当て
contextsディレクトリ配下に以下の構造でファイルを管理します：
- tasks.db: タスク状態管理データベース
- running/: 実行中タスクのコンテキスト
- completed/: 完了済みタスクのコンテキスト
- paused/: 一時停止中タスクのコンテキスト
→ 詳細は context_file_spec.md および CONTEXT_STORAGE_IMPLEMENTATION.md を参照
タスク処理を計画フェーズと実行フェーズに分割し、より構造化されたタスク処理を実現します。
- 計画フェーズ: タスクの分析と実行計画の作成
- 実行フェーズ: 計画に基づいたアクションの順次実行
- 検証フェーズ: すべてのアクション完了後に実装の完全性を検証
- 振り返りフェーズ: 実行結果の評価と計画の修正
- チェックリスト管理: 進捗状況の可視化
- タスク内容を分析し、実行計画を作成
- 計画に基づいてアクションを順次実行
- すべてのアクション完了後に検証フェーズを実行
- 実装の完全性チェック（プレースホルダ検出）
- 成功基準の達成度確認
- 問題が検出された場合、追加作業を実行
- 最大検証ラウンド数まで再検証を繰り返し
- 必要に応じて計画を修正（振り返りフェーズ）
- 全アクション完了で処理終了
→ 詳細は PLANNING_SPECIFICATION.md を参照
実行中のタスク処理を一時停止し、後から同じ状態から再開できる機能です。
- シグナルファイル検知: pause_signalファイルの存在で一時停止を検知
- 状態保存: 一時停止時にコンテキストと状態を保存
- 自動再開: 次回Producer実行時に一時停止タスクを自動的にキューに再投入
- ラベル管理: 一時停止状態をラベルで可視化
- pause_signalファイルを検知
- 現在のコンテキストをpausedディレクトリに保存
- ラベルを「coding agent paused」に変更
- 再開時、pausedディレクトリからコンテキストを復元
- 処理を継続
→ 詳細は PAUSE_RESUME_SPECIFICATION.md を参照
Issue/PR/MRからコーディングエージェントのアサインを解除することで、タスクを停止する機能です。
- アサイン状況監視: 定期的にアサイン状況をチェック
- 停止処理: アサイン解除検出時にタスクを停止
- 状態保存: 停止時にコンテキストをcompletedディレクトリに移動
- ラベル管理: 停止状態をラベルで可視化
| 項目 | 一時停止 | 停止 |
|---|---|---|
| トリガー | pause_signalファイル | アサイン解除 |
| 再開可能性 | 可能 | 不可（新規タスクとして開始） |
| 状態保存先 | paused/ | completed/ |
| ラベル | coding agent paused | coding agent stopped |
→ 詳細は TASK_STOP_SPECIFICATION.md を参照
タスク処理中に追加されたユーザーコメントを検知し、LLMコンテキストに反映する機能です。
- コメント監視: 一時停止チェックと同じタイミングでコメントをチェック
- 差分検知: 前回チェック時以降の新規コメントを特定
- ボット除外: 自身（ボット）のコメントは除外
- コンテキスト追加: 新規コメントをLLMに通知
- 現在のコメント一覧を取得
- 前回取得時のコメントIDと比較
- ボットのコメントを除外
- 新規コメントをLLMコンテキストに追加
→ 詳細は COMMENT_DETECTION_SPECIFICATION.md を参照
Docker Composeを使用して、ProducerとConsumerをそれぞれ独立したコンテナとして継続的に動作させるモードです。
- Producer継続動作: 設定した間隔でタスク取得をループ実行
- Consumer継続動作: タスクがあれば即座に処理、なければ待機
- Gracefulシャットダウン: シグナルファイルによる安全な停止
- スケールアウト: 複数Consumerの並列実行
main.pyに--continuousオプションを追加して継続動作モードを有効化します。
→ 詳細は CONTINUOUS_MODE_SPECIFICATION.md を参照
プロジェクトごとの個別設定やルールを定義し、エージェントの動作をカスタマイズする機能です。
- ルールファイル: プロジェクトルートの設定ファイルでルールを定義
- システムプロンプト拡張: プロジェクト固有のプロンプトを追加
- ツール制限: 使用可能なMCPツールを制限
- ファイルパターン: 操作対象ファイルの制限
→ 詳細は PROJECT_AGENT_RULES_SPECIFICATION.md を参照
IssueやMerge Request/Pull Requestの処理を行う際、対象プロジェクトのファイル一覧を初期コンテキストに含める機能です。
- 自動取得: タスク処理開始時にローカルgitリポジトリからファイル一覧を自動取得
- 階層制限: 取得するディレクトリ階層を制限可能（デフォルト: 無制限）
- フォーマット: フラットリスト形式で出力
- 格納位置: システムプロンプト末尾に追加
- エージェントがプロジェクト構造を把握した状態で処理開始
- ファイル一覧取得のためのツール呼び出しを削減
- より適切な判断による処理品質の向上
→ 詳細は PROJECT_FILE_LIST_CONTEXT_SPECIFICATION.md を参照
ユーザーごとにLLMのAPIキーやモデル設定を管理する機能です。
- REST API: コーディングエージェントからの設定取得
- Streamlit管理画面: ブラウザからの設定管理
- Active Directory認証: 企業環境での認証連携
- データベース管理: SQLAlchemyによる設定の永続化
- FastAPIサーバー（ポート8080）: 設定取得API
- Streamlitサーバー（ポート8501）: 管理画面
→ 詳細は USER_CONFIG_WEB_SPECIFICATION.md および user_management_api_spec.md を参照
bhouston/mcp-server-text-editorを使用して、コマンド実行Docker環境内でテキストファイルの生成・編集を行う機能です。ClaudeのテキストエディタツールAPIと同一のインターフェースを提供します。
- ファイル表示:
viewコマンドでファイル内容やディレクトリ構造を表示 - ファイル作成:
createコマンドで新規ファイルを作成 - 文字列置換:
str_replaceコマンドでファイル内の文字列を置換 - 行挿入:
insertコマンドで指定行にテキストを挿入 - 編集取り消し:
undo_editコマンドで直前の編集を取り消し
テキスト編集MCP機能が有効な場合（デフォルト）、GitHub/GitLab MCPをLLMに提供せず、以下で代替します：
| 従来の機能 | 代替手段 |
|---|---|
| ファイル作成・更新 | text_editor（create, str_replace） |
| ファイル取得 | text_editor（view） |
| ブランチ操作 | gitコマンド（command-executor経由） |
| コミット・プッシュ | gitコマンド（command-executor経由） |
→ 詳細は TEXT_EDITOR_MCP_SPECIFICATION.md を参照
コーディングエージェントからExecutionEnvironmentManagerを通じてDocker実行環境でコマンド実行を行う機能です。ビルド、テスト、リンター等のコマンドを安全なDocker環境で実行します。
実装方式:
- 外部MCP Serverを使用せず、ExecutionEnvironmentManagerが直接コマンドを実行
- Function callingツール名:
command-executor_execute_command - PlanningCoordinatorが内部でExecutionEnvironmentManagerを呼び出し
- Docker実行環境: タスク毎に独立したDockerコンテナを作成
- プロジェクトクローン: Git経由でプロジェクトファイルを自動ダウンロード（git自動インストール）
- コマンド実行: ExecutionEnvironmentManager経由で直接コマンドを実行
- 自動クリーンアップ: タスク終了時にコンテナを自動削除
- Docker in Docker: ホストのDocker socketをマウントして実行環境コンテナを管理
- SSL対応: セルフホストGitLab対応（http.sslVerify=false）
- タスク開始時にDockerコンテナを作成（ExecutionEnvironmentManager.prepare）
- コンテナ内にgitをインストール（apt-get install git）
- プロジェクトリポジトリをクローン（GitLab: path_with_namespace使用）
- 必要に応じて依存関係をインストール
- LLMが
command-executor_execute_commandツールを呼び出し - PlanningCoordinatorがExecutionEnvironmentManager.execute_command()を実行
- タスク終了時にコンテナを削除（TaskHandler.finally）
→ 詳細は COMMAND_EXECUTOR_MCP_SPECIFICATION.md を参照
GitHub/GitLabのIssueで依頼された内容を自動的にMerge Request (MR) / Pull Request (PR) として作成する機能です。Issueの内容に基づいてLLMがブランチ名を決定し、新しいタスクとしてMR/PRを作成・処理します。
- ブランチ名自動生成: LLMがIssue内容を分析し、Bot名とIssue番号を含む適切なブランチ名を決定
- 内容転記: Issue本文とコメントをMR/PRに転記
- 自動タスク化: MR/PRにBotをアサイン・ラベル付与することで自動的にタスク処理開始
- 元Issueへの報告: 作成されたMR/PRへのリンクを元Issueにコメント
coding agentラベルが付与されたIssueを検知- Issue内容をLLMに送信し、ブランチ名を生成（Bot名+Issue番号を含む）
- 新規ブランチを作成（空コミット）
- MR/PRを作成し、Issue内容とコメントを転記
- MR/PRにBotアサインと
coding agentラベルを付与 - 元Issueに作成報告をコメント
- 元Issueを
coding agent doneに更新 - MR/PRが自動的にタスクとして処理開始
→ 詳細は ISSUE_TO_MR_CONVERSION_SPECIFICATION.md を参照
同一のIssue、Merge Request、Pull Requestに対して、過去にコーディングエージェントが処理した際のコンテキストを引き継ぎ、処理の継続性と効率性を向上させる機能です。
本機能は、通常モードと計画実行モード（Planning Mode）の両方で動作します。
- 過去コンテキスト検索: TaskKeyのハッシュ値を使用した高速検索
- 引き継ぎデータ管理: 要約、計画履歴、ツール実行履歴の引き継ぎ
- Planning Mode対応: 計画・実行・検証・振り返り履歴の引き継ぎ
- トークン制限対応: 引き継ぎコンテキストのトークン数制御
- ユーザー制御: コメントコマンドによる引き継ぎ動作の制御
通常モードとPlanning Modeで以下のデータを引き継ぎます：
| データ | 通常モード | Planning Mode |
|---|---|---|
| 要約履歴 | ✅ | ✅ |
| メタデータ | ✅ | ✅ |
| ツール実行履歴 | ✅ | ✅ |
| 計画履歴 | ✅ | ✅ |
| 検証結果 | - | ✅ |
| リフレクション | - | ✅ |
| 再計画判断 | - | ✅ |
→ 詳細は CONTEXT_INHERITANCE_SPECIFICATION.md を参照
本プロジェクトで使用する外部APIの仕様については、以下を参照してください。
- OpenAI API: external-api/openai.md
- Ollama API: external-api/ollama.md
- LM Studio API: external-api/lmstudio.md
- MCP Client: external-api/mcp_client.md
- GitHub MCP Server: external-api/github-mcp-server.md
- GitLab MCP Server: external-api/gitlab-mcp-server.md
| ファイル名 | 内容 |
|---|---|
| spec.md | プロジェクト基本仕様 |
| class_spec.md | クラス設計・関係図 |
| context_file_spec.md | コンテキストファイル化仕様 |
| CONTEXT_STORAGE_IMPLEMENTATION.md | コンテキストストレージ実装仕様 |
| CONTEXT_INHERITANCE_SPECIFICATION.md | 過去コンテキスト引き継ぎ仕様 |
| PLANNING_SPECIFICATION.md | 計画実行モード仕様 |
| PAUSE_RESUME_SPECIFICATION.md | 一時停止・再開機能仕様 |
| TASK_STOP_SPECIFICATION.md | タスク停止機能仕様 |
| COMMENT_DETECTION_SPECIFICATION.md | 新規コメント検知機能仕様 |
| CONTINUOUS_MODE_SPECIFICATION.md | 継続動作モード仕様 |
| PROJECT_AGENT_RULES_SPECIFICATION.md | プロジェクトエージェントルール仕様 |
| PROJECT_FILE_LIST_CONTEXT_SPECIFICATION.md | プロジェクトファイル一覧コンテキスト仕様 |
| USER_CONFIG_WEB_SPECIFICATION.md | ユーザー設定Web仕様 |
| user_management_api_spec.md | ユーザー管理API仕様 |
| TEXT_EDITOR_MCP_SPECIFICATION.md | テキスト編集MCP Server連携仕様 |
| COMMAND_EXECUTOR_MCP_SPECIFICATION.md | Command Executor MCP Server連携仕様 |
| MULTI_LANGUAGE_ENVIRONMENT_SPECIFICATION.md | 複数言語対応実行環境仕様 |
| ISSUE_TO_MR_CONVERSION_SPECIFICATION.md | IssueからMR/PR変換仕様 |
文書バージョン: 1.2
最終更新日: 2024-11-30
ステータス: 統合ドキュメント