こんにちは！
ツクリンクでアソシエイトエンジニアリングマネージャーをしている八尾(@Tomoki____Y)です。
普段は、プロジェクトが円滑に進むようにサポートしたり、エンジニアが開発に集中してユーザーと向き合える環境を整えたりしています。
そんな中でドキュメントの改善に挑戦している事について、本記事では書いていきたいと思います。
はじめに
開発チームが大きくなりプロダクトが成長する中で、こんな課題に直面することはないでしょうか？
- 「開発が進むにつれて、『これって結局、誰のどんな課題を解決するんだっけ？』と目的を見失ってしまう」
- 「仕様書に『手段（How）』しか書かれておらず、迷った時に立ち返る場所がない」
- 「QAフェーズになってから『あ、このパターンの考慮が漏れていた』と気づき、手戻りが発生する」
こういうこと、あるあるだと思うんですが、うちのチームも例外じゃなかったです。
私たちのチームも、以前は少人数の「阿吽の呼吸」でなんとかなっていました。
でも 組織が大きくなって職能横断で動くようになってから、職種ごとの前提の違いがそのまま 認識のズレ になって、開発中の迷いが増えていった気がします。
そんな感じで、PBIドキュメントを見直しました。やったのは単なるフォーマット変更じゃなくて、「職能横断チームで、より手戻りなく素早く価値を届けるには、どういうドキュメントが適切か？」を考え直すこと。この記事では、現在挑戦している改善の記録をまとめます。
なぜドキュメントを見直したか（改善前の課題）
改善前のドキュメントは、ロジック自体は書いてあるんですが、深いネスト（階層）がある箇条書きになっていました。
読めます。読めるんですが、欲しい情報がどこにあるのか探しづらい。そのせいで解釈に時間がかかって、結果あまり参照されない状態になっていると感じてました。
「スパゲッティコード」化したドキュメント
▼ 新着通知機能のロジック（改善前サンプル）
- 通知条件
- 対象ユーザー
- 会員登録から 1 週間以内のユーザー
- ※ただし設定で OFF にしている人は除く
- 表示順
- 上から優先
- 重要フラグがあるもの
- （重要フラグの定義は別紙参照）
- 日付が新しい順
- 下記条件に合うものは除外する
- 過去 3 日間にすでに通知済みの案件
- ブロックリストに入っている企業
ソースコードで言えば、if が何重にもネストしている状態に近いです。
「この除外条件って親階層のどこまで効くんだっけ？」
「条件 A と条件 B がぶつかったら、どっちが勝つんだっけ？」
こういうのを読み解くのに認知負荷がかかります。その結果、誤読や解釈の違いが起きることが度々ありました。
ドキュメントに残っていなかった「Why（ユーザーの物語）」
もう1つ課題と感じたのはこちらになります。
以前も目的（Why）の欄はありましたが、書かれていたのは「KPIである閲覧数の向上」みたいな 数値目標が中心である事が多かったです。
もちろん企画段階やチームとして話す場では「ユーザーにとってこういう嬉しさがあるよね」という話はしています。ただ、それがドキュメントとして残っていなかった。
開発が進んで細かい判断に迷ったとき、最後に頼れるのは「書いてあること」だけになりがちです。そうなると、口頭で共有していたはずのユーザーへの想いは薄れていき、結果として運営側目線中心での開発となりがちな気がしてます。
（自分も、思い当たる節があります）
私たちが使っているPBIドキュメントの構成（改善後）
「伝わらないのは書き手の問題というよりフォーマット（UI）の問題なんじゃないか」
そう考えて、読み手が迷わない形に組み直しました。改善後のフォーマットは下記の様な状態にしております。
いまは大きく、PBIの目的 (Why) → 全体要求・スコープ（やる / やらない）→ ストーリー分割（物語で切る）→ ストーリー詳細（Gherkin で振る舞いを定義）という流れにしています。
この形にしてから、議論の質が少し変わった気がします。「それってユーザーのどの困りごとでしたっけ？」って話に戻りやすくなったと感じてます。
PBIの目的 (Why) について
一つ目の大きな変化としては目的の書き方でした。KPI（＝目標指標）だけを書いて終わりにせず、その背景にあるユーザーの課題と行動仮説もセットで据えます。
▼ 改善後のWhy（サンプル）
目的: ユーザーのアクティブ化
課題仮説: 「ユーザーは平日忙しく、新着情報を見逃していることにストレスを感じている」
解決策: 「週末にまとめて確認できる『週次ダイジェスト』を送ることで、見逃しの不安を解消する」
ここが書いてあるだけで、実装の判断が変わる…と思っています。たとえば、忙しい人が読むなら件名はシンプルにする。見逃し案件だと一目で分かるUIにする。こういう判断が好みじゃなくて、Whyに紐づいた議論として出せるようになりました。
ストーリー分割（物語で切る）について
PBI 全体が見えたら、機能をユーザーストーリーに分割します。ここは以前からやっていましたが、やり方を少し変え挑戦しています。
昔は、巨大な仕様書で例外もUIも全部決めきってから、ユーザーストーリーを切っていました。
このやり方は「大きい塊を、ただ小さく切っただけ」という傾向が強く、実質的にはウォーターフォールの様な状態でした。
いまは、ユーザーストーリー単位で仕様を完成させる方式で挑戦しています。
たとえば、「メールを受け取る」、「オプトアウトできる」という2つのユーザーストーリーがあった場合、「メールを受け取る」のユーザーストーリーを詳細を決め実装に進み、「オプトアウトできる」のユーザーストーリーは次のPBRで詰めるという考え方です。
これにより、初期の不確実性が高い段階で全部を確定させることによる手戻りを減らしやすくなります。また、1つのユーザーストーリーにフォーカスして議論できるので、論点が散らかりにくいと感じています。
ストーリー詳細（Gherkin で振る舞いを定義）について
分割された各ストーリーには、仕様だけではなく、「何をもって完了とするか」という受け入れ基準を明確に記載しています。
この受け入れ基準を曖昧にしないために、Gherkin（ガーキン）記法を取り入れています。
受け入れ基準を明確にする「Gherkin」とは
自然言語の箇条書きは、読み手によって解釈がブレやすく、「AかつB、またはCの場合」といったロジックが曖昧になりがちです。
そこで、「前提（Given）」「もし〜したら（When）」「どうなる（Then）」という形式で振る舞いを記述するGherkinを採用し、構造化しています。
▼ 実際の記述例：案件の表示順序ロジック
SCENARIO: 規定の優先順位（重要 > 新着 > ID）で案件が並ぶ
GIVEN 対象期間内に以下の3つの案件が存在する
| 案件名 | 重要フラグ | 日付 | ID |
| 案件A | OFF | 2/5 | 1 |
| 案件B | ON | 2/1 | 2 |
| 案件C | OFF | 2/5 | 3 |
WHEN 週次メール内の案件リストが生成される
THEN 案件は以下の順番で表示される
1. 案件B (重要フラグONが最優先)
2. 案件C (日付が新しい)
3. 案件A (同日の場合はID順 ※降順なら3→1)
この書き方を導入したことで、チームとして認識を合わせるメリットだけではなく、エンジニア・デザイナー双方の目線においても以下のメリットがあると考え取り入れています。
エンジニア目線でのメリット
Gherkinで入力と出力が厳密に定義されているため、エンジニアはこれを「実装の正解」として迷いなくコーディングできます。
また、この記述はそのままテストコードのテストケースとして利用できるため、実装後の動作確認や自動テストの実装もスムーズになり、ロジックレベルの手戻りが削減できるというメリットがあります。
デザイナー目線でのメリット
Gherkinはデザイナーにとっても助けになります。「前提条件（Given）」や「結果（Then）」を定義する過程で、見落としがちな「画面の状態」が可視化されるからです。
- GIVEN データが0件の時 → 「あ、Empty State（空の状態）のデザインが必要だ」
- THEN エラーメッセージが表示される → 「トーストで出すのか、モーダルで出すのか決めなきゃ」
これにより、デザイナーは「とりあえず一覧画面を作る」のではなく、「ユーザーが遭遇するあらゆる状態を網羅的に設計する」ことが可能になり、実装フェーズでの「ここのデザイン足りません」という手戻りを防げるようになりました。
さらに、あらゆる挙動を推測しながら作る形ではなく、一定の振る舞いは明確になった状態でデザイン着手できるため、より「UXの設計」や「創造性を発揮」に集中できると考えてます。
生成AI時代のドキュメントの意味
最近はCursorやClaudeCodeみたいな生成AIが、普通に開発の相棒になってきました。その中で思うのは、ドキュメントの質って、そのままAIの出力の質になると考えてます。
曖昧な箇条書きを投げても、意図どおりの実装は返ってきづらいです。
でも、Gherkinみたいに構造化した「受け入れ基準」を渡すと、テストコードも実装案もかなり良くなります。
人間がHowを全部書ききるんじゃなくて、人間は受け入れ基準をちゃんと定義して、実装の一部はAIに任せる。
この流れに寄せAIを効果的に活用するという意味でも、今回の形式は相性がいいんじゃないかなと思っています。
ドキュメント作成までのプロセス
このドキュメントは、PdMや企画者が一人で完璧に書いて「これで作って」と渡すものじゃないです。
それだと、このドキュメントの効果も職能横断チームを採用している効果も薄れると考えてます。
現状では、まずPdMや企画者がWhyと大まかな要求のドラフトを作ります。
この時点でユーザーストーリーの詳細などは空でもいいです。むしろ無理に埋めると引っ張られてしまうので埋めない方が良い場合もあるくらいで考えてます。
次にPBRで、エンジニア・デザイナー・QAも混ぜて「このユーザー体験作るならこう考える方がいいんじゃない」「このロジック複雑すぎない？」「このエッジケースどうする？」を詰めます。
私はここでの会話が、開発をしていく中で一番価値がある部分だと感じています。
最後に、議論結果を詳細なユーザーストーリーに落とし込み、受け入れ基準をGherkinで記載していくという流れで進めています。
いまのところ、この流れが職能横断チームとして手戻りなく素早く価値を届けるには一番しっくりくる流れだと考えています。
最後に
ドキュメントを丁寧に書くのって、一見「開発スピード落ちそう」と思われがちです。
でも実際は、迷いながら実装する時間 と 手戻りで直す時間 を減らすための投資だと思っています。
最初に共通認識を作っておくと、結果的にリリースまで最短距離になることが多いです。もちろん、いつもそうとは限りません。
もし、「手戻りが多いな」「実装中に迷う事が多いな」という感覚がありましたら、私はドキュメントを見直してみる事をオススメします。その時にこの記事が少しでも参考になれば嬉しいです。
Discussion