「動いてるんだから、いいじゃないですか」――その『動いている』は、誰も中身を説明できなくなった瞬間に、もっとも直しにくい資産へと変わります。 AI に自然言語で指示してシステムを作る「バイブコーディング（vibe coding＝雰囲気で作る開発スタイル）」では、驚くほど短時間で「動くもの」が完成する。ところが、その「動くもの」は、書いた本人ですら数ヶ月後には「なぜこう書いたのか」を説明できず、引き継いだ人は**「どこを触れば何が起こるのか分からない」――そんな保守不能（unmaintainable）**の状態に陥りやすい。

ソフトウェアは、作って終わりではない。仕様変更・障害対応・法改正対応・セキュリティ修正と、作った後の「直し続ける」期間のほうが、はるかに長い。「動くもの」を作る能力と、「直し続けられるもの」を作る能力は別物である。AI は前者を劇的に速くしてくれるが、後者――保守性（maintainability）――は、人間が意識して設計しないと、簡単に失われる。

連載「バイブコーディング危機」は、第 11 回（セキュリティスキャン）・第 12 回（ノーコード/ローコードの技術的負債）・第 13 回（OSS ライセンス混入）と「防衛策の実装編」を進めてきた。本記事・第 14 回は、その実装編の中でも、組織にとって最も静かに、しかし深く効いてくる問題――「動くけど誰も直せない」引き継ぎ問題を扱う。これは第 8 回（退職者がブラックボックスを残す日）で扱った属人化と地続きの、AI 時代版の課題である。

本記事では、なぜ「動くけど直せない」が生まれるのか、保守性を決める 6 つの要素、AI 生成コードを「引き継げる状態」にする実務、設計判断の記録（ADR）と README、中堅企業の現実的な対応ステップ、FAQ を整理する。「AI に書かせるな」ではなく、書かせるからこそ、引き継げる状態に整えましょう、という趣旨である。

目次

  1. なぜ「動くけど誰も直せない」が生まれるのか
  2. 保守性を決める6つの要素
  3. AI生成コードが特に陥りやすい3つの罠
  4. AI生成コードを「引き継げる状態」にする実務
  5. 設計判断の記録（ADR）とREADME
  6. 中堅企業の現実的な対応ステップ（30〜90日）
  7. 中堅・中小企業が陥りやすい5つの失敗
  8. よくある質問（FAQ 10問）
  9. 参考一次ソース
  10. まとめ
  11. 関連記事

なぜ「動くけど誰も直せない」が生まれるのか

「動くけど誰も直せない」は、サボった結果ではなく、「動くこと」だけをゴールにした自然な帰結である。仕組みを整理する。

理由1：「動いた」で開発が止まる

バイブコーディングでは、AI が出力したコードが動けば、そこで開発が「完了」と見なされやすい。動作確認はするが、「半年後の自分や他人が読めるか」は確認しない。可読性・ドキュメント・テストは、動作とは別に意識しないと作り込まれない。

理由2：書いた人も「なぜ」を覚えていない

AI との対話で次々に修正を重ねると、最終的に動いたコードについて、「なぜこの作りになったのか」という判断の経緯が、人間の頭にもコードにも残らない。数ヶ月後には、書いた本人ですら「これは何のためだったか」を説明できなくなる。第 8 回で扱った属人化が、書いた本人の中でさえ起こる。

理由3：一貫性のない継ぎ接ぎ

AI は、その都度の指示に応じてコードを出力する。全体の設計方針を人間が持っていないと、**命名・構造・パターンがバラバラの「継ぎ接ぎ」**になりやすい。部分的には動いても、全体として読み解くのが難しいシステムになる。

理由4：テストがないので「触れない」

テストがないと、変更したときに何が壊れるか分からない。すると引き継いだ人は、**「怖くて触れない」「動いているから触らない」**を選ぶ。結果、必要な修正がされず、システムは硬直化していく。第 11 回・第 12 回で繰り返し触れた「壊れたら気づけるか」が、ここでも効いてくる。

「保守できないシステム」は資産ではなく負債

動いていても、誰も安全に直せないシステムは、第 12 回で扱った 技術的負債そのものである。仕様変更や障害対応のたびに、解読・再調査という「利子」を払い続けることになる。

要点：「動くけど直せない」は、能力ではなくゴール設定の問題である。「動く」をゴールにすれば直せないものができ、「引き継げる」をゴールにすれば直せるものができる。

保守性を決める6つの要素

「引き継げるかどうか」は、感覚ではなく、いくつかの具体的な要素に分解できる。保守性を決める 6 つの要素を整理する。

要素1：可読性（読んで意図が分かるか）

コードを読んだときに、「何をしているか」が素直に理解できるか。過度に技巧的・難解な書き方は、動いても保守性を下げる。

要素2：命名（名前が説明になっているか）

変数・関数・テーブルなどの名前が、その役割を表しているか。意味のない名前・誤解を招く名前は、読み手の負担を大きく増やす。

要素3：構造（責任が分かれているか）

機能ごとに役割が分かれ、「どこを直せば何に影響するか」が見通せるか。すべてが一箇所に詰め込まれた構造は、一部の変更が予期せぬ箇所に波及する。

要素4：ドキュメント（外から把握できるか）

コードを全部読まなくても、システムの目的・全体像・動かし方が分かる説明があるか。README・構成図・運用手順などがこれにあたる。

要素5：テスト（壊れたら気づけるか）

主要な振る舞いについて、変更後に「壊れていないか」を確認できる仕組みがあるか。テストがあれば、引き継いだ人も安心して手を入れられる。

要素6：判断の記録（なぜそうしたか分かるか）

「なぜこの設計・この技術を選んだか」という意思決定の理由が残っているか。これがないと、引き継いだ人は「変えていいのか、変えてはいけないのか」を判断できない。

6要素 早見表

要素問い欠けると起こること
可読性読んで意図が分かるか解読に時間がかかる
命名名前が役割を表すか誤解・読み違い
構造責任が分かれているか変更が予期せぬ箇所に波及
ドキュメント外から全体像が分かるか全部読まないと分からない
テスト壊れたら気づけるか怖くて触れない
判断の記録なぜそうしたか分かるか変えていいか判断できない

AI生成コードが特に陥りやすい3つの罠

人間が書いたコードでも保守性は問題になるが、AI 生成コードには特有の罠がある。

罠1：もっともらしいが一貫しないコード

AI の出力は、個々は「もっともらしく」見えるが、全体としての一貫性に欠けることがある。命名規則やパターンが箇所ごとにブレ、後から読むと「同じことを別のやり方でやっている」箇所が散在する。

罠2：説明（コメント・意図）が伴わない

AI は動くコードを速く出すが、「なぜそうしたか」までは自動では残らない。人間が意識して記録しないと、判断の記録（要素6）が決定的に欠落する。

罠3：「理解しないまま採用」の連鎖

AI が出したコードを、仕組みを理解しないまま採用すると、そのコードを保守できる人が最初から一人もいない状態が生まれる。第 13 回（OSS 混入）で触れた「中身を理解しないまま採用」が、保守性の文脈でも同じ問題を起こす。

要点：AI は「動くもの」を速く出すが、「一貫性」「意図の記録」「理解」は人間の仕事として残る。ここを省くと、最初から誰も保守できないシステムができあがる。

AI生成コードを「引き継げる状態」にする実務

では、AI に書かせたコードを、どうやって「引き継げる状態」に整えるか。実務的な手順を示す。

実務1：「動いた」の後に「読めるか」を確認する

動作確認で終わらせず、**「これを初めて見る人が読んで理解できるか」**を必ず確認する工程を入れる。レビュー（人の目）を通すことが、可読性・命名・構造を底上げする。第 11 回で触れた「人によるレビューとガバナンス」は、保守性の観点でも有効である。

実務2：最重要部分にはテストを置く

すべてに自動テストを置く必要はないが、「壊れたら困る中核の振る舞い」には、入力と期待出力を定めたテストを置く。テストは「正しさの確認」であると同時に、「このコードは何をするものか」を示す生きた説明にもなる。

実務3：AI に「説明」も書かせる、ただし人が検証する

AI には、コードだけでなく**「このコードが何をしているか」の説明・コメントも出させ、それを人が読んで正しいか検証**する。AI の説明を鵜呑みにせず、人の理解を通すことで、「理解しないまま採用」の罠（罠3）を避ける。

実務4：一貫性のルールを先に決める

命名規則・ディレクトリ構成・使う技術の方針といった**「一貫性のルール」を人間が先に決め、AI にそのルールに沿わせる**。場当たりに生成させるのではなく、枠を与えることで、継ぎ接ぎ（理由3）を防ぐ。

実務5：「一人しか分からない」を作らない

特定の一人だけが理解している状態を作らない。レビュー・ペア作業・ドキュメント共有で、最低でも複数人が中身を把握している状態を保つ。これは第 8 回（退職者ブラックボックス）の属人化対策と同じ発想である。

設計判断の記録（ADR）とREADME

保守性の 6 要素のうち、AI 生成で特に欠けやすい**「ドキュメント」と「判断の記録」**を補う、具体的な仕組みを紹介する。

README：最初に読むべき1枚

README は、そのシステムを初めて見る人が最初に読む説明書である。最低限、次を書いておくと引き継ぎが大きく楽になる。

  • このシステムは何のためのものか（目的）
  • どう動かすか（セットアップ・起動手順）
  • 全体構成（主要な部品と、その役割の概要）
  • どこを触ると何に影響するかの注意点
  • 連絡先・参照先（関連ドキュメント、責任者）

ADR（Architecture Decision Record）：なぜそうしたかの記録

ADR は、「なぜこの設計・技術を選んだか」という意思決定を、簡潔に記録するものである。「何を決めたか」「なぜそう決めたか」「他にどんな選択肢があったか」を、1 件あたり数行〜1 ページ程度で残す。これがあると、引き継いだ人は**「変えてよい判断か、変えてはいけない判断か」**を見分けられる。

AI 時代の記録のコツ

  • AI との対話で決めた重要な判断は、その場で ADR に書き出す（対話ログに流して消さない）
  • AI に「この設計の理由」を説明させ、人が検証してから記録する
  • README・ADR は、コードと同じ場所でバージョン管理し、変更履歴を残す（第 12 回で触れたバージョン管理の発想）

ドキュメントは「完璧」より「最新」

分厚い完璧なドキュメントより、短くても最新の README・ADR のほうが価値が高い。更新されない詳細仕様書は、かえって誤った理解を招く。**「変えたら、説明も直す」**を習慣にすることが、保守性を保つ近道である。

中堅企業の現実的な対応ステップ（30〜90日）

専任の開発チームが小さい中堅・中小企業でも、段階的に「引き継げる状態」を整えられる。

ステップ1（〜30日）：棚卸しとREADME整備

まず、**「動いているが、誰がどこまで中身を把握しているか」**を棚卸しする。一人しか分からない・誰も分からないシステムを特定し、最重要のものから README を整備する（目的・動かし方・全体構成）。

ステップ2（〜60日）：レビューと最重要テスト

AI 生成コードを取り込む際に、人のレビューを通す工程を定着させる。あわせて、中核の振る舞いにテストを置くことから始め、「怖くて触れない」を解消していく。

ステップ3（〜90日）：判断の記録と一貫性ルール

重要な設計判断を ADR として記録する習慣を始める。あわせて、命名規則・構成・技術選定の一貫性ルールを明文化し、AI にそれを守らせる運用に移行する。

対応の優先順位

優先度対象やること
最優先一人 or 誰も分からない中核システムREADME 整備・複数人での把握
高壊れたら困る中核の振る舞いテストを置く
中AI 生成コードの取り込みレビュー工程・説明の検証
継続全社の開発ADR・一貫性ルールの定着

中堅・中小企業が陥りやすい5つの失敗

1. 「動いた」をゴールにしてしまう

動作確認で開発を終え、可読性・ドキュメント・テストを作り込まない。動くが直せないシステムが量産される。

2. 一人しか分からない状態を放置する

特定の担当者しか中身を知らないまま運用を続ける。その人の異動・退職で、システムがブラックボックス化する（第 8 回の構図）。

3. テストがなく「怖くて触れない」

テストがないため、必要な修正すら「壊れたら困る」と見送られる。システムが硬直し、技術的負債（第 12 回）が膨らむ。

4. 判断の理由を残さない

「なぜこうしたか」を記録しないため、引き継いだ人が変えてよいか判断できず、誤った修正や過剰な現状維持を招く。

5. AI の出力を理解しないまま採用する

仕組みを理解しないままコードを取り込み、最初から誰も保守できない状態を作る。AI の説明を人が検証する工程が欠かせない。

よくある質問（FAQ 10問）

Q1. 「動いているのに直せない」とは、具体的にどういう状態でしょうか？

A. 動作はするものの、可読性・命名・構造が整っておらず、ドキュメントもテストも判断の記録もないため、引き継いだ人が「どこを触れば何が起こるか分からない」状態です。書いた本人ですら数ヶ月後には説明できなくなることがあります。

Q2. なぜ AI に書かせると、この問題が起きやすいのでしょうか？

A. AI は「動くもの」を速く出しますが、一貫性・意図の記録・理解は自動では残りません。次々と修正を重ねると、命名やパターンがバラバラの継ぎ接ぎになり、「なぜそうしたか」も残らず、最初から誰も保守できないシステムができることがあります。

Q3. 保守性は、感覚ではなく具体的に測れるのでしょうか？

A. 測れます。本記事では可読性・命名・構造・ドキュメント・テスト・判断の記録の6要素に分解しました。それぞれ「読んで意図が分かるか」「壊れたら気づけるか」などの問いで点検できます。

Q4. すべてのコードに自動テストを書く必要があるのでしょうか？

A. いいえ。まずは「壊れたら困る中核の振る舞い」にテストを置くことから始めます。テストは正しさの確認であると同時に「このコードが何をするものか」を示す生きた説明にもなり、「怖くて触れない」を解消します。

Q5. ドキュメントは、どこまで詳しく書けばよいでしょうか？

A. 完璧で分厚い仕様書より、短くても最新の README・ADR のほうが価値があります。更新されない詳細仕様書は誤解を招きます。「変えたら、説明も直す」を習慣にすることが、保守性を保つ近道です。

Q6. ADR とは何で、なぜ必要なのでしょうか？

A. ADR（Architecture Decision Record）は「なぜこの設計・技術を選んだか」を簡潔に記録するものです。これがあると、引き継いだ人が「変えてよい判断か、変えてはいけない判断か」を見分けられ、誤った修正や過剰な現状維持を防げます。

Q7. AI に説明やコメントも書かせてよいのでしょうか？

A. 書かせてよいですが、鵜呑みにしないでください。AI の説明を「人が読んで正しいか検証する」工程を必ず入れます。これにより「理解しないまま採用」の罠を避け、人の理解を通したうえで記録できます。

Q8. 一貫性のないコードを防ぐには、どうすればよいでしょうか？

A. 命名規則・構成・使う技術の方針といった「一貫性のルール」を人間が先に決め、AI にそのルールに沿わせます。場当たりに生成させるのではなく、枠を与えることで継ぎ接ぎを防げます。

Q9. 退職者ブラックボックス（連載第8回）とは、どう違うのでしょうか？

A. 地続きの問題です。第8回は「特定の人が抜けると分からなくなる」属人化を扱いました。本記事は、AI が速く大量に作るぶん「最初から誰も理解していない」状態が生まれやすい点に踏み込んでいます。対策（複数人での把握・ドキュメント・記録）は共通します。

Q10. 結局、まず何から始めればよいでしょうか？

A. 「動いているが、誰がどこまで中身を把握しているか」を棚卸しし、一人 or 誰も分からない中核システムの README を整備することから始めてください。次に中核へのテスト、AI 出力のレビュー、ADR と一貫性ルールへと段階的に進めます。

参考一次ソース

  1. IPA（情報処理推進機構）「DX 白書」
  2. IPA「ソフトウェア開発・保守に関する各種資料」
  3. 経済産業省「DX レポート（DX の推進に関する資料）」
  4. ISO/IEC 25010（システム・ソフトウェア品質モデル：保守性を含む）

※システムの保守性評価や引き継ぎ体制の最適解は、自社の規模・体制・システムの重要度によって異なる。重要な意思決定の前には、自社の状況に即した専門家への相談を推奨する。

まとめ

  1. 「動くけど誰も直せない」は、サボった結果ではなく、「動く」だけをゴールにした自然な帰結である
  2. AI は「動くもの」を速く出すが、保守性（直し続けられること）は人間が意識して設計しないと失われる
  3. 保守性は 可読性・命名・構造・ドキュメント・テスト・判断の記録の 6 要素に分解できる
  4. AI 生成コードは特に 一貫性の欠如・意図の記録の欠落・理解しないまま採用の 3 つの罠に陥りやすい
  5. 「引き継げる状態」にするには、動いた後に読めるか確認・中核にテスト・AI の説明を人が検証・一貫性ルールを先に決める・一人しか分からないを作らない
  6. **README（最初の1枚）と ADR（なぜそうしたかの記録）**で、欠けやすいドキュメントと判断の記録を補う
  7. 中堅企業は **棚卸しと README（〜30日）→ レビューと最重要テスト（〜60日）→ ADR と一貫性ルール（〜90日）**で段階的に整えられる

「AI に書かせる」を続けるなら、「次の人が引き継げる状態に整える」をセットにする。これが、バイブコーディングを資産にするための、実装レベルの最後の一歩である。

「動くけど誰も直せない」を解消したい方へ

GXO の バイブコーディング監査 + 保守性・引き継ぎ改善支援サービスでは、中堅企業向けに次のようなご相談を承っている。

  • 保守性の棚卸し：誰がどこまで把握しているか、保守不能リスクの可視化
  • README・ドキュメント整備：目的・全体像・動かし方の整理
  • 中核テストの整備：「怖くて触れない」を解消する最小限のテスト設計
  • ADR・判断記録の運用設計：設計判断を残す習慣づくり
  • AI 生成コードの取り込みルール：レビュー・説明検証・一貫性ルールの整備

→ 30 分無料相談を予約する

関連記事

著者: GXO株式会社 初回公開: 2026 年 6 月 3 日 最終更新: 2026 年 6 月 3 日 連載: バイブコーディング危機 第 14 回（全 30 回予定 / 第 3 週・防衛策の実装編）