AI 従業員

​

ソリューションアーキテクチャ

本ソリューションでは、イベントを生成する唯一の信頼できる情報源として GitHub を使用します。GitHub Actions がイベントのフィルタリングと安全な転送を担い、QoderWake API の自動タスクがロール別の Waker を起動します。各 Waker はコード、レビュー、バグ、テスト証跡、リリースを GitHub に書き戻します。ロールの振る舞いは BIBLE によって継続的に管理され、タスクは分離モードで実行され、GitHub マーカーを通じて業務状態を維持します。

​

ソリューションの特長

​

特長 01：イベント駆動により、無駄なポーリングと競合状態を削減

要件ステータスの変更、PR の更新、コードのマージには、それぞれ明確なイベントが定義されています。Waker は意味のある変更が発生した場合にのみ起動されるため、定期スキャンによる待機コストや「スキャン中に状態が変わる」競合を回避できます。

​

特長 02：1 ロール、1 つの責任境界

開発、レビュー、テスト、リリースでは、独立した Waker、BIBLE、API 自動タスクを使用します。Developer は自身の成果を承認できず、Reviewer はコードを変更せず、Tester は成果物を捏造せず、Release Waker はユーザーに代わってマージしません。

​

特長 03：AI の出力を信頼できる情報源へ書き戻す

コード、テスト、コメント、バグ、タグ、リリースはすべて GitHub に書き戻されます。チャット履歴は実行状況の確認に役立ちますが、次の Waker が読み取り、ユーザーが監査できる事実は GitHub に残ります。

​

特長 04：機械による実行と人による意思決定を異なるレイヤーで運用

Waker は分析、コーディング、テスト、資料準備を自動化しますが、コードのマージと正式リリースは引き続きユーザーが確認します。AI が実行効率を高める一方で、リスクに対する説明責任は人が保持します。

​

特長 05：技術的な冪等性と業務上の冪等性を両立

呼び出しレイヤーでは、wakeSessionUniqueId により同一配信の二重実行を防止します。業務レイヤーでは、head SHA、merge SHA、GitHub マーカーによって作業完了済みかを判断します。プラットフォームによる再試行や重複イベントが発生しても、Waker は再確認した上で安全に NOOP します。

​

特長 06：認証情報はシークレット境界内にのみ存在

PAT と API アドレスは GitHub Actions Secrets のみに保存されます。ランチャーは入力をマスクし、暗号化された書き込みを使用します。Workflow は実行時にのみ認証情報を注入し、エラーログにはレスポンス本文や認証情報を出力しません。

​

ビジネスシナリオ

​

シナリオ 01：Release Waker がイテレーション境界とリリースパッケージを作成

イテレーション作成後に自動でブランチを切り、テスト合格後にリリース PR を準備し、ユーザーがマージした後にタグとリリースを作成します。

• 顧客課題：イテレーション境界やリリース資料の準備を手作業に依存すると、漏れや遅延が発生しやすくなります。
• トリガー：イテレーションの作成、または Tester による再テストの完了。
• Agent の処理：main から iteration/* ブランチを作成し、要件、バグ、PR、CI 証跡を集約してリリース PR を作成します。ユーザーによるマージ後、タグと GitHub Release を作成し、Milestone を終了します。
• 成果物：専用イテレーションブランチ、リリース PR、タグ、リリース、終了済み Milestone。
• 完了条件：イテレーション境界が明確で、リリース資料が完全かつ監査可能であること。
• Human Gate：ユーザーがリリース PR のマージを確認します。

​

シナリオ 02：Developer Waker が要件の事実に基づいて開発成果を提供

要件が開発段階に入ったとき、またはバグが差し戻されたときに起動し、事実を読み取ってコード、テスト、コード PR を提供します。

• 顧客課題：AI は明示的に呼び出したときにしか動作せず、毎回手作業でコンテキストを説明する必要があります。
• トリガー：要件が開発段階に入る、またはバグが差し戻される。
• Agent の処理：要件、受け入れ条件、コメント、既存 PR を再確認し、イテレーションブランチから demo/feature/* または demo/bugfix/* ブランチを作成します。テストを追加して最小限の実装を完了し、npm test と npm run lint を実行します。テスト証跡、関連 Issue、配信マーカーを含むコード PR を作成または更新します。
• 成果物：実装、テスト、関連 Issue、配信マーカーを含むコード PR。
• 完了条件：コード PR がローカルテストに合格し、要件に関連付けられていること。
• Human Gate：ユーザーが差分をレビューし、コード PR をマージします。

​

シナリオ 03：Reviewer Waker が特定リビジョンを独立レビュー

PR の作成と新しいコミットのイベントだけを監視し、head SHA ごとに独立したレビューを完了して結論を書き戻します。

• 顧客課題：人によるレビュー能力には限界があり、AI のレビュー結果がチャット内だけに残ると監査できません。
• トリガー：PR の作成、またはソースブランチへの新しいコミットの push。
• Agent の処理：head SHA をレビュー単位として、完全な diff、関連要件、CI を確認します。独立したワークスペースでテストを実行し、ブロッキング問題があれば CHANGES_REQUESTED を書き込み、合格時には [QW-REVIEW][sha][PASS] を残します。
• 成果物：テスト、lint、CI、受け入れ条件、diff 範囲を網羅した、PR に書き戻されたレビュー結果。
• 完了条件：Reviewer が PASS、CI が成功し、ユーザーによるマージ待ちであること。
• Human Gate：ユーザーがコード PR のマージを確認します。

​

シナリオ 04：Tester Waker が受け入れ失敗を開発へ自動で差し戻す

コードがイテレーションブランチへマージされた後に独立検証を行い、問題が見つかった場合はバグを作成して Developer を自動起動します。

• 顧客課題：テストで問題が見つかってもチャットで通知されるだけになりやすく、証跡が不完全で、修正後の再テストも追跡しにくくなります。
• トリガー：コードがイテレーションブランチへマージされる。
• Agent の処理：独立して検証し、失敗時には再現手順、期待される動作、実際の動作、ログ、親要件を含む Bug を作成して Developer を起動し、修正フローへ戻します。再テスト合格後、Bug と Requirement を検証済み完了状態へ移行します。
• 成果物：Bug Issue、または再テスト合格ステータス。
• 完了条件：同じ Developer → Reviewer → Merge → Tester のチェーンで不具合が修正され、再テストされること。
• Human Gate：ユーザーが修正版コード PR のマージを確認します。

​

リファレンスプラクティス

​

プラクティス名

QoderWake × GitHub：イベント駆動型開発コラボレーションのリファレンスプラクティス

​

背景

• 顧客・業界：GitHub を信頼できる情報源として使用する開発チーム。
• 従来のワークフロー：ステータス同期は手動のリマインドに依存し、コンテキストを繰り返しコピーする必要があり、AI の成果はチャット内に留まります。
• 主な課題：イベントから AI 実行を自動起動できない、単一 Agent では責任を分離できない、自動化プロセスを監査できない。
• パイロット範囲：Release、Developer、Reviewer、Tester の各ロールと完全なイテレーションを網羅する、オープンソースのリファレンス実装リポジトリ。

​

プラクティス設計

• イベントの取り込み：Milestone、Issue、PR、CI などの状態変更時に GitHub がイベントを生成します。例として、要件の開発移行、PR の作成・更新、イテレーションブランチへのコードマージ、再テスト合格があります。
• 制御レイヤーのルーティング：GitHub Actions がイベントを監視し、ノイズを除外して最小限のコンテキストを準備し、QoderWake API の自動タスクへ安全に転送します。PAT は GitHub Secrets からリクエストヘッダーへ注入されます。
• Agent の実行：QoderWake API の自動タスクは分離モードで動作し、ロール別 Waker を起動します。各 Waker は実行ごとに GitHub の事実を再確認し、BIBLE が利用可能なツール、標準ワークフロー、禁止事項を制約します。
• 結果の書き戻し：Waker はコード、レビュー結果、バグ、テスト証跡、タグ、リリースを GitHub に書き戻し、次のロールが読めてユーザーが監査できる事実を形成します。
• 失敗時の差し戻し：Reviewer がブロッキング問題を発見すると CHANGES_REQUESTED を書き込み、Developer へ戻します。Tester の受け入れ検証が失敗すると、再現証跡付きの Bug を作成し、Developer を自動起動して修正フローへ戻します。
• 人による意思決定：コード PR とリリース PR のマージはユーザーが確認します。Release Waker は代理でマージせず、リリース資料の準備のみを行います。

​

プラクティスのワークフロー

​

成果

• クローズドループの実現：要件のイテレーション投入からバージョンリリースまで、開発、レビュー、テスト、リリース、バグ差し戻しを含む完全な引き継ぎを実現します。
• 検証済みの能力：イベント駆動の起動、4 ロールの責任分離、GitHub への事実の書き戻し、人による Merge ゲート、冪等実行。
• データと証跡：サンプル実行のスクリーンショットと実行記録を参照できます。再起動のたびに一意の Iteration と番号が生成されます。
• 今後の拡張：イベントアダプターレイヤーと事実読み取りツールを置き換えることで、企業独自の DevOps プラットフォームへ移行できます。

​

推奨製品構成