密集_ドキュメントのコロケーション_with_AWS_Lambda

Transcript

1. 密集、ドキュメントのコロケーション with AWS Lambda 2025.02.15 SATOSHI KANEYASU
2. 2 自己紹介 氏名：兼安 聡 所属：株式会社サーバーワークス アプリケーションサービス部 在住：広島（フルリモート） 担当：DevOps、技術支援、PM、SM 2024 Japan AWS Top Engineers (Database) 2024 Japan AWS All Certifications Engineers Certified ScrumMaster PMP ←2025/01/13 X：@satoshi256kbyte
3. 3 コロケーションとは ➢ コロケーションとは、関連するリソースを近くに置くことを指します。 ➢ コロケーションは、Next.jsの公式ページが参考になります。 ➢ コロケーション自体は設計書だけに焦点をあてたものではないのですが、私のチームではこれをバックエンドプログラ ムの設計書に適用してみました。
4. 4 やってみたコロケーションのイメージ ➢AWS LambdaとPythonによるバックエンドのプログラムでやってみました / ├── app │ ├── function_a │ │ ├── handler.py │ │ └── README.md │ ├── function_b │ │ ├── handler.py │ │ └── README.md │ └── function_c │ ├── handler.py │ └── README.md ├── docs │ ├── database.md │ └── system_diagram.drawio └── README.md 業務ごと（＝AWS Lambda関数ごと）でディレクトリを分けている これが設計書、いわゆるプログラム設計書に相当 プログラム テーブル定義、構成図など機能・業務を跨ぐものはここ
5. 5 このような構成にした理由 ➢ 設計書はシンプルにしたい（スクラムで回してるので余計そう思う） ➢ 設計書もプルリクエストを回したい ➢ 何がどこにあるか見通しをよくしたい ➢ 後から来る人にもわかりやすくしたい
6. 6 現在の構成に至るまでに考えた他の構成候補 / ├── app │ └─── functions │ ├── function_a.py │ ├── function_b.py │ └── function_c.py ├── docs │ ├── database.md │ ├── function_a.md │ ├── function_b.md │ ├── function_c.md │ └── system_diagram.drawio └── README.md / ├── app │ └─── functions │ ├── function_a.md │ ├── function_a.py │ ├── function_b.md │ ├── function_b.py │ ├── function_c.md │ └── function_c.py ├── docs │ ├── system_diagram.drawio │ └── database.md └── README.md 実案件ではもっと関数が多い 場所が遠くで探しづらい functions配下が煩雑 実際には関数の名前はもっと不規則 なのでかなり見づらい
7. 7 この構成における設計書で書くもの ➢ Markdownで書く ➢ 機能の概要 ➢ 何をする機能か ➢ 大まかな処理の流れ ➢ 入出力内容 ➢ パラメータ ➢ 出力するファイル・データのフォーマットなど ➢ 使用方法／テスト方法 ➢ フローチャートやシーケンス図は開発者からの需要がなく、メンテ負荷になったのでカット ➢ Marmaidも不採用、AWSを使用してるのでアイコンが揃ってるdraw.ioで書いた方が良いとなった
8. 8 メリットとデメリット メリット デメリット ➢ 目論見通り、見やすい ➢ プルリクエストで設計書がレビューできる ➢ 設計だけできてるのか？実装まで済んでるの いか？がツリーに表れる ➢ 設計書の配置に関してはやり切った感があり、 最近設計書の配置に関する無駄な議論がない ➢ ディレクトリ構造そのものに工夫を入れてい るので、他のPJにも展開できると言い切れな い（AWS Lambdaを使用してるからできてる とも感じる） ➢ レビュアーがGitに入らないといけない
9. 9 その他の悩み ➢ 設計書を非常にシンプルにしているが故に、なぜその機能がそうなっているのか？というのは語りきれていない ➢ これを補うために「意思決定の経緯」を文書として残っている（＝ADR) ➢ BacklogでPBI/SBIを管理している ➢ ソースコードと設計書はGit ➢ ADRはBacklogのWiki ➢ 故に、実は設計書よりBacklogの方が情報量が多い・・・
10. 10 まとめ ➢ 導入にはディレクトリ構成レベルでの工夫が必要になりますが、ドキュメントをコロケーションすると快適だと思います ➢ もし試されたら意見交換しましょう