はじめに
この記事では、既存システムの刷新プロジェクトで暗黙知が多いと、なぜ開発が遅くなるのかを整理します。
ここで扱う暗黙知は、単に「仕様書がない」という話だけではありません。
環境、ブランチ、チャット、リポジトリ、起動手順、現行仕様の読み方など、開発を進める前提が人の頭の中に寄っている状態を指します。
刷新案件では、現行システムを見れば分かる、既存メンバーに聞けば分かる、という進め方になりがちです。
しかし、途中から入った人にとっては、何を正として見ればよいのかが分かりません。
結果として、実装そのものではなく、前提を探す時間が増えていきます。
暗黙知は作業前の判断を止める
暗黙知が多い現場では、コードを書く前に次のような判断で止まります。
- どの環境を見ればよいのか
- どのブランチが最新なのか
- どのURLから画面を確認するのか
- どのチャットを見れば障害やメンテナンスが分かるのか
- どのリポジトリが何を管理しているのか
- 現行仕様と刷新後仕様のどちらを優先するのか
これらは一つひとつを見ると小さな問題です。
しかし、途中参加者にとっては毎回の作業開始時に発生する確認コストになります。
特に困るのは、失敗したときに原因を切り分けられないことです。
画面が表示されないとき、それが未実装なのか、メンテナンス中なのか、古いブランチを見ているのか、環境構築に失敗しているのかが分かりません。
この状態では、調査の出発点が定まりません。
画面が動かない理由を画面から判断できない
開発中の画面では、未実装やメンテナンス、バックエンド未接続などが混ざりやすいです。
例えば、画面を開いた直後に何も表示されない場合、次の可能性があります。
- 初期表示タブが未実装
- APIが未接続
- 検証環境がメンテナンス中
- 認証や権限の前提が足りない
- 手元のブランチが古い
利用者向けの完成画面でなくても、開発者向けには状態が分かる必要があります。
最低限、未実装なら未実装と表示する。
メンテナンス中なら画面上に出す。
API未接続なら、モックなのか実APIなのかを区別できるようにする。
これだけで、原因の切り分けはかなり楽になります。
チャットで「今メンテナンス中です」と流すだけでは足りません。
チャットは流れます。
途中参加者や別作業中の人は、その告知を見逃します。
開発者が最初に見る画面やREADMEに、現在の状態を確認する導線を置く方が確実です。
環境名だけでは意味が伝わらない
検証環境には st、it、dev、uat のような名前がよく使われます。
ただし、これらの略称の意味や使い分けは現場ごとに異なります。名前だけでは、誰が何を検証し、どのデータや外部連携を使う環境なのか判断できません。
必要なのは、略称そのものではなく、次の情報です。
- その環境の目的
- どのブランチからデプロイされるか
- 誰が使う環境か
- データは本番相当か、検証用か
- メンテナンス情報はどこに出るか
- 不具合を見つけたとき、どこへ連絡するか
環境名を知っていても、どの環境を確認すればよいか分からなければ意味がありません。
特に刷新案件では、現行システム、刷新中のシステム、モック環境、結合環境が並びます。
この対応関係が説明されていないと、動作確認の結果を信用できません。
ブランチ運用が不透明だとコードが信用できない
ブランチが多いこと自体は問題ではありません。
問題は、どのブランチが何を表しているのか分からないことです。
次のような状態になると、手元のコードと環境の動きが一致しなくなります。
- デフォルトブランチが開発中の最新ではない
- マージ済みブランチが残り続けている
- 日付だけのブランチ名が多い
- 環境ごとのデプロイブランチが分からない
- 親ブランチと子ブランチの関係が説明されていない
この状態で不具合を追うと、自分が読んでいるコードが正しいのか分かりません。
コードを読んでいるつもりが、実際には古いブランチを読んでいるだけかもしれません。
検証環境で再現している挙動が、手元のブランチには存在しないかもしれません。
その結果、実装理解ではなく、履歴と運用の解読に時間を使うことになります。
ブランチ運用では、少なくとも次をREADMEや開発者向けドキュメントに書くべきです。
- 最初にcheckoutするブランチ
- 開発のベースブランチ
- 環境ごとのデプロイ元
- リリースブランチの作り方
- マージ後に削除してよいブランチ
- 残す必要があるブランチ
「聞けば分かる」ではなく、「見れば分かる」に寄せることが重要です。
チャットは知識の置き場ではない
チャットは連絡には向いています。
しかし、ルールや手順の保管場所には向いていません。
チャットに重要なルールを流すと、次の問題が起きます。
- 後から検索しづらい
- 最新情報がどれか分からない
- チャンネルの目的が分からない
- 参加していない人に伝わらない
- 流量が多いと埋もれる
重要なのは、チャットで知らせることではなく、正しい置き場へ反映することです。
例えば、環境メンテナンスはチャットで通知してもよいです。
ただし、現在のメンテナンス状況や恒久的なルールは、README、Wiki、運用ページなどに残すべきです。
チャットには「更新しました」という通知を流し、本文はドキュメント側に置く。
この形にすると、後から入った人も追いやすくなります。
チャンネルが多い場合は、チャンネルの目的も明文化した方がよいです。
- 障害連絡
- 開発相談
- リリース連絡
- 環境メンテナンス
- 雑談
この程度でも、どこを見ればよいかの迷いは減ります。
READMEがない大きなリポジトリは入口がない
大きなリポジトリほど、READMEの重要度は上がります。
READMEにすべての仕様を書く必要はありません。
ただし、入口として次の情報は必要です。
- このリポジトリが管理している範囲
- 関連リポジトリとの関係
- ローカル起動方法
- 起動後にアクセスするURL
- 環境変数の置き場所
- 主要ディレクトリの役割
- よく使うコマンド
- 参照すべき設計資料やAPI仕様
これがないと、途中参加者はディレクトリ構成から文脈を推測するしかありません。
特に、複数の業務領域が同じリポジトリに入っている場合は注意が必要です。
ディレクトリ名だけでは、分け方の意図が分かりません。
単に src があるだけならまだよいです。
しかし、領域ごとに別の src があり、モジュール名や共通処理の置き場にも制約がある場合、設計上の前提を知らないと変更しづらくなります。
READMEは詳細設計書ではなく、迷わず最初の一歩を踏むための地図です。
現行仕様を正とするなら、現行の読み方が必要になる
刷新案件では「現行仕様を正とする」という方針がよくあります。
これは現実的な判断です。
既存システムが長く動いている場合、仕様書より現行挙動の方が信頼できることがあります。
ただし、この方針には落とし穴があります。
現行仕様を正とするなら、現行システムの読み方も共有する必要があります。
- どのブランチの現行コードを見るのか
- どの画面を正とするのか
- 例外仕様はどこにあるのか
- 表示・非表示のロジックはどこで決まるのか
- データがない場合と権限がない場合をどう区別するのか
これがないまま「現行を見てください」と言われると、現行コード全体を読むしかなくなります。
さらに、フロント側の表示制御にビジネスロジックが埋まっている場合、単なるコンポーネント表示の有無にも業務判断が混ざります。
この場合、設計資料がないことはかなり大きな負担になります。
現行仕様を正にすること自体は悪くありません。
問題は、正とする対象にたどり着くための道筋がないことです。
バックエンド未完成のままフロントを進めるなら契約が必要
刷新プロジェクトでは、フロントエンド、BFF、バックエンド、外部連携の開発順序が揃わないことがあります。
これは珍しいことではありません。
ただし、バックエンドが未完成のままフロントを進めるなら、境界の契約が必要です。
- API仕様
- リクエストとレスポンスの例
- エラー形式
- モックデータの扱い
- 未接続機能の見分け方
- 結合前にマージしてよい条件
これらがないまま画面だけを先行すると、動いているように見えるが実際には結合できない、という状態になります。
SwaggerやOpenAPIを使うなら、単にファイルを置くことが目的ではありません。
フロント、BFF、バックエンドの間で「この形でつなぐ」という合意を作ることが目的です。
契約がない状態でマージされると、後から結合したときに認識差がまとめて出ます。
この手戻りは、実装ミスというより開発順序と合意形成の問題です。
AIを使うほどプロジェクトコンテキストが重要になる
最近は、既存実装を読みながらAIに修正案を出させる場面も増えています。
このとき、READMEや開発者向けのコンテキストがないと、AIも人間も同じところで迷います。
- どのディレクトリが対象か
- 命名規則は何か
- どのブランチを見ればよいか
- どの仕様が現行なのか
- どのコマンドで検証するのか
人が毎回説明しなければならない情報は、AIにも毎回説明する必要があります。
AGENTS.md、copilot-instructions.md、開発者向けREADMEのようなファイルは、AIのためだけのものではありません。
途中参加者のためのオンボーディング資料でもあります。
プロジェクトの前提をテキストで残しておくほど、人もAIも同じ文脈で作業しやすくなります。
最初に整えるべきもの
暗黙知をなくすといっても、すべてのドキュメントを整備する必要はありません。
まずは、作業開始時に必ず詰まる情報から整えるのが現実的です。
優先度が高いのは次です。
- リポジトリのREADME
- ローカル起動手順
- 起動後にアクセスするURL
- 環境名と用途の一覧
- ブランチ運用の説明
- チャットチャンネルの用途
- メンテナンスや障害情報の置き場
- 現行仕様を見るときの入口
- API仕様やモックの扱い
これらは、きれいな設計書より先に必要です。
開発者が最初の1日で必ず使う情報だからです。
ここが整っていないと、実装スキルに関係なく全員が同じところで時間を使います。
ドキュメントは完璧でなくてよい
暗黙知を減らすためのドキュメントは、最初から完璧でなくてよいです。
むしろ、最初は短い方が使われます。
例えばREADMEには、次のような最低限の入口だけでも効果があります。
# プロジェクト名
## このリポジトリの役割
このリポジトリは、管理画面のBFFとフロントエンドを管理します。
バックエンドAPIは別リポジトリで管理しています。
## ローカル起動
```bash
npm install
npm run dev
```
起動後は `http://localhost:3000/login` を開きます。
## 環境
| 環境 | 用途 | デプロイ元 |
| --- | --- | --- |
| dev | 開発者確認 | develop |
| st | 結合試験 | release/st |
| prod | 本番 | main |
この程度でも、何もない状態とは大きく違います。
大事なのは、知識を一度で完成させることではありません。
迷った人が追記できる場所を作ることです。
まとめ
暗黙知が多い刷新プロジェクトでは、開発が遅くなる理由が実装の難しさだけではありません。
実際には、次のような前提確認に時間を使っています。
- どの環境を見ればよいか
- どのブランチが正しいか
- どの画面状態が正常か
- どのチャットを追えばよいか
- どのリポジトリが何を持つか
- 現行仕様をどこから読むか
これらは、設計や実装の前に必要な情報です。
刷新案件では、現行システム、既存運用、未完成の新システムが同時に存在します。
そのため、暗黙知を放置すると、途中参加者ほど前提の解読に時間を取られます。
まず整えるべきなのは、完璧な設計書ではありません。
README、環境一覧、ブランチ運用、起動URL、チャットの用途、現行仕様の入口です。
「聞けば分かる」を減らし、「見れば分かる」を増やすことが、刷新プロジェクトの開発速度を安定させます。
認識差や結合遅れが手戻りに変わる問題については、「手戻りをどのように見積もるか、ソフトウェア見積りに関して」でも整理しています。