「資料？ないよ」から始まる地獄
「この機能、どういう仕様だったっけ?」
「担当者が部署移動しちゃって…」
「え、この変更って他にも影響ある？」
開発現場でこういう状況、よくありますよね。私も最初のプロジェクトで「設計書？ああ、多分どこかにあると思うけど…」と言われたときは絶望しました。PM、デザイナー、QA、営業など、エンジニア以外の立場だと特に厳しい。
正直、「ドキュメントが不完全な状態」は開発現場あるあるです。古いシステムはもちろん、今動いてるプロジェクトでも資料が更新されてなかったり、そもそも作られてなかったり。で、結局仕様確認に無駄な時間がかかって、プロジェクト全体が遅れていく…という悪循環。
ここでは、私が実際に試して効果があった対処法を紹介します。特別なスキルは不要なので、明日からでも試せるはずです。
なぜこうなるのか
なぜこうなってしまうのか？理由はだいたい決まってます。納期が厳しくて「とりあえず動くもの優先」になるパターンがほとんど。あとは人の入れ替わりが激しくて、前任者が口頭で伝えてた知識が消えていく。仕様変更が頻繁すぎて更新が追いつかない。情報がSlackやNotionやJiraなどなどに散らばってて、どこに何があるか分からない。
開発チームは「コード読めば分かるでしょ」って言うけど、会社はエンジニアだけでうごいているんではないんですよね…。どこのチームも似たような状況なので、あなたのチームだけの問題じゃないです。
実際どうやって対処したか
1. とにかく人に聞く
まず基本は、知ってそうな人に片っ端から聞くことです。ただ、いきなり「この機能について教えてください」って聞いても「えーと…」ってなるので、事前準備が大事。
モバイルアプリの改修案件で設計書が皆無だったときは、こんな感じで進めました。開発者、前任PM、QA、実際に使ってるユーザーまで、とにかく情報を持ってそうな人をリスト化。で、「この機能って何のためにあるんですか」「どんなときに動くんですか」「他の機能と連動してます？」みたいな質問を用意しておいて、会話しながらその場でガンガンメモ。
この方法で、比較的大きめのプロジェクトでも3日くらいで主要機能の8割は把握できました。しかも、「あれ、これって誰も仕様知らなくない？」っていう危ない部分も見つかって、事故を未然に防ぐことができました。
2. コードから逆算する（開発者の力を借りて）
「コード読めないし…」って思いますよね。私もそうです。でも、コードそのものは読めなくても、開発者に協力してもらえば情報は引き出せます。
画面遷移の仕様が謎だったとき、開発者に「どのファイルがどの画面なのか一覧作ってもらえます？」ってお願いしました。あと、コード内のコメント（開発者のメモ）だけ抜き出してもらって、「ここはこういう理由でこうなってる」みたいな背景を把握。実際に開発環境で動かしてみて、分からないところは30分くらいペアで見てもらう。
これで「どこに何が書いてあるか」の地図ができたので、次に似たような疑問が出たときに自分で調べられるようになりました。開発者の時間を取りすぎないのもポイントです。
3. ひたすら触って動きを記録
資料がないなら、実際に動かしてみればいい。ECアプリの決済機能の仕様書がなかったときは、考えられるパターンを全部試しました。
普通に購入できるか確認して、画面キャプチャ撮って。で、「金額0円だとどうなる？」「通信エラー起きたら？」「2回連続でタップしたら？」「遷移中に戻るボタン押したら？」みたいに、ありとあらゆるパターンを試す。QAっぽい作業ですね。
1週間くらいかけて確認したら、かなり詳しい仕様が分かりました。「え、こんな動きするの？」っていう予想外の挙動とか、「ここ制約あったんだ」っていう発見もあって、これはドキュメント読むより実際に触った方が早いかもって思いました。
4. 他のプロジェクトから盗む（参考にする）
ゼロから作る必要ないですよね。似たようなプロジェクトがあれば、そっちの資料をパクる…じゃなくて参考にすればいい。
新規アプリで通知機能の仕様を考えるとき、社内の他プロジェクトで通知機能があったので、そのドキュメント探して中身を確認。使えそうな部分をコピーして、今回のプロジェクト固有の部分だけ書き換え。で、関係者に「たたき台作ってみました」って見せてレビューしてもらう。
これで半分以上の時間を節約できたし、すでに実績がある構成を使ってるから抜け漏れも少ない。車輪の再発明をする必要はないです。
5. 完璧を目指さない
「全部ちゃんとしたドキュメント作ろう！」って思うと確実に挫折します。私も何度も失敗しました。
レガシーシステムのリニューアル案件で、全体を把握する資料が欲しかったんですが、全部作るのは無理ゲーだったので、優先順位つけて段階的に行いました。
最初の2週間でまず作ったのは、システム全体の構成図（一枚絵）、主要な画面遷移、外部連携の仕様。これだけあれば、とりあえずチーム全員が最低限の会話はできる。その後、必要になったタイミングで各機能の説明とか、データの流れとか、ビジネスロジックとかを追加。詳細な画面定義とかエラーパターンは一番最後。
3ヶ月後には必要なドキュメントが一通り揃ってましたが、最初から全部やろうとしてたら絶対終わってなかったです。「まずはこれだけ」って決めるのが大事。
やってみて良かったこと
こういう対応をしていくと、実際に色々改善されます。
まず単純に、「これ誰に聞けばいいんだっけ」「どこ見ればいいんだっけ」っていう迷う時間が減ります。1件あたり30分くらいは短縮されてる感覚。仕様の認識ズレによる手戻りも減って、開発が早くなりました。
あと、些細な質問が4割くらい減って、開発者に話しかけるハードルが下がった（笑）。共通認識ができてるから、会議でも本質的な話に時間を使えるようになったのも大きいです。
体系的に情報整理すると、「あ、これ見落としてた」っていう要件や制約が見つかるのも良かった。テストの網羅性も上がるし、新しいメンバーが入ってきたときの立ち上がりも半分くらいの期間で済むようになりました。
あと地味に重要なのが、キーパーソンが急に辞めても何とかなること。前は「◯◯さんしか知らない」みたいな情報が多かったけど、だいぶ減りました。
気をつけた方がいいこと
一応、いくつか注意点もあります。
情報の正確性
ヒアリングで聞いた話って、実は間違ってることもあります。だから複数の人に確認したり、実際に動かして確かめたりした方がいい。「これは推測」「これは確認済み」って区別しておくのも大事です。
やりすぎない
完璧なドキュメント作ろうとすると、いつの間にかドキュメント作りが目的になってしまいます。「必要十分」を見極めて、「このドキュメント、実際使われてる？」って定期的に確認しましょう。
更新し続ける
一度作っても、仕様変わったら古くなります。「いつ誰が更新するか」決めておく。完璧より、「まあまあ最新」を目指す方が現実的です。
機密情報に注意
調査してると、たまに機密情報や個人情報に触れることがあります。取り扱いルールは事前に確認して、アクセス権もちゃんと設定しましょう。
一人で抱え込まない
チーム全体で取り組まないと続きません。開発者の負担にならないよう、効率的にコミュニケーション取って、小さな成功を積み重ねていくのがコツです。
まとめ
「ドキュメントがない」状況って、どこの現場でもあります。珍しくない。大事なのは嘆くことじゃなくて、できることから始めることです。
ここで紹介した方法は、特別なツールも技術知識も要りません。明日からできることばかり。
- 気になる機能について開発者に15分だけ時間もらう
- 実際にアプリ触って画面キャプチャ撮る
- 社内の他プロジェクトで使えそうな資料を探す
- 「最低限これだけは」って決めて1つだけ作る
完璧じゃなくていい。10%でも20%でも、今より良くなればOKです。
これからAIツールが発展して、コードから自動でドキュメント生成とかできるようになるでしょう。でも、現場の文脈を理解して適切に情報を整理するのは、結局人間の仕事だと思います。
ドキュメント欠損への対応力って、これからもっと重要になっていくスキルだと思うので、ぜひ試してみてください。うまくいった方法があれば、チーム内で共有していくと、組織全体が良くなっていきます。
