最近、Reddit で興味深い投稿を見つけました。
あるエンジニアが Claude Code を6か月間本格的に使い込んだ結果、30万行規模のプロジェクトを一人で書き換えた経験を共有していたのです。
私もAIツールを活用した開発には興味がありました。
そのため、この投稿とそのコメントを詳しく読み込みました。
そこには実戦で鍛えられた貴重なノウハウが詰まっていました。
今回は、その投稿から学んだ Claude Code の実践的な活用法をまとめてご紹介します。
これは単なる使い方ではありません。
大規模開発で実際に機能するシステムの構築方法です。
なぜ Skills 機能が使われないのか
Anthropic が提供する Skills 機能。
これは再利用可能なガイドラインを Claude が参照できる素晴らしい機能のはずでした。
しかし、現実は違います。
多くの開発者が同じ問題にぶつかっていました。
Skills を作成しても、Claude がそれを使ってくれないのです。
投稿者も同じ壁にぶつかっていました。
フロントエンド開発、バックエンド開発、データベース操作など、数千行に及ぶベストプラクティスを Skills として整備しました。
それなのに Claude は Skills を無視し続けたそうです。
まるで高価な装飾品のように、そこにあるだけで機能しない。
これが多くの開発者が経験する Skills の現実でした。
Hooks による自動化という発見
この問題を解決する鍵は「Hooks」でした。
Claude が自発的に Skills を使わないなら、強制的に使わせればいい。
そんな発想から生まれたのが、TypeScript による Hooks システムです。
このシステムは2段階で動作します。
まず「UserPromptSubmit Hook」が、あなたのメッセージが Claude に届く前に介入します。
そして、プロンプトの内容を分析し、関連する Skills があれば、Claude への指示を自動的に挿入するのです。
たとえば「レイアウトシステムはどう動作しますか?」と質問するとします。
その際、Claude が読む前に「🎯 SKILL ACTIVATION CHECK – Use project-catalog-developer skill」という指示が追加されます。
次に「Stop Event Hook」が、Claude の応答完了後に動作します。
これは編集されたファイルを分析し、エラーハンドリングが必要な箇所があれば、優しくリマインドを表示します。
この仕組みにより、Skills の活用率が劇的に向上したそうです。
設定ファイルで制御する賢さ
Hooks システムの中核は skill-rules.json という設定ファイルです。
各 Skill に対して、以下の条件を定義できます。
- キーワードによる明示的なマッチング。「layout」「workflow」「database」といった単語を検出します。
- 意図パターンの正規表現。「create」や「add」といった動作と、「feature」や「route」といった対象を組み合わせて検出します。
- ファイルパスのトリガー。編集中のファイルの場所で判断します。
- コンテンツのトリガー。ファイルに含まれる特定のパターンで判断します。
たとえばバックエンドのコードを編集していると、自動的にバックエンド開発ガイドラインが適用されます。
フロントエンドなら React のパターンが適用されます。
こうして一貫性のあるコードが生成されるようになったのです。
開発ドキュメントで文脈を維持
Claude Code には致命的な弱点があります。
それは「健忘症」です。
自信満々に作業を進めていても、30分後には当初の計画を忘れてしまう。
これを防ぐために考案されたのが「Dev Docs システム」でした。
大きなタスクを開始するとき、必ず3つのドキュメントを作成します。
- 計画書には、承認された実装計画を記録します。
- コンテキスト文書には、重要なファイルや設計上の決定事項を記録します。
- タスクリストには、作業項目のチェックリストを作成します。
これらのドキュメントは dev/active/[task-name]/ というディレクトリに保存されます。
そして、Claude が常に参照できる状態にします。
作業を再開するときは、まずこれらのドキュメントを読み込ませてから作業を続行するのです。
シンプルな仕組みですが、効果は絶大でした。
Claude が途中で迷子になることがなくなったそうです。
PM2 でバックエンドのデバッグを変革
7つのマイクロサービスが同時に動作するバックエンド。
その問題は、Claude がログを見られないことでした。
最初は各サービスのログをファイルに書き出していました。
Claude はファイルを読めるため、一応機能します。
しかし、リアルタイムではありませんでした。
そこで導入したのが PM2 です。
これは Node.js のプロセス管理ツールですが、Claude との相性が抜群でした。
PM2 を使うと、すべてのサービスが管理されたプロセスとして動作します。
そして、各サービスのログは個別のファイルに記録されます。
その結果、Claude はリアルタイムでログを確認できるようになりました。
「メールサービスでエラーが発生している」と伝えると、Claude は自分で pm2 logs email –lines 200 を実行してログを確認します。
そして問題を特定し、pm2 restart email でサービスを再起動します。
人間がログをコピペする必要がなくなったのです。
エラーを残さない自動チェック
TypeScript のエラーを残したまま次の作業に移る。
これも Claude の悪い癖でした。
数時間後にビルドを実行すると「いくつか TypeScript エラーがありますが、今の作業とは無関係なので問題ありません」と言い出す始末。
いや、問題大ありです。
この問題を解決するため、編集後の自動チェックシステムを構築しました。
まず「File Edit Tracker」が、どのファイルが編集されたかを記録します。
次に「Build Checker」が、Claude の応答完了時に動作します。
これは編集されたリポジトリでビルドを実行し、TypeScript エラーをチェックします。
5個未満なら Claude に表示し、5個以上なら自動修正エージェントの起動を提案します。
このシステムを導入してから、エラーが残ることはなくなったそうです。
Prettier による自動フォーマットの落とし穴
当初は Prettier による自動フォーマットも Hook に組み込んでいました。
これは Claude が編集したファイルを自動的にフォーマットする仕組みです。
しかし、重大な問題がありました。
ファイルが変更されるたびに、Claude は という通知を受け取ります。
この通知には変更された行の情報が含まれており、大量のトークンを消費するのです。
検証では、Prettier のフォーマットだけで16万トークンも消費したケースがあったそうです。
特に大きなファイルや厳格なフォーマットルールがある場合、影響は甚大になります。
この問題を受けて、投稿者は Prettier Hook を削除しました。
フォーマットは手動編集時に実行すれば十分だという結論に至ったのです。
計画こそすべての基盤
「計画なしに Claude Code を使うのは、設計図なしに家を建てるようなもの」
投稿者はこう断言していました。
新機能の開発を始めるときは、必ずプランニングモードを使用します。
プランニングモードの Claude は、通常モードより優れた調査能力を発揮するそうです。
さらに strategic-plan-architect というサブエージェントを作成しました。
このエージェントは、コンテキストの収集、プロジェクト構造の分析、包括的な計画の作成を自動化します。
計画には、エグゼクティブサマリー、フェーズ、タスク、リスク、成功指標、タイムラインが含まれます。
そして、これらが自動的に3つのファイル(計画書、コンテキスト、タスクリスト)として生成されるのです。
重要なのは、生成された計画を人間が必ず精査することです。
Claude の提案を鵜呑みにせず、理解し、必要に応じて修正します。
この過程が、プロジェクトの成功を左右するといいます。
Skills の構造化と最適化
Anthropic の公式ベストプラクティスによれば、Skills のメインファイルは500行以内に抑えるべきだそうです。
投稿者は最初、この指針を知らずに1,500行を超える巨大な Skills を作成していました。
これではトークンを無駄に消費してしまいます。
そこで Skills を再構築しました。
- フロントエンド開発ガイドライン：398行のメインファイル + 10個のリソースファイル
- バックエンド開発ガイドライン：304行のメインファイル + 11個のリソースファイル
メインファイルは軽量に保ちます。
そして、詳細な情報は必要に応じてリソースファイルから読み込みます。
この構造により、トークン効率が40~60%改善したそうです。
実用的なスクリプトの活用
Skills にユーティリティスクリプトを添付するパターンも有効でした。
たとえば、認証が必要なルートのテストについて説明するだけでなく、実際のスクリプトを提供します。
node scripts/test-auth-route.js http://localhost:3002/api/endpoint
このスクリプトは、Keycloak からリフレッシュトークンを取得し、JWT で署名し、Cookie ヘッダーを作成し、認証付きリクエストを実行します。
Claude がルートをテストする必要があるとき、スクリプトの存在と使い方を知っています。
そのため、毎回新しいスクリプトを生成する必要がありません。
車輪の再発明を防げるのです。
まとめ
Reddit の投稿から学んだ Claude Code の活用法。
それは単なるテクニック集ではありませんでした。
大規模プロジェクトで実際に機能するシステムの構築方法でした。
Skills の自動化、文脈の維持、エラーの撲滅、計画の重要性。
すべてが実戦で鍛えられた知恵です。
投稿者は最後にこう締めくくっていました。
「私はただの一人のエンジニアで、これは私のやり方に過ぎない」と。
しかし、30万行のコードを一人で書き換えた経験から生まれた知見には、確かな説得力があります。
AIツールは急速に進化しています。
しかし、それを使いこなすのは結局人間です。
適切なシステムを構築し、AIの長所と短所を理解した上で活用する。
そうすれば、一人でも大規模なプロジェクトを成し遂げられます。
この投稿は、そんな可能性を示してくれました。
