AI と進める Qt 開発を再開しやすくする — NEXT.md による作業コンテキスト管理

（掲載 2026年11月1日）

AI と一緒に Qt アプリケーションを改修し、翌日続きを始めたとき、「どこまで確認したか」「なぜその方法を選んだか」を説明し直した経験はないでしょうか。別の端末や担当者へ作業を渡すと、ソースコードだけでは伝わらない情報がさらに増えます。

本記事では、作業の現在地を NEXT.md、判断と理由を DECISIONS.md、後に取り組む課題を backlog.md に残す方法を紹介します。共通の運用ルールを含めた四つのファイルで、人も AI も続きを把握できるようにします。QML の性能調査を題材に、記入例と日々の使い方を説明します。

この方法は、筆者が異なるホスト間で作業を続けるために始め、実際の運用で起きた問題を調べながら育てたものです。特定の AI 製品の機能ではありません。以下の QML プロジェクト、ファイル名、検証状態は説明用の架空例であり、性能改善の実測報告ではありません。

1. 再開時に必要なのは、現在地と判断の背景

Qt 開発では、ソース以外にも、Qt の版、コンパイラー、ビルド構成、対象機器、検証した操作、未確認の環境が作業の前提になります。QML の描画が遅い場合も、原因を特定したのか、仮説を立てただけなのかで、次の作業は変わります。

「性能改善を進めた」だけでは、翌日の自分にも十分ではありません。「計測手順を整理した。原因は未確定。次は同じ入力でトレースを採取する」と残せば、調査をやり直さずに始めやすくなります。このように、目的、制約、状態、判断、次の行動をまとめた情報を、ここでは作業コンテキストと呼びます。

会話の再開機能は、それまでのやり取りをたどるために便利です。一方、会話履歴が保存されていることと、今の応答で必要な情報が参照されることは同じではありません。また、別の AI や担当者が同じ会話を開けるとも限りません。ファイルに現在地を残す方法は、会話の再開機能と組み合わせて使えます。

2. 四つのファイルに役割を分ける

NEXT.md は作業再開の入口です。すべての履歴を集める場所にはせず、詳しい検証ログや仕様書には、保存先と読む目的を付けて参照します。

判断が未決であることと、作業を後回しにしていることも分けます。「キャッシュを導入するか、メモリー量を測って決める」は判断の論点です。「採用したキャッシュの長時間試験を後で行う」は残作業です。後者に次回着手すると決めたら、NEXT.md に次の行動を書き、詳細は backlog.md を参照できます。

README は導入・ビルド・利用方法、仕様書は満たすべき仕様や構造を説明します。作業管理ファイルは、それらを置き換える文書ではありません。情報の正本を決めて参照し、同じ説明を何か所にも複製しないようにします。

3. 最初に共通ルールと参照先を用意する

本方式では、各端末のホームディレクトリーに AGENTS.next.md を置き、対象プロジェクトの直下に三つの作業管理ファイルを置きます。~ は利用者のホームディレクトリーを表します。AI の実行環境が異なる場合は、その環境から読める場所を明示してください。

ホームディレクトリー/
  AGENTS.next.md       共通運用ルール

対象プロジェクト/
  NEXT.md             再開の入口
  DECISIONS.md        判断と理由
  backlog.md          後に取り組む課題
  README.md           導入・ビルド・利用方法
  src/                ソースコード

ファイル名だけで、どの AI でも自動的に読み込むわけではありません。利用する AI にファイルを読む手段と権限があり、参照指示を理解できることが前提です。初回は、共通ルールと三つのファイルを読めたか確認します。ファイルを直接読めない環境では必要な内容を渡し、更新結果を人が保存する方法も取れます。

NEXT.md を含む作業管理テンプレートは、筆者の GitHub リポジトリー qt-tools / work-templates で公開しています。NEXT.md、AGENTS.next.md の全文、DECISIONS.md、backlog.md と 利用ガイド を参照できます。日本語版に加えて英語版もあります。

導入時は、GitHub の各ファイルを開き、Raw 表示から内容を取得して保存します。共通ルールはホームディレクトリーへ、三つの作業管理ファイルは対象プロジェクトへ配置してください。既存ファイルがある場合は上書きせず、差分を確認して必要な内容を取り入れます。説明用の項目は、自分の作業の現在地と判断に置き換えます。

共通ルールには、少なくとも次を明記します。これは記事用に整理した導入時の確認項目であり、配布テンプレート全文ではありません。

1. NEXT.md の読み込み依頼では、DECISIONS.md と backlog.md も読む。読み込みだけでは変更しない。
2. 更新依頼では、三つのファイル、関連文書、実ファイル、Git の差分と直近のコミットを確認する。
3. 現在地、継続する判断、後の課題を分類して、必要なファイルを更新する。
4. 無関係な変更を保護する。日付や行数だけを理由に情報を削除しない。
5. セクション単位の削除、複数の独立項目の削除、設計判断や不採用理由の削除、大幅な再構成は、通常更新として自動実行しない。対象・理由・移動先を示し、変更前に利用者の承認を得る。
6. 更新後は差分を確認し、ファイル別の変更内容と検証結果を報告する。

NEXT.md 冒頭には、次のように共通ルールへの参照を書きます。既存ファイルがある場合は、空のテンプレートで上書きせず、内容を確認して取り入れます。

# NEXT

このファイルを読む、または更新する前に、~/AGENTS.next.md を読み、
その指示に従うこと。
~/AGENTS.next.md が存在しない場合は、このファイルを整理・削除せず、
利用者に確認すること。
このルールは、ユーザーから明示的な指示がない限り変更しない。

4. QML の性能調査を記録する例

ここからは「一覧画面のスクロールが引っ掛かる」という架空の調査を例にします。最適化方法を決める前に、再現条件と測定方法を整えている段階です。記録中のパスも例示なので、自分のプロジェクトに実在するファイルへ置き換えてください。

NEXT.md：次の作業に着手できる記録

前節の参照指示に続けて、次の内容を書きます。

## 対象の版と確認記録
- 最終確認日：YYYY-MM-DD（実際に確認した日へ置換）。
- ブランチ：調査に使うブランチ名を記入。
- 対象コミット：調査対象ソースのコミットIDを記入。
- 未コミットのソース変更：なし（ある場合は対象と保存先を記入）。
- 検証記録：docs/performance-plan.md。トレースは未採取。

## 現在の状態
- 目的：一覧画面のスクロール時の引っ掛かりを調査する。
- 再現操作と入力データを docs/performance-plan.md に整理済み。
- 原因は未確定。修正前のトレース採取はまだ行っていない。
- 使用する Qt、Qt Creator、OS、ビルド構成は同文書に記録済み。

## 次にやること
1. 記録した条件で再現を確認し、修正前のトレースを採取する。
2. 統計と時間軸を確認し、調査対象を一つ選ぶ。

## 未完了
- 修正前の計測と原因の切り分け。改善効果はまだ判断できない。

## 触るファイル
- docs/performance-plan.md：実際に使った採取条件を追記する。
- docs/performance-results.md：採取結果と未確定事項を新規記録する。

## 注意
- 計測前に src/qml/DeviceList.qml を最適化しない。
- 開発用 PC の結果だけで、対象機器の性能を判断しない。

## 関連ファイル
- DECISIONS.md：調査の順序と、その理由。
- backlog.md：原因調査後の評価項目。
- docs/performance-plan.md：入力、操作、環境、採取手順。

「整理済み」と書く前に、その文書が存在し、必要な条件が実際に記載されているか確認します。次に触るファイルには、パスだけでなく変更する理由も添えます。次の行動を一つか二つに絞ると、再開直後に着手順を考え直す負担が減ります。

DECISIONS.md：結論だけでなく理由を残す

# DECISIONS

## 計測後に修正方法を決める
- 判断：再現条件と修正前の結果を残してから変更する。
- 理由：原因が未確定で、変更前後の比較対象が必要なため。
- 現時点で採らない案：一覧の実装を先に全面的に書き換える。
- 不採用の理由：複数の変更が混ざると、効果の原因を追いにくい。
- 再検討条件：計測で構造上の問題が確認され、局所修正では
  必要な応答を得られないと判断した場合。

## 評価範囲
- 開発用 PC での確認と、対象機器での確認を区別する。
- 対象機器での合格条件は未決。
- 装置の操作要件と実測結果を確認して決める。

この記録があれば、次の AI や担当者は、全面的な書き換えを見送った理由を理解できます。前提が変わった場合は、以前の判断に固執せず、変更日、新しい判断、変更理由を残します。

backlog.md：後の課題をなくさず、今の作業と分ける

# Backlog

## 原因調査後に取り組むこと
- 修正候補を同じ入力・操作条件で比較する。
- 対象機器で応答、表示、メモリー使用量を確認する。
- 長時間動作とデータ件数増加時の評価を行う。

## 保留
- 一覧以外の画面の最適化。
  理由：まず今回の再現条件で原因を絞る。
  再検討条件：修正と対象機器での評価が完了した後。

性能調査そのものの進め方は、別記事「QML の性能を測定結果から読み解く — qmlprofileranalyzer の活用」で扱っています。ここでの要点は、未測定を測定済みにせず、仮説と結果を区別して次へ渡すことです。

5. 終了時と再開時の依頼を決める

共通ルールと参照関係を用意すると、日常の依頼は短くできます。作業を中断するとき、テーマが変わったとき、一区切りついたときに更新します。

NEXT.md を更新してください。

AI は実際の変更と検証記録を照合し、三つのファイルを必要に応じて更新します。たとえば、トレースを採取できたなら、保存先、採取条件、確認できたこと、残った仮説を記録し、次の行動を進めます。処理を実行しただけで結果を見ていない場合は、確認済みと書きません。

次は、トレースを採取して内容を確認した後の更新例です。これも架空の例であり、測定値や性能改善を報告するものではありません。第4節の記録をそのまま追記し続けるのではなく、現在の状態と次の行動を更新します。共通ルールへの参照や注意事項は維持します。

## 対象の版と確認記録
- 最終確認日：YYYY-MM-DD（トレースを確認した日へ置換）。
- ブランチ・対象コミット：採取に使った実際の値を記入。
- 未コミットのソース変更：なし。最適化はまだ行っていない。
- 検証記録：docs/performance-results.md。
  採取条件、トレースの保存先、対象ソースの版を記録済み。

## 現在の状態
- 記録した入力と操作で、修正前のトレースを採取した。
- 統計と時間軸を確認し、一覧項目の生成処理を次の調査対象にした。
- 生成処理が引っ掛かりの原因かは未確定。改善効果も未検証。

## 次にやること
1. トレース内の対象区間と DeviceList.qml の処理を照合する。
2. 仮説と追加の確認方法を docs/performance-results.md に記録する。

## 未完了
- 原因の切り分けと修正候補の検討。改善効果はまだ判断できない。
- 対象機器での確認は未実施。

## 触るファイル
- src/qml/DeviceList.qml：対象処理を読む。原因を絞るまでは変更しない。
- docs/performance-results.md：既存の採取結果に仮説と確認方法を追記する。

コミットIDは、この記録自身を含むコミットを予測して書くのではなく、実際に計測したソースの版を記します。未コミットのソース変更がある場合は、コミットIDだけでは再現できないため、変更内容と引き継げる差分の保存先も残します。

再開時は、次のように依頼します。

NEXT.md を読んでください。

この段階では状態を把握し、記録と実ファイルに食い違いがあれば報告します。読む依頼だけを、コード変更や文書の整理を始める指示にしないことが大切です。

翌日、記録と参照先を実際に読めた場合には、次のような再開時の確認ができます。

修正前のトレース採取と統計・時間軸の確認まで完了しています。
原因は未確定で、最適化もまだ行っていません。
次は対象区間と DeviceList.qml の処理を照合します。

この要約を見て、人が続きを指示します。トレースを開けなかった場合や、記録後にソースが変わっていた場合には、その違いを先に報告し、確認済みの範囲を広げて表現しません。

コミットも行う場合は、更新と区別して明示します。

NEXT.md を更新し、必要なファイルと合わせてコミットしてください。

コミット対象には、今回の成果物と対応する記録を含めます。関係のない未コミット変更は混ぜません。リモートへの push も、記録更新とは別の操作として扱います。

人は更新報告から現在地を確認し、疑問がある箇所は元の差分や検証結果を見ます。毎回すべてのログを読み直すためではなく、必要な根拠へ戻れるようにするための仕組みです。

6. 別端末・別担当者へ渡すときの確認

三つの記録だけを移しても、未コミットのソース変更は移りません。成果物と記録を同じ版として渡すことが前提です。Git を使う場合はブランチと対象コミットを明確にし、必要な変更を取得できる状態にします。未コミット変更を渡すなら、差分本体と適用先も必要です。

ホームディレクトリーの共通ルールは、プロジェクトを Git で取得しただけでは配置されません。既存ルールと内容を比較して用意します。また、受け取り側に未コミット変更があれば、それを保護してから取り込み方法を決めます。

ソース配布時に判断記録を添えることもできます。たとえば、ある依存ライブラリーを採らなかった理由や、未検証の環境を明示すれば、利用者は改修の前提を理解できます。ただし、内部の検討記録をそのまま公開するのではなく、配布する版に対応させ、認証情報、顧客情報、社内限定情報を含めないように確認します。

7. 長く使うための整理と限界

筆者の運用では、日付付きの作業記録を、直近5実作業日以内、または現在のテーマが完了するまでを目安に整理します。実作業日は、実際に作業・判断・検証・コミットを行った日です。セッション数や暦日だけで数えません。この期間は必須ルールではなく、作業の規模や引き継ぎの間隔に応じて調整する運用上の目安です。

この目安は、現在も有効な設計判断、不採用理由、仕様、制約の有効期限ではありません。「古いから消す」と、再び同じ議論が必要になります。長い完了履歴や検証ログを整理する前に、同じ情報が専用文書や特定できる Git コミットに保存され、参照できることを確認します。

ファイルに書いた内容は、常に正しいとは限りません。AI がすべてを記憶する保証にもなりません。実際のファイル、差分、検証結果と照合して初めて、次の判断に使える記録になります。

8. 一つの作業から始める

まず、いま中断している作業を一つ選び、「どこまで確認したか」「次に何をするか」「なぜその順序か」を書いてみてください。翌日の自分や別の担当者が、元の会話を探さずに着手できるかを確かめます。

Qt 5 から Qt 6 への移行、QML の性能調査、ビルド環境の整備など、判断と検証を重ねる作業ほど、コードと一緒に背景を残す意味があります。短い依頼で再開できるようになることに加え、同じ前提での検討の繰り返しを減らし、必要なときに判断を見直しやすくなります。

本記事の資料と関連する技術記事

本記事は、筆者のセミナー資料「作業コンテキスト管理と NEXT.md」（ドラフト v0.4.6）と「作業コンテキスト管理テンプレート 利用ガイド」を基に、Qt 開発向けの例と確認事項を加えたものです。社内・ローカル環境の参照先に依存せず読めるよう、導入手順と記入例を本文にまとめました。

• QML の性能を測定結果から読み解く — qmlprofileranalyzer の活用
• Qt 5 から Qt 6 への移行戦略 — 移行先の選定から段階的な実施・検証まで
• Qt の開発支援・コンサルティング