Claude Codeを実案件に投入してみて出てきた課題と、その後の対応
社内で「AIコーディングツールを導入していきたい」という話があり、いろいろなAIを検討していましたが、最終的にClaude を採用し、実案件で初めて使用してみました。Webシステムの開発案件で、自分を含めて3人体制。うち2人は若手です。
結論から書くと、品質面では想像以上にうまくいきました。ただし進め方の面ではそれなりに反省点が残ったので、そのあたりを整理しておきます。
事前準備をほとんどせずに始めた
最初にお断りしておくと、この案件では設定らしい設定をほぼ作らずにスタートしました。CLAUDE.mdも最低限、スキルもエージェント定義もなし。ほぼ素の状態です。
ガチガチにルールを固めてから始めると、そのルールが妥当かどうかを判断する材料がないため、一度素で使ってみて、実際に困ったところを潰していくほうが、最終的に良い設定ができるだろうという判断です。
若手2人への指示も、機能と画面の割り当てだけ伝えて、実装のやり方はAIの使い方も含め、ほぼ本人たちに任せました。レビューは今回はAIを使わず、普段通り全部私が見るようにしました。
この判断自体は今も間違っていなかったと思っていますが、案の定いくつか問題が出ました。
課題1：何を作っているのか把握できない
Claude Codeは指示を出すと勝手にどんどん進めてくれます。それが便利さの本質なんですが、裏を返すと「今この瞬間、AIが何をどう作っているのか」がこちらから見えない。ファイルを何個も触って、気づいたら一通り出来上がっている。
で、出来上がったものを見てから「あ、そこはそういう作りにしてほしくなかった」となる。この手戻りが何度かありました。
勝手にどんどん進むから途中で止めることも難しく、特に若手は「AIが動いているうちは待つもの」という感覚になりがちで、結局追加の修正が必要になってしまいました。
課題2：メンバー間で完成度に差が出た
裁量に任せた結果として、これは予想していたことではあります。
AIへの指示の出し方、どこまで任せてどこから自分でやるかの線引き、生成されたコードをどう検証するか。このあたりの「慣れ」の差が、そのまま成果物の差になって出ました。
同じツールを使っているのに、片方はほぼ手直し不要で、もう片方はレビューでそれなりに指摘が必要になる。ツールが優秀なぶん、使い手の差が見えやすくなった感覚があります。
一方で、品質は明確に良かった
課題ばかり書きましたが、品質面については素直に驚きました。
単体テストでは、ほとんど問題が出ませんでした。AIが仕様書を細かく拾って実装してくれるので、実装漏れという類のバグがそもそも発生しにくい。人間が書くと「あ、このパターン考慮してなかった」が必ず何個か出るんですが、それがほとんどなかったです。
結合テストでは認識違いによるNGが少し出た程度。「想定と全然違う動きをする」みたいな根本的な問題はほぼゼロでした。
受入テストでも、細かい仕様の取りこぼしはちょこちょこあったものの、大きな認識齟齬はなし。しかもどれもすぐ直せるレベルのものでした。
また、AI起因のバグはほとんどありませんでした。 出た不具合を洗い直すと、原因はほとんど人間側です。仕様の確認漏れ、指示の曖昧さ、そもそも仕様が固まっていなかった箇所。人間が担当している部分の抜け漏れが、そのまま不具合として出ていました。
修正作業もほとんどClaudeと対話しながら進めました。現象を伝えて、原因を一緒に確認して、直し方を決めて、実装してもらう。この流れが想像以上にスムーズで、修正のコストはかなり低かったです。
案件が終わってから設定を整備した
課題については、案件の途中で直すのは現実的に難しかったので、終わってから腰を据えて設定を作りました。
何を作っているのか把握できない問題には、プランモードを強制する形で対応しました。デフォルトでプランモードから始まるようにして、「変更するファイル」「変更内容」「検証方法」を提示させてから、こちらが承諾して初めて実装に入る。承諾前のコード編集はツール側でブロックされるので、プロンプトの書き方に頼らずに確実に止まります。
あわせて、作業の途中経過をファイルに書き出すスキルも用意しました。タスクを一つ終えるたびに引き継ぎ用のメモが更新されるので、途中で覗いたときに何をやっているかがわかる。作業を中断して翌日再開する場合にも役立っています。
メンバー間の差には、設定一式をチーム共通で配布することにしました。ルールもスキルもエージェント定義もMCPの設定も全部まとめて、プロジェクトにコピーすれば誰でも同じ状態から始められる。品質チェックも「レビューして」の一言で全員が同じ項目を走らせるようにしました。
個人の習熟度に依存する部分を、なるべく設定側に寄せてしまおうという発想です。
サブエージェントは役割ごとに分けた
設定の中で一番効いているのがこれかもしれません。
Claude Codeはサブエージェントを定義できるので、作業の種類ごとに担当と使うモデルを分けています。全部を上位モデルでやる必要はないよね、という単純な話です。
- explorer（Haiku）— コードベースを読んで調べるだけの役。書き込み系のツールは持たせていない
- implementer（Sonnet）— 仕様が固まったあとの実装・修正・一括変更
- test-runner（Haiku）— テストとビルドとlintを回して結果を整理する。修正はさせない
- reviewer（Opus）— コミット前の差分レビュー。こちらが明示的に頼んだときだけ動かす
- deep-worker（Fable） — どうにも歯が立たないタスク用の枠
調査系をHaikuに寄せるだけでもトークン消費はけっこう変わります。入力・出力の単価がSonnetの3分の1なので、「まずファイルを片っ端から読んで把握する」みたいな一番トークンを食う工程が一番安いモデルで済むのは大きい。
もう一つ地味に効いているのが、調査結果だけがメイン会話に返ってくる点です。読んだファイルの中身が全部こちらの文脈に積み上がらないので、長い作業でもコンテキストが汚れにくい。キャッシュも維持されやすくなります。
reviewerだけOpusにしているのは、レビューは見落としたら意味がないので、ここはケチらないという判断です。ただし毎回自動で走らせるとかなりトークンを食うので、明示的に呼んだときだけ動くようにしています。
作成したスキル
スキルは今のところ5つです。
autonomous-work — 「タスクを分解して、自分で検証して、次にやることを判断する」という進め方の型を文章で定義したもの。どこまで自分で判断してよくて、どこからは聞くべきかの線引きや、やりがちな失敗パターンも書いてあります。素の状態だと確認が細かすぎたり逆に突っ走ったりするので、ここを言語化しておくと安定します。
debugging — 原因のわからないバグ用。いきなり直そうとせず、現象の整理・仮説出し・検証・修正の順で進めさせるだけのものですが、これがあるかないかで迷走の量が違います。
pre-commit — コミット前の品質チェックを一括で走らせるスキル。動作確認、余計な複雑さの点検、セキュリティ観点の確認をまとめて実行します。「レビューして」で全員が同じ項目を通せるようにしたかったのが目的です。
handoff — 先述した引き継ぎメモのスキル。セッション開始時に前回の続きがあるか自動で見にいくようにしてあります。
ops-log — 「今のログして」と打つと、AIの挙動で気づいたことを1行だけ記録するもの。設定を改善するネタは使っている最中にしか出てこないので、その場でメモを残せる仕組みを作っておきました。地味ですが、次に設定を見直すときに一番役に立つと思っています。
MCPは常時3つだけ
MCPサーバーは絞っています。増やしすぎると起動が遅くなるし、ツール定義がコンテキストを圧迫するためです。
context7 —ライブラリの公式ドキュメントを参照するためのMCPサーバー。AIは学習データの時点で知識が止まっているので、比較的新しいバージョンのAPIについて、存在しないメソッドを書いてくることがあるため導入。
playwright —実際のブラウザを操作して画面を確認させるためのMCPサーバー。「動いている」の確認までAI側でやらせられるので、フロント側の検証がだいぶ楽になります。
mysql —スキーマの確認とクエリ実行用。ただしDELETEとDDLは通らないようにしてあります。SELECTでテーブル定義を見て実装させる、という使い方が中心です。
PostgreSQLやOracleを使う案件もあるので、そのあたりは共通設定には入れず、案件側の設定ファイルで必要なときだけ有効化する形にしました。
今後
この設定で次の案件に導入していきます。おそらくまた別の課題が出てくるはずなので、そのたびに設定を更新していく形になると思います。
最初から完璧な運用ルールを作ろうとしなかったのは、振り返ってみても正解でした。実際に使って困ったことしか、本当に必要な設定にはならない。手戻りは発生しましたが、それを含めて必要なコストだったと思っています。
導入を検討している方の参考になれば。
