カオスからコンテキストへ：AIと組む開発ワークフローのつくり方

1回のセッション中に、同じ指摘を何度もAIアシスタントに繰り返す。あのもどかしさには、独特のものがあります。最新の大規模言語モデル（LLM）は驚くほど優秀で、これまで出会ったなかで最も熱心な弟子と仕事をしているような感覚をもたらしてくれます。ただし、その弟子は記憶を保てません。「はい、コミットメッセージは本当にその形式にしてほしいんです。この話をするのは、これで3回目ですよ」

あるいは、複数のAIセッションを並行して動かそうとしたところ、それぞれが同じ課題に独立して取り組み、互いの成果を消し合ってしまう。そんな経験をお持ちの方もいるかもしれません。

こうしたもどかしさが、試行錯誤の出発点になりました。私はGitLabの2つのAI機能、脆弱性の説明と脆弱性の修正の初期バージョンの開発に携わっていました。当時はどちらも素朴な仕組みで、もっと多くのことができるはずだと感じていたのです。

それを実現したのが、エージェント型AIでした。こちらからプロンプトを投げ、返ってきた提案をコピーして貼り戻す。そんな一問一答ではなく、エージェントは自らコードベースを読み、変更を加え、テストまで実行します。助言するだけでなく、実際に作業を担うわけです。そこからGitLab Duo Custom Agents、VS Codeとの連携を経て、最終的にたどり着いたのがOpenCodeでした。「ターミナル、IDE、デスクトップでコードを書く」ことを支援すると自ら説明する、オープンソースのエージェントです。

その過程で、自分にとって有効だった要素を絞り込んできました。AIコーディングアシスタントは確かに大きな変化をもたらしますが、方向づけにはエンジニアとしての勘が欠かせません。良い判断も悪い判断も等しく増幅されるため、どこへ向かわせるかが決定的に重要になります。ツールは今後も変わり続けるでしょう。ここでは、現時点で日々の開発に効いている考え方を紹介します。

最適化されたAIワークフロー

原則の話に入る前に、最適化されたAIワークフローが実際にどのようなものかを見ておきましょう。

優先順位は向こうからやってくる。 セッションを開始すると、AIは進行中のセッション、未解決のブロッカー、常設のディレクティブ、直近の意思決定を読み込みます。続いてGitLabのto-do、進行中のマージリクエスト、追跡中のエピックを取得し、あらかじめ定義した優先順位で提示してくれます。順序は、放置されている項目（見落とされがちな案件）、他者からのレビュー依頼（チームメイトを待たせない）、自分の回答待ちの質問、自分がブロックされているマージリクエスト、そしてその他すべて。何に取り組むべきかを考える時間は、もう必要ありません。コンテキストのほうから届きます。

集中のあり方が変わった。 ソフトウェア開発では従来、意味のある成果を出すために何時間もの中断のない集中が必要でした。それが変わりました。15分や30分の隙間時間でも、キューの先頭にある項目を尋ね、AIにその項目のコンテキスト（過去の意思決定、ブロッカー、関連する手順）を読み込ませ、コーディングやテストの委任を始められます。自分で頭の中の文脈を組み立て直すのではなく、AIがほぼ即座に状況を共有してくれるのです。

複数のマージリクエストを並行して進める。 git worktreeと分離したテスト用データベースを組み合わせ、複数のマージリクエストにAIセッションを同時に取り組ませています。ワークツリーごとに専用のセッションと専用のデータベース。作業を確保する仕組みが、セッション同士の衝突を防ぎます。テストの実行とコードの動作確認はAIが担当し、私は正しさの観点からレビューします。

繰り返す作業は手順化する。 優先度の高いエピックについては、AIが週次のステータス更新を担当します。GitLabから現在の状態を取得し、前週の状態と比較して差分を算出し、進捗指標を添えて更新内容を下書きする。この手順はディレクティブに記述してあるため、どのセッションでも同じように実行できます。

トークン効率は無視できない。 コンテキストのオーバーヘッドを減らすため、GitLabのREST APIとGraphQL APIやOpenCode GitLabプラグインに改善を提案してきました。あわせて、よく使うパターンを組み込んだローカルのワークフロー用Model Context Protocol（MCP）サーバーも構築しています。AIが毎回ゼロから手順を組み立てるのではなく、データ収集を担う最適化されたツールを呼び出し、推論だけをLLMに任せる。これにより応答が速くなり、トークン使用量も管理しやすくなります。

根底にあるのは能動的な委任。 トップレベルのコンテキストと方向性は私が保ち、個別のタスクの実行をAIに任せます。マージリクエストの作業に入る前に、AIは競合を防ぐためにそのマージリクエストを確保し、メモリから履歴を読み込み、関連するディレクティブを確認する。方向性の監督は私が、実行のスピードはAIが担う形です。

曖昧な指示ではなく、狙いを定めたディレクティブを書く

セッションは毎回ゼロから始まります。何も手を打たなければ、同じ好み、同じ規約、同じコードベースの癖を、そのつど説明し直すことになります。

解決策は、明示的で永続的なディレクティブです。エージェント型AIツールでは、起動時のコンテキストとして読み込まれるAGENTS.md設定ファイルが標準になりつつあります。ただし重要なのは、ディレクティブが必要だという点ではありません。具体的でなければ意味がないという点です。

「コメントには気をつけて」といった曖昧な指示は機能しません。AIはいったん了解しますが、結局は元々やろうとしていたことを実行します。効果があるのは、次のような具体性です。

「ALWAYS：ユーザー名義でコメントを投稿する前に、必ずユーザーIDの存在を検証すること。判断がつかない場合はSTOPして確認すること」

すべて大文字のキーワードは、単なる強調ではありません。これがあることで、AIは指示により確実に反応するようです。

応用できるパターン： AIツールがミスをしたら、修正して終わりにしないこと。次に同じミスを防ぐにはどんなディレクティブが必要か、AI自身に尋ねてみてください。そのやり取りを経て、次回のために記録するよう指示します。これを積み重ねると、机上のベストプラクティスではなく、実際のワークフローに即した指示の集合が育っていきます。

私のagents-configリポジトリには、こうして生まれた専用の設定ファイルが十数個ありました。コードレビューのガイドライン、マージリクエストのワークフロー、データベースレビューの手順、コメント記述の基準といった内容です。いずれも、繰り返す頻度が高く、手順化してAIに一貫して実行させる価値があったから存在しています。後述するメモリシステムによって、この方針は身軽になりました。これらのディレクティブは、静的なファイルではなく検索可能なメモリに置かれています。現在のリポジトリには、実用的なサンプルと、日々の進め方を示す使い方ガイドが入っています。

並行セッションには協調のためのプリミティブが要る

複数のAIセッションを同時に走らせることは、うまく管理できれば効率的です。3つのターミナル、3人のアシスタント、3本の並行した作業の流れ。しかし協調の仕組みがなければ、おそらく見覚えのある問題にぶつかります。

• 互いの存在を知らないまま、同じファイルを編集するセッション
• 同じ項目に複数のセッションが取り組む（作業を確保する手段があれば別ですが、たいていはまだないでしょう）
• 個別に判断された、互いに矛盾する意思決定
• 互いの成果を消してしまう、あるいは無関係なマージリクエストに自分の変更ごと平然とコミットしてしまうセッション
• どちらのセッションも相手の作業を把握していないことによる、重複した労力

並行処理のプログラミング経験があれば、これらが古典的な協調問題だとすぐに分かるはずです。解決策も同様で、作業の確保、状態の追跡、コンテキストの共有を担うプリミティブが必要になります。

最初に試したのは、ファイルベースの作業メモでした。機能はしましたが、検索できず、対象の作業とひも付いておらず、日をまたぐと十分に残りません。関連するコンテキストを自動的に浮かび上がらせる仕組みが必要でした。

そこで構築したのが、永続的なセマンティックメモリシステムopencode-memoryです。アーキテクチャに反映されているのは、それまでディレクティブで解決し続けてきた問題への答え。ハイブリッド検索（完全一致にはキーワード、曖昧な想起にはセマンティック検索）、claim/releaseによるセッションの協調、そして重要なディレクティブを自動的に提示する起動時コンテキストの3点です。

システムは初期版から大きく育ちました。現在は76万を超えるコードエンティティをインデックス化し、会話の要約を含む1万5000件以上のメモリと、それらをつなぐ2万7000本のリンクを持つ、本格的なナレッジグラフになっています。ソフトウェア開発ライフサイクル（SDLC）全体をインデックス化するナレッジグラフOrbitがGitLabから発表されたとき、私がローカルで進めていた方向とほぼ一致していることに気づきました。Orbitはコード、マージリクエスト、パイプラインを結び付け、「このサービスを変更したら何が壊れるか」といったSDLC横断の問いに答えます。私のメモリモジュールはすでにコードベースをローカルにインデックス化して高速な想起を実現していたため、広い視野を一から作り直すのではなく、Orbitを組み込んで強化する道を選びました。ローカルのメモリが意思決定、ブロッカー、手順といったセッション単位のコンテキストを保持し、その上にOrbitがGitLabのより広いSDLCグラフを重ねる構成です。特にありがたいのは、会話のなかで関数名に触れるだけで、AIがその所在を正確に思い出してくれること。自分で調べる必要がありません。

マージリクエストの作業に入るときには、過去の意思決定も自動的に表示されます。ブロッカーは明示的に解消されるまで残り、一度定義した手順は永続的に使えます。必要な場面で自ら注意を引くリマインダー。ローカルメモリとOrbitのSDLCデータを組み合わせたグラフは、単純なテキスト検索よりもはるかに効率的かつ的確に、こうした問いに答えてくれます。

作る前に、まず調べる

唯一無二のアイデアなど存在しません。AIコーディングアシスタント向けのメモリシステムを検索すれば、何十もの方式が見つかります。あなたが思いつく3週間前に、誰かがコーヒー漬けのAI開発ラッシュのなかで同じものを作り終えている。そんな世界です。実際、opencode-memoryという名前のPyPIパッケージが存在し、ベクターデータベースのバックエンドが違うだけで、私が作ったものとよく似た機能を提供しています。

必要なものを自作する際のハードルは、劇的に下がりました。その結果、多くの人が独立に似た解へたどり着きます。アイデアから動くプロトタイプまで、1週間あれば到達できるのです。

新しいプロジェクトを立ち上げる前に、既存のものがないか確認することをおすすめします。課題をほぼ解決してくれるものがあるなら、亜種をもう1つ作るよりコントリビュートするほうが良いかもしれません。この助言はソフトウェア開発そのものと同じくらい古いものですが、AIはそれを100倍の規模で突きつけてきます。

私のメモリシステムも、当初は既存の解決策に対してほとんど優位性がありませんでした。数か月の改良とGitLabとの深い統合を重ねて、ようやく存在意義があると思えるようになった程度です。少なくともOpenCode GitLabプラグインについては、フォークするのではなく改善をコントリビュートしました。そのほうが、変更が最も多くの人の役に立つからです。

自問する価値のある問いは、こうです。この課題を解決する既存のものがないか、きちんと調べただろうか。それとも、AIによってコードを書くことが簡単になりすぎて、事前確認をすべて省いてしまっただろうか。

能動的な想起から、受動的なコンテキストへ

ベクトル化したメモリ検索は、すぐに効果を発揮しました。構築したその日のうちに移行したほどです。有用な情報の想起は、造作もない作業になりました。次の課題は、毎回こちらが促さなくても、記憶する価値のある事柄をAIが暗黙的に判断できるようにすることでした。

進展はありました。特定の手順をトークン効率よく記憶する仕組みと、自然に想起されるメモリの蓄積です。とはいえ、装飾を加えたAGENTS.mdを作り直しているだけのようにも感じました。もっと賢い仕組みが必要だったのです。

答えは、能動的なコンテキスト注入でした。AIが想起用のツールを明示的に呼び出すのではなく、やり取りのたびにシステムが関連するメモリを自動で検索します。マージリクエストの番号に触れれば、関連する過去の意思決定が求めずともコンテキストに現れる。コメントを書こうとすれば、コメント記述のガイドラインが自動的に浮かび上がる。少なくとも、たいていの場合は。まだ発展途上ですが、日々少しずつ精度を高めています。

能動的な想起から受動的な想起への移行は、明確な違いを生みました。30日間の運用で、関連コンテキストを自動的に提示する有効性は約91％に達しています。能動的な注入を有効にしたセッションでは、明示的な想起呼び出しが平均0回。無効の場合の17回と比べれば、その差は歴然です。完璧ではなく、記憶するよう、あるいは改善するようAIに伝える必要がある場面は今も残ります。ただ、これは反復的なプロセス。着実に良くなっています。

取りこぼしの内訳も、示唆に富んでいました。その多くは、起動時のコンテキスト読み込みの仕組みを試行錯誤していた時期に発生したものです。対策として導入したのが、ブートゲート。起動時コンテキストに最小限のトリガーを置き、他の処理に入る前にいったん止まってディレクティブを読み込むようAIに指示する仕組みです。能動的な注入があっても、まず立ち止まって考えるよう伝える必要はあります。

AIにまだできないこと

手順がコンテキストに含まれていれば、AIはそれをかなり安定して実行できます。考えるよう促せば、自分自身への指示を改善することも可能です。プリミティブさえ与えれば、セッションをまたいだ協調も成立するでしょう。

しかしAIは、暗黙のうちに何かへ気づくことがありません。ある手順が使いにくいと感じることもありません。今週すでに同じ問題に3回ぶつかっている、と認識することもありません。深夜2時に本番システムをデバッグしながら、大工にでもなっておけばよかったと考える。そんな年月から生まれるパターン認識は、AIにはないのです。少なくとも、現時点では。

ちょうど良いバランスは、雑務の削減にAIを使い、適切なタイミングで適切なコンテキストを与え、AIが見落としたものに目を配ることにありそうです。戦略的な監督とパターン認識は人間が担い、疲れを知らない実行力と、かつて退屈で時間のかかる作業だと感じていたタスクへの意欲はAIが担う。この分担には、大きな力があります。

AIが意気揚々と機能を作りながら、自分のツールに並行処理のバグを埋め込み、同期処理で自らを止めてしまう場面も見てきました。本人にはまったく自覚がありません。振り返れば、これは方向づけの問題でした。もっと早い段階で一緒に設計し、適切な非同期パターンを確保しておくべきだったのです。最初から良いパターンを組んでくれるだろうという期待は、楽観的すぎました。私がアーキテクチャ上の欠陥を指摘して方向を修正すると、数分で直りました。

これがパターンです。人間が問題を見つけ、AIが素早く修正を実行する。自分でも直せましたが、これほど速くはできません。AIはまだ、メタなレベルの非効率を検知できない。もっとも、そのための専用エージェントを誰かが書いている最中でしょう。

ツールそのものに投資する

この進め方を選ぶことは、絶え間ない変化を受け入れることでもあります。私の日々の仕事は、数か月のあいだに何度も、そして完全に姿を変えました。キャリアの初期にはワークフローが何年もかけてゆっくり変わっていたことを思えば、対照的です。

「新しい常態」に落ち着こうとしないでください。それはまた変わります。今のペースでは、今日役立っているツールが来週には時代遅れになっていてもおかしくありません。

むしろ、ツールそのものを改良し続けましょう。作業を速くするワークフロー自体が、最適化の対象になります。私自身、AI支援開発で必要になったという理由から、グループアップロードやマージリクエストワークフロー向けのGraphQLミューテーションといった新しいAPIエンドポイントをGitLabにコントリビュートしてきました。

これはメタなループです。良いツールが生産性を高め、その余力がさらにツールの改善を生む。「木を切り倒すのに6時間もらえるなら、最初の4時間は斧を研ぐのに使う」という古い格言があります。最近の私は、斧を研ぐことにかなりの時間を割いています。しかも、これほど優れた砥石を手にしたことはありません。

まとめ

コードはもはやコモディティです。私たちが対価を得ている理由は、コードを打ち込むことではありません。どんなコードが存在すべきかを見極めること。あるアプローチが根本的に間違っていると気づくこと。非効率が問題になる前に発見すること。そして、素の能力を有用な成果へ変える方向づけを与えること。価値はそこにあります。

私はGitLabのCREDITバリューをAI活用にどう適用するかというガイダンスを作っていました。ところがGitLab 第2章：エージェント型AI時代への戦略転換によってCREDITは完全に廃止され、エージェント型AI時代に向けた新しい行動指針へ置き換わりました。この領域の変化の速さを示す好例です。自分のガイダンスは、世に出る前に追い抜かれてしまいました。それでも核心は変わりません。このバランスを正しく取ることは、個人だけでなく組織のレベルで重要だということ。AIは人間の仕事を代替するのではなく、拡張すべきものです。

ツールは進化を続け、細部は変わっていきます。しかし、この根本的な洞察は変わりません。AIは人間の判断を増幅するものであり、置き換えるものではない。放っておけばAIは置き換えようとしますが、その代償はたいていコード品質と安定性です。バイブコーディングでもかなりのところまで進めます。それでも、どれほど入念にAIがレビューしても、品質の担保と設計上の慎重な検討をAIが単独で提供する場面は、まだ見たことがありません。

GitLabの同僚の何人かが、このワークフローを自分なりに変えて使い始めています。彼らが同じ「なるほど」の瞬間を体験する様子は、この取り組みが正しかったという確認そのもの。先日は、opencode-memoryモジュールについて「プラグインを使い始めてから、セッションが明らかに良くなった」というメッセージをもらいました。あの日一日、上機嫌だったことは否定しません。問いは「AIにXをやらせるにはどうするか」から「AIがXをうまくやるために必要なコンテキストをどう与えるか」へ移っていきます。本当の鍵は、ツールそのものではなく、コンテキストこそがボトルネックだと気づくことにあります。

興味深いのは、これが上達するほど、ボトルネックは自分自身かもしれないと気づき始めることです。ただしそれは、自分のプロセスをさらに改善できるという合図でもあります。上限に達したという感覚は、まだまったくありません。AIを活用する場合でも、タスクによって適したアプローチは異なり、試すべきことは山ほど残っています。

最後に、変化の速さについて一言。このメモリシステムには、1か月足らずで143件のコミットが入りました。MCPの上に構築されているため、このプロトコルを話せるエージェントであれば何とでも連携します。OpenCodeだけでなく、Claude CLIやCursorなども対象です。この記事を読むころには、今はまだ思いついてもいない機能が追加されているでしょう。それが、今この領域で仕事をするということ。ツールはドキュメントよりも速く進化します。

この記事で紹介したツールは、いずれもオープンソースです。AIディレクティブの設定にはagents-config、永続的なセッションメモリにはopencode-memoryをご覧ください。