AIと領収書システムを1日で作って、6回つまずいた記録 — VWork教材パッケージを公開しました
領収書をPDFで発行して、ダウンロードURLをメールで送るシステムを作りました。1日です。
そして6回つまずきました。
その記録を、動くコードと VWork フレームワークごとパッケージにして公開しました。
kinvoice — 領収書メール送信システム ＋ VWork 教材パッケージ（MIT License・無償）
なぜ「失敗の記録」を売り物にするのか
バイブコーディングの解説は「AIに頼んだらこう出てきました」で終わりがちです。でも実際にやると、そこは問題になりません。
本当に難しいのは、「動いたように見えて動いていない」を見抜くことです。
AIは指示すればコードを書きます。速いです。そして平気で「できました」と言います。その判定が正しいかどうかを確かめるのは、いまのところ人の仕事です。
今回踏んだ6つは、全部そこでした。
罠1: メールが「送信済」なのに届いていない
画面に「送信しました」と出て、送信履歴も「送信済」。台帳にも mail_ok: true。
でも受信箱には来ていませんでした。
PHPの mail() は、サーバーが受け付けた時点で true を返します。届いたかどうかは分かりません。
原因はSPFでした。
From: info@exdirect.net SPF: redirect=_spf.ocnk.net → このサーバーは許可されていない
From: info@exbridge.jp SPF: include:_spf.heteml.jp → 許可されている
送信サーバーがSPFに入っていないドメインを差出人にすると、受信側が黙って捨てます。エラーも返りません。
成功の表示は、成功の証明ではない。これが1つめです。
罠2: 設定ファイルを置いたのに、値が効かない
会社名を設定ファイルに書いたのに、まったく反映されませんでした。ファイルの場所も中身も合っています。
PHPの define() は先勝ちでした。読み込み順がこうなっていたのです。
require_once 'kinvoice_lib.php'; // ← ここで既定値を define してしまう
require_once 'kinvoice_config.php'; // ← もう遅い
「設定したのに効かない」は、たいてい値ではなく順番の問題です。
罠3: 動いているのに、売り物にならなかった
システムは完成し、本番でも動いていました。しかし他人が使うことはできませんでした。
会社名も住所もコードに直接書いてあり、ログインは自社専用の認証基盤に固定。クローンした人の画面に、こちらの会社名が出る状態でした。
「動く」と「他人が使える」は別です。自分の環境だけで検証していると、この差に気づけません。
確かめる方法は1つ。設定を消した状態で、まっさらな場所に置いて動かしてみることです。
罠4: サーバーの設定を、古い版で上書きしかけた
.htaccess に1行足そうとして、手元のリポジトリの版を上げようとしました。
直前にサーバーの現物を落として比べたら、手元は6行足りませんでした。別システムのルーティングと文字化け対策が入っていたのです。
そのまま上げていたら、関係ないシステムが2つ壊れていました。
手元にあるものが最新とは限りません。誰かが直接サーバーを触っているかもしれない。
罠5: 画像が汚い原因が、直感と逆だった
ヘッダーのアイコンが潰れて見えました。「解像度不足だろう」と考えるところです。
逆でした。大きすぎたのです。
使っていた画像: 760×1133（1.4MB）
表示サイズ : 38×38 の丸
20倍に縮小したうえ、頭の部分だけ切り抜いていました。表示サイズに合った192pxを作り直したら、1.4MB → 13.7KBで、しかも鮮明になりました。
症状から原因を推測しない。実物を測る。
罠6: 数字を読み違えて、結論を間違えた
アクセスログを集計して「6,942PV」と報告しました。間違いでした。
ログの列を取り違えていて、実際は「そのページから出ていったクリック数」。正しくは13,911。しかも最初はボットを除外していませんでした（生ログの72%がクローラー）。
気づいたきっかけは、集計結果に https://www.google.com/ が「ページ」として出てきたことでした。Googleは自社のページではありません。
集計スクリプトは何を渡しても動きます。エラーは出ません。
6つに共通していること
| 罠 | 共通点 |
|---|---|
| メール | 成功の表示が、成功の証明ではない |
| 設定 | 値ではなく順番 |
| 売り物 | 自分の環境でしか試していない |
| .htaccess | 手元が最新とは限らない |
| 画像 | 症状から原因を推測した |
| 数字 | 出どころを確かめずに集計した |
すべて「確認したつもり」です。
VWork には VERIFICATION.md（「できました」と言う前の確認手順）という文書があります。抽象的だと思っていましたが、6つ全部がここに書いてあることでした。守っていれば、もっと早く気づけたものばかりです。
中身
動くシステムは GitHub にMITで公開しています。
領収書PDFの発行とメール送信。DB不要・外部ライブラリ不要・約1,180行で全部読めます。
デモも触れます（https://proto.exbridge.jp/kinvoice/・パスワード demo2026）。
教材版には、それに加えて次が入ります。
docs/02-failures.md— 上の6つの詳細docs/03-exercises.md— 請求書・見積書への改造練習AGENTS.md/INSTALL.md— AIエージェントに渡すと、設置と初期設定を各段階の確認つきで進める手順書- VWork 一式 — AIと仕事を進めるための作法をまとめたドキュメント
改造練習を入れたのは、読むだけでは身につかないからです。領収書 → 請求書 → 見積書 は、非エンジニアが自分で試して、自分で結果を確認できる良い題材です。
仕組みで1つだけ
PDFをメールに添付していません。
添付にすると、宛先を1文字間違えた瞬間に領収書が他人の手元に残ります。取り消せません。
なので、推測困難なURL（32桁）を送り、開いたら宛先メールアドレスの入力を求めます。2つ揃わないと開きません。認証前の画面には顧客名も金額も出しません。
こういう判断の理由も、全部 docs/01-overview.md に書いてあります。
関連書籍『AIと作る自動取引ボット入門』
『AIと作る自動取引ボット入門：バイブコーディング×バイブトレーディングで暗号資産・FX戦略を育てる』（小嶋 篤 著・Kindle）は、非エンジニアがAIと対話しながらシステムを組み上げ、運用するまでを、実際の失敗と学びから全49章にまとめた実践書です。
この記事と同じ姿勢で書いています。うまくいった話ではなく、つまずいた話を残しました。Kindle Unlimitedなら追加料金なしで読み放題です。
まとめ
コードは GitHub にMITで置いてあります。誰でも取得できます。
有償で提供しているのは、コードへのアクセスではありません。どう作って、どこでつまずいて、どう気づいたか。そして、それをあなたのPCでできる状態にするところまでです。
VWork は、AIと仕事を進めるための作法をまとめたドキュメント一式です。目的と成果物の決め方、禁止事項、そして「できました」と言う前の確認手順が書いてあります。教材版にはこれを同梱しています。
まずは docs/02-failures.md を読んでみてください。同じ罠に、たぶん当たります。