AIが書いた自動化コードを、原本で試さない｜投稿CSVで学ぶ、小さな自動化の検査

ファイルができた。エラーも出なかった。それでも、変換が正しいとは限りません。

投稿番号の「0007」が「7」になっていたり、二行に分けた文章が一行につながっていたりする。画面に「完了」と出るだけでは、残したかったものが残ったかまではわかりません。

AIに小さなコードを書いてもらえるようになると、作る前より、使ってよいか決めるところで迷います。コードを全部読めないまま試すのは不安。でも「気をつけて確認する」だけでは、何を見ればよいのかが曖昧です。

この記事では、確認する条件を先に書き、実際のファイルで答え合わせをします。架空の投稿CSVから確認用JSONを作る、小さな教材を用意しました。意図的に間違えた変換、修正版、出力を壊す練習を通して、「動いた」と「条件を満たした」を分けます。

GitHubのAI生成コードをレビューするための案内でも、要件との一致、テスト、人による確認が扱われています。この資料は本教材の効果や安全性を保証するものではありません。ここでは、その考え方を一つの固定された小さな処理で練習します。

最後に、自分で作った架空の一件を追加し、同じ検査をやり直します。目標は、未知のプログラムを安全と言い切れることではなく、「何を残し、何を拒否し、何と照合したから、この結果を採用するのか」を一件で説明できることです。

練習ZIP（26ファイル・記入シート付き）は、記事末尾の添付から無料で取得できます。展開後、README.mdとguard.pyのあるフォルダから始めてください。

始める前に、対象と限界を決める

対象は、すでにPythonを実行できる環境があり、フォルダを開いて短いコマンドを一行ずつ実行できる人です。コードを書く経験は多くなくても構いませんが、Pythonの導入や端末の基本操作は扱いません。

読む時間を含めて35〜60分ほどの練習を想定しています。これは設計上の目安で、一般読者の所要時間を測定した結果ではありません。教材はPython標準ライブラリだけを使い、追加パッケージ、外部AI、APIキー、有料契約は不要です。

制作時の実行検査はLinux・Python 3.12.14で行っています。Windows、macOS、別バージョンでの動作を実測したわけではありません。端末でのPythonの呼び出し方が違う場合は、以下の「python」を自分の環境で確認済みの呼び出し方に置き換えてください。

最初に守ることは四つです。

- 使うのは同梱の完全架空データだけ。顧客、売上、実在の投稿予定、秘密情報は入れない。
- 教材を展開した練習用フォルダで作業する。管理者権限を付けず、わからないエラーを権限拡大で解消しない。
- 結果は確認用のJSON。SNSへの投稿や予約、外部サービスへの取り込みには使わない。
- 別フォルダは安全な隔離環境ではない。この練習に通ったことを理由に、出所や動作がわからないコードを仕事用PCで実行しない。

プログラムの実行を認められていない端末なら、担当者に確認するところで止めてください。実データがすでに変わった場合の復旧も、この教材の範囲外です。上書きや再実行を重ねず、組織の担当者や利用サービスの窓口へ相談します。

今日扱うのは、架空の文具店の五件

教材の店舗「余白と線」、投稿文、番号、画像名は、すべてこの練習のために作った架空のものです。実在の依頼や成功事例ではありません。意図的な欠陥も教材用に作成したもので、実際に特定のAIが出した誤りの記録ではありません。

入力は fixtures/posts.csv。列は、次の順番で四つです。

post_id,caption,asset_name,status

post_id は投稿を見分ける文字列、caption は本文、asset_name は画像名の文字列、status は draft または ready です。画像ファイルを開く機能はありません。ready でも投稿は実行されません。

五件には、先頭ゼロ、半角カンマ、引用符、本文の途中の改行、前後の空白を含めてあります。単純な一行だけで試すと見落とす違いを、自分で見つけるためです。

この教材が受け付けるのは、BOMなしUTF-8、四列の名前と順番が一致する、1〜100件、ファイル全体が64KiB以下のCSVです。IDは半角数字1〜12文字で重複なし。本文は空白だけではなく1〜1,000文字、画像名は空白だけではなく1〜100文字。その他の制限は同梱の仕様書にまとめています。

これは世の中のCSV全部に当てはまる規則ではありません。たとえばBOM付きUTF-8を使うアプリもありますが、本教材では変換を勝手に推測せず拒否します。

PythonのCSV公式資料は、CSVの区切りや引用の違いを説明し、通常の読み取りでは各項目を文字列として返すとしています。「数字に見えるから数値にする」と決めるのは、CSVの必須動作ではありません。今回、番号を変えないのは、私たちが先に決める条件です。

1．実行する前に、合格条件を書く

まだコードは動かさず、次の五項目をメモします。手元のチェックシートにも同じ欄があります。

1. 入力ファイルの中身を変えない。
2. 五件の順番と四項目の値を変えない。番号の先頭ゼロ、本文の改行、空白も残す。
3. 確認用の新しいフォルダを作り、既存の結果を上書きしない。
4. 列不足、番号重複、不明な状態などは、推測して補わず止める。
5. 完了表示だけでなく、入力と実際の出力を照合する。

入力を変えないことと、入力どおりの出力を作ることは、別の条件です。もし入力と出力が一緒に変われば、二つを比較するだけでは見逃します。だから、実行前の入力の状態も残します。

教材フォルダに移動し、実行前のSHA-256を保存してください。

python -B source_hash.py save fixtures/posts.csv original.sha256

既存の保存先は拒否されます。この基準を処理の後に作り直さないでください。SHA-256はファイルの内容から計算する値です。前後の値が違えば、少なくとも同じバイト列ではありません。ただし、それだけで中身の正しさやコードの安全性が証明されるわけではありません。基準ファイルまで変更された場合や、最初から入力が誤っていた場合も見分けられません。

次に、入力の形式を確認します。

python -B guard.py check fixtures/posts.csv

OK check records=5 に続いてハッシュが表示されます。この段階では結果フォルダを作りません。

ここで OK になったのは、今回の入力条件に合ったということだけです。実在する文章の正確さ、投稿の許可、画像の権利まで確認した表示ではありません。

小さな完了条件は、「何を残すかを五つ書き、五件として読めると確認した」です。

2．ファイルはできたのに、不合格にしてみる

最初に使う authored_fault.py は、二つの欠陥を意図的に入れた練習用です。入力ファイルを上書きするプログラムではありません。新しいフォルダに、条件を満たさない結果を作ります。

run-01-fault というフォルダがまだないことを確認してから、一行ずつ実行します。

python -B authored_fault.py fixtures/posts.csv run-01-fault
python -B guard.py verify fixtures/posts.csv run-01-fault

一つ目は、欠陥入りの結果を作ったという表示で終わります。二つ目は FAIL validation となり、post_id mismatch や caption mismatch を含む差分を返すのが正しい動作です。

ここで「失敗したので先へ進めない」と思わなくて大丈夫です。今回は、通してはいけないものを止められたことが成果です。

run-01-fault/review.json をテキストエディタで開きます。最初の番号は、文字列の "0007" ではなく数値の 7 になっています。また、三件目の本文は途中の改行を失っています。

CSVの三件目は、物理的なファイルの三行目とは限りません。引用符の中に改行を含むためです。検査の record 3 は、見出しを除く三件目のデータを指します。

次のように、差と条件を結び付けてメモしてください。

- 番号：文字列で残す約束なのに数値になり、先頭ゼロを失った。
- 本文：文字をそのまま残す約束なのに、改行が空白へ置き換わった。
- 判定：結果ファイルは存在するが、採用しない。

検査器の表示を写すだけでなく、元CSVとJSONの該当箇所を一度見比べるのがこの段階の仕事です。最後に原本ハッシュを再照合します。

python -B source_hash.py verify fixtures/posts.csv original.sha256

OK source-hash verify なら今回の前後比較は一致です。以後も、各処理の後にこのコマンドを使います。

3．修正版で、別の結果を作り直す

欠陥入りフォルダを消す必要はありません。新しい名前を使います。

python -B guard.py build fixtures/posts.csv run-02-good
python -B guard.py verify fixtures/posts.csv run-02-good

両方が OK になったら、run-02-good/review.json と summary.txt を開きます。

確認するのは次の点です。

- 件数は5。順番は 0007、0012、0100、0101、0200。
- IDは引用符で囲まれた文字列で、先頭ゼロが残っている。
- 三件目の本文に改行が残っている。JSONでは改行が \n と表示されることがある。
- 二件目のカンマ、四件目の引用符、五件目の前後の空白が残っている。
- 集計は draft: 2、ready: 3。これは確認用の件数で、投稿実行数ではない。

JSONで引用符が \"、改行が \n と表現されることと、本文自体を変えてしまうことは違います。検査器はJSONを読み戻した値を入力と比較します。テキストの見た目だけでエスケープ表現を削らないでください。

build は作成後に読み戻して検査します。続けて verify を実行するのは、保存されたファイルそのものを改めて照合するためです。summary.txt にあるハッシュや件数だけを信用して終わる設計にはしていません。

ただし、作成と検査は一部の処理を共有しています。検査器にも間違いはあり得ます。そこで、元の値を人が見る確認と、次の「検査器を試す」段階を重ねます。

ここでも実行前の原本ハッシュと照合します。小さな完了条件は、「合格表示を見た」ではなく、「元の五条件に対して、保存された結果と原本保持を確かめた」です。

4．合格したコピーを壊し、検査器も試す

合格するデータしか通していない検査では、何でも OK にする見せかけの検査と区別できません。

そこで、合格結果を残したまま、本文一か所を変えた新しいコピーを作ります。

python -B corrupt_copy.py run-02-good run-03-corrupt
python -B guard.py verify fixtures/posts.csv run-03-corrupt

一つ目は、コピー側の一件目の本文だけを、練習用の別の文に置き換えます。元の結果フォルダは変更しません。二つ目は record 1: caption mismatch を含む FAIL validation で止まるはずです。

このコピーには、元の件数やハッシュを記した情報が残っています。それでも本文の不一致を検出できるかを試しています。「ハッシュ欄があるから合格」とするだけでは足りないことが見えます。

最後に、残しておいた正常な結果も再検査します。

python -B guard.py verify fixtures/posts.csv run-02-good

こちらは OK。壊したコピーは FAIL。この違いを自分で確認できたら、検査器が少なくとも今回の本文変更を拒否することを確かめられました。

全種類の欠陥を検出する証明ではありません。たとえば自分が条件に入れなかった誤りは、この検査だけでは止められません。何を検査して、何は見ていないかも記録します。

5．止まったとき、古い結果を成功扱いしない

次は同じ正常な出力先でもう一度実行します。

python -B guard.py build fixtures/posts.csv run-02-good

destination already exists で拒否されます。空のフォルダでも再利用しない仕様です。既存の結果を保持するためなので、削除して無理に通すのではなく、必要なら新しい名前を使います。

入力そのものが条件を満たさない場合も試します。

python -B guard.py build fixtures/duplicate_id.csv run-04-rejected

番号の重複で止まり、この入力検査の失敗では新しい結果フォルダを作りません。別の練習ファイルには、列不足、不明な状態、空のレコードもあります。詳しい期待結果はREADMEで確認できます。

エラーの読み方は三つに分けます。

- FAIL validation：入力や出力が固定仕様に合わない。どの条件かを確かめ、データや使ったファイルを見直す。
- FAIL I/O：読み書きが完了していない。パスや利用権限を確認する。自分で判断できない権限変更はしない。
- 正常終了：そのコマンドが定めた処理を終えた。欠陥作成コマンドの正常終了もあるので、「終了した」だけを品質判定に使わない。

検査違反の終了コードは2、読み書きの問題は3です。コマンドの使い方の誤りでも2になるため、数字だけでなく表示も読みます。途中の書き込みが失敗した場合は、新規フォルダの一部だけが残る可能性があります。そこを成功扱いしたり、前回の正常フォルダを今回の成果だと思ったりしないでください。

一行ずつ実行し、期待した結果と違えばそこで止めます。新しい名前で再試行するのは、止まった理由を説明できてからです。

6．答えのない一件を、自分で追加する

ここまでのコマンドが通るだけでは、教材の手順を再現した段階です。最後は、予想する結果を自分で決めてから試します。

fixtures/new_record.csv は、同じ架空の店の六件目を追加した見本です。見本のまま動かすだけで終えず、テキストエディタで別名の my-posts.csv として保存し、六件目を作り直してください。UTF-8・BOMなしを選び、表計算ソフトの自動的な数値変換には任せません。

変更するのは、次の四つです。

1. 先頭ゼロを含む、既存と重ならない新しいIDを決める。
2. 自分で考えた架空の投稿本文を書く。半角カンマか改行を一つ含める。
3. 実在の画像を参照しない、架空の画像名にする。
4. draft と ready のどちらかを自分で選ぶ。

本文にカンマや改行を含める場合は、フィールドを二重引用符で囲みます。本文中の二重引用符は二つ重ねます。既存の行を見本にして構いませんが、壊れた場合に元のファイルまで直そうとしないでください。

実行前に紙へ、六件のIDの順番、新しい本文のどこを残したいか、draft と ready の予想件数を書きます。六件目を draft にしたなら3対3、ready にしたなら2対4です。

新しいファイルについても、実行前ハッシュを別名で保存してから進みます。

python -B source_hash.py save my-posts.csv my-original.sha256
python -B guard.py check my-posts.csv
python -B guard.py build my-posts.csv run-05-mine
python -B guard.py verify my-posts.csv run-05-mine
python -B source_hash.py verify my-posts.csv my-original.sha256

合格したら、出力を開いて自分の予想と照合し、原本ハッシュも再確認します。新しい番号、文字列の型、本文のカンマや改行、順番、状態と件数が全部一致しているでしょうか。

違った場合は、次の順番で戻ります。

1. 元の見本ではなく、自分が保存した my-posts.csv を指定したか。
2. 予想メモと入力が一致しているか。
3. 入力の書式が条件を満たしているか。
4. 指定した結果フォルダが今回のものか。

この演習では、自分の入力に合わせて、検査器の条件を緩める必要はありません。仕様を変える仕事は、別の設計と検査が必要です。

最後に「この一件では、何を確かめたから採用できるのか」を二、三文で書きます。たとえば、単に「OKだった」ではなく、「追加したIDを文字列のまま保持し、本文の改行と六件の順番を入力と照合した。実行前後の入力ハッシュも一致した。今回は確認用JSONまでで、SNSには渡していない」と説明します。自分の結果に合う内容へ書き換えてください。

次の小さな自動化にも持っていくメモ

空欄のシートを埋めるときは、今回の記入例を横に置きます。

目的：投稿CSVを、確認用JSONにする
入力：架空5件、UTF-8・BOMなし、固定4列
変えてよいもの：CSVからJSONへの表現形式
残すもの：4項目の値・型・順序、入力ファイル
拒否するもの：列違い、重複ID、不明な状態、既存出力先
予想：5件、draft 2 / ready 3、先頭ID "0007"
実行前：原本ハッシュを別ファイルに保存
実行後：値の比較、原本ハッシュ照合、結果フォルダ確認
検査器の試験：本文を変えたコピーを拒否したか
採用しない条件：不一致、不明な終了、途中の出力
今回見ていないもの：投稿許可、画像権利、外部取込、任意コードの安全性
次の行動：条件に合う確認結果を残す。実運用は別途判断する

同梱の受入テストも実行できます。

python -B -m unittest discover -s tests -v

ただし、テスト数の多さだけで安心しないでください。用意した入力と条件についての結果です。本当の業務、あらゆるCSV、未知のプログラムを網羅してはいません。

また、Pythonの実行入口に関する公式資料には、直接実行した場合だけ動かす処理を if __name__ == "__main__": の下へ置く方法があります。ただし、その囲みの外や読み込む別モジュールの処理まで止める仕組みではありません。「importなら読むだけ」「mainがあるから安全」という判定はしないでください。

今回できるようにしたいのは、コードを疑い続けることではありません。試す前に条件を決め、残した原本と実際の結果を見て、採用するか止めるかを決めることです。

最初から仕事の全体を自動化しなくて構いません。一つの小さな処理について、変えてはいけないものと、確かめた範囲を言える。その一件を持って、次へ進みましょう。

練習ファイル（無料）

26ファイルを収録しています。展開後、README.mdとguard.pyのあるフォルダから始めてください。