ユビーが長期に渡ってソフトウェアを進化させ続けるためのドキュメンテーションプラクティス

こんにちは、スープです。
ユビーでソフトウェアエンジニアをしています。
最近は、マイクロサービス化推進や社内のスクラムマスター育成のお仕事をしています。

この記事では、ユビーが長期的に設計と向き合うために採用しているプラクティスを紹介します。

Web スタートアップが陥りやすい技術の問題

一般的に、Web スタートアップでは価値検証のためのフィードバックサイクルを高速化することが重要視されます。それは極めて正しいことと思いますが、その反面、ソフトウェア設計が軽視されやすくもあります。単に「動くもの」を作ることが優先されるがあまり、ビジネス要件の変化に設計が耐えられなくなったり、チームの生産性が大きく下がったりするのを何度も見てきました。

また、Web スタートアップは人員の入れ替わりが激しいため、チームの誰にも既存のコードベースの設計意図やコンテキストがわからないということがよくあります。そのような状況下では、加えたい変更が、果たして良いものかどうか判断しにくくなってしまいます。

そのため、ソフトウェアが進化しつづけられるためには、変更しやすい構造を設計に持たせることに加えて、設計の意図やコンテキストが何らかの方法で保存される必要があると考えています。

ユビーはどうやっているか？

ユビーでは去年から、ADR という仕組みを導入しています。これは Architecture Decision Records の略で、アーキテクチャにおける重大な決定を記録するためのフレームワークです。

例えば、特定の技術やフレームワークを採用した理由、また逆に採用しなかった理由などを記録します。これによって、意思決定の背後にある考えや解決したかった課題を知ることができます。

また、時が経って状況が変化し、以前に解決したかった課題が消失することはよくあります。そのようなときに、ADR で記録が残っていれば、加えようとする変更に対して自信が持ちやすくなります。

刻一刻と変化する世界では、ソフトウェアの形も変え続ける必要があります。ユビーは、ビジネスもソフトウェアもどんどん変化していますが、この仕組みにより、長期的に設計と向き合っていくことができます。

ユビーでの ADR 運用

ユビーでは、下記の項目を Markdown 形式で書いて、ADR 用の Github リポジトリにコミットする形式で運用しています。

このような形式です。

# 1. ADR の記事のタイトル

Date: 日付

## Status

proposed | rejected | accepted | deprecated | superseded by 記事リンク

## Context

この決定の背景やコンテキスト、決め手、制限等

## Decision

提案したい変更点、あるいは合意が交わされた変更点

## Other Options (任意)

他に検討した選択肢
なぜそれらを選ばなかったかの説明

## Consequences

この変更によって便利になること、不便になること
この変更によって生じるリスク、対処する必要があること

ADR を導入したことでどう変わったか

新たな決定に関して、設計方針がクリアに伝わりやすくなりました。また、過去の決定についても ADR を書くことで、特定メンバーしか知らなかったことが形式知化されました。またさらに、キャッチアップのための資料としても役立ってもいます。

ADR に対する社内の声

最後に

今回は、ユビーにおける、長期的に設計と向き合うためのプラクティスを紹介しました。

ユビーではあらゆる職種で、一緒にがんばってくれる仲間を募集しています。少しでも興味を持ってくださった方は、下記採用サイトからご連絡ください。

https://recruit.ubie.life/

参考リンク

https://adr.github.io/
https://assets.thoughtworks.com/assets/technology-radar-vol-18-en.pdf