目次
要件定義書がExcelの巨大な1ファイルになっていて、誰かが開きっぱなしにすると編集できない。セルの結合で行をコピーすると番号がずれる。「どの要件がどの要件から派生したか」を追いたいのに、リンク列に貼った参照はいつの間にか古い番号を指している。差分を見ようとしても、Excelの版管理は「要件定義_v3_最終_本当に最終.xlsx」になりがちです。
このあたりに心当たりがあるなら、テキストベースの要求管理ツールである StrictDoc が選択肢になります。要件をプレーンテキスト（.sdocファイル）で書くので、コードと同じように Git で履歴を残せて、git diff でどの要件のどの文言が変わったかが行単位で見えます。レビューもプルリクエストに乗せられる。台帳を1ファイルで奪い合う構図がなくなります。
この記事では、インストールから要件1件の書き方、要件同士のトレーサビリティ、HTML/PDF出力、Web UIでの編集までを手を動かせる形でたどります。
StrictDocをインストールして最短で動かす
StrictDoc は Python 製なので pip で入ります。
pip install strictdoc
入ったら、空のプロジェクトを作ります。strictdoc new にプロジェクト名を渡すと、雛形の .sdoc ファイルが入ったディレクトリができます。
strictdoc new hello_world
cd hello_world
中身を見て手応えを掴むのが早いので、いったんそのままHTMLに書き出してみます。出力先のディレクトリ名を指定しなければ output/ に書かれます。
strictdoc export .
output/html/ 以下に生成されたHTMLをブラウザで開くと、雛形の要件がドキュメントとして表示されます。ここまでで「テキストを書く → HTMLになる」という往復が一周します。
要件を1件、自分で書いてみる
.sdoc ファイルの最小構成はこれだけです。[DOCUMENT] がドキュメントの根で、TITLE が必須。その下に [REQUIREMENT] を並べていきます。
[DOCUMENT]
TITLE: ログイン機能の要件
[REQUIREMENT]
UID: REQ-001
TITLE: パスワード認証
STATEMENT: >>>
システムは、登録済みのメールアドレスとパスワードの組み合わせでユーザーを認証できること。
<<<
フィールドの意味はそのまま読めると思いますが、3つだけ。
UIDは要件の一意な識別子です。後でリンクを張るときの宛先になるので、REQ-001のように自分で決めた採番ルールで振っておきます。TITLEは要件の見出し。STATEMENTが要件の本文です。>>>と<<<で囲むと複数行を書けます。1行で済むならSTATEMENT: 〜と直接書いても構いません。
Excel台帳でいう「ID列・要件名列・要件内容列」がそのままフィールドになった、と捉えると移行のイメージが付きます。1行が1要件ではなく、1ブロックが1要件になります。
要件をリンクして要求管理のトレーサビリティを取る
要求管理でExcelが一番つらくなるのが、ここです。「上位要件 REQ-001 から派生した詳細要件はどれか」を追跡したい。StrictDoc では要件側に RELATIONS を書いて、親要件の UID を指すだけです。
[REQUIREMENT]
UID: REQ-001
TITLE: パスワード認証
STATEMENT: >>>
システムは、登録済みのメールアドレスとパスワードの組み合わせでユーザーを認証できること。
<<<
[REQUIREMENT]
UID: REQ-002
TITLE: ログイン失敗時のロック
STATEMENT: >>>
システムは、パスワード認証に5回連続で失敗したアカウントを一時的にロックすること。
<<<
RELATIONS:
- TYPE: Parent
VALUE: REQ-001
REQ-002 の RELATIONS で TYPE: Parent / VALUE: REQ-001 と書くと、「REQ-002 は REQ-001 の子要件」という親子関係になります。HTMLに書き出すと、各要件のページに親・子へのリンクが張られ、要件をクリックして辿れるトレーサビリティのビューが生成されます。
ここがテキストベースの効くところで、REQ-001 という宛先は文字列なので、grep REQ-001 すればどの要件から参照されているかが一発で出ます。Excelのリンク列のように、行を挿入したら参照がずれる、という事故が起きません。
HTML / PDF に書き出す、Web UIで編集する
成果物として配る形式は strictdoc export の --formats で選びます。HTMLとPDFを両方出すなら、こうです。
strictdoc export . --formats=html,pdf
何も指定しなければHTMLがデフォルトで出ます。HTMLが StrictDoc のネイティブな出力形式で、トレーサビリティのリンクが効くのもHTMLです。配布用にきれいな1枚物が欲しいときはPDFを足す、という使い分けになります。
--formats には他に rst reqif json excel も指定できます。既存のExcel台帳と並走させたい時期は excel で書き出して関係者に渡す、といった逃げ道があるのは移行期に助かります。
テキストを直に書くのに抵抗がある人や、要件を眺めながら直したいときは、ローカルのWeb UIが使えます。
strictdoc server .
これで http://127.0.0.1:5111 にローカルサーバが立ち上がり、ブラウザから要件の閲覧・編集ができます。UIで直した内容はそのまま .sdoc ファイルに書き戻されるので、編集はUI・履歴管理はGit、と役割を分けられます。チームの中に「テキストはちょっと…」という人がいても、その人だけUIを使い、ファイルとしてはテキストで揃う、という運用が成り立ちます。
Markdown から始める使い方もあるので入口は低い
「いきなり独自の .sdoc 記法を覚えるのか」と身構えるかもしれませんが、StrictDoc は入力フォーマットとして Markdown（.md）にも対応しています。普段から README や設計メモを Markdown で書いているなら、見出しと本文をそのまま要件ドキュメントとして読み込ませられます（こちらは実験的サポートという位置づけです）。
なので導入のハードルはかなり低くて、まずは手元の Markdown を1本食わせて strictdoc export でHTMLにしてみる、くらいから始められます。UID や RELATIONS を使った本格的なトレーサビリティが欲しくなったところで .sdoc に書き換えていけば、最初から全部を覚える必要はありません。
自分の場合は、新規プロジェクトの要件はトレーサビリティが欲しいので最初から .sdoc で書き、既存のMarkdownメモが大量にあるリポジトリでは、まずそのまま食わせて見た目を確認してから移行を判断しています。Excelの台帳を1ファイルで開きっぱなしにして編集権を取り合う、あの状態から抜けたい人は、pip install strictdoc して strictdoc new するところまでを今日やってみると、感触が掴めると思います。