目次

明確な制約や十分なレビューなしにClaude Codeへ機能実装を任せると、変更しにくいコードが生まれることがあります。実装は委ねても、設計判断、検証、最終的なマージには責任者を置きましょう。

要点#

  • 単独では動く機能でも、アプリケーションのAPI契約、権限、データモデルと整合しない場合があります。
  • Claude Codeに変更を依頼する前に、具体的な参考実装と明確な制約を示しましょう。
  • 設計の一貫性だけではコードの正しさや安全性は保証されないため、構造と動作の両方をレビューしましょう。
  • 元記事の「1〜2か月」という警告は、測定に基づく期限ではなく、経験談として扱いましょう。

不整合が積み重なる仕組み#

提示されたゆうき氏の記事は、よくある失敗パターンを説明しています。開発者が個別の機能を依頼し、動く成果物を受け入れた結果、後になって実装同士がかみ合わないと気づくのです。あるエンドポイントだけレスポンスの構造が異なり、別のエンドポイントではエラー処理が異なります。タスクごとに独自の実装が追加され、似たヘルパー関数も増えていきます。

こうした違いは、次の変更に必要な作業を増やします。開発者はまず、どの規約が適用されるのか、重複した関数が同じ動作をするのか、既存のレスポンスにどの呼び出し元が依存しているのかを調べなければなりません。個々の成功が、保守上の問題になるのです。

記事では、この悪化が1〜2か月で起こるとしていますが、裏付けとなるデータは示されていません。この問題を経験するチームの割合に関する主張も、検証が必要です。警告をきっかけに作業の進め方を点検し、その期間を予測として扱わないようにしましょう。

委ねる前に決める#

実装を依頼する前に、短い作業指示書を書きましょう。小さな変更なら、まず5分を充てます。認証、決済、データベースのマイグレーション、公開インターフェースに影響する作業には、より多くの時間を確保してください。

次の4点を含めます。

1. 期待する動作： ユーザーが何をできるようになるのか、操作が失敗したときにどうなるべきかを示します。 2. 参考ファイル： 意図したパターンに従う既存の実装を指定します。 3. 制約： 権限、レスポンス形式、依存関係、互換性の要件を明示します。 4. 受け入れ確認： 変更が正しく動くことを示す、観察可能な結果を記述します。

たとえば、「商品検索エンドポイントを参考に、注文検索を追加してください。既存のページネーション形式を維持してください。ユーザーが検索できるのは、自分の組織に属する注文だけです。検索結果が空の場合と、別の組織の注文へのアクセスを試みた場合を検証してください」と指示します。

これにより、Claude Codeに具体的な目標を示せます。成果物も評価しやすくなります。

判断の根拠を追えるようにする#

元記事は、人間が判断し、AIが作業を行うべきだと主張しています。責任の所在を明確にするルールとしては有用ですが、能力の線引きとしては厳しすぎます。Claude Codeはリポジトリ内のファイルを調べ、設計を提案し、トレードオフを説明できます。ただし、その提案はプロジェクトの実際の制約に照らして検証する必要があります。

調べたファイルを挙げ、既存のパターンを説明し、そこから外れる提案には理由を示すよう求めましょう。「アーキテクチャに従っています」という説明だけでは、根拠として不十分です。具体的なファイル名やインターフェース契約に基づく比較のほうが役立ちます。

重要な判断はリポジトリに記録しましょう。エンドポイントが特定のエラー形式を使う理由を短く記すだけでも、同じ議論の繰り返しを防げます。実装がその判断に従っているかをレビュー担当者が確認できるよう、具体的に書いてください。

構造だけでなく動作もレビューする#

元記事は、構造が正しければ実装の詳細はおおむね信頼できると示唆しています。しかし、この助言は行き過ぎです。整理された関数でも、認可チェックが抜けていたり、トランザクションを誤って処理したり、機密情報を漏らしたりする可能性があります。

提案された変更を、次の2つの観点でレビューしましょう。

  • 設計： このモジュールに置くべきか、適切な抽象化を再利用しているか、既存の契約を維持しているか。
  • 動作： 権限を適切に適用しているか、失敗を正しく処理しているか、関係する境界条件で期待どおりの結果になるか。

テストは判断の代わりではなく、根拠として使いましょう。AIが生成したテストは、実装と同じ思い込みを繰り返す場合があります。期待する動作を独立して定義し、起こり得る不具合をテストで検出できるか確認してください。注文検索なら、ある組織が別の組織のレコードを取得できてしまわないかを確認すると有効です。

追加する前にずれを直す#

すでに規約がばらついているなら、次の機能を依頼する前に、頻繁に変更される領域を1つ調べましょう。レスポンス形式、エラー処理、重複したヘルパー関数を比較します。参考実装は、正しく動作することを確かめてから選んでください。

そのうえで、範囲を絞って修正します。契約を1つ統一するか、重複した処理を1つにまとめ、呼び出し元を検証し、その変更を単独でマージしましょう。影響をレビューしにくい大規模な整理は避けてください。

その後の数回の変更では、リグレッション、レビューでの手戻り、正しいパターンを特定する時間、小さな機能のために変更したモジュール数など、保守状況を示す指標を追いましょう。こうした観察からは、生成された行数や自信に満ちた完了報告よりも多くのことが分かります。

次の一歩#

次にClaude Codeへ依頼する前に、期待する動作、参考ファイル、制約、受け入れ確認を含む作業指示書を書き、それを使って生成された差分をレビューしましょう。

出典: https://note.com/yukiedu/n/n4d25f5e1d590

目次