はじめに
こんにちは。カナリーでソフトウェアエンジニアをしている @react_nextjs です。
私たちは 【もっといい「当たり前」をつくる】 をミッションに掲げている不動産テックカンパニーです。弊社では、現在下記のプロダクトを運用しています。
- 「CANARY」: BtoC のお部屋探しマーケットプレイス（アプリ/Web）
- 「CANARY Cloud」: BtoB SaaS（不動産の仲介会社様向けの顧客管理システム）
この記事では、マーケットプレイスチーム(BtoCアプリ)で技術的な意思決定を記録する文化を作った経緯についてご紹介します。
背景 / 課題
マーケットプレイスチームでは、毎週1時間のKPTミーティングを開催しています。この時間を通して、現状の成功点や強みを維持しつつ、問題点を洗い出し、改善や新たな挑戦に積極的に取り組んでいます。
その中で以下の課題が挙げられました。
- 技術的な過去の意思決定が不明確
- ドキュメントを「誰が」「いつ」「どのように」書くべきかが明確になっていない
「CANARY」は2019年のリリースから間もなく6年を迎えますが、これまでの技術選定や意思決定の背景について不明瞭な点が多く残っています。なぜ当時その技術を採用したのか、その判断基準が明文化されておらず、新しくチームに加わったメンバーが同じような議論や迷いを繰り返してしまう状況が発生していました。また、当時のメンバーにとっても技術選定の理由が曖昧なケースがありました。さらに、意思決定を記録するためのドキュメント作成プロセスが整備されておらず、「誰が」「いつ」「どのように」記述すべきかといったルールも明確ではないという課題がありました。
意思決定を残す仕組みづくり
ADRの導入
技術的な意思決定や設計を記録する方法には、ADR(Architecture Decision Record)やDesign Docなどさまざまな手段があります。当初は、ライブラリなどの選定はADR、アーキテクチャやAPI設計はDesign Docに記録する、といった棲み分けも検討しました。しかし、棲み分けの基準は人によって解釈にばらつきがあり、運用が複雑になる懸念がありました。達成したいことは、「チームとしての意思決定を明確に残すこと」であるため、ドキュメントの形式を分けず、ADRに一本化する方針に決定しました。
ADR作成ルールの確立
ADRを書くルールとして、ADRを書くためのADRを作成しました。
以下は一部抜粋したものになります。
✅ 誰が書くのか
チームメンバー全員が、必要になったタイミングでADRを作成する。
🕒 書くタイミング
以下のようなケースでADRを記載します：
- 新しいライブラリ／フレームワーク／ツール（例：Datadog）の導入時
- 既存ツールの廃止時
- 新機能の追加、設計変更、修正の際
📝 書かなくてもよい場合
以下の場合はADRの作成は不要です：
- 既存のADRや設計ドキュメントでカバーされている場合
- 小規模なバグ修正やリファクタリング
- コード内コメントで十分な説明が可能な場合
🔄 承認フロー
- 作成したADRはチーム内でレビュー
- TLE（Technical Lead Engineer）と PLE（Product Lead Engineer）の承認を経て正式化
📕管理場所・書き方
- 管理場所：Notion にて一元管理
-
記載項目：
- タイトル
- ステータス（下書き／提案中／承認済／廃止／保留中）
- 背景
- 決定内容
- 決定理由と他の選択肢との比較
- 影響範囲
- 参考資料 など
- ステータス管理：Notionのプロパティ機能を使用
導入後の変化
2024年12月にADRを導入してから、現在（2025年4月）までの約4ヶ月で、59件のADRが記載されました。
また、以下のような変化がありました。
- ドキュメントが着実に蓄積されており、Notion AIによる検索性が向上。新しくチームに加わったメンバーも、必要な情報に素早くアクセスできるようになり、キャッチアップにかかる時間が大幅に削減されました。
- ADRの導入をきっかけに設計や技術選定に関する議論が活発になり、その時点でのベストな判断をチーム全体で行えるようになりました。
中でも特に効果を感じているのが、「議論の活性化」です。従来は、ライブラリなどの技術選定を個人の裁量に任せる場面が多く、その判断が本当に最適だったのかを振り返る術がありませんでした。現在では、チーム全体で議論を重ねたうえで意思決定を行っており、結果として技術選定の透明性が高まり、チーム全体の技術力と意思決定の質の向上につながっています。
今後の展望
従来のADRは主に人が読むためのドキュメントでしたが、今後は人だけでなくAIも活用できる形へと役割が進化しています。ソースコードとADRを同じ場所（GitHub）で管理することで、設計や意思決定がAIに読み込まれ、AIが生成するコードの品質向上につながると考えています。そのため、ADR管理をGitHubへ移行することにチャレンジしたいです。また、過去に蓄積したADRの内容をAIに学習させることで、新しいADR作成にかかるコストも削減できると感じています。
おわりに
弊社では、Cursor、Devin、DifyなどのAIツールを会社負担で利用できる環境が整っています。今後も生成AIを積極的に活用し、開発効率を大幅に向上させていきたいと考えています。
もし弊社の取り組みにご興味をお持ちいただけた方は、ぜひカジュアル面談にお越しください！
最後までお読みいただき、ありがとうございました！
Discussion