Claude Codeでツールを作った体験記 - 事前準備が AI 駆動開発の成否を左右する

こんにちは。
小売流通ソリューション部 SRE チームの池田です。

以前、「日々の業務に生成AIを取り入れて - 1年間の学びと発見」という記事で、AI Starter を利用して Python のタスク管理ツールを作った経験を共有しました。
2025年11月からは Claude Code も業務利用させていただいています。普段の主な用途はドキュメントの改善やデータの集計などで、担当業務的にもコーディングを行う機会はほぼありません。
今回はシークレットキーやアクセストークンなど、本来は誰でも閲覧可能な状態であってはいけない情報（以降、機微な情報と記載）が、社内 Wiki として利用している Notion のページに誤って平文のまま記述されていないかを自動でチェックするツールを AI に作ってもらった体験記をご紹介しようと思います。
なお、本ツール作成において著者は1バイトもコードを書いておらず、すべて自然言語による指示のみ行いました。

先日、部内に運用開始をアナウンスしたのですが、その時点ですでに Version2 でした。Version1 は本番環境での動作検証でパフォーマンスに問題があることがわかったため、Version2 としてゼロから作り直してもらっています。

結論（Version2 を成功させる過程で学んだこと）

Version1 での失敗を踏まえて Version2 で試してよかったことなどを列挙します。

• 自立型コーディングエージェントを利用する場合は、人間に依頼するよりも丁寧に関連情報を集めてファイルで渡すのが良い（ユーザープロンプトで渡すと発生する「物忘れ問題」を回避できる）
  • 利用する API の仕様（今回は Notion API）をあらかじめ Deep Research で調査したものを用意
  • 求める機能とそれが必要になる背景情報（部内でのルールなど）、制約事項を記載したマークダウンファイル
  • 期待する結果の出力方法とそのサンプル
  • 想定している実行環境や利用方法の説明資料（Version2 では GitHub Actions による定期自動実行を指定）
  • 機微な情報が指す具体的な例と、なぜ平文で記述されていてはいけないのかの説明も用意
• 何をどのように進めるのか、計画の全体像とタスクの洗い出しに時間をかける
  • いきなりプログラムを書かせるのではなく、事前に渡した情報を踏まえた実装計画を立てさせる
  • 自分の期待と AI の認識に齟齬がないことを丁寧に確認する
  • この段階までで作成したドキュメントが意思決定の記録になる
• コーディングそのものは AI に全て任せてしまっても良い
  • 今回は部内で利用するプライベートなツールであること、比較的単機能（ページ内コンテンツ取得、文字列検索、issue 作成程度）なためコードレビューに時間をかけるよりも結果で判断していく方が早いと考えたことが主な理由
  • 発生したエラーや、実際の結果と期待する結果の差分などを伝えれば、改善点は AI がサクッと見つけて修正してくれるので、自分で調べたり修正とテストを繰り返すより数十倍〜数百倍早い
  • おそらくですが、最終的に複雑なシステムを作る場合も可能な限り小さな機能単位に細分化すると多くの作業を AI 任せにできるのではないかなと思いました

Version2 の準備から完成（動作検証の完了）までは、5時間のプラン制限に到達して作業が進められない時間もありましたが、待ち時間を含めておよそ5営業日程度だったと思います。ターミナルで Claude に指示を出したり、出力されたものをレビューしたりといった具体的な作業時間は 10〜15時間程度だと思います。
指示を出したあとは放置して、ほかの業務を並行して行い、区切りのいいところでターミナルに戻る。という進め方ができたので効率よく時間を使えたと思います。

Version1（失敗）

これ以降ははじめて Claude Code とプラグインを利用してツールを作成してもらった記録です。無駄に長いので多くの方には不要な情報だと思いますが、Version1 の供養を兼ねて記載します。
失敗の原因は、機微な情報の有無を調査する際のフィルターの適用やページ内要素の取得処理の順序が悪かったようです。本番環境での動作検証で一度の実行に2時間以上かかってしまうことが判明し、お蔵入りとなっています。
これは Notion そのものと API の仕様を正確に把握していれば起きなかった問題だと考え、前述のような事前準備を行なったうえで Version2 を作成することとしました。
（本題よりも失敗談の方が長文なのは内緒です）

プラグイン tsumiki の導入

Tsumiki マニュアルの説明の通りに進めてスムーズに導入できました。

最初に伝えた指示

諸々初期設定を終えた後は、Claude に tsumiki の使い方を聞いて（ドキュメント読め）次のコマンドで tsumiki を起動（？）したと思います（PC 再起動とかで実際のやりとりとかが消えてしまっているため記憶ベースです）。

kairo-requirements これは要件定義をするためのコマンドということだったので、以下をテキストエディタで用意して、まるっとコピペで指示しました（これが Version1 失敗の原因でした）。

/tsumiki:kairo-requirements
Notion API を利用して、アクセストークンやパスワードなどの機密情報が平文で記述されたページが存在しないかチェックする仕組みを作りたい
- MacOS ローカル環境上でユーザーが任意のタイミングに実行（実行コマンドは未定）
- Notion API トークンは 1Password に保管し、1Password CLI を利用して環境変数へ格納して使用する
- 調査結果ログをターミナル上に表示
- 機密情報が見つかった場合のログには一部をマスクして表示する
- 機密情報が記載されたページの最終編集者の名前を取得してログに出力する
- 事前に知りたいことはヒアリングしてください

いくつか質問を受けた後、いろいろと md ファイルが生成されていくのを横で開いていた VSCode のツリーで見ているのが楽しかったです。
このやり方は SDD 「Spec-Driven Development（仕様駆動開発） by Gemini の解説」と呼ぶようです。

その後、順に以下のコマンドで進めていった記憶です。

kairo-design - 設計文書生成
kairo-tasks - タスク分割
kairo-implement - 実装実行

ファイルの出力や編集は毎回確認を求めるようにして使いました。
途中でツールの名前を決めていないことに気がつきましたが、tsumiki がよしなに「notion_secret_scanner」という名前をつけてくれていたようでした。
プラグインのインストールから、時間にしておよそ1時間半程度、MAX100 プランで約 45% 程度のトークン消費で「テストまで完了した」と報告を受けました。
ちょうど退勤する時刻だったため、その日はここで終了しています。

auto-debug が便利すぎた

翌日、本当にテストまで完了したのかな？と、別のターミナルを使い同じプロジェクトのディレクトリで起動した Claude にテスト結果を確認してもらったところ、テストコードはいくつかあるが、テストは実行可能な状態ではなく「テストまで完了した」状態ではないことがわかりました。
もしかすると「テストの作成まで完了した」という報告を誤認してしまっていたのかもしれません。これは人間同士のやり取りでもよくあるすれ違いですね。

そもそも pytest を使える状態にしていなかったため、セットアップを済ませてから Claude にテストを実行してもらったところ、いくつかのテストが失敗またはエラーとなりました。そこで /tsumiki:auto-debug コマンドにテストの修正を依頼しました。
このコマンドは不具合を修正するためのテストを作成し、テストがパスするまでひたすら修正とテストを繰り返すというもので、Claude が独り言のように「これから何をするか」、「何が問題か」、「何をどう修正するか」などメッセージをどんどんターミナルに出力していく様子はなんとも言えない未来感がありました。

動作検証から自動化まで

Claude が一通りのテストをパスしてコードが完成したと報告してきたので、情報システム担当に依頼して Notion のサンドボックス環境で動作検証をさせてもらいました。
ひとまずはローカル環境で実行させ、1Password CLI 経由でアクセストークンを使いサンドボックス環境へアクセスできること、期待した文字列を機微な情報として検出し、マスクした状態でレポートが出力されることを確認しました。

この段階で、Claude が「自動化も可能です」と提案してきたので、どのような方法で実現するのか聞いてみました。GitHub Actions を利用した定期実行を勧められたので実装を任せることにしました。

いよいよ本番環境での確認

サンドボックス環境に対して GitHub Actions での自動実行も期待通りの結果を得られることが確認できたので、いよいよ本番環境での動作確認です。
GitHub Actions のワークフローが開始される時間になり、わくわくしながら Slack に通知が届くのを待っていたのですが10分経っても届かないためログを確認したところ、延々 Notion 上のコンテンツ情報を取得し続けていることがわかりました。エラーなどは見受けられなかったため終了するまで待つことにしました。
2時間程度かかって本番環境での処理が完了し、期待通りに動作検証用に記述したダミーのアクセストークンの文字列は検出できたのですが、毎回こんなに時間がかかってしまうのは現実的ではないため処理内容のログを取得して Claude Code にチェックしてもらいました。

失敗の原因

ログを Claude に分析してもらった結果、機微な情報の有無をチェックする対象（ページ）を「過去24時間以内に作成または更新されたもの」としていたのですが、対象を絞る前に既存のコンテンツすべての情報を読み取り、その後にチェック対象となるページの絞り込みをしていることが原因だと判明しました。
また、他にもデータベースに格納されている要素の重複チェックをはじめとした複数の「無駄な処理」が行われていることもわかりました。

見つかった問題の多くは Notion API の仕様を Claude に把握させていなかったこと、処理が完了するまでの目標時間など具体的な指標を提示していなかったことなど、事前に用意することが可能な情報ばかりだとこの時点でやっと気がつきました。特に Notion API の仕様については、設計の流れの中で Claude が調査してくれることを期待していたことが反省点です。
改めて Claude に Notion API について調べてもらい、API の仕様を無視した実装になっている箇所などを確認してもらいましたが、修正には破壊的変更が必要だという結論に至ったため Version2 としてゼロから作り直した方が早いと判断しました。
最終的に Version2 ではチェックの処理がおよそ 5分程度で完了するまで改善ができました。
失敗談は以上となります。ここまで読んでくださりありがとうございます。