業務の傍ら、有志でアジャイルの勉強会をしています。認定スクラムマスターという資格を取ったり、スクラムでアプリの開発を行って、体験談をまとめるというような活動をしています。この勉強会では、タスク管理や設計資料を Excel で作成し、発表資料を PowerPoint で作成し、議事録をメモ帳で作成し、ドキュメント管理に onedrive を使っていました。
スクラムでのアプリ開発のために Github を使うようになったので、各種ツールを Github に寄せる形で見直し、実際に運用してみました。スクラムで Github をどう使ったのか、この経験を書き残しておきます。
前提と準備
勉強会の活動の一環として、チームでアプリケーション開発をすることになり、以下のような制約がありました。この制約をクリアできそうだったのが、Github でした。特にチーム利用が無料でできる点が魅力でした。
- コードやドキュメントはネット上に公開しないこと
- 無料で使用できること
- git でソース管理できること
- チーム利用ができること
まず、チームで利用するために、Organization を作成しました。こちらの記事をもとにしました。また、ネット上に公開しないため、リポジトリはプライベートで利用するようにしています。もちろん、Git をインストールして各自ソースツリーや VScode の Git 機能などを用いて操作しています。エディタは VScode を使用しております。
今回の使用したVScodeのプラグインは以下の通りです
- Markdown All in One：テキストの装飾（太字、斜体など）、リストやテーブル作成のサポート、自動補完、目次（TOC: Table of Contents）の生成などMarkdownで書くために必要なものがそろっています
- markdownlint：ルールに沿っているかをチェックする静的解析（Linter）ツールです
- Mermaid Graphical Editor：Mermaid 記法で書かれた図（シーケンス図など）を編集・作成するための専用エディタです
- Markdown Preview Mermaid Support：VS Code 標準の Markdown プレビュー機能に、Mermaid 記法の描画機能を追加します
- Marp for VS Code：Markdown ファイルを使って、スライド資料を作成するためのツールです
- Markdown PDF：Markdown ファイルを、PDF や HTML などの多様な形式にエクスポートするためのツールです
＊
Github を使って以下のような 3 つの管理をするように変更しました。工夫したのは、コード管理だけではなく、タスク管理やドキュメント管理も Github に統合したことです。これによって、チームに必要な情報が一元化され、管理しやすく、必要な情報を探しやすくなりました。以前は様々なツールを使っていたので、探すのがめんどうであったり、ツールを切り替えるのが大変でした。一元管理することで、VScode か github だけで作業が簡潔することができました。
- コード管理（PR でのレビュー、コードの保管）
- タスク管理
- ドキュメント管理（設計書、議事メモ、レビュー）
タスク管理では、Github Projects を利用しました。タスク管理する UI を選択できたり、項目を自由にカスタマイズでき柔軟性に優れています。PR とチケット（issue）を紐づけることができ、更新漏れを防げることも魅力です。タスクは終わっているけど、WBS は更新していない みたいなあるあるを防ぐことができました。
Github 利用に伴って、ドキュメントは markdown で作成することに統一させました。具体的には、議事メモや設計書、レビュー資料を markdown/marp/mermaid で作成しました。markdown で書けば最低限の装飾はできますし、プラグインを利用すれば、設計書もスライドも作成することができます。markdown のドキュメントは Github 上で差分を表示してくれたりと Github と相性がよいです。
スクラム開発では、ドキュメントより対話を重視する思想があり、ドキュメント作成に必要な最低限の機能があれば十分やっていける算段もありました。そして、さらに Github-markdown は生成 AI とも相性が良いです。markdown の資料を簡単に生成 AI に読ませることができますし、生成 AI も markdown で出力してくれます。今後の AI 活用としても、発展の余地があります。
コード管理
Github のメイン機能として、アプリケーション開発におけるソース管理を行いました。コードを保管する・共有する・レビューするとアプリケーション開発に必要な機能がそろっています。チーム利用であっても無料で使えるのが最高です。
プライベートリポジトリを作成して、非公開なリポジトリを作成でき、要件に合致できたことも勉強会にはメリットでした。さらに、Github であれば使い慣れている人も多いので、学習コストが低いこともメリットです。最近では、Github copilot も利用してアプリケーション開発を行いました。
タスク管理
タスク管理は、Github Projects という機能を使いました。Github 上でタスク管理できる機能です。スクラム開発で Github Projects を使う記事を探し、先達の知識も借りながら自分たちで使い方カスタマイズしていきました。一番参考にした記事は以下の記事。
PR とタスクを紐づけて、常にタスク管理表と作業の実態が一致していることがメリットでした。コメントにタスクの状況をメモしたり、概要にタスク内容を書いておいたりして、後から必要な情報を探しやすいことも魅力です。
ドキュメント管理
設計書、議事メモ、レビュー資料でドキュメントを作成しますが、これも markdown で書いて github で管理しました。
設計書について
設計書はアジャイルだと書かないと思う人もいるかもしれないが、書きました。チーム開発なのでメンバーの共通理解の醸成と記録として立ち返れるように作成しました。具体的には、仕様まとめメモ/機能一覧/ER 図/API 一覧は最低限必要と判断し、作成しました。
設計書は Github で管理するように markdown で書きました。github で管理すると差分がわかっていいですね。コードレビューと同じフローでドキュメントもレビューでき、便利でした。
さらに、ER 図となど図を使う時は、mermaid を導入しています。これで markdwon で図を書けますし、テキストで管理できます。mermaid でかなりかけることを発見しました。複雑な図は難しいかもしれないですが、充分でした。AIと相性がいいのもいいですね。
レビュー資料
スクラムではスプリントレビューというレビュー会が 1 スプリントに 1 回発生しています。元々は PowerPoint でレビュー資料を作成していましたが、markdwon で書いて、marp でスライド化してレビュー資料を書くように変更しました。
結果、作成時間がだいぶ減りました。PowerPoint だと見た目に凝って作業時間を増えがちですが、marp で書くと、箇条書きが通常になり、必要なことだけを書くことになるので、作業時間が減りました。「レビュー資料って簡素でいいじゃん！」と思うようになりました。
作業者の視点からみると、VScode でコードをみたり、設計書を見たりして、同時にレビュー資料を作成できたので、情報がとっちらかさずに済みました。以前、marpでスライドを作成できるよういろいろ調べた経験が役に立ちました。
議事録
各種 MTG では議事メモを作成していました。取らないときもありましたが、振り返りをするので記録として残しておいた方がいいです。これも markdown＆github で管理しました。ドキュメントと同じ場所にあった方が使いやすいです。
また、勉強会ではスクラム開発の経験を言語化し、知見/経験を社内に公開する取り組みもしています。そこで、markdwon で知見/経験をまとめた「ハンドブック」を作成していました。これも markdown＆github で管理し、PR でチーム内でレビューして作成しました。公開する際は、markdown を PDF に変換し、社内の共有フォルダに置かせてもらいました。pdf に変換するために、vscode のプラグインを利用しました。
Github によせたメリット
個人的には、ツールを Github によせたのは成功だったと思います。vscode+github だけでたいていのことが済ますことができ、初動が早いです。markdown 関連の拡張機能も多数あり、柔軟にやり方を変えることができました。早いと柔軟性があるというのはスクラム開発とかなり相性がよく、安定的にチーム開発を進めることができました。
さらに、情報が見つけやすくなりました。いろいろ使うより、多少できることが少なくともまとめてしまった方が楽なのかもしれません。そして、ドキュメントもコードと同じレビューフローをたどれることもメリットです。作成物ごとにレビューフローが違うとそれだけで煩雑ですが、フローが同じことで、ストレスなくアウトプットを作り上げることができました。
Github によせたデメリット
ツールの移行が大変でした。Excel や PowerPoint などから github/markdonw/projects に移行したのですが、（勉強会のため活動時間が短いこともあり）使い方が浸透できず、「あれこれどうするんだっけ？」とスピードが出ない時期がありました。自分がツール移行を主導して一番の学びは、「使い方についての懇切丁寧なドキュメントを作っても、人は見ないこと」を知れたことでした。ドキュメントで説明するより、使ってみる機会を作った方が浸透しました。
また、予想ですがエンジニアではない人がチームに参画してくると、学習コストがかかることがデメリットかなと思いました。さらに github と相性が悪いツールは使いづらいかもしれません。ただ、エンジニアの少数チームであれば充分使えるとは思います。
終わりに
Github を中心にして開発を行えることがわかりました。Github でできないこともまだまだあるし、エンジニア以外の人が使いにくいという側面はあるかもしれません。しかし、小規模アプリであれば、むしろ Github になるべくよせて簡素化した方がいいかもしれません。
今後の展望としては、徹底的に Github を使い倒していきたいです。Github actions や Github discussions、Github copilot などなど、アプリケーション開発で便利な機能がたくさんあります。このあたりの使い方は試行錯誤していきたいです。できれば、organization の無料プランでも wiki を使えると嬉しいです。この記事が誰かの役に立てれば幸いです。
最後まで読んでいただいた方、ありがとうございました。