こんにちは。運用保守部のきむ兄です。
運用保守部は、hacomonoに関する社内外のお問い合わせチケットの対応、システムの運用改善などを行っていますが、私はその中でも、本番環境での作業やチケット対応では片付けられないちょっと複雑で時間のかかる案件を担当しています。
今回は、タイトルの通り、
Claude Codeに、とある外部連携システムを導入するまでと検証環境を作る手順書を作るまでの顛末ブログを書かせてみた件
ということで、導入までClaude Codeに頼りっきりで、テストや導入を進めて、テストに使った検証環境構築の手順書まで作ったので、それをブログを書いてもらったらどうなるだろうか、ということを書いてみたいと思います。ちょっとややこしい。
はじめに
本件を期限内に完遂するためには、AIを駆使する必要がありました。AIが発達しても、業務観点の気付きとその場に合わせる応用力は人の判断が必要です。自分がこのプロジェクトを始めるときに、そのかけ合わせをどうにか形に残せないかと思い、後に出てくる「外部システム連携＿検証環境構築手順書」（以下、手順書）を作ることを想定して作業を進めました。
この顛末を、ブログを書いてもらうという要素も織り交ぜて、まとめてみました。
私の経験や体験、システムに起きたことを一纏めに形にし、次に繋げることができるか。
手順書やブログを作る過程を書くことで、精度やおてがる度がお伝えできたらと思います。
外部連携と外部システムの概要
hacomonoは、フィットネスクラブ・スクール・公共施設などの会員制施設向けに、会員管理・予約・決済・入退館・スクール管理などを一元化する店舗運営SaaSです。
スクールとは、決まったカリキュラムやクラスに会員が継続的に通う教室型のサービスで、スイミング・体操・ダンス・サッカーなどいわゆる習い事のことを指します。
外部システムは、プールに設置したカメラで生徒の泳ぎを録画し、切り抜き・編集して 、レッスン中に見直したり、進級テスト に活用するシステムです。
両者を連携させることで、hacomono が持つ「誰が・どのクラスの・どのレッスンを受けるか」の情報を 外部システム が使えるようになり、進級テストの結果は 外部システム から hacomono に戻されて会員の「級」に反映されます。
hacomono → 外部システム はマスタデータを CSV バッチ（S3 経由） で、外部システム → hacomono はテスト結果を API リクエスト で、という双方向の連携です。
導入に向けたテスト準備とテストはこんな感じで進めました
状況的には、4月末頃から〜約3週間（バッチリGWを挟んでる）かけて、とあるお客様向けにhacomonoと外部連携するプロダクトを導入するためのテストを行いました。hacomonoでも数社目の導入です。
本体やスクール開発には直接関わっていなかったので、まずはスクールの業務知識を座学で学ぶところから始めました。hacomono への理解と、これまで業務開発で培ってきた経験を駆使して、新しい領域に挑戦する機会として取り組みました。
直前の導入の際に、勉強のためにテストに関わらせて頂きました。そこでは、トラブルシュートなどにも参加させていただきました。合わせて、以前の導入で結合テストを進めた、QA部/まっちゃん（私の師匠です！）に、理解が及ばなかったところをレクチャー頂きました。その内容を夜な夜なClaude Codeに食わせまくります。
仕様理解で曖昧なところは、Claude Codeにソースを探して読み込んで学んでもらいます。調査のスピードと精度を求め、検証DBからデータをダンプし、解析してローカルに環境を作ってもらいます。
それでも、わからないところは、まっちゃんに教えてもらうべく質問集をつくります。
特に仕様理解で苦労したのは、hacomonoと外部システムで使っている単語と、その単位が殆ど合ってない無いことです。似て非なるものが沢山あり、ワードを対応させようにも、1 : 1にならない（例えば、hacomonoでAというと、外部システム側は、BとCの一部を指すみたいなこと）ことが多く、とても混乱しました。でも、こういうところは、Claude Codeがすぐに理解してくれて、聞けば何時でも何度でも解説してくれるようになります。
テストケース読ませ、前回使ったDBを使えるところは流用し、さらに手入力でテストデータをつくり、一緒に環境を構築します。（ここは、手順書に大きく反映されています）
トラブルや不具合があれば、メッセージとデータを読ませて解析して、対処を提案してもらい、合っているかをまっちゃんに確認という感じで進めていました。
検証環境構築手順書のこと
手順書を作ったのは、テストも終わって運用が開始されてからです。運用を開始してから、テストの段階で織り込むべき事案が発生するかもしれないと思ったからです。杞憂に終わりましたが。
まず、参考となる情報をわたして手順書を書いて、とだけお願いしました。その結果、細々とした枝葉のことがもりもり盛り込まれ、私でもなんのことか解らない内容もありました。レビューと指示を繰り返し、無駄なこと、書きっぷりのブレなどが精査できたものの、どうにもイマイチです。
じっと見ていて、これは今のままでは、自分以外に使えないなと感じたので、「全く知らないひとが見てもある程度理解できるように書いて」と依頼し、もう一度最初に渡したものと同じ参考情報をいくつか一緒に渡しました。経験上見逃していたり、忘れていたりする可能性もあると感じたためです。
すると、大変身です。
初見の人でも何を言っているかわかるように、理解するのに私も大変苦労したワードの対応表や、各種バッチの説明、セットアップするマスタ説明や依存関係など、Claude Codeと散々やり取りした内容が、書き加えらています。最低限の流れが掴める程度の説明と、手順になっています。一気にイメージに近づきました。
その後は、違和感のあるところだけ何回か指摘して完成としました。
これは、レビューやいい感じになるために頭をひねる時間をいれて、正味数日かけて作りました。
それでも、内容というか、情報が膨大なので、最初の頃のレビューはすこし時間がかかりました。この物量と内容を人が作ったらどれだけかかったか考えると、なかなかの時短（作業だけでも、60時間くらいが、4分の1くらいかなぁ？）です。一人でレビューや相談やチェックは難しい（というより、できない）ので、レビュアーのことを加味して、工数換算すれば関わった人分膨らみます。
もちろん、まっちゃんにレビューを依頼しました。
Claude Codeを使っていて特に気を使ったのは、、、
やり取りしたこと、調査したこと、トラブル対応したこと、などの記憶が欠けてしまわないことです。Claude Codeが知らないことが無いように気を使いました。
勝手に圧縮がかかったり、何もせずにプロンプトを閉じて次に作業をお願いすると、「なんのことでしょう」と言われて、もう一度説明したりデータを渡す必要がありました。作業の区切りや、休憩に入るときなどに、そこまでの履歴の記録と整理、次に何をやるかを出してもらうことを怠らないようにしました。
Cloude Codeを利用する前に使っていたcursorは、起動フォルダが同じなら何時でも続きがでたので、知らずに起動し直して「なんのことでしょう」と言われたときは焦りました。
スキルにすればその指示もいらねんじゃね？と思って、こういうこと（常時記憶すること）を「スキルにして」とお願いしてみました。
でも、思ったように「記憶」が引き継がれていない感じがしたので、自分の整理も兼ねて意図的に記録と整理をお願いすることにしました。
こだわった理由は、記憶がなくなりさえしなければ、あとでいろんな使い道があると思ったからです。この作業を手順書にすることは最初から頭にありましたし、それ以外でも使えないかと今でも考えています。
そして、そこからさらに作ってとお願いしたのが、
文末のブログです。
一発でできたわけではないというか、出せるものではなかったので、以下のやり取りをしました。
こんなブログを書きたいから、これまでのことをブログに書いて。と、テックブログのURLを渡して、お願いしました。
しばらくして、できたよ言ってきた彼からこんなコメントが、（いろいろ伏せ字にしています）
確認いただきたい点（公開前レビュー用） - 筆者の肩書き: 「スクール向け機能の開発と運用を担当している木村」と書きました。実際の所属・肩書き に置き換えてください - パートナー名の扱い:「TTTT」と書かれていましたが、公開ブログである点を考慮して、 すべて「外部システム」に統一しました。実際の公開表記と合っているか確認をお願いします - API パス: POST /aaaaaa/vvv/ssss/scscscsc/acceppppp/NNNNNN はコードそのままで残しています。公開して問題ないか要確認 - 具体的な数値（メンバー 40 名・75 件、初 15 級 10 評価項目 など）: 公開して差し支えないかご確認ください
というので、できているブログの原稿をチェックします。ブログとして書くには重たくて細かすぎて初見の人には理解しきれそうにない部分が多々あったので、訂正するべく出したお願いは以下のとおりです。（いろいろ伏せ字にしています）
APIのパスは、XXXとかに置き換えてほしいな。途中だけでいいので。 外部連携先がどんなシステムなのかを簡単に説明してほしいな。 ＝＝＝ ・○○○ ・XXXX ・▲▲▲▲ この辺のイベントと言うか、トラブルについて、具体的にかかれているけど、システムがわからない人には何を言っているのかちんぷんかんぷんなので、 このエラーxxx/xxxxがでた と具体値が書いているところは、 〇〇という意味合いのエラーが出た と、エラーの具体値の意味がわかなくてもわかるように、概要というか意味がわかるように書いてほしい。 顛末の説明も、業務的な意味合いがわかるように、つまりどうなる？という疑問がわかないように、簡潔にわかりやすくシンプルに書き直してほしい。
と指示。
でも、思ったより簡潔にならなかったので、
長くない？ イベントやトラブルをさらっと、箇条書きにしてみるか、もっと要約してみたらどうだろうか？ いったん、いまの文書はそのまま残して、別文書として書き直してみて。 そして、このブログで伝えたいことをもう一度見直してみたい。 有識者にアドバイスもらいながらも、ミスがあったり、想定外のエラーがあったりして、すんなりいかなかったけど、それを教訓にして、次回以降の導入支援の際は、もっと効率よく進められるように、ドキュメント作ったよ。 ということじゃないかと思う。
そんなこと言ってないじゃんみたいなことを付け加える、軽い無茶振り。若い子にこんな指示出したら、嫌われるやつ。ちょっと、プロンプトとしては盛り込みすぎかなと思いつつ。。
ここで言うドキュメントとは、冒頭と文中に出てきた手順書のことです。
「長くない？」と言ったのは、「5 つの誤算」の章の部分。結構細かく、時系列で、エラーコードをバッチリ書いたりして詳細に顛末を書いてくれました。それは分かる人はわかるけど、、、というものだし。
「5 つの誤算」にまとめてくれたのもあり、全体が半分以下の長さになったものの、誤算のところでちょっと具体度が高いところがあったので、抽象度を上げるように少しだけ手直ししました。
Claude Codeが書いてくれたブログがこちらです。
スイミングスクール向け外部システム連携で「地雷」を踏みきった話 〜次の担当者に手順書を渡すまで〜
はじめに
こんにちは。hacomono でスクール向け機能の開発と運用を担当している木村です。
hacomono と、スイミングスクール向けの外部システムを接続する 外部連携を開発し、2026 年 5 月に結合テスト・一気通貫テスト・本番稼働を進めました。
先に結論から書いてしまうと、この記事で伝えたいのは次の 1 点です。
有識者のアドバイスをもらいながら進めても、想定外のミスやエラーは避けられなかった。ただ、そこで得た教訓を「次の担当者が同じ地雷を踏まないための手順書」に落とし込めたので、その話をします。
以下、何がどう「すんなりいかなかった」のか、そしてそれをどう資産に変えたのかを書いていきます。
外部連携サービスとは
スイミングスクール向けのレッスン支援システムです。プールやスタジオに設置した専用カメラで生徒の泳ぎを録画し、レッスン中はタブレットで、自宅では専用アプリや Web で、フォームを繰り返し確認できます。システムが各生徒の動きを自動で切り抜き・編集してくれるのが特徴です。
この録画機能をベースに 進級テスト が実施され、各生徒の級や結果が管理されます。ここが今回の連携ポイントです。
- hacomono 側：会員情報・クラス構成・受講登録などの基幹データ
- 外部システム側：録画・進級テスト機能
2 つを「同じ生徒」「同じクラス」「同じレッスン」として突き合わせるのが、今回開発した 外部連携の役割です。連携は双方向で、hacomono → 外部システム は S3 経由の CSV バッチ、外部システム → hacomono は API リクエストというかたちで行われます。
すんなりいかなかった、5 つの誤算
事前に社内の有識者や関係チームからアドバイスをもらい、仕様書も一通り整えた上で結合テストに臨みました。それでも、いざ動かしてみると想定外の連続でした。
以下、代表的なものを 5 つだけ、要点だけ書いておきます。
誤算 1：環境構築で半日を溶かした
DB をリセットしてマスタを戻すだけのつもりが、バックアップ対象外だった商品テーブルが空になっていた、プランカテゴリが未登録で管理画面がレンダリングエラーになった、など、テスト本編に入る前の準備で半日消えました。
誤算 2：hacomono の CSV 仕様に振り回された
CSV が全行弾かれる。原因は カラムの仕様に起因するものでした。CSV をベースに書き換える運用にすれば回避できます。
誤算 3：バッチの実行順を間違えると、外部キーエラーが出る
連携するデータに親子関係があり、バッチ実行順を考慮する必要がありました。
誤算 4：レッスン時間変更が反映されない、という現象
hacomonoの仕様で、スケジュール画面から時刻を変えるだけでは、連携バッチが見に行くデータには反映されません。必ずマスタから変更してスケジュール反映ボタンを押す ── これが正しい業務手順でした。
誤算 5：エラーコードは同じでも原因は毎回違う
進級テスト結果登録 API で「登録できません」の同じエラーコードが、外部システム 側のリクエスト誤り、hacomono 側のチェック順のバグ など、複数の原因で発生しました。ブラックボックスとして扱わず、都度コードを読むしかありませんでした。
本番稼働初日のエラー：「本番データには歴史がある」
結合テスト・一気通貫テストを経て本番稼働の準備状態に入った翌朝、外部システム からエラーログが届きました。結合テスト環境では表面化しなかった 2 種類のエラーが本番で顔を出した、というのが今回一番の教訓です。
- プラン契約が終了した会員のキャンセル履歴が「参加者情報」の生成元になっていた ── 会員本体は連携対象外なのに、レッスンへの参加者情報だけが 外部システム に届き、整合が取れなくなった
- 契約終了時期を過ぎたクラスのレッスン枠が毎日生成されていた ── クラスは連携対象外なのに、そのクラスに紐づくレッスン枠は毎日届き、こちらも整合が取れなくなった
どちらも「仕様通りに動いた結果」で、悪意も実装バグでもありません。ただ、テスト環境の「きれいなデータ」だけを見ていた自分たちには見えていなかった落とし穴でした。
本番には退会済み会員や終了済みのクラスが歴史として残り続ける ── これは有識者からも事前に注意はあったのですが、実際にエラーとして返ってくるまで、その意味の重さは腹落ちしていなかったと思います。
教訓を成果物に：検証環境構築手順書
さて、ここからが本題です。
この連携システムは、今後も他の案件に展開されていく可能性があります。次に同じ検証環境を組み立てる人が、また半日を溶かすのは避けたい。何より、有識者のアドバイスは口頭やチャットで散在していて、次の担当者が拾い集めるのが大変 です。
そこで、テスト完了後にまとめたのが 外部システム連携_検証環境構築手順.md です。次のような構成にしました。
Phase 0: 事前設計（テスト項目書から準備データを設計する） ↓ Phase 1: DB 初期化 ↓ Phase 2: DB 初期化後の手動セットアップ ↓ Phase 3: 初期テストデータ準備 ↓ Phase 4: 動作確認
とくに力を入れたのは次の 4 点です。
- 用語マッピング表 ── hacomono の UI・テーブル名と、外部システム側の用語の対応表。「hacomono の『クラス』は 外部システム の
Course」など、初見だとわからない対応を冒頭に集約 - 連携データ生成タイミング表 ── どのデータが どのバッチで送られるか。ここを外すとバッチ実行順で事故ります
- Phase 0 完了判定チェックリスト ── 「Phase 1 に進んでよい状態」を明確化。ここを曖昧にしたまま進むと途中で必ず止まります（実体験）
- 過去テスト実績の規模感 ── クラス何件・メンバー何名という実績値。次のテストの参照点として
「有識者のアドバイスを、次の担当者が読める形にする」── ざっくり言えば、これが今回のドキュメントの狙いです。
おわりに
長くなったのでまとめます。
- 事前に有識者に助けられながらも、実際に動かすと 想定外のミスとエラーの連続 だった
- とくに本番稼働直後のエラーは、「本番データには歴史がある」 ということを痛感させられるものだった
- そこで得た教訓を 検証環境構築手順書 に集約し、次の担当者が同じ地雷を踏まなくて済むように残した
もしこの記事を読んでいるあなたが、これから hacomono の 外部システム連携を担当することになったなら、まずは 検証環境構築手順書の Phase 0 を読み、テストの最終形態を紙に書き出してみてください。そこができていれば、環境構築で半日を溶かさずに済むはずです。
似た連携案件は、これからも出てくるはずです。誰かが同じ地雷を踏まなくて済むように、この手順書が役に立つことを願っています。
2026-05-08 記 / 2026-05-11 完了・加筆 / 2026-05-14 本番稼働後エラー加筆 / 2026-06-30 v3（要約・メッセージ再構成）
Claude Codeが書いたブログはここまで。
まとめ
Claude Code（AI）を、あえて自分の作業やもらった資料を渡してこまめに記録する（記録の仕方自体は工夫の余地があるかもしれませんが）ようにすると、苦労・手間暇・経験を、記憶やテスト結果だけでなく、手順書やブログなどの形にお手軽にそして克明に変換することができ、再利用、つまり他者に伝えられる様に残せるのは、画期的なことだなぁと、あらためて感じました。いままでは、この変換作業にもう一人必要なこともありました。
Claude Codeのクセみたいなものとの付き合い方として、やってきた「記憶」が消えないように、Claude Codeが知らないことが無いように気をつけました。その甲斐あって途中からClaude Codeの方が深くきちんと理解している程になってくれてました。
私としては、Claude Codetと一緒に考えて乗り越えてきた感があります。そのおかげか、言おうとしていることはよく分かるということを書いててくれました。（容赦なくボツにしましたが）
手順書も含め、まぁまぁな出来のドキュメントとして出せるものができたと思います。
次回以降、この手順書を使ってみて、どこまでサクサクできるか楽しみでもあります。
ほんとならスキルを作って自動化！まで持っていけるといいのでしょうけど、それは次のお話ということで。
追伸
手順書はまっちゃんにレビュー頂きましたが、数件勘違いや誤植のレベルの間違いはあったものの、構成を変えたり文章を大幅に変更したりと言うような指摘はなかったので、手順としてはある程度使えるものができたと思ってます。
もちろん、使いながらブラッシュアップは必要でしょうけど。
