AIに修正を頼むたびに別の場所が壊れるとき、どう立て直すか

AIにエラーを直してもらったら、今度は別の画面が動かなくなった。もう一度修正を頼むと、前に直したはずの問題が戻ってきた。自分で業務ツールを作る中で、このような状態に困っている方もいると思います。

もし私が相談を受けたら、目の前のエラーに加えて、一度に実装する範囲、仕様の整理、実装と評価の手順、テスト、既存の設計を確認します。原因が分からないまま修正を重ねる前に、何を作ろうとしていて、どこまで確かめられているかを整理したいからです。

この記事では、私が開発で実践している進め方をもとに、修正が終わらなくなったときの立て直し方を紹介します。挙げる項目は、原因を調べるための観点です。毎回すべてを作り直したり、設計を変更したりする必要があるという意味ではありません。

まず、何をすると何が起きるかを残す

「動かないので直して」だけでは、期待した動作と、実際に起きていることが十分に伝わりません。最初に、次の情報を整理します。

• どの画面で、どのような操作をしたか。
• どのような入力や条件で起きたか。
• 本来はどうなるはずだったか。
• 実際には何が起きたか。エラーが出た場合は、その内容。
• 毎回起きるのか、特定の条件でだけ起きるのか。

私は、Sentryに記録されたエラーや、CloudWatch Logsなどに残るアプリの動作記録を確認して、原因を調べます。使うサービスは開発・運用環境によって異なりますが、実際に起きたことの記録を調査に使う考え方は同じです。問題に応じて再現テストも行います。記録がない場合でも、操作と結果を書き出すことから始められます。

また、変更履歴はGitで管理し、コミットという記録の単位でコードを戻せるようにしています。非エンジニアの方も、AIへ「修正前の状態を記録し、今回の変更と比較したり取り消したりできるようにしたい」と相談してみてください。すでに変更がある場合は、何が含まれているかも確認します。

ただし、コードを元に戻しても、書き換えた実データまで戻るわけではありません。データを変更する作業があるなら、その影響と戻し方は別に確認する必要があります。

関連する機能の仕様を、読める言葉で整理する

修正を繰り返しているなら、私は一度、関連する機能全体の仕様を文書にしてもらいます。その上で、直したい箇所がほかの機能にどう関係するか、詳細を整理します。

例えば、注文の状態を変える処理なら、その変更によって一覧への表示や、次にできる操作がどう変わるかも関係します。一つの画面だけを見て直すと、別の画面で期待していた動作と合わなくなる可能性があります。

ここで必要なのは、非エンジニアには読めない技術用語だけの仕様書ではありません。「誰が何をすると、どうなるか」を、自分で確認できる言葉にしてもらいます。

「関連する機能全体について、現在の動作と、私が実現したい動作を整理してください。非エンジニアにも分かる言葉で書き、違っている点や、まだ判断できない点を分けてください。修正する箇所がほかの機能に与える影響も説明してください。」

現在のコードを説明してもらうだけでは、不具合まで正しい仕様として扱われるおそれがあります。文書を読んで「この仕事ではこう動いてほしい」「この操作は必要ない」と確認し、意図と違う部分を直します。技術的に正しい実装かは別途検証が必要ですが、何を作りたいかは利用者自身が判断できます。

全体を整理してから、実装する範囲を分ける

私は、少し表示を変えるような小さな修正を除き、仕様書を作ってから機能を実装します。また、一度に依頼する範囲が大きくなりすぎないように分割しています。

「注文管理機能を作ってください」という依頼には、注文の登録、外部からの取得、一覧、状態変更など、多くの仕事が含まれます。これを一度の実装でまとめて進めるのは、私なら避けます。

ただ、小さく分ける前に、全体で整合する設計は必要です。最初に全体の仕様を整理し、それをもとにAIへタスクの分割を頼むと、個々の機能のつながりも考えやすくなります。

私自身はエンジニアとして工数を見積もりますが、非エンジニアの方には、その判断が難しいと思います。最初の目安は、正常に動くときの流れを、無理なく説明できる範囲です。

例えば、「注文の状態ごとに一覧を分け、状態を変更したら対応する一覧へ表示されるようにする」といった単位です。それでも、実装上はさらに分ける必要があるかもしれません。「外部サービスから注文を取得して保存する」のように、短く説明できても実装には多くの検討が必要なものもあります。

「全体の仕様を踏まえて、実装と動作確認を一区切りずつ行えるタスクに分けてください。それぞれで何を変更し、どうなれば完了か、先に必要な作業は何かを説明してください。」

修正の場合も同じです。関連機能の仕様と影響範囲を整理した後で、修正する範囲を分けます。一つの修正が確認できてから次へ進めるようにすると、何を変えた後に問題が起きたかも追いやすくなります。

作る役割と、確かめる役割を分ける

私が普段使っているのは、仕様書の作成、仕様レビュー、実装、実装後の評価を分ける進め方です。AIに別の作業担当を持たせるサブエージェントを使い、仕様を確認する担当と実装する担当を分けています。

仕様レビューでは、主に次の点を確認させます。

• 曖昧な表現や、決まっていない動作がないか。
• 入力、出力、エラー時の扱いが決まっているか。
• 今回やらないことが明確か。
• 既存の機能と、どのようにつながるか。

指摘を仕様書へ反映してから実装を依頼し、実装後は正確性、仕様との一致、テスト、設計などの観点で評価します。変更の内容によって、レビュー回数の上限や確認の厚みも変えています。

役割を分けても、AI同士が同じ前提を見落とすことはあり得ます。レビューで問題なしと返ってくることだけを完了の根拠にはせず、テストと実際の動作も確認します。私も修正後の動作確認は自分で行っています。

非エンジニアの方が取り入れるなら、まずは「仕様を決める」「仕様を確認する」「実装する」「実装結果を確認する」という段階を、AIへの依頼の中で明確にするところから始められます。

テストがあるか、継続して実行されているかを確認する

修正した場所が動いても、関連する機能が壊れていないかは別の確認です。そのため、テストがどんな動作を確認しているかと、変更時に実行する仕組みがあるかも調べます。

CI（継続的インテグレーション）は、コードの変更をこまめに共通のコードへ取り込み、組み合わせた状態で問題がないかを継続的に確認する開発の進め方です。その確認を支えるために、ビルド（アプリを実行できる形にする処理）やテストを自動化します。詳しくはGitHubのCI解説でも紹介されています。

この記事で確認したいのは、その中でもテストを継続して実行し、結果を確認する仕組みです。テストが用意されていても実行されなかったり、失敗を見逃したりしていれば、問題に気づく機会を失います。

AIには、「今回の修正に関係する既存のテストと、それらが確認している動作を説明して」「テストはいつ実行され、失敗はどこで分かるか確認して」と頼めます。

私の開発ルールでは、不具合を直すためにテストを追加する場合、そのテストが修正前のコードで実際に失敗することも確認します。修正前にも成功してしまうなら、その不具合を検出できているか見直す必要があります。既存のテストで確認できるなら、それを使います。

今回だけの確認を、すべて残すテストにしない

一方で、テストは増やせばよいとも考えていません。私がAIの実装を確認するときは、今回の変更だけに必要なテストが、恒久的なテストとして追加されていないかも見ます。

例えば、画面の要素を一つ削除したとき、AIが「削除した要素が存在しないこと」を確認するテストを追加することがあります。しかし、変更後の画面で何がどう表示されるべきかを既存のテストが確認できていれば、そのテストは重複している場合があります。私は、そのような不要な追加は削除します。期待する表示が変わるなら、既存のテストを更新します。

もちろん、権限のない人に情報を表示しないなど、「表示されないこと」自体が守るべき仕様なら、確認する意味があります。判断するのは、不在を確認しているかどうかではなく、今後も守りたい仕様を検証しているかです。

今回の変更直後に確かめる作業と、今後も繰り返し実行するテストを分ける。重複したテストを積み重ねると、実行を待つ時間や、テストを維持する作業も増えていきます。必要な検証を保ちながら、不要な負担を増やさないことも大切です。

今の用途には不要な複雑さが入っていないかを見る

私の経験では、AIが提案する設計が、小さく方針を変えながら育てたいプロダクトには複雑すぎることがあります。

例えば、実際の業務で必要かを十分に確認しないまま、細かな状態管理や操作制限、履歴の仕組みが追加される場合です。また、短時間の停止を許容できるツールでも、無停止で切り替えるための段階的な処理が提案されることがあります。

一時的な切り替えのために追加した設定や分岐が、その後も残ると、次の実装ではそれも維持すべき仕様として扱われかねません。すでに使っていない処理でも、変更や確認の対象が増えてしまいます。

私自身、ある機能の設計が複雑になっていたことを見落とし、後の機能開発で、想定していた工数や実現したい動作との違いが大きくなった経験があります。最終的には、データの持ち方から見直し、内部の構造を整理し直しました。この経験は「修正するたびに別の場所が壊れた」というものではありませんが、設計の複雑さが後の変更の負担になることを実感した事例です。

すべての履歴や状態管理が不要という意味ではありません。そのツールの利用者、業務、必要な制約に対して、仕組みを追加する価値と、維持する負担が合っているかを確認します。

必要性を判断できなければ、AIに前提を伝え直して問い返してみてください。例えば、実際に短時間の停止を許容できる場合なら、次のように頼めます。

「このツールでは短時間の停止を許容しています。利用者と業務の前提を踏まえて、この仕組みが必要な理由を説明してください。追加しない場合、誰がどのような場面で困りますか。より簡単な方法で対応できますか。追加した後に維持する負担も、非エンジニアに分かる言葉で説明してください。」

移行用の仕組みなら、「いつ不要になり、何を確認して取り除くのか」も聞きます。理解できないまま追加することも、名前だけで不要と決めて削除することも避け、必要性を確認してから判断します。

修正の依頼から、進め方の相談へ切り替える

修正を繰り返しているとき、次の依頼をまた「直して」にする必要はありません。「繰り返さないために、何を整理すべきか」を相談できます。

「修正すると別の問題が出る状態が続いています。まず原因と影響範囲を調べてください。関連機能の仕様、タスクの分け方、レビュー、テストの不足を確認し、何を根拠にそう判断したか説明してください。その上で、修正と確認を分けて進める計画を提案してください。」

そこで出てきた計画を、自分の目的と照らして確認します。仕様を読み直すだけで気づくこともあれば、テストの不足を補う必要がある場合や、設計の見直しが必要な場合もあります。状況に合わせて、取り組む範囲を決めます。

業務としてどう動いてほしいかは分かっても、その実装や設計が適切か判断できない部分は残ることがあります。エラーの記録、関連する仕様、試した修正、まだ確認できていないことがあれば、専門家にも状況を伝えやすくなります。すべてを整理し終えてから相談する必要はありません。

cyfrでは、自分で開発を続けたい方に向けて、作っているものと困りごとを一緒に確認し、次に取り組むことを整理する支援を行っています。修正が進まない、どこから確かめればよいか分からない場合は、AIで作った業務ツールを実務で使うための支援をご覧ください。

修正が落ち着き、社内で使い始める準備を進めたい方には、AIで作った業務ツールを、社内で使い始める前に確認することで、業務に沿った確認や切り替えの考え方を紹介しています。