T204-あなたも新人も成長する仕様書の書き方_ローコード、ノーコードでもココまで残せ

あなたも新人も成長する 仕様書の書き方 ローコード、ノーコードでもココまで残せ！！ 2024 Tetsuji Hayashi 2024/6/13(Thu) 1

質問 御社の開発はアジャイル、ノーコードという名目で 行き当たりばったり、無法地帯開発 になっていませんか？ 無法地帯では、コンプライアンスとか情報セキュリティとか無理 2

仕様書どうしてますか？ • 発注側？ • 受注側？ • 「データベースについて文書」に残す • ソース内のコメントだけ • 要求されていないので書いていない • 要件定義段階で、要求元との理解の齟齬を埋めるために書いてる • ツール(設計の一覧機能、TeamStudio)で出して終わり ソースから仕様書を書く仕事 も受注していますが、インタ ビューなしには作れません 設計の一覧機能、TeamStudioから、仕様書書けますか？ 設計一覧から、実装背景、デザイン思想、利用シーンが再現できるのはニュータイプだけ 3

IT現場で使用される仕様書・ドキュメント No 名前 用途 記入者・部門 1 要件定義書 現状の業務フロー、IT化後の理想の業務フロー、実現したい機能、現 状のデータ量・利用者・利用タイミング 要求部門、現場部門 2 基本設計書 IT化する際のアーキテクチャー、ネットワーク構成、開発言語、デー IT部門、開発者 タベース、実装する機能、画面イメージ、制限事項、セキュリティ、 パフォーマンスなど IT化後システムの全体像、実装機能、制約 3 詳細設計書 テーブル構造(テーブル名、ER図)、クラス構造、関数呼び出し関係な ど ソース理解、改修、メンテナンスに役立つ情報 IT部門、開発者 4 機能仕様書 (要件定義と基本設計書をマージしたようなもの) 実装を外注する際に書いてた IT部門、開発者 5 テスト仕様書 モジュールごとのテスト、結合テスト、制約、パフォーマンス IT部門、開発者 6 導入マニュアル OS設定、プラットフォームインストール手順など、ゼロから再構築 出来る手順 IT部門、開発者 7 操作マニュアル 操作手順(最近は動画) IT部門、開発者 8 運用マニュアル 操作マニュアルを自部門の運用に当てはめた具体的操作例 運用部門 4

IT技術者の仕事って？ 現状理解 理想の業務 設計 実装・テスト 保守・サポート 基本設計を別の形で 表現しただけ 要件定義書 基本設計書 プログラム 詳細設計書 テスト仕様書 操作マニュアル 導入マニュアル 仕事のアプリ開発では、ノーコードでも設計書が必要 5

なぜ、仕様書を書くか？ 1. (発注者側)仕様書に書かなかった機能は実装されない ① 2. 3. 4. 5. (受注者側)仕様書に書かなかった機能は実装しなくて良い ① ユーザーからクレームが来た時の最後の砦が機能仕様書、基本設計書、詳細設計書 ② だから・・・要件定義で「実装しない」と決まったこと、「制限事項」も書いておく(お客様も自分も忘れる) ③ 書いてないと無償対応させられる (死なないけど、会社の損害と、自分の人生の時間が削られる) ずっと自分がサポートするとは限らない ① 組織変更などで自分がバトンを渡す日が来ることを想定して、初見の人がわかるように書いておく ② 自分が突然入院したり、退職した場合、会社のメンバー、お客様に迷惑がかかる プログラムを書く前に、実装の精度を上げられる ① 想定される入力や、動作、イレギュラーを想定しておけば、実装時に楽になる ② お客様に事前に説明しておける(トラブルになるのは、完成してから「思ってたのと違う！」) ③ 事前にお客様とイレギュラーパターンを協議しておけば、信頼度も上がる(ラポールを築ける) 基本設計書がなければ、テスト仕様書が書けない ① 6. 仕様書ないのに実装してくれるのは変人 (見積外だし・・・) 基本設計書を書いておけば「あの人しか知らない」を防げるので、作業を分担できる トラブル発生時のエビデンスになる ① バグが発生した際、お客様に「お前らどんな基準で、どんなテストしてるねん！」って言われた場合に出せる(出せと言われる) 6

なぜ、仕様書を書くか？ • 仮に自分が書いた仕様書がファイルサーバーの肥やしになったとしても・・・ 書くこと自体、自分が考えて、悩んだこと自体に意味がある プログラムからでは、実装の意図まで読み解けないので 機能の背景・意図、なぜその仕様なのか？は絶対必要 7

どうやったら良い仕様書が書けるか？ • 仕様書を書くこと自体が目的化すると、絶対に形骸化する →本気で書いてないものは、だいたい役に立たない →メンバーの能力、性格で精度がバラバラ 常に目的をチームで共通認識しておく 誰が、いつ、何のために？ 上司のレビューだけでなく、 メンバーレビューも有効 8

仕様書記述の基本の「き」 1. 全体像、概要から機能詳細へブレイクしていく ① 背景、現状の業務フロー、問題、IT化後の業務フロー、NW構成、アーキテクチャ、個別の機能 2. 全体に関わる前提条件、実装条件、制限事項、仕様は先に書いておく 3. データのIN、OUT、項目は明確に書く ① 実装のベースラインになる ② 入力画面、出力画面がある場合は、データ型、入力チェック、最大長も 4. これまでの定例会議資料、議事録、その他の資料を網羅できるようにする ① 議事録重要 5. 実施内容の「する」「しない」を明確に記述する。 例) ① 容量は室外機名から抽出できる。→× ② 容量は室外機名から抽出する。 →○ 6. 同じ意味の用語は必ず統一する。 ① 開発者から見て、変数名が違えば、用途が違うのと同じ。 7. パターンがあるものは表で書く 8. 全体的なデータの流れは図で書く 9

鬼滅に例えると・・・ No ストーリー 1 人物、背景の説明 2 修行 3 バトル ここがしっかりしているのが感情 移入しやすい良い漫画 (背景、誰を救うのか？) 基本設計書 背景、目的、全体像、利用者 炭治郎と禰豆子の関係(背景) 家族が惨殺され、禰豆子が鬼になる 禰豆子を人間に戻す(目的) 業務フロー データ量、必要なパフォーマンス、 費用の設計、モジュール分割の検討 鱗滝さんと出会う 技を身につける 狭霧山で石を切る モジュールごとの処理、実装 最終選別の手鬼、沼の鬼、手鞠鬼と矢印鬼 バトルシーンから炭治郎の背景、 目的を探るのは難しい ツールで出せるのはバトルシーンだけ 10

ソフトウェアにおけるエレガント、美しいとは？ • 同じ特徴、パターンを見つけて「抽象化」 dog関数 dogクラス を作る 設計でも、実装でも 美しい抽象化がゴール なのは変わらない キメラ関数 キメラクラス 誕生 早い段階で細かいパラメータ含め全体を把握することが最も重要 11

設計範囲 企画 設計 ココでケチって利用者の 負担を増やすのは 良い設計/実装ではない テスト開発 POC 製品開発 開発 テスト 運用 運用も含めた形で設計を行う 製品の利用 自分の後ろには、バトンを渡した先に人がいる 12

ところで、みんなどうやってアプリ作ってるの？ 要望から部品単位で組み合わせていく イメージボードのようなものを作る どっちが得意か？によって仕様書に残す項目の好みが変わる 13

最低限必要な項目 ■背景・解決すべき課題 • マスター ・なぜ必要か？業務を取り巻く状況 →本質的な背景 ■目的・ゴール・ビジョン • 自動化、低コスト化、時間短縮 →本質的な目的 ■ユーザー • 利用者(利用部門、グループ) • 重 要 度 権限、役割分け • 利用者以外の関係部門 ■利用シーン • いつ、どんな場所、状況で？ ■業務フロー • データの発生元と時系列の変化(データ変化の全体像) • データ量、パフォーマンス • 既存(別DB、別サーバーから貰う) • 自DBに持つ • データ項目の重要度、優先度 • 左から順に重要度が高いなど法則をつけて並べる ■機能 • 処理 • 特殊処理(特権、メンテ用) • セキュリティ(ACL、ロール、フィールド制限) ※画面は機能を説明するのにわかりやすくなるならあっても良い ■その他 • DB分類 • 更新頻度を考えると大体3つくらいに分けられる 1. 台帳(マスター) －年1、棚卸 2. 計画 －年初、月初、期初、月末、期末 3. 記録 －随時 ■データのIN、OUT • IN(手入力、CSV、REST)、OUT(画面、グラフ、CSV、REST) 14

「背景」「目的」が明確でないと・・・ 巨人の力は発動しない 15

巨人の力が発動できないと・・・ キントーンでも Intramartでも作れ る無味無臭アプリ 無垢の巨人か？奇行種 怖くて誰も メンテナンス出来な いマニアアプリ 16

業務フローに必要な要素 1. 登場人物、データの発生元 ① 利用者、組織、管理者、他システム 2. データ ① いつ、どんなデータが発生するか？ 3. データの変化、時系列、処理タイミング ① ② 登場人物がいつどんな処理をするか？ データがどんな変化をするか？ 登場人物(データの発生元)とデータ変化の全体像がわかる 17

業務フロー(例) 過去 時間の流れ 1.初期設定 2.日報作成 3.メール通知 未来 4.日報入力 5.サポート 人事 新規作成 設定 (アラート値、 部署ID) 日報作成 メール通知 メール通知 (手動) (手動) (エージェント) 健康日報 健康日報 日報作成 (エージェント) 登 場 人 物 ・ デ ー タ の 出 所 上司 サポート 健康日報 (フラグ書込) 一般 健康日報 健康日報 (値入力) 健康日報 (アラート表 示) 表でメッシュを作ってデータ元と推移を明確化 受けられ る サポート 18

業務フロー(プレゼン用) 1.初期設定 人 事 対象部署、閾値、 サポート方法 2.日報作成 3.メール通知 健康日報 健康日報 対象部署 一括作成 4.日報入力 5.サポート 健康日報 全社員の 状態確認 メール通知 健康日報 サポート 入力 上 司 部下のサポート Nomad Mobile対象範囲 健康日報 一 般 社 員 アラート 表示 健康状態入力 (GPS測位) 平均値計算 受けられ る サポート 19

なんで業務フローが大切か？ 1. 2. 3. 4. 実装を始める前に業務の全体像が把握できる 登場人物、データの出所がわかる データの変化タイミング(入力、出力)がわかる 標準化されていない業務、特権が必要な業務が見えるようになる 1. 必要であれば、業務を変えるか？特別な機能を実装するか？コストも踏まえて相談 5. 無駄な操作、IT後逆に不便になる業務を机上で確認、解消できる 1. 実装を始めてからだと、人生の時間が無駄遣いになる(あと桜は何回見られるのか？) 6. ココで作った業務の流れがUI実装時の指標になる 1. 誰が、いつ、どんな風に操作したいというシーンがないとUIは設計できない 2. 外注するにしても、利用シーンが明確でないと、最終的にしわ寄せが行くのは、現場部門、実ユーザー になる 7. AWSサービス構成図や機能ブロック図から業務フローを起こすのは無理 8. ソースから業務フローを起こして、非効率や矛盾が見つかってももう後戻り出来ない アジャイルでもテスト開発でも先に業務フローは書いておく 20

超簡易フォーマットサンプル 「データベースについて」に書くイメージ 背景・解決すべき課 題 目的・ビジョン 利用部門 利用シーン 利用部門以外の関係 部門 利用頻度 IN 登録データ OUT 内容 □ 手入力 □ NSF データベース名を書く □ CSV ファイルパスを書く □ REST(JSON) サーバーのURLを書く アプリ名 登録データ 内容 □ 一覧(画面) 項目の表示順 文字サイズ、色に変化をつけるなら画面 ショット □ チャート 最大値、最小値を表現したチャートサン プル □ CSV 項目の出力順 □ REST(JSON) サーバーのURLを書く 連携データIN マスターデータ 内容 □ NSF データベース名を書く □ RDB サーバー名、データベース名を書く □ REST(JSON) サーバーのURLを書く 21

参考：ネットワーク図① • 新規でサーバーを導入、サービスを構築する場合は絶対に必要 ネットワーク経路、構成機器、通信プロトコル、セキュリティ防御を表現する 22

参考：ネットワーク図② 本社(サーバールーム) SMTP ①背景でブロック に分ける Internet Windows FileServer 光電話GW Domino Server VPNルータ ONU ONU VPNルータ 広域 Ethernet 本社 L3SW 大阪支店 名古屋支店 UTM VPNルータ ②用途・意味づけ によって線の色、 太さを変える 光電話GW 光電話GW 23

参考：AWSサービス構成 • ネットワーク図のハードウェアがソフトウェアになったもの DNS、ログ管理、拡張方法(AutoScaling)なども表現しておく 24

本気の仕様書ひな形 No 項目 1 用語定義 2 現在の運用、開発の背景・目的 3 前提条件 4 業務フロー 5 想定データ件数 6 ネットワーク構成、サービス構成 7 パフォーマンス 8 可用性 9 運用コスト 10 開発環境・実行環境 個別 11 共通機能 機能 12 画面ごとの機能 13 定期実行機能 目的 全体像 共通項目 25

形骸化を防ぐためには？ 1. 目的の共有を定期的に行う(ビジョンの共有) 2. 上司のレビュー 自分よりもコーディングに 詳しいわけでもないし、他 のこともあるので無理 ① ただし、上司のタイプにもよるし、上司の能力が部下を上回ってるとは限らない ② 私の場合、全体構成を見て欲しかったが、上司は抜けポイント、誤字の指摘が多かった 3. チーム内レビュー ① SharePoint使ってれば、同時編集でコメント残せる(便利) ② 各自が他人のコメントを読まずに思いつきで書くと、レビュー依頼者が後で大変(やっぱり意思疎通、チームワーク) ③ 依頼者側にレビューして欲しい項目があればメールなどで書いておく(見積金額なのか？実現妥当性なのか？) 4. 定例会議で順番に発表 5. 仕様書を書く人と、実装する人を輪番制にする ① 他人に仕様書を読むことで、わかりやすい仕様書をマネするようになるかも ② 人によってはインセンティブをつけないと無理？ 6. ワークの配分を120％にしない ① 忙しすぎるとどこかを適当にする ② バグは怒られるので、チェックされにくい仕様書(機能仕様書、テスト仕様書)が適当になる 26

どっちにしても旗振り役は必要 部下に任せる場合、 権限委譲することをチームで合意 する(儒教文化) 能力があり ビジョンの高い上司 上司 顧客志向 ドキュメント大切マン 部下A 部下B 部下C 標準化(フォーマット)も大切だが、チーム運営、エンゲージメントの問題 27

まとめ 1. 要件定義書、機能仕様書を書くことで、完成後に「思ってたのと違う」を防ぐことができる 2. 業務フローを書くことで、イレギュラーパターン(特権、標準化されていない業務)がないか見極められる 3. 業務の抽象化力を高められる ① ITを使った効率化は、抽象度を上げる作業(業務レベルでも、コーディングレベルでも) 4. 仕様書を書くことで、概算見積や要件定義のタイミングで先に押さえておかないと行けないポイントがわか るようになる(想定できるパターンが増えて、事前確認できる) ① セキュリティ要件、パフォーマンス要件、データ容量 ② 技術的課題、機能的に使い物になるか？実装実験すべきポイント 5. 押さえるべきポイントを確認して初めて、最適なアーキテクチャ設計、ライブラリ選択ができる ① 10件/日と10万件/日のデータ量ではプラットフォームが別 6. 仕様書や業務フローを書くことで生まれる疑問や、アイディアがある ① コーディング中ではもう仕様は変えられない 7. 日本企業では発注者が受注側のIT技術者よりスキルが上回っていることは希 ① IT技術者はそれに甘えず、発注側を成長させるくらいのつもりで、何が問題か？を見極め、何が大切か？を一緒に考 えていく必要がある あきらめず、腐らず、仕様書を書きましょう！自分のために、誰かのために 28

結論 半歩ずつでも良いので 少しでも良い日本にしていきましょう！！！ 29

Q&A • 二度手間になりませんか？ • 要件定義の段階でフォームでモックを作り、仕様確定後ロジックを実装しています • 仕様書はWordで作るべき？Excelで作るべき？ • 見出し機能で複数階層を持つ章立てを作ることを考えるとWordが便利です • Visio持ってないけど、ネットワーク図は何で作る？ • PowerPoint?draw.io? 30