みなさん、こんにちは！
「ALPHA FORGE 開発秘話」の第21話です。
「祝日は非対応」。そう書かれたドキュメントの裏で、祝日対応はとっくに動いていました🙄
AIと開発すると、コードは1日で何千行も進みます。ドキュメントは、その速さに全然ついてきません。
日本株のAI銘柄スクリーニング＆継続学習端末「ALPHA FORGE（アルファフォージ）」を、Claude Code と二人三脚で個人開発しています。今回は【事件簿】と【ハーネス】の合わせ技回。実装とズレたドキュメントを棚卸しして、ファイルを3つ消した日の話です📚
【要約：この記事で伝えたいこと】
- 「MDファイルと実装の差異がないか確認して」と頼んだら、「祝日は非対応」「画面は6つ」「起動スクリプトは未整備」など、とっくに直った話が古いまま残っていた
- 続けて重複も棚卸しし、16件のMDから3件を削除（765行）。何を消して何を残すかを決めたのは人間
- 持ち帰り：AIはドキュメントを素直に信じる。古い文書はAIを「正しく間違わせる」ので、情報源を1つに決めて写しを消す
※本記事はnote連載［ALPHA FORGE 開発秘話 #21］ の技術的な部分を、エンジニア向けに再構成したものです。
🤔 「対処はしたのではなかったかな」
9月22日の夕方、私はAI（Claude Code）にこう聞きました。
違和感から始まった大掃除
副作用の対処はしたのではなかったかな。確認して、対応済であればCLAUDE.mdを書き直して
CLAUDE.md（Claude Code が毎回読むプロジェクトの指示書）には、「定期実行のスケジューラ（celery beat）は自動では起動しない」と書かれていました。9月14日、起動した瞬間に溜まっていた仕事が一斉に発火する事件があり、そのときに入れた一時的な方針です。
ところが原因はとっくにコードで直っていて、私自身もログオン時に全部を自動起動する運用に移っていました。AIが調べると、まさにそのとおり。ルールブックだけが1週間前のまま止まっていたんです🕰️
これをきっかけに、もう一歩踏み込みました。
MDファイルと実装の差異がないか確認してください、差異のある場合はMDファイルを修正してください
📜 書いてあることと、動いていることが違う
地図には昔の道が描かれたまま。信じて進むと、正しく道を間違える
AIがドキュメントを1つずつ実装と突き合わせると、出るわ出るわ😅
| ドキュメントの記述 | 実際 |
|---|---|
| 「祝日は非対応」 | 2日前に、祝日も休場日として判定するガードが入っていた。その修正自体が計画書の記録から漏れていた |
| 「画面は6つ」 | チャート画面を足して7つ。設計書の画面一覧に一度も追記されていなかった |
| 「起動・停止のスクリプトは未整備」 | 9日前に整備済み。運用ドキュメントの「既知の制限」に残っていた |
| 「beat は自動起動しない」 | さっきの件。CLAUDE.md 以外にも同じ古い記述があった |
直したのは8ファイル、23行の追加と19行の削除。コードの変更はゼロです。たったこれだけの差分が、開発開始から12日分の「ドキュメントが置いていかれた跡」でした。
たとえば CLAUDE.md の1行は、こう変わりました（要旨）。
1行の嘘を直すのに、コードは1行も要らなかった
- シグナル監視は 9:00–15:30 平日（祝日は非対応）
+ シグナル監視は 9:00–15:30 平日（祝日も除外。休場日判定を適用済み）
CLAUDE.md のような「AIが毎回読む指示書」に一時的な方針を書くと、原因を直したあとも方針だけが残りがちです。一時的な方針には、外す条件（「〇〇が直ったら削除」）も一緒に書いておくと棚卸しが楽になります。
🗑️ 同じことを書いた3つのファイルを消す
写しを片づけて、情報源を1つにまとめる
食い違いを直したあと、続けて頼みました。
MDファイルに重複記述があるから、すべてのMDファイルを分類して整理して、不要なものは削除してください
AIは16件のMDファイルを1つずつ棚卸しし、3件を削除候補に挙げました。
消した3つ。どれも「写し」だった
- ハーネスの仕様書📄: CLAUDE.md の運用ルールをほぼ丸ごと写したファイル。その日の15時に作ったばかりでしたが、どの設定からも読まれていませんでした。方針を直しても写しは直らず、ファイルの中で表と本文が食い違っていました（第19話の失敗談です）
- デザインの資料🎨: 画面の色を書き出したスナップショット。本当の色はデザイントークンという1枚のCSSで管理しているのに、資料のほうは黒と青の旧配色のまま放置されていました（第17話で、配色は3回変わっています）
- 構築プロンプト集🧱: プロジェクト立ち上げのときの構築プロンプトとほぼ同じ内容の別ファイル。ただ、運用の中で得た知見を足したプロンプトという独自の価値もありました。そこだけを原本へ統合してから消しました
3件とも、価値のある情報は先に移してから消しています。git の履歴からいつでも戻せることも確認済み。18時11分、765行がまとめて消えました✨
やったこと／やらなかったこと
- やったこと: 写し3件を、価値ある部分を移してから削除。情報源を1つに寄せた
- やらなかったこと: 計画書と運用ドキュメントの統合。内容は似ていても、計画書は作った時点で凍結した「計画」、運用ドキュメントはいまを書き続ける「実際」。役割が違うので両方残した
- やらなかったこと: 写しを直して同期し続ける案。読まれない文書は、直しても次の変更でまた置いていかれるから
- 決めたのは人間: 何を消して何を残すかの線引き。AIは棚卸しと、情報を失わない移し替えを担当
🧰 今回のハーネス術：AIが読む文書は、コードと同じくらい大事
人間なら、古いドキュメントを読んでも「これ、もう直ってたよね」と気づけることがあります。でもAIは、渡された文書を素直に信じます。CLAUDE.md に「祝日は非対応」とあれば、AIは祝日対策が無い前提で考え、正しく推論して、間違った結論にたどり着く。古いドキュメントは、AIを正しく間違わせるんです🌀
嘘をつかせないための3つの習慣
- 情報源は1つに決める。色ならトークンのファイル、運用ルールなら CLAUDE.md。写しは作らない
- コードを直したら、同じ変更でドキュメントも直す。後回しにしない
- ときどき「MDファイルと実装の差異がないか確認して」とAIに棚卸しを頼む。突き合わせは、AIがいちばん速い
ちなみに、コミットのメッセージも嘘をつくことがあります。第15話の、子プロセスの即死を本当に直した修正は、まったく別の大きな変更のコミットにまぎれていて、メッセージには一言も書かれていませんでした。経緯が残っていたのは、コードのコメントだけ。記録は、置き場所まで含めて設計するものですね🗂️
🤝 まとめ：今回の役割分担
人間が疑い、AIが突き合わせ、人間が線を引いた
- 疑ったのは人間🧐: 「対処はしたのではなかったかな」「差異がないか確認して」「重複があるから整理して」。どれも、ドキュメントを信じきらない人間の懐疑から始まった
- 突き合わせて直したのはAI🛠️: 全ドキュメントと実装の照合、食い違いの修正、16件の棚卸しと3件の削除案、価値ある情報の移し替え
- 決めたのは人間✋: 何を消して何を残すか。計画書と運用ドキュメントを両方残す線引きも含めて
保存用チェックリスト
- AIが毎回読む指示書に、古い方針が残っていないか定期的に確かめる
- 同じ内容の写しを作らない。情報源を1つに決める
- コードを直したコミットで、ドキュメントも一緒に直す
- 消す前に、価値ある部分を原本へ移す
- 役割の違う文書（計画と実態）は、似ていても無理に統合しない
次回は【事件簿】回。「最新モデルに替えたら、AIピックが全件エラー ― そしてシャドウは13日間黙っていた」。新しいAIに乗り換えた朝の、ちょっと怖い話です😱
☕ note.comで開発秘話と毎朝の検証ログを連載中
note.comでは、「ALPHA FORGE」の開発秘話と、毎朝のアルゴリズム検証ログを公開しています。
👉 元記事（note連載第21話）:
https://note.com/featured_stocks/n/n33f9e72305f9
エンジニアでない方向けに「AIへの仕事の頼み方」をまとめた連載（メンバーシップ「AIとつくるラボ」）もはじめました。第0話は無料で読めます。
免責事項
本記事は個人開発およびAIエージェントを活用したシステム開発の技術記録です。特定の銘柄の売買推奨や投資助言を行うものではありません。本ツールは証券会社等への発注機能を持ちません。記事中の日付・時刻・件数・行数は、開発時の記録と変更履歴にもとづくものです。紹介したドキュメントの文面は要旨です。
⚠️ 【システム検証記録に関する免責事項・注意事項】
- 本記事は、独自開発アルゴリズム「ALPHA FORGE」の動作検証およびデータ分析過程を公開する技術・運用の個人的な記録ログです。
- 掲載されているすべてのデータ（各スコア、基準観測値、統計的変動上限、シナリオ無効化水準など）は、過去の市場データに基づき数式（ATR等）により機械的に算出されたバックテスト・シミュレーション用のパラメータであり、特定の有価証券の売買勧誘、取引の推奨、投資助言・代理行為を目的としたものではありません。
- また、将来の株価変動や運用成果を保証するものではありません。実際の投資判断および最終決定は、必ずご自身の責任と判断において行っていただけますようお願いいたします。