PHPカンファレンス名古屋-テックリードの経験から学んだ設計の教訓

Slide 1

Slide 1 text

もう一度やり直せるならこうする：テックリードの経験から学んだ設計の教訓 2025/2/22 PHPカンファレンス名古屋工藤颯斗

Slide 2

Slide 2 text

©︎tete marche CO., LTD. 2 工藤颯斗(クドウハヤト) @metalic_kudo_h ■ 所属テテマーチ株式会社 ■ プロダクト SINIS for Instagram ■ 職業 Webアプリケーションエンジニア ■ 趣味天体観測・魚を捌くこと

Slide 3

Slide 3 text

©︎tete marche CO., LTD. 3 本セッションでは「こうすればよかった・ここ失敗したな」という経験からもう一度やり直せるならこうするという事例や教訓を紹介しますはじめに

Slide 4

Slide 4 text

©︎tete marche CO., LTD. 4 お話する内容はすべてのプロダクトに当てはまるものではないため「こういう考え方もあるのかー」というスタンスで聞いていただければ幸いです！はじめに

Slide 5

Slide 5 text

©︎tete marche CO., LTD. Index 目次 5 1. ドキュメント設計・ADRもっとはやく導入すればよかった 2. テスト戦略・アイスクリームコーン型の放置をしなければよかった・カバレッジ率を計測すればよかった 3. 移行戦略・ストラングラーパターンに沿って進めればよかった

Slide 6

Slide 6 text

©︎tete marche CO., LTD. ドキュメント設計・ADRもっとはやく導入すればよかった 01. 6

Slide 7

Slide 7 text

©︎tete marche CO., LTD. 7 この章では、ADRを導入したらいい感じだったのでどういう課題があってADRを導入しようと考えたか時系列順にお話しようと思います (ADRについての解説は後ほど) この章のオチ

Slide 8

Slide 8 text

©︎tete marche CO., LTD. 8 ドキュメントを作る際のルールがなく好きな場所に好きなフォーマットで運用していたドキュメント運用の問題点 • 議事録のようなフロー型の情報と、設計ドキュメントのようなストック型の情報が混在していた • エンジニア用の情報とビジネス用の情報も混在していた • フォーマットが統一されていない etc…

Slide 9

Slide 9 text

©︎tete marche CO., LTD. 9 ドキュメントを作る際のルールがなく好きな場所に好きなフォーマットで運用していたその結果、情報が断片的に散在しメンテナンスされなくなった古いドキュメントが増えていったドキュメント運用の問題点

Slide 10

Slide 10 text

©︎tete marche CO., LTD. 10 ドキュメント運用の問題点プロダクトの初期フェーズではドキュメントの量も少ないしメンバーも限られていたので暗黙知でどうにかなっていた

Slide 11

Slide 11 text

©︎tete marche CO., LTD. 11 プロダクトの初期フェーズではドキュメントの量も少ないしメンバーも限られていたので暗黙知でどうにかなっていたプロダクトのフェーズが進み、ドキュメントと新しいメンバーが増えてくると、徐々に実害のある問題が浮き出てくるようにドキュメント運用の問題点

Slide 12

Slide 12 text

©︎tete marche CO., LTD. 12 フェーズが進むごとに実害がでてきた問題 • どこに情報があるのかわからない • 信用できる情報かわからない • 同じ内容の議論が何度も蒸し返される • 後から振り返りができない

Slide 13

Slide 13 text

©︎tete marche CO., LTD. 13 フェーズが進むごとに実害がでてきた問題 • どこに情報があるのかわからない • 信用できる情報かわからない • 同じ内容の議論が何度も蒸し返される • 後から振り返りができないドキュメントが散在しているため欲しい情報の格納先がわからない

Slide 14

Slide 14 text

©︎tete marche CO., LTD. 14 フェーズが進むごとに実害がでてきた問題 • どこに情報があるのかわからない • 信用できる情報かわからない • 同じ内容の議論が何度も蒸し返される • 後から振り返りができないドキュメントがメンテナンスされている保証がないので古い情報の可能性がある

Slide 15

Slide 15 text

©︎tete marche CO., LTD. 15 フェーズが進むごとに実害がでてきた問題 • どこに情報があるのかわからない • 信用できる情報かわからない • 同じ内容の議論が何度も蒸し返される • 後から振り返りができないコードレビューで一度議論した内容を忘れて、また別の人と同じ議論をしたり、時間が経ってから同じ内容の議論をしたり

Slide 16

Slide 16 text

©︎tete marche CO., LTD. 16 フェーズが進むごとに実害がでてきた問題 • どこに情報があるのかわからない • 信用できる情報かわからない • 同じ内容の議論が何度も蒸し返される • 後から振り返りができない外部のライブラリをいれる際に、・当時どのような制約や要件があって・競合ライブラリはどういう状態で・どういう判断からそのライブラリを選定したみたいな意思決定の背景が残っておらず、当時と状況が変わった際に動けない

Slide 17

Slide 17 text

©︎tete marche CO., LTD. 17 後から振り返りができないことでの問題状況の変化に対応できない • 世の中の技術もプロダクトの状況も変化するし、自身やチームの知識や経験も日々変化する • 現在の状況に基づいて最適な選択肢を検討しようとしても、過去の意思決定がどのような理由で行われたのかが不明なため、変更の影響範囲やリスクを正確に把握できないなんでこんな設計にしたんだっけ？忘れた …

Slide 18

Slide 18 text

©︎tete marche CO., LTD. 18 後から振り返りができないことでの問題状況の変化に対応できない • 世の中の技術もプロダクトの状況も変化するし、自身やチームの知識や経験も日々変化する • 現在の状況に基づいて最適な選択肢を検討しようとしても、過去の意思決定がどのような理由で行われたのかが不明なため、変更の影響範囲やリスクを正確に把握できないなんでこんな設計にしたんだっけ？忘れたじゃあいっか… 現状維持の選択を取りがちになっていた

Slide 19

Slide 19 text

©︎tete marche CO., LTD. 19 問題への対策今後も自然に解消することはないだろうな

Slide 20

Slide 20 text

©︎tete marche CO., LTD. 20 問題への対策 ADRの導入

Slide 21

Slide 21 text

©︎tete marche CO., LTD. 21 ADRとは？ ADRとはArchitecture Decision Record の略称で直訳すると「アーキテクチャ決定記録」 • Architecture = アーキテクチャ • Decision = 決定 • Record = 記録 Action-Domain-Responder ではないよ

Slide 22

Slide 22 text

©︎tete marche CO., LTD. 22 ADRとは？その名のとおりADRとはアーキテクチャに関する意思決定の記録を残すためのドキュメント

Slide 23

Slide 23 text

©︎tete marche CO., LTD. 23 ADRの目的なぜアーキテクチャの決定記録を残す必要があるのか？こういう事態になることを防ぎたい • 過去の意思決定した状況とは大きく変わっているのに見直しがされない • 「ここの設計どうしてこうなってたんだっけ？」が発生してしまう • 同じ内容の議論が何度も蒸し返される • 議論の内容が曖昧で何が意思決定されたのかわかりにくい

Slide 24

Slide 24 text

©︎tete marche CO., LTD. 24 ADRフロー 1. オーナーなど関係なく、作ったほうが良いと考えた人がテンプレートを元にADRを作成する 2. ADRが作られたらそのプロダクトの開発メンバー全員でレビューする 3. 全員の承認を受けたらAccepted、非承認の場合はRejectedにする 4. 承認されたADRの内容を後から変更する場合は、新規にADRを作成し、既存ADRは Deprecatedにする

Slide 25

Slide 25 text

©︎tete marche CO., LTD. 25 ADRフロー 1. オーナーなど関係なく、作ったほうが良いと考えた人がテンプレートを元にADRを作成する 2. ADRが作られたらそのプロダクトの開発メンバー全員でレビューする 3. 全員の承認を受けたらAccepted、非承認の場合はRejectedにする 4. 承認されたADRの内容を後から変更する場合は、新規にADRを作成し、既存ADRは Deprecatedにする（メンバー規模によるが）全員参加がオススメ設計の合意形成を取りつつ、集合知を初動で結集できる

Slide 26

Slide 26 text

©︎tete marche CO., LTD. 26 ADR格納場所 ■ 必須要件 • 開発メンバー全員が閲覧できること • リンクが作れること • Slack連携ができること • コメント機能があること ■ 希望要件 • ADRフォーマットのテンプレート化ができること • 使い馴染みがあること • コメント機能が充実していること

Slide 27

Slide 27 text

©︎tete marche CO., LTD. ■ 必須要件 • 開発メンバー全員が閲覧できること • リンクが作れること • Slack連携ができること • コメント機能があること ■ 希望要件 • ADRフォーマットのテンプレート化ができること • 使い馴染みがあること • コメント機能が充実していること 27 ADR格納場所コードレビュー等での参照先にできるように

Slide 28

Slide 28 text

©︎tete marche CO., LTD. 28 要件を満たした格納場所候補 • Notion • GitHub • Issues • Repository • Discussions

Slide 29

Slide 29 text

©︎tete marche CO., LTD. 29 要件を満たした格納場所候補 • Notion • GitHub • Issues • Repository • Discussions ← 採用

Slide 30

Slide 30 text

©︎tete marche CO., LTD. 30 要件を満たした格納場所候補 • Notion ← レビュープロセスが難しい • GitHub • Issues ← 問題についてのみ扱いたい • Repository ← ソースコードについてのみ扱いたい • Discussions ← 採用

Slide 31

Slide 31 text

©︎tete marche CO., LTD. 31 要件を満たした格納場所候補 • Notion • GitHub • Issues • Repository • Discussions 完全に好みなのでチームに合うツール選定で大丈夫

Slide 32

Slide 32 text

©︎tete marche CO., LTD. 32 ADRフォーマット • Title (〇〇についてのような体言止めにせず、〇〇にするみたいな文にする) • Status (ADRが承認中なのか等のステータス) • Context (決定が必要となった背後にある動機や理由) • Material for decision (決定時に参照した材料) • Decision (最終的な決定内容と理由)

Slide 33

Slide 33 text

©︎tete marche CO., LTD. 33 GitHub DiscussionsのテンプレートYAMLファイル

Slide 34

Slide 34 text

©︎tete marche CO., LTD. 34 GitHub Discussionsの入力画面

Slide 35

Slide 35 text

©︎tete marche CO., LTD. 35

Slide 36

Slide 36 text

©︎tete marche CO., LTD. 36 タイトルにこのADRで決めたい内容

Slide 37

Slide 37 text

©︎tete marche CO., LTD. 37 Contextに背後にある動機や理由

Slide 38

Slide 38 text

©︎tete marche CO., LTD. 38 Material for decision に参照材料

Slide 39

Slide 39 text

©︎tete marche CO., LTD. 39 Decisionに最終的な決定内容と理由

Slide 40

Slide 40 text

©︎tete marche CO., LTD. 40 LabelsでADRステータスを管理

Slide 41

Slide 41 text

©︎tete marche CO., LTD. 41 ADR運用の感想 Good • 設計の意思決定に関するドキュメントが散在しなくなった • 同じ内容の議論が何度も蒸し返されなくなった • 後から振り返りができるようになった • 全員が設計の議論に関わるので合意形成を取りながら設計できるようになった More • アーキテクチャ設計以外のドキュメントは以前と問題が残ったまま • プロダクト初期フェーズに意思決定した内容がADR化されておらず、古いドキュメントが混乱の元になっている

Slide 42

Slide 42 text

©︎tete marche CO., LTD. 42 記録も記憶も曖昧になっていて今からADR化するのが困難になっている ADRもっとはやく導入すればよかった

Slide 43

Slide 43 text

©︎tete marche CO., LTD. 43 ドキュメントが整備されていないことで困るのは設計した本人ではなく、その後に続く人たち最初からADRを導入すべきだった ADRもっとはやく導入すればよかった

Slide 44

Slide 44 text

©︎tete marche CO., LTD. テスト戦略 02. 44 • アイスクリームコーン型の放置をしなければよかった • カバレッジ率を計測すればよかった

Slide 45

Slide 45 text

©︎tete marche CO., LTD. アイスクリームコード型テストの放置 45

Slide 46

Slide 46 text

©︎tete marche CO., LTD. アイスクリームコーン型テストとは？ 46 • 自動テストを「ユニットテスト、インテグレーションテスト、E2Eテスト」の3つの階層で考えた際、下に階層に行くほど、テストケース数が多いのが望ましい • アイスクリームコーン型は、その逆のアンチパターンで「上の階層に行くほどテストケースが多い」という比率を示している

Slide 47

Slide 47 text

©︎tete marche CO., LTD. アイスクリームコーン型テストとは？ 47 • 自動テストを「ユニットテスト、インテグレーションテスト、E2Eテスト」の3つの階層で考えた際、下に階層に行くほど、テストケース数が多いのが望ましい • アイスクリームコーン型は、その逆のアンチパターンで「上の階層に行くほどテストケースが多い」という比率を示しているフロントエンドが手動テストに頼りすぎていた

Slide 48

Slide 48 text

©︎tete marche CO., LTD. なぜアイスクリームコーン型テストになったのか？ 48 • 0→1フェーズの開発であったため、頻繁に仕様変更が発生する可能性があり、自動テストが無駄になる可能性が高いと判断して手動テストに頼った • 手動テストにより一定の品質を維持できていたため、改善の必要性を感じられず、現状維持の誘惑に屈していた

Slide 49

Slide 49 text

©︎tete marche CO., LTD. アイスクリームコーン型テストの問題は 49 短期的には問題がなくても、機能に変更が入る度に手動でテストをする必要があり、テストにかかるコストが増大していく • 頻繁なリリースが必要なほど、手動テストをする回数が増えるのでコストが高くなる（弊社は毎週リリースしているので大変） • 手動テストに時間がかかり開発が遅れる

Slide 50

Slide 50 text

©︎tete marche CO., LTD. 50 ではどうすればいいのか？

Slide 51

Slide 51 text

©︎tete marche CO., LTD. 今どうしたらよいのか 51 自動テストの比率を増やしピラミッド型にしていく (↓例) • 以降追加されるコードにはテスト必須とする • 既存のコードに優先順位をつけてテストを整備する

Slide 52

Slide 52 text

©︎tete marche CO., LTD. 当時どうすればよかったのか 52 前提としてアイスクリームコーン型であること自体が悪いというわけではない仕様が固まっていない時点でテストに多くのコストをかけたくない MVP開発は初期リリースを最小限のコストでしたい

Slide 53

Slide 53 text

©︎tete marche CO., LTD. 当時どうすればよかったのか 53 問題はアイスクリームコーン型になっていたこと自体ではなくてこの状態が長続きしていたこと我々の場合、自動テストを中心にテストをしなかったのは、0→1フェーズの仕様変更が多い時にテストにコストをかけたくなかったから

Slide 54

Slide 54 text

©︎tete marche CO., LTD. 当時どうすればよかったのか 54 問題はアイスクリームコーン型になっていたこと自体ではなくてこの状態が長続きしていたこと我々の場合、自動テストを中心にテストをしなかったのは、0→1フェーズの仕様変更が多い時にテストにコストをかけたくなかったから仕様が固まった時点で、自動テストの比率を増やしピラミッド型に移行するための戦略を立てるべきだった

Slide 55

Slide 55 text

©︎tete marche CO., LTD. 教訓 55 手動テストは短期的には有効で依存しやすく長期的な課題に気づきにくい • 長期的視点での総合的なコストも判断材料に含めるべき • 早期に自動テストを整備するほどテストの恩恵を長く得られたはず

Slide 56

Slide 56 text

©︎tete marche CO., LTD. 教訓 56 後からテストを整備する困難さ • テストはビジネス成果が見えにくく、リソース確保が後回しになりがち • 手動テストだけで進めた場合、それが基準になってしまい、自動テスト導入を「開発コスト増」と見なされる恐れがある • 初期フェーズのアイスクリームコーン型テストの理由や背景をステークホルダーとしっかり共有することが、ピラミッド型移行時のリソース確保において必要だった

Slide 57

Slide 57 text

©︎tete marche CO., LTD. テストカバレッジの未計測 57 57 テストどのくらい書いてる？全部！！ …

Slide 58

Slide 58 text

©︎tete marche CO., LTD. テストカバレッジとは？ 58 テストがソースコードのどの程度を網羅しているかを示す指標主に以下の網羅基準で評価する • 命令網羅 (statement coverage) (C0) • 分岐網羅 (branch coverage) (C1) • 条件網羅 (condition coverage) (C2) • 経路網羅 (Path Coverage) (PC)

Slide 59

Slide 59 text

©︎tete marche CO., LTD. テストカバレッジをなぜ計測しなかった？ 59 テストカバレッジへの理解不足 • コードの書き方によってテストカバレッジは変わるらしい？ • テストカバレッジが高いからと言って、良いテストとは限らない？ • テストカバレッジを100%にしても、バグ検出できないパターンがあるらしい？

Slide 60

Slide 60 text

©︎tete marche CO., LTD. テストカバレッジをなぜ計測しなかった？ 60 テストカバレッジへの理解不足 • コードの書き方によってテストカバレッジは変わるらしい？ • テストカバレッジが高いからと言って、良いテストとは限らない？ • テストカバレッジを100%にしても、バグ検出できないパターンがあるらしい？テストカバレッジ = 信頼性の低い定量データと考えた結果、必要性を感じなかった

Slide 61

Slide 61 text

©︎tete marche CO., LTD. どういうテスト戦略にしていた？ 61 ■フロントエンド • リリースタイミングでの受け入れテスト • 重要なロジック・複雑なロジックのみ自動テスト化 ■ バックエンド • ユースケースに基づいたテストケースを自動化

Slide 62

Slide 62 text

©︎tete marche CO., LTD. どういうテスト戦略にしていた？ 62 ■フロントエンド • リリースタイミングでの受け入れテスト • 重要なロジック・複雑なロジックのみ自動テスト化 → アイスクリームコーン型になっているためカバレッジは低い ■ バックエンド • ユースケースに基づいたテストケースを自動化 → ユースケースを網羅しているしカバレッジも高いだろう

Slide 63

Slide 63 text

©︎tete marche CO., LTD. テストカバレッジを測定してみた 63 • 実際にPHPUnitでカバレッジを計測したところ10%台だった

Slide 64

Slide 64 text

©︎tete marche CO., LTD. テストカバレッジを測定してみた 64 • 実際にPHPUnitでカバレッジを計測したところ10%台だった • ほとんどのユースケースをカバーできていると考えていたが、残りの80%以上にバグの可能性がある状態で、本当にカバーできているとは言いにくい

Slide 65

Slide 65 text

©︎tete marche CO., LTD. テストカバレッジの計測は必要なのか？ 65 100%など高すぎるカバレッジを目標にするべきではない

Slide 66

Slide 66 text

©︎tete marche CO., LTD. テストカバレッジの計測は必要なのか？ 66 だがカバレッジの計測はテストコードの質が悪いことを判断するのには効果的

Slide 67

Slide 67 text

©︎tete marche CO., LTD. テストカバレッジを計測する目的は？ 67 引用: https://qiita.com/odekekepeanuts/items/d02eb38e790b93f44728

Slide 68

Slide 68 text

©︎tete marche CO., LTD. テストカバレッジの目安は？ 68 GoogleのCode Coverage Best Practices を参照 • 「理想的なコードカバレッジの数値」というものはない • 60% を「許容範囲」 • 75% を「推奨範囲」 • 90% を「模範的」引用: https://testing.googleblog.com/2020/08/code-coverage-best-practices.html

Slide 69

Slide 69 text

©︎tete marche CO., LTD. テストカバレッジの目安は？ 69 GoogleのCode Coverage Best Practices を参照 • 「理想的なコードカバレッジの数値」というものはない • 60% を「許容範囲」 • 75% を「推奨範囲」 • 90% を「模範的」引用: https://testing.googleblog.com/2020/08/code-coverage-best-practices.html うわっ・・・我々のテストカバレッジ、低すぎ・・・？

Slide 70

Slide 70 text

©︎tete marche CO., LTD. 教訓 70 テストコードが存在しているだけで安心せず、実際にどの程度を網羅しているのか把握しておく必要がある • テストカバレッジの数値だけでは「良いテストかどうか」を完全には判断できないが、十分に網羅されていなければテストの質が低いと判断できる • 後からカバレッジ不足に気づいてテストを充実させようとしても、時間やリソースの確保が困難になる • 初期段階からテストカバレッジを測定し、目標値を設定してテスト戦略を充実させるべきだった

Slide 71

Slide 71 text

©︎tete marche CO., LTD. 教訓 71 テストを書いていないと、テストをしにくい設計になっていることに気が付けない • クラス内で直接依存オブジェクトを生成したり、静的メソッドを多用したりすると、システムが密結合になり、モックへの差し替えが難しくなる • テストを書くことで、こうした設計上の問題に気づき、改善の機会を得られる • テストを書かないことは設計自体の改善の機会を逃すリスクにつながる

Slide 72

Slide 72 text

©︎tete marche CO., LTD. テストを書いていないと、テストをしにくい設計になっていることに気が付けない • クラス内で直接依存オブジェクトを生成したり、静的メソッドを多用したりすると、システムが密結合になり、モックへの差し替えが難しくなる • テストを書くことで、こうした設計上の問題に気づき、改善の機会を得られる • テストを書かないことは設計自体の改善の機会を逃すリスクにつながる教訓 72 初期段階からテストカバレッジの計測をし高カバレッジを実現する戦略を立てるべきだった

Slide 73

Slide 73 text

Slide 74

Slide 74 text

Slide 75

Slide 75 text

Slide 76

Slide 76 text

Slide 77

Slide 77 text

Slide 78

Slide 78 text

Slide 79

Slide 79 text

Slide 80

Slide 80 text

Slide 81

Slide 81 text

Slide 82

Slide 82 text

Slide 83

Slide 83 text

Slide 84

Slide 84 text

Slide 85

Slide 85 text

Slide 86

Slide 86 text

Slide 87

Slide 87 text

Slide 88

Slide 88 text

Slide 89

Slide 89 text

©︎tete marche CO., LTD. 古いアプリケーションで開発を継続 89 このディレクトリ配下で開発 • コードの移行が進まない (1年で全体の1/10) • その間サポートが切れたPHPバージョンで開発し続けなければいけない • コードの移行は進まないが、機能開発は進んでいたため、古いPHPバージョンのコードが増えていき、移行が完了した後のバージョンアップ対応が大変

Slide 90

Slide 90 text

Slide 91

Slide 91 text

©︎tete marche CO., LTD. ストラングラーパターンとは？ 91 出典：https://learn.microsoft.com/ja-jp/azure/architecture/patterns/strangler-fig 機能の特定の部分を新しいアプリケーションに徐々に置き換えることで、レガシーシステムを段階的に移行する手法

Slide 92

Slide 92 text

Slide 93

Slide 93 text

Slide 94

Slide 94 text

Slide 95

Slide 95 text

©︎tete marche CO., LTD. 教訓 95 ロードマップを作成し、期限を設けるべきだった • 移行にここまでの時間がかかることを見越せず、短期的に有効と思われる戦略をとってしまった • 初期段階で移行のロードマップを策定し、明確な期限を設けることで、移行を計画的に進められたはず • どのくらいで移行が完了するかの目安を把握し、長期的視点でのトレードオフも含めて判断できるようにすべきだった古い環境のコードを増やさない戦略を徹底すべきだった • 古いアプリケーションでの開発を続けることによるデメリットや、後任者にかかるコストを軽視していて、短期的な成果を求めすぎた • 古い環境で開発を続ける後に続く人のコストを考え、新しいアプリケーションへの移行が実現可能かをもっと真剣に検討する必要があった

Slide 96

Slide 96 text

©︎tete marche CO., LTD. 96 ドキュメント設計 • ドキュメント運用のルールを整備していないことで、多くの問題に繋がっていた • 対策としてADRを導入したが、プロダクト初期に意思決定された内容を、後から充実させることは困難 • ドキュメント整備の不足は、設計者自身よりも、その後に引き継ぐ人たちに大きな負担を強いるため、最初からADRを導入しておくべきだったテスト戦略 • フロントエンドのテストが手動テストに依存しすぎていてアイスクリームコーン型になっていた • アイスクリームコーン型自体は悪ではないが、現状維持に満足していると、長期的なコストが増大し、また後からテストを充実させることが難しくなる • バックエンドは自動テスト化していたが、テストカバレッジの測定をしておらず、テストが充実していないことに気付けなかった • テストカバレッジだけではテストの品質が良いことを判断できないが、テストの品質が悪いことの判断はできるので、初期段階からカバレッジを測定し高カバレッジを実現する戦略を立てるべきだった移行戦略 • 短期的な成果を求めた結果、古い環境で開発を続ける決断をし、長期的に多くのコストがかかる戦略をとってしまった • 古い環境で開発を続けるデメリットを理解し、古い環境のコードを増やさないために、ストラングラーパターンに沿った移行を進めればよかったまとめ