AI-DLC Workflow V2のMemory：使うほど賢くなる仕組み
「さっきも言ったじゃん！！」。エージェントとの開発で一度は感じたことがあるのではないでしょうか。AI-DLC Workflow V2のMemoryは、一度指摘したら二度と同じ修正が必要にならない仕組みです。どう実現しているのか、見ていきましょう。シリーズ第6回。
Series: AI-DLC Workflow V2の解説 (31 articles)
- …
- 6AI-DLC Workflow V2のMemory：使うほど賢くなる仕組み This article
1. はじめに
この記事はAI-DLC Workflow V2（以降V2）シリーズの第6回です。第5回 ではAdaptive Composerによるステージ構成の動的提案を扱いました。
Adaptive Composerが「何をやるか」を決める仕組みだとすれば、今回のテーマは「どうやるか」の品質を使うほど高めていく仕組みです。V2にはMemoryと呼ばれるルールシステムがあり、人間のフィードバックをプロジェクト固有のルールとして永続化します。
エージェントを一度修正したら、次からはその修正が最初から織り込まれている。これがMemoryの役割です。
2. V1のワークフロー定義
V2の話に入る前に、V1のアプローチを振り返っておきます。
V1では
ai-dlc-rules-v<release-number>.zipをReleasesページからダウンロードし、展開したaidlc-rules/フォルダをプロジェクトにコピーする方式でした（V1 README ）。aws-aidlc-rules/にワークフローのコアルール、aws-aidlc-rule-details/に詳細ルールが入っています。この方式には強みがあります。シンプルで、依存が少なく、どのプロジェクトでもすぐ使える。しかし運用を続けると見えてくる課題もあります。
| 観点 | V1の状況 |
|---|---|
| ルールの更新 | 新しいzipをダウンロードして再コピー |
| ユーザーの修正 | その場限り。次のセッションには引き継がれない |
| プロジェクト固有の文脈 | ルールに反映する仕組みがない |
| チーム間の知見共有 | 手動でファイルを編集・配布 |
たとえば「このプロジェクトでは"transaction"はDB操作ではなく銀行取引を意味する」と修正しても、次にワークフローを起動したときには同じ誤解が起きるかもしれません。フィードバックを永続化するパスがなかったためです。
V2のMemoryは、この課題を解決するために設計されました。
3. V2のMemoryの仕組み
Memoryのファイル配置
V2のルールはワークスペースルートの
aidlc/spaces/<active-space>/memory/に格納されます（Rules and the Learning Loop ）。1
2
3
4
5
6
7
8
9
aidlc/spaces/<active-space>/memory/
├── org.md # フレームワーク＋組織全体のデフォルト
├── team.md # チームが承認したプラクティス
├── project.md # このプロジェクト固有の特殊化
└── phases/
├── ideation.md # Ideationフェーズのガードレール
├── inception.md # Inceptionフェーズのガードレール
├── construction.md # Constructionフェーズのガードレール
└── operation.md # Operationフェーズのガードレールファイル名がそのままスコープを表します。
scope:のようなメタデータは不要で、org.mdなら組織スコープ、project.mdならプロジェクトスコープ。命名規則だけでスコープが決まります（Rule System ）。各レイヤーの役割
それぞれのファイルには異なる粒度の情報が入ります。
| レイヤー | ファイル | 誰が書くか | 例 |
|---|---|---|---|
| org | org.md | フレームワーク / 組織管理者 | トランクベース開発、テスト方針 |
| team | team.md | practices-discoveryの承認 | 「GitHub Flowを使う」「BDDで書く」 |
| project | project.md | Learning Loopの承認 | 「transactionは銀行取引を意味する」 |
| phase | phases/*.md | フレームワーク | 「ADRには代替案を2つ記載」 |
| stage | （将来予約） | — | — |
5層がどう合成されるか
ワークフロー開始時に、フレームワークはこれらを1つのチェーンとして解決します。
1
org → team → project → phase → stageここで重要なのは**strict-additive（厳密加算）**というモデルです。適用可能なすべてのルールがエージェントのコンテキストに含まれます。何かが暗黙的に上書きされたり脱落したりすることはありません。
たとえば
org.mdに「トランクベース開発」、team.mdに「ブランチ名にはチケット番号を含める」と書いてあれば、両方がエージェントに届きます。狭いスコープが広いスコープを「上書き」するのではなく、全部積み上がる。だから矛盾が入り込まないよう、書き込み時点で止める設計になっています（これはセクション6で詳しく見ます）。コンパイルは一度だけ
チェーンの解決はワークフロー開始時に一度だけ行われ、結果は
stage-graph.jsonの各ステージに焼き込まれます。実行中にチェーンを再度たどることはありません。ネットワークルーターと同じ発想です。経路を計算するのは起動時だけ、パケットを流す時は計算済みのテーブルを引くだけ。なぜこうなっているかはセクション7で見ていきます。
4. Learning Loop
ここまでで5層のルール構造を見ました。では、そこにルールが書き込まれる仕組み、Learning Loopを見ていきましょう。
4つのステップ
Learning Loopには4つのユーザーに見えるステップがあります（Rules and the Learning Loop ）。
| Step | 内容 |
|---|---|
| 1 | エージェントがmemory.mdに記録 |
| 2 | ゲートで候補が提示される |
| 3 | ユーザーが保持する項目を選択 |
| 4 | project.mdに書き込む → 次回から自動適用 |
それぞれを順に見ていきましょう。
ステップ1: memory.md
ステージ実行中、フレームワークは
<record>/<phase>/<stage>/memory.mdに観察ログを自動で維持します。エントリは4つの見出しに分かれます。- Interpretations: 指示が曖昧だった場面でエージェントが行った解釈
- Deviations: 指示から意図的に逸脱した箇所とその理由
- Tradeoffs: 検討した代替案と選択の根拠
- Open questions: 次回までに確認すべき事項
各エントリにはタイムスタンプが付きます。このmemory.mdを書くことがLearning Loopにおけるエージェントの仕事です。memory.mdの後のすべて（候補の提示、ルーティング、ファイル書き込み）は決定論的ツールかユーザーの明示的選択で行われます。
ステップ2: ゲートで候補が提示される
ステージが完了して承認ゲートに到達すると、Learning Gate（§13 ritual）が走ります。決定論的ツールが
memory.mdを読み、4つの見出し下の非空白行をそのまま候補として表示します。言い換えや要約は行われません。書いたままの形で出てきます。加えて「次回のために何か追加しますか？」という自由記述の欄も表示されます。
ステップ3: ユーザーが保持する項目を選択
提示された候補から、次回も覚えておいてほしいものにチェックを入れます。そのステージで
memory.mdが空だった場合でも、「何か追加しますか？」の質問は必ず聞かれます。ステップ4: project.mdに書き込まれる
保持された項目は
memory/project.mdに書き込まれます。ファイルパスを選ぶ必要はなく、見出しが行き先を決めます。- Interpretations、Deviations、Tradeoffs →
project.mdにプラクティスとして記録 - Open questions → 書き込み対象外（研究項目であり、ルールではないため）
デフォルトはproject（最も狭いスコープ）です。「チームに昇格」のワンクリックで
team.mdに広げることもできます。org.mdへの自動書き込みパスはありません。orgは組織管理者が別プロセスで管理するものだからです。最も狭いスコープをデフォルトにする理由はシンプルです。1つのプロジェクトで見つけた発見が、うっかり組織全体のルールになる事故を防ぐためです。
具体例: ANZバンキングプロジェクト
ここまでの説明を具体的に追ってみましょう。ドキュメントに記載されているANZバンキングプロジェクトの例です（Rules and the Learning Loop § Worked example ）。
Samが
/aidlc featureでANZバンキングプロジェクトのワークフローを開始し、requirements-analysisステージに到達しました。Samはステークホルダーノートに「リトライ時にトランザクションが重複してはいけない」と書きます。Samの意図する「トランザクション」は銀行取引（支払い処理）です。ところがProduct Agentは「トランザクション」をデータベーストランザクションと解釈し、ACID冪等性の要件としてアーティファクトに記述しました。Samが修正し、エージェントはアーティファクトを更新して続行します。
ここからLearning Loopが動きます。
1. 日記に記録される。
memory.mdの## Interpretationsにエントリが追加されます。1
2
3
- 2026-05-21T09:14:32Z: ステークホルダーノートで"transaction"が使われた。
データベーストランザクションと解釈したが、Samの修正により
銀行取引（DB書き込みではなく、処理中の支払い）を意味すると判明。この時点ではまだルールにはなっていません。あくまでエージェントの観察メモです。
2. ゲートで候補が提示される。
ステージ完了後、承認ゲートの前にLearning Gateが走ります。上のエントリが候補として表示されます。
Samはこの候補にチェックを入れます。さらに自由記述で「エージェントがAWSアカウント用語をデフォルトで使っていた。銀行顧客エンティティは常に'ANZ customer'と呼ぶべき」と追加し、Deviationの見出しに分類します。
3. コンフリクトチェックが走る。
フレームワークが両エントリを
org.mdと照合します。「ANZ transaction」も「ANZ customer」も、orgルールのどの見出しとも矛盾しない。通過します。決定論的ツールが両方の行を
project.mdに書き込み、監査ログにRULE_LEARNEDを記録します。4. 今のワークフローは変わらない。
ステージが承認され、次の
user-storiesに進みます。新しい行はディスクにありますが、今のワークフローのコンパイル済みビューには入りません。Samはこのステージで既にエージェントを直接修正しているので、今回は問題ありません。5. 次のワークフローで効く。
その日の後半、Samが
/aidlc bugfixを実行します。ワークフロー開始時のコンパイルがproject.mdを読み込み、全ステージのコンテキストに含めます。バグ修正ワークフローのステージ1から、エージェントは「トランザクション」が支払いを意味すること、顧客エンティティが"ANZ customer"であることを知っています。修正のコストを払ったのは一度。ゲートでチェックを入れた瞬間です。以降のワークフローでは、ディレクトリを読むだけのコストでリターンが得られます。
5. practices-discovery
Learning Loopは「ワークフロー実行中の修正を1つずつ保存する」仕組みでした。Memoryにはもうひとつの入り口があります。practices-discoveryです。
Learning Loopとの違い
| 観点 | Learning Loop | practices-discovery |
|---|---|---|
| タイミング | 各ステージの承認ゲート | Inceptionフェーズの専用ステージ |
| 粒度 | 1エントリずつ | セクション単位で一括 |
| 書き込み先 | project.md（デフォルト） | team.md |
| いつ使うか | エージェントの誤りを修正した時 | チームの既存プラクティスを記録したい時 |
どう動くか
practices-discoveryはInceptionフェーズのステージで、チームの既存のやり方を聞き取って
team.mdに記録します。- インタビュー: エージェントがブランチ戦略、テスト方針、デプロイ手順などを質問する
- ドラフト: 回答を
team.mdの各セクションとして構成する - 承認ゲート: チームがドラフトを確認し、承認・編集・却下する
- 書き込み: 承認されたセクションが
team.mdに一括で書き込まれる
Learning Loopが「間違いからの学習」だとすれば、practices-discoveryは「既存知識の明文化」です。同じMemoryファイルに書き込みますが、入り口と粒度が違います。
いつ使うか
チームに確立されたプラクティスがある場合に有効です。「GitHub Flowで開発している」「BDDでテストを書いている」「ステージングへのデプロイはマージ時に自動」といった情報を、ワークフローの序盤で
team.mdに記録しておけば、以降のすべてのステージでエージェントがその前提で動きます。プロジェクト初期でまだプラクティスが確立していない場合は、このステージをスキップしてLearning Loopで徐々に蓄積していくのも有効です。
6. コンフリクト解決
なぜ書き込み時なのか
5層のstrict-additiveモデルでは、すべてのレイヤーのルールがエージェントに同時に届きます。もし矛盾するルールが共存していたら、エージェントはどちらに従えばいいのか判断できません。
V2のアプローチはシンプルです。矛盾するルールはディスクに書き込ませない。ランタイムで解決するのではなく、入り口で止める。
Admission Check（入場チェック）
Learning Loopでユーザーが候補を保持すると、ディスクに書き込む前にセクションレベルのチェックが走ります。
矛盾が検出されると、ゲートが停止して矛盾するorgの文がインラインで引用表示されます。ユーザーには3つの選択肢があります。
- 修正する: 矛盾を解消して再提出
- スキップする: この候補は書き込まない
- エスカレーションする: orgルールの管理者に相談
「orgに矛盾するけど無視して書き込む」という選択肢は設計上ありません。これにより、ランタイムのリゾルバーは常に矛盾のないルールセットだけを扱えます。
書き込み後のドリフト
orgルールが後から更新された場合はどうでしょうか。既にディスクにある
team.mdやproject.mdと新しいorgが矛盾するケースです。この「書き込み後のドリフト」は
/aidlc --doctorで検出されます。doctorは重複する見出しを特定し、ファイル名・セクション名・矛盾するorg文を提示します。このチェックはアドバイザリー（助言的）で、ワークフローをブロックしません。チームが確認し、修正するか受容するかを判断します。7. 適用タイミング
なぜ「今すぐ」ではないのか
ANZの例で見たように、Learning Loopで保持されたルールは今のワークフローの残りのステージには適用されません。新しいルールが効くのは、次に
/aidlcを実行した時です。ルールをディスクに書き込んだのに、なぜ今のワークフローでは使わないのか。ここにはControl Plane / Data Planeの設計判断があります。
3つのプレーン
V2はネットワーク機器の設計パターンを借りています。
| プレーン | 何をするか | AI-DLCでは |
|---|---|---|
| Control Plane | ルートを計算する | ワークフロー開始時にルール・センサー・ステージをグラフにコンパイル |
| Data Plane | パケットを転送する | コンパイル済みグラフを参照してステージを実行 |
| Management Plane | 監視・設定する | /aidlc --doctor、監査ログ |
ルーターがパケット転送中にルーティングテーブルを再計算しないように、V2はワークフロー実行中にルールチェーンを再コンパイルしません。
この設計が守る2つのこと
安定性: ワークフローの途中でルールが変わると、前半のゲートで承認した内容と後半のエージェントの振る舞いが食い違う可能性があります。ゲート承認時のルールセットが全ステージで一定であること。これがゲートの信頼性を支えています。
再現性: セッションが中断して再開した時、同じルールセットから同じ振る舞いが期待できます。ルールが動的に変わる設計では、再開時の状態が予測できなくなります。
使ってみると
具体的にはこんな流れです。
- ステージ中にエージェントを修正する（今回のための即座のフィードバック）
- ゲートで候補にチェックを入れる（次回以降のための永続化）
- 次のワークフローを開始する → 修正が最初から織り込まれている
「修正は今回効き、ルールは次回から効く」。この2段構造が、即座のフィードバックと長期的な学習を両立させています。
8. まとめ
この記事ではV2のMemoryとLearning Loopを見てきました。
- 5層ルールチェーン: org → team → project → phase → stageのstrict-additiveモデル。すべてのルールがエージェントに届き、暗黙の上書きはない
- Learning Loop: ステージ中の修正が、観察日記 → ゲート候補 → ユーザー選択 → project.mdへの書き込みで永続ルールになる
- practices-discovery: チームの既存プラクティスをインタビュー形式で聞き取り、team.mdに一括記録する別の入り口
- Admission Check: 矛盾するルールはディスクに書き込まない。ランタイムではなく入り口で止める
- 次回のワークフローから適用: Control / Data Plane分離で安定性と再現性を保証
ここまでの話をまとめると、Memoryが描く世界は「ルールが有機的に育つプロジェクト」です。初日は
org.mdのデフォルトだけで始まり、practices-discoveryでチームの知見が加わり、日々のワークフローでproject.mdにプロジェクト固有の文脈が増えていく。V2の設計原則の1つに「すべての修正はルールの候補である」（Principle 9: Learning from Practice ）があります。特別なことをする必要はありません。ゲートで候補にチェックを入れる。その積み重ねでエージェントはプロジェクトを学び、人間の労力は使うほど下がっていきます。モデルやツールの進化を待つ必要はありません。
Series: AI-DLC Workflow V2の解説 (31 articles)
- …
- 6AI-DLC Workflow V2のMemory：使うほど賢くなる仕組み This article
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article