マニュアルと実物がズレる

実際に起きたこと7件

• 自動化

  「できない」と自分で書いた記録を、1ヶ月そのまま信じていた

  以前に作った仕組みの手順書に、「この数字は画面でしか見られない。プログラムからは取れない」と書いていました。だから毎回、手で書き写していました。

  別のものを作っているときに、たまたま同じ機能をプログラムから叩いてみたら、あっさり取れました。 命令1行です。

  書いた時点では合っていたのかもしれません。 ただ、その後に何度も同じ場所を触っているのに、一度も確かめ直していませんでした。

  「できる」と書いたことは、使うたびに検証されます。 動かなければすぐ分かるからです。「できない」と書いたことは、誰も試さないので、間違っていても永遠に残ります。

• 自動化

  「前と同じやり方で」と決めて、比べなかった

  似た仕組みを2つ目に作るとき、「1つ目と同じやり方を移植する」と決めました。予定表にも「別の方法は不要」と書いています。

  ところが1つ目の手順書には、別のやり方も使えると自分で書いてありました。 読んでいたのに、選択肢として見ていませんでした。

  結局そのあと、1つ目のやり方では物理的に無理だと分かって、別のやり方に切り替えました。判断して変えたのではなく、行き止まりに当たって変えただけです。

  移植は楽なので、比べる手間を飛ばす動機が働きます。 「前と同じで」は結論に見えますが、たいてい過去の判断をそのまま置いただけです。

• 書類作成

  説明書に書いてある処理が、実際には動いていなかった

  ツールと一緒に、マニュアルもAIに書いてもらっていました。あとから読み返して気づきました。

  マニュアルには「この情報を使って計算します」と書いてあるのに、実際の処理では使われていませんでした。

  説明書もAIが書き、中身もAIが書いています。両方それらしいので、突き合わせない限り分かりません。

• 会議録ツール

  毎回言わないと、説明書は更新されない

  中身を直すたびに「仕様書やマニュアルにも反映してね」と指示しないと、説明書は前のままです。

  中身を直したことは覚えていても、説明書を直し忘れたことは覚えていません。

• 書類作成

  ファイルを開いたままで、更新が入っていなかった

  マニュアルを開いたまま作業していたので、更新が反映されていませんでした。

  手元の画面には古い内容が出たままです。直したつもりでいました。

• 会議録ツール

  自分で作らせたのに、何で動いているか分からなくなった

  「このツールはAIを使っていますか」と、自分でAIに聞き返しています。

  指示したのは自分です。それでも、しばらく経つと何がどう動いているのか分からなくなりました。

• 会議録ツール

  自分では確かめられないと気づいた

  「バグがないか、客観的な目線でチェックしてください」とAIに頼んでいます。

  作ったのもAI、点検するのもAIです。この構造に気づいたときは、少し怖くなりました。

そもそもの原因

説明書と中身が、別々のタイミングで書かれるからです。中身を直したときに説明書を直し忘れる。しかも説明書のほうが、それらしく書けてしまいます。

この型を防ぐには

やることは3つです。渡す相手が、それぞれ違います。

次の決まりを、いま作業しているフォルダの CLAUDE.md に書き足してください。
ファイルが無ければ作ってください。

処理を直したら、同じ作業の中でマニュアルと突き合わせてください。

1. マニュアルに書いてあるが、実際には行われていない処理
2. 実際には行われているが、マニュアルに書かれていない処理
3. 書かれている手順と、実際の順番が違う箇所

そのうえで、マニュアル側を実物に合わせて直してください。直した箇所は、何をどう変えたか一覧にしてください。

守ってほしいこと
・文はそのまま書いてください。言い換えないでください
・すでにある決まりは消さないでください
・似た決まりが既にあれば、書く前に教えてください
・書いたあと、CLAUDE.md 全体をそのまま表示してください