AIに「全部任せる」と怖い。「全部確認する」と遅い。どっちも3日で疲れます😇
しかも張り切って作った「ハーネスの仕様書」は、たった3時間で古くなってゴミ箱行きになりました。

日本株のAI銘柄スクリーニング＆継続学習端末「ALPHA FORGE（アルファフォージ）」を、Claude Code と二人三脚で個人開発しています。今回は【ハーネス】回。AIに気持ちよく走ってもらうために、どこに線を引いて、どんな仕組みで止めているかを全部見せます🛠️

【要約：この記事で伝えたいこと】

線引きはシンプル。コードの編集・テスト・調査は確認なしで任せ、コミット・公開・削除・課金は必ず人間が確認する
止める仕組みは道具ごとに役割が違う。計画モードは「作る前」、フックは「毎回必ず」、/loop は「待つ間」、ローカルCIは「出す前」。どこに置くかを決めたのは人間
持ち帰り：ハーネスの約束は、AIが毎回読む場所に1つだけ置く。別に作った仕様書は約3時間で CLAUDE.md と食い違い、削除した

※本記事はnote連載［ALPHA FORGE 開発秘話 #19］の技術的な部分を、エンジニア向けに再構成したものです。

📏 全部任せる？全部確認する？どっちもツラい

AIエージェントと開発していると、最初にぶつかる悩みがこれです。

任せすぎると怖い、確認しすぎると遅い。両極端はどちらも長続きしない

全部任せると、速いけれど「どこで止まるか」が分からない。気づいたらプッシュ済み、課金済み…なんて想像するとヒヤッとします😱
逆に、ファイルを1行直すたびに「いいですか？」と聞かれると、こちらがハンコを押す係になってしまい、AIの速さが台無しです。

そこで、その間に線を1本引くことにしました。

「元に戻せるか」と「外に出るか」で線を引く

区分	操作
確認なしでGO	コードの編集、テストの実行、調査、ドキュメントの更新
必ず人間が確認	コミットとプッシュ、外への公開、ファイルの削除、料金のかかる操作

基準は「元に戻せるか」と「外に出るか」の2つだけ。コードの編集は git で戻せるし、テストは何回流しても誰も困りません。一方で、プッシュした履歴、公開したもの、消したファイル、払った料金は、戻せないか、戻すのがとても大変。ここだけは、AIがどんなに自信満々でも人間が最後に見ます🧐

この線引きは、全プロジェクト共通のグローバル指示（ユーザー単位の CLAUDE.md）に書いています。プロジェクトごとに書くと、プロジェクトをまたいだときに線がぶれるからです。

🚦 線の上に「止まる場所」を置いた

線を引いても、守られなければただの落書きです。そこで、作業の段階ごとに止まる場所を置きました。

作る前・毎回・出す前。段階ごとに止まる場所を置いて、最後の扉は人間が開ける

🗺️ 計画モード（作る前に止まる）

複数のファイルにまたがる変更は、いきなり書かせません。計画モードで「何をどう変えるか」の設計だけを出してもらい、私が承認してから実装に入ります。前回（第18話）の「試し打ち」モードも、この流れで作りました。

設計が重いときは、より強いモデルに計画だけを考えてもらうこともあります。考える役と書く役を分けるイメージです。

🪝 フック（毎回、必ず走る）

フックは、AIの判断とは関係なく、決まったタイミングで必ず実行される処理です。ALPHA FORGE では、クラウドの作業環境（Claude Code on the web）で会話を始めた瞬間に、Celery のブローカーに使う Redis などをそろえる「セッション開始フック」を置いています。

.claude/settings.json（抜粋）

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh"
          }
        ]
      }
    ]
  }
}

スクリプトの先頭では「クラウドでなければ何もせず終わる」ようにしています。手元の Windows は別の手順で起動しているからです。

.claude/hooks/session-start.sh（抜粋）

set -euo pipefail

if [ "${CLAUDE_CODE_REMOTE:-}" != "true" ]; then
  exit 0
fi

Redis は「起動済みなら何もしない」形にして、何回走っても同じ結果になる（冪等な）作りにしています。

AIに「毎回これやってね」とお願いするのではなく、仕組みとして毎回走らせる。お願いはAIが忘れることがありますが、フックは忘れません📜

🔁 /loop（待つ間を任せる）

機械学習の学習は、何時間もかかることがあります。9月20日には、4種類のモデルの学習の進み具合を /loop で定期的に見張ってもらいました。

見張り番を任せて、人間は止まったときだけ動く

実際に打ったのはこれだけです。

/loop 学習進捗(xgboost/random_forest/lstm/transformerの4モデルタイプ)を定期的に確認する

人間は画面に張り付かなくてOK。止まったら知らせてもらえる、それだけで十分ありがたいんです☕

🧩 ワークツリーとサブエージェント（混ぜない）

並行して進めたい作業は、作業用のコピー（git worktree）や、別のAI（サブエージェント）に分けます。終わったら取り込んで、作業場は片づける。同じ作業ツリーで2つの変更がごちゃ混ぜになる事故を防ぎます。

💰 最後の関所：ローカルCIと、課金前のひと声

プッシュの前には、GitHub Actions と同じ検査を手元で全部通します。

対象	検査
backend	ruff / black / mypy / bandit / pytest
frontend	tsc / jest / eslint / next build

この手順はプロジェクトのスキル（local-ci）にまとめてあり、AIは毎回これを流してから「プッシュしてよいですか」と聞いてきます。それでもCIが落ちたら「CI通して」の一言で原因を調べて直してもらいます。

そして、料金のかかる操作の直前のひと声。計画を承認していても、実際にお金が動く実行（実LLMを呼ぶE2E検証など）の前には、もう一度確認してもらいます。

計画の承認は、課金の白紙委任ではありません🙅 「計画を承認した＝その中の課金も承認した」とAIに解釈させないよう、課金前の確認は計画とは別のルールとして残しています。

📄 やらかし：ハーネスの仕様書、3時間で寿命を迎える

ちゃんと失敗も書いておきます😅

読まれない場所に書いた約束は、すぐ古くなる

9月22日 15:00　AIと一緒に、ハーネスの設定をまとめた「仕様書」を CLAUDE.md とは別のファイルとして追加。きれいに整理されていて「いいものができた！」と思っていました
同じ日　定期実行（celery-beat）の起動方針を変更。AIは CLAUDE.md を直したものの、仕様書は古いまま。しかも仕様書の中で表と本文が食い違う状態に。どこからも参照されていないので、誰も気づきません👻
夕方　私が「MDファイルに重複記述があるから分類・整理し、不要なものは削除して」と依頼。AIが全MDファイル（16件）を棚卸しし、仕様書が CLAUDE.md とほぼ丸ごと重複していると報告
18:11　価値のあった一部の情報（ベクトル検索APIが止まっているときの症状）だけ運用ドキュメントへ移してから削除。作ってから約3時間の短い命でした🪦

やったこと／やらなかったこと

やったこと: ハーネスの約束は、AIが毎回読む CLAUDE.md に1つだけ置く。役割の違う計画書（凍結）と運用ドキュメント（継続更新）は重複とみなさず残す
やらなかったこと: 仕様書を直して2冊を同期し続ける案。どこからも読まれない文書は、直しても次の変更でまた置いていかれるからです
決めたのは人間: 整理と削除を頼み、残す・消すの線引きを承認したのは私。AIは棚卸しと、情報を失わない移し替えを担当しました
削除は git rm なので、中身は git の履歴から復元できます

読まれない場所に書いた約束は、すぐ古くなる。そして古い約束は、AIを「正しく間違わせ」ます。

🧰 仕組みの選び方早見表

ハーネスは鎖じゃなくて手すり

やりたいこと	仕組み
作る前に止めたい	計画モード
毎回必ずやらせたい	フック
長い待ち時間を任せたい	/loop
作業を混ぜたくない	ワークツリー、サブエージェント
出す前に確かめたい	ローカルCIをスキル／CLAUDE.md の手順に
戻せない操作の前で止めたい	確認必須の線引き（コミット・公開・削除・課金）

ハーネスは、AIを縛る鎖ではなく、安心して任せるための手すりだと思っています。手すりがあるから、線の手前では思いきり走ってもらえるんです🏃

🤝 まとめ：今回の役割分担

人間が線を引き、AIが線の手前を全力で走る

線を引いたのは人間🧭: 任せる範囲と止める範囲、どの仕組みを使うか、計画の承認と課金の許可
走ったのはAI🛠️: 計画づくり、フックのスクリプト、/loop での見張り、ローカルCIの実行と修正
一緒にやらかしたのは両方🤝: 二重管理の仕様書。作ったのも二人、重複に気づいて整理を頼んだのは人間、棚卸しして片づけたのはAI

保存用チェックリスト

線引きの基準は「元に戻せるか」「外に出るか」の2つに絞る
複数ファイルの変更は、計画を承認してから実装させる
毎回やらせたいことは、お願いではなくフックにする
計画の承認とは別に、課金の直前でもう一度止める
約束はAIが毎回読むファイルに1つだけ。別の仕様書を作らない

次回は【事件簿】回。「タイムマシンで学習する ― 過去日リプレイ学習と予算15ドル」。過去の相場を1日ずつやり直して、AIに学ばせる仕組みの話です⏰

☕ note.comで開発秘話と毎朝の検証ログを連載中

note.comでは、「ALPHA FORGE」の開発秘話と、毎朝のアルゴリズム検証ログを公開しています。

👉 元記事（note連載第19話）:

免責事項
本記事は個人開発およびAIエージェントを活用したシステム開発の技術記録です。特定の銘柄の売買推奨や投資助言を行うものではありません。本ツールは証券会社等への発注機能を持ちません。記事中の日付・発言・時刻は開発時の記録にもとづくもので、実行環境により異なります。紹介した設定は抜粋・要旨であり、実際の設定ファイルそのものではありません。

⚠️ 【システム検証記録に関する免責事項・注意事項】

本記事は、独自開発アルゴリズム「ALPHA FORGE」の動作検証およびデータ分析過程を公開する技術・運用の個人的な記録ログです。
掲載されているすべてのデータ（各スコア、基準観測値、統計的変動上限、シナリオ無効化水準など）は、過去の市場データに基づき数式（ATR等）により機械的に算出されたバックテスト・シミュレーション用のパラメータであり、特定の有価証券の売買勧誘、取引の推奨、投資助言・代理行為を目的としたものではありません。
また、将来の株価変動や運用成果を保証するものではありません。実際の投資判断および最終決定は、必ずご自身の責任と判断において行っていただけますようお願いいたします。