最適ワークスの仕様はどう管理されているのか

こんにちは。スカイディスクでWeb開発チームのテックリードをしている山口です。今回は、私たちが今年7月にリリースした最適ワークスの仕様管理についてお話しようと思います。

仕様管理のベストプラクティス？

ソフトウェアエンジニアリングの世界には、様々なベストプラクティスがあります。コーディング、インフラ構成、セキュリティ、開発方法など、多くの場面で「こうするのが良い」とされているものが知識として体系化されていて、私たちはオンラインの記事や書籍からそういった情報を学ぶことができます。

それに対して、「プロダクトの仕様管理」はどうでしょうか。仕様とは「このように動くべき」というものを定義する知識であり、プロダクトの根幹を成すものです。これが定められていることによって、エンジニアは「正しい動作」を把握して設計や実装が可能となるし、QAチームによる動作確認や、CSチームのマニュアル作成なども実施することができます。そして、これはプロダクトの拡大とともに更新されるのが望ましいのですが、その管理方法のベストプラクティスがあるかというと、「これが正解」と言えるものは現状ありません。

仕様管理の難しさ

仕様の管理には、なぜベストプラクティスが無いのでしょうか？それは、仕様を管理する上で以下のような困難があり、それぞれを解決するベストな方法が世の中で確立されていないからだと考えています。

1. 最新の挙動に追従することの難しさ

最適ワークスのようなSasSのプロダクトでは、「一度作ったら終わり」ではなく、開発は継続して行われます。その中で、プロダクトへの機能開発や修正が頻繁に行われますが、それらを常に仕様ドキュメントへと反映して最新に保つのは、決して簡単ではありません。

2. 仕様の分散

多くのプロジェクトでは、開発する機能単位で作業タスクを管理していることかと思います。そして、それらのタスクはGitHub issue, Jira, Notion などといったツールで定義されていることが多いですが、開発対象とする仕様がそれらのissueなどに記載されたままだと、仕様が分散されたまま一元管理されません。

3. 属人化

仕様をドキュメント化して管理できていたとしても、その仕様を記述する人がプロジェクト内の限られたメンバーだけであるということもあります。その場合、そのメンバーがチームを抜けた時には仕様が適切にメンテナンスされなくなるリスクがあります。

最適ワークスの仕様管理

では、上記のような困難に対処するために、スカイディスクでは最適ワークスの仕様をどのように管理しているのでしょうか。まず、前提として我々が仕様管理に使用しているツールからお話します。

Notionによる仕様管理

最適ワークスでは、仕様を管理するためにNotionを利用しています。これはNotionが、我々が仕様管理に求める以下の要件を満たしているからです。

1. 誰でも閲覧や編集が可能であること

2. 同時編集が可能であること

3. 個々の記述にコメントが可能であること

4. 画像の埋め込みやFigmaとの連携が容易であること

まず、プロダクトの仕様はチームやポジションに関わらず、誰でも参照可能で無ければいけません。また、複数の機能開発が同時に行われることからも、「誰でも参照が可能であり(1)、同時編集も可能である(2)」という要件が生まれます。
また、仕様策定の段階では仕様そのものに対するレビューも行われるため、仕様ドキュメント内の個別の記述に対する指摘や返信ができること(3)も必要でした。
さらに、仕様とデザインは密接に関連するので、仕様ドキュメントの中でデザインの画像、あるいはFigmaそのものを埋め込むことができる(4)必要があります。
これら全ての要件を満たせるのがNotionでした。

Notionで管理している最適ワークスの仕様。
機能・UIパーツ、ページ、などといった観点でカテゴライズもしている

仕様の記述

ここからが重要な点となりますが、最適ワークスでは機能開発や修正に伴って、Notionに記載された仕様を修正します。そしてその修正タイミングは、主に以下の2点になります。

1. 機能開発前

2. 機能リリース後

まず、機能開発を行うにあたって、当然仕様を定めます。この際、仕様の記載先は個々のタスクを定義するissueではなく、Notionの仕様書そのものになります。ただし、そのまま仕様を上書きしてしまうと「開発中の機能」と「既にリリースされている機能」が判別できなくなってしまうため、「これは開発中の機能の仕様である」ということが把握できる構成とします。具体的には、Notionのカラム機能を使って、左側に現状の仕様、右側に開発中の仕様を記述します。

カラムを使って記述された開発中の仕様

機能がリリースされた後は、上述した2カラム構成のうち「現状の仕様」を削除し、「開発中の仕様」を最新の仕様として反映します。

仕様変更の流れ

なお、仕様の記述は誰かに限定することなく、タスクをアサインされた人が実施するという運用にしています。これだけだと、仕様の記述方法が担当者によって差異が出てしまう可能性もありますが、これはレビューにより一貫性を担保しています。

この運用で解決できること

この運用により、上述した問題を解決しています。
まず、機能開発時には必ず仕様を更新するので、機能追加や修正に伴う仕様更新漏れが発生しません。また、仕様の記述先は「Notionで管理している仕様ドキュメント」そのものなので、仕様の記載場所が分散してしまうこともありません。さらに、仕様の記載メンバーを限定しないことで、仕様管理の属人化を避けています。

運用の効果

このような運用を始めるまでは、仕様が適切にされていると言える状態ではありませんでした。そのため、「メンバーが抜けてしまい、詳細な仕様を把握しているメンバーがいない」「過去のSlackの会話、GitHub PR、Notionのタスクなどから情報をかき集めなければいけない」というようなことが度々発生していました。

それに対し、この運用を適用して以降はプロダクトの挙動と仕様ドキュメントを同期させることができており、「仕様はここを見に行けばわかる」という状態を維持しています。これはCSチームによるマニュアル作成、QAチームによるテストシナリオ作成など、開発のみに留まらない範囲で影響を与えており、健全なプロダクト開発を継続する上での土台となっています。

AIによるサポート

上述した方法によって大きな課題は克服できているものの、「必要な仕様を膨大なドキュメントの中から探し出す」というのも、簡単な作業ではありません。

そこでスカイディスクでは、社内のエンジニアによって構築された、LLMによる仕様確認サポートの仕組みを利用しています。これは、Notionに記述された仕様をもとにLLMが学習を行い、仕様に関する質問に回答できるようにするというものです。質問はSlackを通して行うことができ、社内のメンバーであれば誰でも利用可能になっています。

Slackで仕様の質問をしている様子

また、回答の元になったドキュメントの場所も同時に教えてくれるので、必要に応じて詳細を確認することもできます。
この仕組みにより、私たちは以下の問題も解決することができています。

• 仕様の記述箇所の把握が難しい

• 仕様確認のために、他のメンバーに質問したり、逆に回答したりすることに時間を費やしてしまう

最後に

冒頭で述べたように、仕様管理には、「これがベストプラクティスである」と言えるものはありません。しかし、上述したような取り組みによって、スカイディスクでは「仕様を適切に管理している」と言える状態に近づけています。とはいえ、より良い方法はあるかもしれないし、今後の技術の進化に伴って仕様管理をさらに簡単にする方法も現れることと思います。今後も現状の仕組みに満足することなく、スカイディスクでは仕様管理の方法を改善し続けていきます。

一緒に働いてみませんか

スカイディスクでは一緒に働く仲間を募集中です。仕様を作ってみたい人、仕様に基づいたプロダクト開発をしてみたい人、どなたも下記URLから募集要項を確認してみてください😊