技術的負債を積み上げずにClaude Codeを実際に使う方法
あるとき、ロードマップには「初日から適切なマイグレーションで本番スキーマを構築する」と書いてあった。Claudeは「単純化してプロトタイプを早く作り、後で繋げればいい」と提案した。私はそれに同意した。
2週間後、本来存在するはずのないデータベースマイグレーションに時間を浪費していた。最初からプランで指定されていた土台を後付けで作り直そうとして、テーブルの書き直しとデータ変換にトークンを燃やした。最初から自分の直感を信じなかったせいで。
ロードマップは正しかった。私が交渉して自分を間違いに導いた。
その経験が何かを明確にした：モデルはもはやボトルネックではない。モデルを取り囲むシステムのガバナンスがボトルネックだ。
プロンプトではなくシステムを最適化する。この原則は製造業とプロセスエンジニアリングでは広く理解されている。トヨタ生産方式、リーン、シックスシグマ。いかなる失敗も最終的にはシステムの失敗だ。システムを修正する。
これがデフォルトにならないことへの驚き。プロンプトのミクロ最適化はモデルが改善するにつれ劣化する。構造的規律は複利で効く。
本番作業の私のルール：ロードマップなし=作業なし。プランモードなし=コードなし。
ロードマップはオプションではない
ロードマップ作業をスキップすると、Claudeはセッションごとにプロジェクトのコンテキストを再発明した。先週の決定と矛盾するアーキテクチャ上の推測を自信を持って行った。その瞬間はまだ生産的に見えた。3セッション後にはコードベースのドリフトがあちこちに現れた。
ウィッシュリストでも、ガントチャートでもない。 明確な成果物と明確な受け入れ基準を持つマイルストーン。 「完了」が何を意味するか言えないなら、そのマイルストーンはまだ準備できていない。
基本ワークフロー:
- コードに触れる前にロードマップを書くか更新する。
CLAUDE.mdからロードマップをリンクする。- 同じリポジトリに複数の関心事があれば、サブフォルダにCLAUDE.mdをネストするか、異なるロードマップへのリンクを持つ別セクションを設けられる。
- キックオフだけでなく、各マイルストーンでプランモードを実行する。
- 現実が変わったらロードマップを更新する。
- 受け入れ基準が本当に満たされたら積極的に完了とマークする。
作業中に何かが出てきたとき:
テストや構築中に、ロードマップが考慮していない何かに気づく。現在のフェーズのサブタスクとしてロードマップに追加するか、大きければ将来のマイルストーンとして追加する。それからプランモードが必要か、Claudeに任せていいかを決める。
私はCLAUDE.mdにこう書いている：「この作業にプランモードが必要だと思うならプランモードを実行する。そうでなければただやる。ロードマップのマイルストーンは常にプランを立てる。」
驚くほど効果的だ。Claudeはプランニングが価値を加えるときを判断するのがかなり上手い。
でも個人的にプランモードが必要だと思ったら、Claudeにプランするよう伝えるだけでいい。常にドキュメントを更新する。常に書き留める。
Claudeは交渉してくる。常にそうだ。 「これはモックできます。」 「これはスコープ外かもしれません。」 「単純化して後で戻りましょう。」
答えはロードマップだ。 スコープ内なら、リリースする。 欠けていて必要なら、追加する。 どちらでもなければ、拒否する。
雰囲気なし。即興劇なし。
プランモードは必須
これは意図的に強調したい部分だ。
プランモードを使ってほしい。 必要だと感じる以上に使ってほしい。 「今回はスキップできる」と思ったとき、それがまさに実行すべきタイミングだ。1
プランモードはオーバーヘッドではない。コントロールサーフェスだ。 それなしでは高速なタイピングとアーキテクチャのドリフトが得られる。 それとともに、悪い前提がコードベースに入る前に捕捉できる。
私のハードルール:
- 最初の実装パスの前にプランモード。
- 全てのマイルストーン境界でプランモード。
- スコープが変わるときはプランモード。
- Claudeが「クイックショートカット」を提案するときはプランモード。
- 作業完了と呼ぶ前にプランモード。
本当に些細な作業の例外:
ファイル全体にわたる変数のリネーム。タイポの修正。依存関係のバージョン更新。 曖昧さゼロの機械的な変更にはプランニングのオーバーヘッドは不要。
しかし不確実な瞬間、または変更が動作に触れる瞬間には、プランする。
これが重要な理由:
- コードが書かれる前にClaudeの推論を開示させる。
- 隠れた依存関係を早期に明らかにする。
- 意図が見えるのでレビューが安くなる。
- 「自信を持って間違えた」実装からの手戻りを削減する。
プランモードをスキップすると20分間は速く感じて、2日間は高くつく。
CLAUDE.mdは生きたドキュメント
人々はCLAUDE.mdを一度書いて、スタイルの好みを追加して、忘れる。そしてセッションが一貫しない理由を不思議に思う。
CLAUDE.mdはプロジェクトメモリ＋オペレーティングポリシーだ。
プロジェクトが変わってCLAUDE.mdが変わらないなら、高速なシステムに古い指示を与えていることになる。
それが大規模で高コストなナンセンスを生む方法だ。
どこでも追いかけてくるグローバル設定
私はグローバルなClaudeルール、スキル、ドキュメント、例のシステムを~/.claude/に保管して全マシンにシンボリックリンクしている。全プロジェクトが即座に同じ基盤を得る。
グローバル設定を更新すると、全プロジェクトが一緒にレベルアップする。新しいテストパターンを追加すれば、全プロジェクトがそれを得る。コードレビュールールを洗練させれば、どこでも適用される。ミスを記録すれば、全ての将来のセッションがそれを知る。
最初のバージョンにはPythonとVueの例があった。pytestとVitestのテスト哲学があった。「感覚」が他の言語に引き継がれると思っていた。
完全に間違いだった。
ログリーダーとパーサーのRustコンポーネントを構築し始めた。哲学が移転しなかったからClaudeはゴミのようなテストを書いた。VueのパターンがE2Eに適用されなかったためE2Eテストは特にひどかった。良い例は大いに役立つ。テストスイートは包括的に見えて完全に通過していたが、ほとんど何もテストしていなかった。
学び：言語の境界は思っていたより重要だ。一般的なパターンは自動的に変換されない。Claudeはあなたの心も読めず、個人的な好み（例：pytest）も知らない。
今は言語固有のルールファイルがある：python.md、vue.md、rust.md、go.md。
Claudeは現在のプロジェクトに重要なものだけを賢く読む。
言語を切り替えると、適切なコンテキストが自動的にロードされる。
グローバルシステム。モジュラーなルール。更新は全体に伝播する。
プロジェクトレベルでのフェーズ適切な構造
プロジェクト固有のCLAUDE.mdはこのコードベースに特有のものを扱う:
- グリーンフィールド: 何を構築し、何を拒否するかを定義する。
- フィーチャーフェーズ: アクティブな機能に明示的なセクションとロードマップリンクを付ける。
- メンテナンスフェーズ: 鋭いエッジ、歴史的決定、既知のトラップをドキュメント化する。
グローバル設定は一貫したインフラを提供する。 プロジェクト設定は特有のコンテキストを提供する。 両方にメンテナンスが必要だ。
定期的にコーディングなしでレビューする:
「矛盾とドリフトについてCLAUDE.md、ルール、スキルを見ていこう。」
そのトークン消費はすぐに元が取れる。
まだ持ち続けている一つの迷信: Claudeに自身のルールの一部を下書きまたは改訂させる。2 証拠なし。コストゼロ。助けになるようだ。
Claudeサイズのアーキテクチャ
最初の記事で認知エンベロープを枠組みした。これはその実践的な含意だ。
クリーンなインターフェースとコンパートメント化されたモジュールは単に「良いエンジニアリング」ではない。エージェント駆動の作業がセッションをまたいで一貫性を保つ方法だ。認証にクリーンなAPIがあれば、Claudeは毎セッション認証の内部を再導出することなく、認証に依存するフィーチャー作業をリリースできる。境界が不明瞭なら、Claudeはあまりに多くの状態を保ち続け、推測を始め、ドリフトが始まる。
だからエンベロープと戦わない。それに合わせて設計する。明示的な境界を持つ小さなモジュール。境界間の安定したコントラクト。マイルストーンごとのローカルコンテキスト。1回の実行でのクロスカッティングな変更を少なく。
副作用：人間にとってもクリーンなコードベース。ボーナスではなく、直接の結果だ。
ロール別委任
洞察は「XモデルをYタスクに常に使え」ではない。 洞察は：アーキテクチャ思考を実行からレビューから分離することだ。
Opusはプランニング、アーキテクチャ、思考を担当する。高コストの推論作業。安いモデル（Haiku、Sonnet）のスポットフィクサーエージェントが機械的なマルチファイル変更を処理する。20ファイルにわたる参照変更、importの更新、大規模リネーム。1ファイルに1行変更するためだけにOpusに20ファイルを読ませたくない。トークン効率優先であって、能力の限界ではない。
バックグラウンドオーディターは適格な作業の後、聞かずにSonnetで実行される。test-auditor、security-auditor、ux-auditor。弱いテストやセキュリティリグレッションを作成時に捕捉する方が、サイクル終了時のレビューよりずっと安い。これが価値が積み上がる場所だ。
制約がOpusの制限（Proプラン）なら、高強度のアーキテクチャにOpusを使い、実装にSonnetを使う。どちらにしろ同じ原則：思考を実行から分離する。
テストはゲートであって儀式ではない
「全テスト通過」はマイルストーンではない。
Claudeが明示的なテスト哲学なしでテストを書いたなら、ソフトボールを期待する。
assert True、存在チェック、動作が壊れても通過するアサーションはまだよくある失敗モードだ。
私のパターン:
- プロジェクトドキュメントでテスト哲学を定義する。
- 意味のある失敗条件を要求する。
- 自動スイートを実行する。
- クリティカルなユーザーフローを手動でクリックする。
- テストが捕捉できるか検証するために意図的に動作を壊す。
「失敗するテストはギフトだ。」
test-auditorがこれを強制する。assert True、存在チェック、動作が壊れても通過するアサーションへの許容はゼロ。
Claudeはデフォルトで簡単なテストを書く。オーディターはコミットされる前の作成時にそれを捕捉する。レビュー時や本番で見つけるより安い。
私が見た好きな簡単テスト：出力があるかどうかをチェックするもの。関数が何かを返す限りテストは通過する、そうだろう？オーディターはそれを見つけてClaudeが修正する、あなたが別の場所でアーキテクチャ作業をしている間に。
フロントエンド作業では、人間によるパスは非交渉可能だ。Claudeはチェックとブラウザ自動化を実行でき、大いに助けになる。それでもユーザーが感じる摩擦、混乱、退屈は感じられない。
怠惰にさせるな 3
Claudeが「怠けています」と言うことはほとんどない。 こう言う:
- 「これを単純化できます。」
- 「今はこれで十分です。」
- 「それはスコープ外のようです。」
各提案は単独では合理的に聞こえる。積み重なると、本番コードにプロトタイプロジックが生まれる。
これを苦労して学んだ。根本的なバックエンド変更を伴うAPIv2を構築していたとき。異なる認証モデル、再構築されたデータフロー、パフォーマンス改善。セッション作業を確認したら問題なさそうだった。もっと深く掘り下げたら、v2エンドポイントの半分がv1関数へのパススルーだった。エージェントが既にあるものを再利用することで「動く」ようにした。型シグネチャは一致した。テストは通過した。しかし全ポイントはやり方を変えることだった。古い関数は望む方法ではなかった。
それはガバナンスシステム前の話だ。ロードマップ規律前。必須プランモード前。
失敗はエージェントではなかった。誤ったパターンマッチングとショートカットを許したシステムの失敗だった。システムを修正した。CLAUDE.mdを更新した。ロードマップを締め付けた。より良い例を追加した。
対策は常に構造だ。押し返して、システムを強固にする:
- ロードマップの受け入れ基準を締め付ける。
CLAUDE.mdを更新する。- ルールとスキルを追加または洗練する。
- プランモードを実行する。
システムの問題だ。常にシステムの問題だ。強固にすれば、説得力あるショートカットが機能しなくなる。
メンテナンスコストは本物だ
これら全ては維持するための作業が必要だ。古いガバナンスはガバナンスなしより悪い。なぜなら自信を持って従われるから。
経済性:
初期コスト：ロードマップメンテナンス、ルール更新、オーディターセットアップ。 長期節約：手戻り削減、リグレッション減少、コンテキスト再導出なし。
最初の週はオーバーヘッドのように感じる。3ヶ月後には明らかに価値があった。最終的にClaudeが物事を書き留め、記憶し、YOU自身をトラックに乗せてくれるようになる。価値は双方向に流れる。
アーキテクチャ、コントラクト、ドキュメントに投資した時間は、将来の全セッションでの再調査を削減する。プロンプトのミクロ最適化に投資した時間は、ベースラインモデルが改善するにつれ月を追うごとに価値が下がる。
より良い問いはこうではない: 「このインタラクションからより多くのトークンを絞り出すにはどうすればよいか？」
より良い問いはこうだ: 「次の50インタラクションでより良い結果をもたらすシステム変更は何か？」
その答えは通常、構造であって、プロンプト詩ではない。
システムを最適化する、プロンプトではなく。
革命的な工場自動化を手に入れたなら、それを中心に生産ラインを再編成する。既存のプロセスに落とし込んで願うだけではない。
同じだ。ツールの制約がそれを使うシステムを再形成する。
クロージング
あなたは自分自身とツールから価値ストリームを構築している。安く、速く、クリーンに価値を得ることも、ゆっくりと乱雑に得ることもできる。道は構造、境界、明示的な意図だ。
ロードマップ規律。積極的なプランモード。生きたプロジェクトメモリ。モデルの制約に合わせたアーキテクチャ。ロール別委任。厳格なテストゲート。Claudeが手戻りを引き起こしたとき、システム欠陥として扱う。再発しないようにロードマップ、ルール、テスト哲学を更新する。いかなる失敗も最終的にはシステムの失敗だ。システムを修正する。4
エージェント作業をオートコンプリートとして扱うのをやめる。工場として運用する。