課題
AIと一緒に開発していると、記録のファイルが増えていく。今の方針を書く「計画書」、作業項目ごとの状態をまとめた「状態表」、毎回の作業を日付順に追記していく「作業記録」。自分の場合、書くのはほとんどAIで、自分は読んで判断する側。
そこに「確認済み」と書いてあれば、普通はそのまま信じて次へ進む。でも、その「確認済み」は、誰が、いつ、何を見て書いたものなのか。
今回の例は、空き時間で進めている小さなロボットアームの工作。キーボードで関節を動かす仕組みを、AIと記録を残しながら作っている（直近のMuJoCoで『このサーボでは届かない』と出たロボットアームの話では、部品を買う前にシミュレータで形を決めた流れを書いた）。
その計画書と状態表に、こう書いてあった。
「キーボードで関節を動かす機能は、Raspberry Pi（アームを動かす小さなコンピュータ）の実機で動作確認済み」
ところが10月13日、出どころを辿ってみると、この一文には裏付けが1つも無かった。誰も確かめていなかった。
同じ週には、同じ形のずれがあと2つ見つかった。どれもロボットアームならではの話ではなく、記録の残し方の話。AIと記録を残しながら開発しているなら、同じ形に出会うかもしれない。
解決できるようにすること
- 計画書や状態表にある「確認済み」「待ち」のような今の状態を書いた一文に、裏付けがあるかを、日付順の記録と変更履歴まで辿って確かめられる
- 「確認しました」という報告を受けたとき、その報告が答えていない問いを、ログなどの元の資料で確かめられる
- 決めたあとや区切りのタイミングで、古くなった記述を探す点検ができる。追記するだけでは、古い一文は消えない
先に結論
- AIと記録を残しながら開発していると、計画書や状態表のような今の状態を書く文書は、いつ・何を根拠にそう書いたかを持たない。そのため、裏付けのある一文も無い一文も、同じ書き方で並ぶ。今回、ロボットアームの工作で、その形のずれが3つ見つかった
- 計画書と状態表に「キーボード操作の機能はRaspberry Piの実機で動作確認済み」とあった。10月13日、AIがPiに接続すると、この工作のプログラムもテストの道具も入っていなかった
- AIは書き換える前に、自分へ確認した。自分が覚えていたのは「サーボが正常に動いた」報告で、キーボード操作を確かめた報告ではなかった
- 日付順の作業記録には、むしろ「実機での確認は未実施」と2回書いてあった。変更履歴を検索すると、この一文は8月23日、記録の置き場所を独立させて文書の雛形を作ったときに、最初から書かれていた。裏付けのないまま10月13日まで残っていた
- そのあと自分が実機で試して「確認した」と報告すると、AIはログを直接読んだ。位置の保存・呼び出しが一度も使われていないことは、報告の文面からは分からなかった。一方でAI自身も、ログの末尾25行だけで「端までの確認は未」と言い切り、あとで訂正している
- 10月20日にも、同じ形のずれが2つあった。部品は10月15日に届いていたのに、5日間「部品待ち」と書かれていた。再開できるかの点検では、作業はすべてコミット済みなのに、計画書や状態表に7件の古い記述と漏れが残っていた
この記事でわかること
- 「確認済み」の一文が、本当に誰かの確認に基づいているかを辿る手順
- 報告をそのまま受け取らずに、「報告が答えていない問い」を元の資料で確かめるやり方
- 「予定」「待ち」のような条件付きの記述と、決定で否定された古い記述を残さないための点検
ここで、こう思う人もいるかもしれない。
「計画書に『確認済み』と書いてあるなら、それを信じて先へ進めばいいのでは？」
普段はそれでいいと思う。いちいち疑っていたら進まない。
ただ、計画書や状態表は「今どうなっているか」だけを書く文書で、「いつ、誰が、何を見てそう書いたか」は残らない。今回の一文も、ちゃんと確認された記述のすぐ隣に、同じ書き方で置かれていた。見た目では区別できない、というのがいちばん困るところだった。
前提: この工作の記録は「今を書く文書」と「日付順の記録」に分かれている
この工作の記録は、大きく2種類に分かれている。以前に書いたAIとの開発で「続きから」がうまくいかないのを4つのファイルで防ぐ方法と同じ考え方の分け方になる。
| 種類 | 何を書くか | 書き方 |
|---|---|---|
| 計画書・状態表 | 今の方針、作業項目ごとの状態（完了・作業中など） | 今の形に書き換える。古い内容は残さない |
| 作業記録 | 何をして、何が分かって、何が未解決か | 日付順に追記するだけ。消さない |
| 変更履歴（Git） | どのファイルの、どの行を、いつ変えたか | 変更をまとめて確定する「コミット」ごとに自動で残る |
計画書と状態表は、読めばすぐ今の状態が分かるのが強み。そのかわり、書いた根拠は持っていない。根拠を辿るときは、作業記録と変更履歴のほうを見ることになる。
1件目: 「実機で動作確認済み」の出どころを辿った（10月13日）
Piの中に、確認に使ったはずのものが無かった
10月13日、AIがPiに接続して、配線の前に中の環境を整えていた。
そこでAIが気づいたのは、Piの中に、この工作のプログラムも、テストを走らせる道具も入っていなかったこと。キーボード操作の機能を実機で確かめたのなら、ここに何か残っていそうなもの。
AIは、別のPiで確かめた可能性や、同じSDカードに入っている別のOSで確かめた可能性も挙げた。そのうえで、「記録の正確さに関わるので、確認するまで書き換えない」として、計画書には手を付けずに自分へ報告してきた。
自分の記憶と、記録の突き合わせ
報告を見て、自分はこう返した。
「Raspberry Piの実機で動作確認済みと報告したか？ サーボモーターが正常に動くのを確認した報告は、した記憶がある」
AIは記録を調べ直した。結果は、自分の記憶のほうが正しかった。
- 日付順の作業記録に、キーボード操作の機能をPiで確かめたという報告は1件も無かった
- むしろ8月22日の記録が2か所で逆のことを書いていた。1つは「実機での動作確認は未実施」、もう1つは「Raspberry Piで問題なく動くかは未検証で、実施結果待ち」という趣旨
- 変更履歴を、文字列で検索した。Gitには、ある文字列が追加・削除されたコミットを探す方法（
git log -S "文字列"）がある。たどり着いたのは8月23日のコミットで、この工作の記録を独立した置き場所へ移し、計画書と状態表の雛形を作ったときのもの
つまり、確認した結果をあとから書き足したのではなかった。雛形を作ったAIのセッションが、裏付けなしに最初からそう書いていた。8月23日から10月13日まで、そのまま残っていたことになる。
「あれ、ずっと確認済みのつもりで読んでたな」
記録では、2つの別の事実が混ざっていた、と整理されている。
- サーボ4個が正常に動くこと（10月12日に自分が報告。本当にあった）
- キーボード操作の機能を、Piの上で人が操作して確かめたこと（無かった）
計画書には「サーボ4個は動作確認済み」という、ちゃんと裏付けのある一文もあった。こちらが本当だったことが、もう1つの一文にも裏付けがあるように見せていた可能性がある、と記録は書いている。
AIは計画書と状態表を「仕組みは自動テストで確認済み、人が操作しての確認は未実施」に書き直した。作業項目の状態は「完了」のまま。作るべきだったのはプログラムで、動きの仕組みは自動テストで確かめてあるから、という理由になる。
確かめてみたら、報告だけでは分からない穴があった
ここで、残りは自分が試すだけになった。Piでキーボード操作のプログラムを起動して、関節を選んで、矢印キーで角度を動かす。終わってから「目視で確認した」とAIに伝えた。
AIは、この報告をそのまま記録しなかった。プログラムが書き出すログを直接読んで、裏を取っている。記録には理由も書いてあって、AIはその日、この件を含めて「確かめずに言い切った」例を3件記録した直後だった。
ログで確かめられたのは、たとえばこういう動き。
- 起動すると、全部の関節がホームの90度へ動く
- 上キーで95度、下キーで90度、85度と、5度ずつ動く
- 関節の選択を進めると、最後の関節から最初の関節へ戻って一周する
- ホームへ戻す操作で、90度へ戻る
ここまでは報告どおり。そのうえで、AIは「ログから見て確かめられていないこと」を2つ挙げてきた。
- 動かせる範囲の端（0度・180度）で止まる処理は、まだ確かめられていない
- 位置を保存して呼び出す機能は、一度も使われていない。保存先のファイルが存在しないので、そう言い切れる
ここで、こう思う人もいるかもしれない。
「自分で『確認した』と言っているのに、ログまで読むのは疑いすぎでは？」
自分の報告は事実だった。ただ、「何を確かめて、何を確かめていないか」までは、報告の文面からは分からない。記録には「報告を疑ったのではなく、報告が答えていない問いがあることを前提に、元の資料を見た」とある。実際、位置の保存・呼び出しを試していないことは、自分でも意識していなかった。
自分が残りの操作を試したあと、AIはログ全体と保存ファイルを読んで、こう確かめている。
- 端で止まる処理: ログ全体で「180度へ」が31回、「0度へ」が14回。同じ角度が何度も続けて記録されるのが、端で止まっている跡になる（端でキーを押し続けても、角度が同じ値のまま返ってくるため）
- 位置の保存・呼び出し: 保存ファイルに位置が1つでき、呼び出すと全部の関節がそろって90度へ戻った記録がある
そしてAIは、自分の誤りも1つ訂正している。前の報告の「端までの確認は未」は、ログの末尾25行だけを読んで、ファイル全体を判断した結果だった。記録には「範囲を限定して読んだのなら、結論もその範囲に限定すべきだった」とあり、その日の4件目の「確かめずに言い切った」例として残されている。
元の資料を見に行く、という方針は合っていた。それでも、資料の一部だけで全体を言い切ると、同じ型の誤りになる。ちょっと耳が痛い。
2件目: 「部品待ち」が、届いてから5日間残っていた（10月20日）
10月14日、配線に使うジャンパーワイヤと、電源用のコネクタを注文した。注文するのは自分。
この時点で、工作の状態表では、配線の作業は「ジャンパーワイヤが手元に無い」ことで止まっている扱いになっていた。作業記録にも「未実施: 購入の実行」とあった。
一方、自分が支出をまとめている別の記録には、10月14日の時点で購入がちゃんと記録されていた。到着については「10月15日の予定で、確定ではない」と条件付き。書き方としては正しい。
10月20日、AIが「ジャンパーワイヤとコネクタは届いたか」と確認してきた。
届いていた。しかも注文の翌日、10月15日に。届いたことを、どちらの記録にも書いていなかった。だから配線の作業は、5日間、いつでも始められる状態のまま「部品待ち」と書かれていた。
記録では、原因をこうまとめている。
- 購入も到着も会話の中だけで済んで、「届いた」という事実がどの記録にも入らなかった
- 支出の記録は「予定」と条件付きで正しく書いていた。ただ、その条件をあとで外す担当が決まっていなかった
- 2つの記録が同じ事実について食い違っていて、作業を動かしていたのは古いほうだった
記録上の実害は「5日の空走」。でも、同じ形で「届いていないと思って、もう1回注文する」ことも起こり得た、と書かれている。
対策として残されたのは、「届いた、開けた、動いた」のような物が手元に来た事実は、会話で確かめた時点で記録へ書くこと。支出は買った時点で書かれるけど、到着はそのあとに起きるので、同じ行をあとから更新する必要がある。
3件目: 全部コミットしてあったのに、再開できる状態ではなかった（10月20日）
同じ10月20日、自分からAIに頼んだ。
「セッションが失われても再開できるよう、記録漏れがないか確認してほしい」
その日はシミュレータで寸法を決めたり、部品を選んだり、作業がかなり多かった。AIは「コミットしてあるから大丈夫」とは考えず、計画書・状態表・作業項目の一覧を読み直している。
結果、その日の作業はすべてコミット済みで、テストも135件すべて合格。なのに、今を書く文書のほうに7件の問題が残っていた。
| # | 見つかったこと |
|---|---|
| 1 | その日に起こした作業項目（キーを押すと腕が浮く問題）が、状態表に入っていなかった |
| 2 | 部品を注文して組み立てる作業項目が、やめた4軸の直列アームの内容のままだった |
| 3 | 実機での測定の作業項目も古く、その日に分かった「シミュレータでは分からない量」（歯車のガタ、穴のすきま、部材のたわみなど）が入っていなかった |
| 4 | シミュレータの作業項目が、条件を全部満たしているのに「作業中」のままだった |
| 5 | 計画書の「次にやること」が古かった |
| 6 | 計画書の「手元にある部品」が古く、届いた配線が反映されていなかった |
| 7 | 計画書に、その朝「成り立たない」と確かめた記述が、今の形のまま残っていた |
いちばん重かったのは2。注文して組み立てる、まさに実行する側の作業項目が古い設計のままだった。その日の決定は全部、検討した側の作業項目（シミュレータ）に書かれていて、実行する側から辿れなかった。ここだけ読んで部品を注文していたら、設計を取り違える。
「コミットしたから終わり、じゃなかったのか」
7も、地味に効く話だった。パラレルリンク（根元のモーター2個で腕を動かす仕組み）という形を選んだとき、理由の3つ目に「平行四辺形がペンの向きを一定に保つ」を挙げていた。これはその朝、今の作りでは成り立たないと確かめて取り消している。新しい方針は、計画書に新しい節として追記されていた。
でも、古い節の中の一文は消えていなかった。同じ計画書の中に「ペンの向きは一定に保たれる」と「ペンの傾きは結果として決まり、最悪で9.5度」が同居していた。
記録の結論は2つ。
- 「コミットしてある」ことと「再開できる」ことは別。漏れなく保存されていても、実行する作業項目から必要な決定に辿れなければ、再開した人は迷う
- 追記で今の形にできるのは半分だけ。新しい節を足せば新しい方針は書けるけど、もう成り立たない古い一文は消えない。決めるたびに、「その決定が否定した記述が、今を書く文書のどこかに残っていないか」を探す
再開できるかの点検で綻びが見つかる話は、以前にAIとの開発を管理する『4つのファイル』運用で綻びが3つ見つかった話でも書いた。そちらは、ルールを書いても実行する担当がいないと運用がずれていく話。今回は、追記だけでは否定された一文が残る、という別の抜け方だった。
3つに共通していたこと: 今を書く文書は、根拠を持たない
記録では、1件目の時点でこう書かれている。計画書や状態表は履歴を持たないので、裏付けがあるかどうかが文書の上からは見えない。今回は、日付順の作業記録を消さずに追記だけで残していたから、突き合わせて見つけられた。
3件を並べると、残っていた記述の形はそれぞれ違った。
- 1件目: 最初から裏付けのない「確認済み」
- 2件目: 条件付きで書いた「予定・待ち」が、条件を外されないまま残った
- 3件目: 決定で否定された古い一文が、新しい記述と並んで残った
どれも、計画書や状態表だけを読んでいる限り、正しい記述と見分けがつかない。見つけたきっかけも、Piの中身、自分の記憶、AIからの問いかけ、自分が頼んだ点検とばらばらだった。
ここからは自分の見立てになるけど、「今の文書は正しい」と前提にしているときほど、こういう一文は読み流してしまう気がする。だから、気づいたときに辿る手順を持っておくのが効くと思う。
AIと記録を残しながら進めるときの確かめ方
今回の流れを、ほかの場面でも使える形にまとめるとこうなる。
- 「確認済み」「完了」を見たら、日付順の記録にその報告があるか探す。 無ければ変更履歴で、その一文が入った日を探す。Gitなら
git log -S "その一文"で、追加したコミットまで辿れる - 2つの事実が混ざっていないかを分ける。 「サーボが動いた」と「キーボード操作を実機で確かめた」は別の事実。片方が本当だと、もう片方も本当に見えやすい
- 報告を受けたら、「この報告が答えていない問い」を挙げて、ログや作られたファイルで確かめる。 報告を疑うためではなく、報告の文面に書かれていないことを埋めるため
- 元の資料の一部だけを読んだなら、結論もその範囲に限る。 末尾25行で「未確認」と言わない
- 「予定」「待ち」と書いたら、その条件をいつ外すかも決めておく。 届いた、開けた、動いた、は会話で確かめた時点で記録へ書く
- 決めたら、その決定が否定した記述を、今を書く文書から探して直す。 新しい節の追記だけで終えない
- 区切りでは「コミットしてあるか」ではなく、「実行する側の作業項目から、必要な決定に辿れるか」を点検する
AIに頼むなら、たとえば「この『確認済み』は、いつの、どの記録が根拠？ 見つからなければ、見つからないと書いて」「今決めたことで成り立たなくなった記述が、計画書や状態表に残っていないか探して」と一言添えると、1と6を飛ばしにくくなると思う。
まだ確かめていないこと
- 実物のアームはまだ組んでいない。記録の時点（10月20日）では、配線の最初の段階も、骨組みの部品の注文もまだ
- 「決めるたびに、否定された記述を探す」「届いたら記録へ書く」という対策が、その後も守られているかは、この記録の範囲（10月20日まで）では分からない
- 雛形を作ったAIのセッションが、なぜ「実機で動作確認済み」と書いたのかは、記録に残っていない
- 7件の点検で見つからなかった古い記述が、ほかに残っていないかは確かめていない
こんな人に向いている
AIと一緒に、計画書や作業の一覧、作業記録のようなファイルを残しながら、個人開発をしている人に向いている。
特に、AIが「完了」「確認済み」と書いた状態表を、そのまま次の作業の前提にしている人。書いてあることを信じて進めていい場面と、出どころを辿ったほうがいい場面を分ける材料になるはず。
まとめ
AIと記録を残しながら開発していると、計画書や状態表の「確認済み」が、誰も確かめていない一文のことがある。今回の例では、ロボットアーム工作の計画書と状態表にあった「Raspberry Piの実機で動作確認済み」が、そうだった。日付順の記録には逆に「未実施」とあり、変更履歴を辿ると、記録の置き場所を独立させた日の雛形に最初から書かれていた。
実際に確かめると、自分の「確認した」という報告だけでは分からない穴がログから見えた。そして同じ週に、「届いたのに部品待ち」と「コミット済みなのに再開できない」という、同じ形のずれがもう2つ見つかった。
| 項目 | 内容 |
|---|---|
| 結論 | 今を書く計画書・状態表は根拠を持たないので、裏付けのない「確認済み」、外されない「予定・待ち」、否定された古い一文が、正しい記述と同じ顔で残る。日付順の記録と変更履歴、ログで辿って見つけた |
| 教訓 | 「済み」は出どころを辿る。報告が答えていない問いは元の資料で確かめる。決めたら否定された記述を探す。コミット済みと再開できるは別 |
| 対象読者 | AIと記録を残しながら個人開発している人 |
同じ状況に陥ったときの回避策
- 「確認済み」の一文に引っかかったら、日付順の記録で報告を探し、無ければ変更履歴で追加された日を探す
- 似た2つの事実（部品が動いた／機能を実機で確かめた）を分けて、どちらの裏付けかを確かめる
- 「確認した」と報告されたら、報告が答えていない問いを挙げて、ログや作られたファイルを読む
- 資料の一部だけを読んだときは、結論もその範囲に限る
- 「予定」「待ち」と書いたら、外すタイミングを決めておき、届いた時点で記録へ書く
- 何かを決めたら、その決定で成り立たなくなった記述を、今を書く文書から探して直す
- 区切りでは、実行する作業項目から必要な決定に辿れるかを点検する
次に読むなら
今を書く文書の一文を辿れたのは、日付順の記録を消さずに残していたから。まだ記録の分け方を決めていないなら、計画・状態・作業記録をどう分けて残すかから始めると、同じ辿り方ができるようになる。
- AIとの開発、なぜ「続きから」がうまくいかない？4つのファイルで防ぐ方法 — 決定事項・進捗・状態・作業記録を4つのファイルに分けて残し、AIとの作業をどこからでも再開できるようにする方法
この記事は、筆者が個人の空き時間で取り組んでいるロボット工作（アーム型ロボットの制御）の開発記録（2026年8月22日〜10月20日）を基に、独自調整したAIが下書きを作成し、筆者が事実確認・編集を行った上で公開しています。本文の説明図は、記録の内容をもとにAIが作成しています。
