Thread by @mah_lab

「Claude Code、あんまり使いこなせていないんだよねー」というメンバーに、Claude Codeの使い方をハンズオンしながら話した内容を録音→整理してみたので投稿します。

あくまで私の日常的な利用方法を示したものなので、細かいところは人それぞれの部分があると思います。

以下、スレッドにて👇

【段階的かつドキュメント中心のアプローチ】
AIにいきなりコードを書かせるのではなく、段階を踏んでドキュメントを介して作業を進めることが重要。

① 要件定義・仕様化を最初に行う
💡AIにいきなりコードを書かせるのではなく、まず要件を伝えて仕様書（マークダウンなど）を生成させ、それを人間がレビュー・修正する。

AIが「何をするべきか」を正確に理解していない状態で始めると、見当違いな実装をしてしまい、大規模な手戻りが発生する。

→複雑なタスクを依頼する際は、「この機能を作って」ではなく、「この要件を元に、実装方針をまとめた仕様書を作成して」と指示すること。開発者とAIの間での認識のズレを開発初期段階で最大限解消することが重要。

② 仕様書（中間成果物）を常に更新する
💡AIとの対話を通じて得られた発見や方針転換は、常に仕様書（中間ドキュメント）に反映させ、それを「正」として作業を進める。

口頭だけの指示ではコンテキストが流れてしまい、AIも人間も文脈を見失う。共有されたドキュメントという「中間地点」があることで、AIが混乱した際に立ち戻る場所ができ、プロセスが安定する。

→AIとの対話は、常に共有ドキュメントを更新しながら進めること。AIからの提案や人間からの指示は、まずドキュメントに反映させ、その最新版を元に次のアクションを指示する習慣をつける。

③ 実装前にタスクを細分化させる
💡仕様が固まったら、実装を一気に依頼するのではなく、AI自身に「この仕様を実現するためのToDoリスト」を作成させる。

一度に大きなタスクを任せると、AIが混乱するリスクが高まる。事前にAI自身にタスクを分割させることで、その思考プロセスを可視化し、無理のある計画や見落としを実装前に発見できる。

→「この仕様書を元に開発して」と指示する前に、「この仕様書を実現するための開発ステップを、1つずつ動作確認できる粒度でリストアップして」と依頼する。リストをレビューし、作業内容について合意してから実装の許可を与える。

【「コーチング」的に対話し、AIの能力を引き出す】
AIを単なるツールとしてではなく、学習・成長するパートナーとして捉え、その能力を引き出すコミュニケーション態度をとる。

① 明確な共通言語・専門用語を使う
💡曖昧な日常言語よりも、技術的な専門用語を積極的に使う。

AIは一般的な技術用語で大量に学習しているため、「クラスの責務を一つに」と説明するより「単一責任の原則に従って」と指示する方が、意図を正確かつ簡潔に理解する。

→プログラミングの原則（SOLIDなど）、デザインパターン、アーキテクチャ名など、業界の共通言語を使って指示を出す。コミュニケーションコストが削減され、AIの出力精度が向上する。

② AIが「気づく」まで待つ・誘導する
💡人間が細かく指示してそれに従わせるよりも、AI自身に最適な解決策を「発見」させる。

AIが自らより良い実装方法（例: 構造化出力ライブラリの利用）にたどり着くことで、その後の実装の一貫性と精度が格段に向上する（気がする）。

→AIが非効率な実装を提案したら、「もっとLLMの能力を活かせない？」「この部分の処理、何か便利なライブラリはない？」といった問いを投げかけ、AIの思考を促す。

③ AIの思考のクセを理解し、誘導する
💡AIが特定のパターン（例: 単純なルールベースの実装）に固執する傾向を理解し、それを乗り越えるための明確な指示を与える。

AIの学習データは従来のコードが中心であるため、デフォルトではLLMらしい文脈理解を伴う処理よりも、古典的な文字列検索などを選択しがち。このクセを理解し、適切な場面で思考のモードを切り替えさせる必要がある。

→AIが生成したコードが「賢くない」と感じた場合、「この部分は単純なキーワード検索ではなく、LLMに文脈を判断させて」のように、期待する処理のレベルを明示する。

【AIが自律的に動ける環境の整備】
AIが能力を最大限に発揮できるよう、人間側が適切な作業環境とツールを提供することが重要。

① AIが外部環境を認識できるようにする
💡開発対象のAPIスキーマやデータベース構造などを、AIが自らアクセスして情報を取得できる環境を整える。

MCPサーバのような仕組みを用意することで、例えば連携先システムの状態などを自律的に把握できるようになる。これにより、人間が都度仕様を説明する手間が省け、AIの状況認識の精度が高まる。

→MCP化が難しい場合であっても、外部APIのスキーマ定義ファイル（OpenAPIなど）やデータベースのスキーマ情報をプロジェクトに含め、AIがそれらを参照できるように設定する。

②自己検証できるツールを提供する
💡Linterやテストフレームワークを整備し、AIが生成したコードの品質を自らチェックできる仕組みを作る。

「自分で動作確認しながら進めて」と指示することで、AIはアドホックなテストを実行し、問題があれば自己修正を試みる。これにより、人間がレビューする前に、基本的な品質が担保されるようになる。

→プロジェクトにLinter、フォーマッタ、単体テストの実行コマンド（例: make lint、make test）を用意し、CLAUDE\.mdに「コミット前には必ずテストとLintを実行すること」といったルールを明記する。

③ コーディング規約を明文化する
💡AIに守ってほしいコーディングスタイルや設計方針をCLAUDE\.mdに明記する。

→プロジェクトには反映したくないけど個人的に守って欲しいことはCLAUDE\.local\.mdに書くと良い。

【AI時代の開発者のマインドセット】
AIとの協業は、開発者の役割やスキルセット、さらには「良いコード」の定義さえも変える。

① 基本（タスク分割）に立ち返る
💡開発タスクを細かく分解するという基本的なプラクティスを、AIとの協業において徹底する。

ベテラン開発者は、経験からタスク分割を頭の中だけで済ませがちだが、AIに期待通りの動作をさせるためには明確な指示をする必要がある。AIという「新人プログラマ」と協業するには、この基本動作が改めて重要になる。

※「新人プログラマ」というのは、単にプロジェクトの長期コンテキストを知らないだけであって、実力が新人というわけではない。

→これまで無意識に行っていた思考プロセスを意識的に言語化し、タスクを分解するスキルを磨き直すこと。AIを使いこなす能力は、実は古くからある基本的な開発スキルに根差している。

② 「AIにとっての良いコード」を意識する
💡 「良いコード」の定義を、「人間にとって可読性が高く、パフォーマンスが高いコード」だけでなく「AIが理解しやすく、拡張しやすいコード」へとアップデートする。

責務が明確に分離され、命名が分かりやすい構造的なコードは、AIがその意図を正確に読み取り、精度の高い修正や機能追加を行うための土台となる。

→コードを書く際に、パフォーマンスだけでなく、構造の明瞭さや責務の単一性をより重視しましょう。疎結合なコードは、AIにとってテスト実行などの試行錯誤しやすい状態を作り出せるので、人間だけでなくAIにとってもメンテナンス性の高い資産となる。

③ 開発者の役割は「アーキテクト兼レビューア」へ
💡開発者の主業務は、コードを書くことから、AIへの指示出し、方針決定、生成物のレビューへとシフトする。

開発時間のほとんどが、AIとの対話による仕様の整理や設計の壁打ちに費やされることになる。詳細な実装はAIに委任し、人間はより上流の創造的な作業に集中する。

→自身の役割を「手を動かすコーダー」から、「AIというアシスタントを率いる設計者・プロジェクトマネージャー」へと再定義する。重要なのは、何を作るかを定義し、AIの作業を監督・指導し、最終的な品質に責任を持つこと。

書き忘れたこと：
【AIエージェントは「正射必中」ではない】
→プロセスは正しくても、明確なゴール（受け入れ基準／到達精度の定量値など）がないと、期待通りの成果物は得られない。

「プロセスは良い感じなので、きっと良い感じのものができるだろう」と判断するのは、ダメ！絶対！