「要件定義書はどこ？」「この設計、どの要件から来てるの？」「あれ、このリンク切れてる…」
チームが大きくなると、要件や設計ドキュメントが散らばり始めます。Confluence
、Notion
、Excel、Wiki、Markdown…ツールはバラバラ、リンクは切れ、誰も全体像を把握できません。
SARA
（Solution Architecture Requirement for Alignment）は、この問題を「Markdown + Git
+ 知識グラフ（ドキュメント同士の関係をグラフ構造で表したもの）」で解決するCLIツールです。要件をMarkdownで書き、YAMLフロントマター（Markdown先頭のメタ情報）で関係を定義するだけで、トレーサビリティ（要件から実装までを辿れる性質）を自動で検証できます。
SARAとは？
SARAは、要件・設計ドキュメントを知識グラフとして管理するRust
製のCLI（コマンドラインで操作するツール）です。Apache 2.0ライセンスで利用できます。
主な特徴:
- Markdown-first: プレーンテキストで要件を管理（ベンダーロックイン＝特定ツールに縛られにくい）
- 複数リポジトリ対応: チーム横断でドキュメントを集約
- トレーサビリティ検証: リンク切れ・循環依存・孤児アイテムを自動検出
- Git統合: ブランチ間の差分比較、PRでの自動検証
- カバレッジレポート: 要件の実装状況を可視化
何ができるのか
SARAが提供する主要コマンド:
| コマンド | 用途 |
|---|
sara init <FILE> | Markdownファイルに要件メタデータを追加 |
sara parse | ドキュメントを解析して知識グラフを構築 |
sara validate | リンク切れ・循環依存・孤児を検出 |
sara query <ID> | 要件の上流/下流を追跡 |
sara report coverage | 実装カバレッジを出力 |
sara report matrix | トレーサビリティマトリクスを生成 |
sara diff <REF1> <REF2> | Git参照間で要件の変更を比較 |
実例: 要件のトレーサビリティを追跡
1
2
3
4
5
6
7
8
9
| # ユーザーログインシナリオから派生した要件を全て表示
sara query SCEN-001 --downstream
# 出力例:
# SCEN-001: User Login Scenario
# ├── SYSREQ-001: Response Time Requirement
# │ └── SYSARCH-001: Authentication Architecture
# │ └── SWREQ-001: JWT Token Generation
# │ └── SWDD-001: Auth Service Implementation
|
実例: リンク切れを検出
1
2
3
4
5
6
| sara validate
# 出力例:
# ❌ Broken reference: SYSREQ-999 (referenced by SCEN-001)
# ⚠️ Orphan item: SWDD-042 (no upstream parent)
# ❌ Circular dependency: SYSREQ-010 → SYSREQ-020 → SYSREQ-010
|
Markdownで要件を書く
SARAの要件ドキュメントは、YAMLフロントマター付きのMarkdownファイルです。ドキュメント同士の関係（派生・満たす・依存など）をIDでつなぎます。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
| ---
id: "SYSREQ-001"
type: system_requirement
name: "Authentication Response Time"
derives_from:
- "SCEN-001"
- "SCEN-002"
is_satisfied_by:
- "SYSARCH-001"
depends_on:
- "SYSREQ-002"
---
## 要件
ユーザー認証のレスポンスタイムは500ms以内であること。
## 根拠
SCEN-001で定義されたユーザー体験を満たすため。
|
要件の階層構造
SARAは9種類のドキュメントタイプを認識します:
graph TD
SOL[Solution
顧客向けソリューション]
UC[Use Case
顧客ニーズ]
SCEN[Scenario
システム振る舞い]
SYSREQ[System Requirement
システム要件]
SYSARCH[System Architecture
プラットフォーム実装]
HWREQ[Hardware Requirement
HW要件]
SWREQ[Software Requirement
SW要件]
HWDD[HW Detailed Design
HW実装]
SWDD[SW Detailed Design
SW実装]
SOL --> UC
UC --> SCEN
SCEN --> SYSREQ
SYSREQ --> SYSARCH
SYSARCH --> HWREQ
SYSARCH --> SWREQ
HWREQ --> HWDD
SWREQ --> SWDD
リレーションシップの種類
| リレーション | 方向 | 用途 |
|---|
refines / is_refined_by | 上流 / 下流 | Solution ↔ Use Case ↔ Scenario |
derives_from / derives | 上流 / 下流 | Scenario ↔ System Requirement |
satisfies / is_satisfied_by | 上流 / 下流 | Requirement ↔ Architecture/Design |
depends_on / is_required_by | 同レベル | 同じタイプの要件間の依存関係 |
リレーションは片方向だけ定義すればOKです。SARAが自動的に逆方向のリンクを推論します。
実務での使い方
0. 10分で試す（最小構成）
まずはローカルで、小さな要件セットを作って動かしてみます。
前提:
1. SARAをインストール
1
2
3
4
| git clone https://github.com/cledouarec/sara.git
cd sara
cargo install --path sara-cli
sara --version
|
2. サンプル要件を作って検証
別ディレクトリで、要件Markdownを作ります。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
| mkdir -p demo-requirements/docs/sara
cd demo-requirements
cat > sara.toml <<'EOF'
[repositories]
paths = [
"./docs/sara"
]
[validation]
strict_orphans = true
EOF
cat > docs/sara/SOL-001.md <<'EOF'
---
id: "SOL-001"
type: solution
name: "Customer Portal"
is_refined_by:
- "UC-001"
---
# Customer Portal
EOF
cat > docs/sara/UC-001.md <<'EOF'
---
id: "UC-001"
type: use_case
name: "User Authentication"
refines:
- "SOL-001"
is_refined_by:
- "SCEN-001"
---
# User Authentication
EOF
cat > docs/sara/SCEN-001.md <<'EOF'
---
id: "SCEN-001"
type: scenario
name: "User Login"
refines:
- "UC-001"
derives:
- "SYSREQ-001"
---
# User Login
EOF
cat > docs/sara/SYSREQ-001.md <<'EOF'
---
id: "SYSREQ-001"
type: system_requirement
name: "Authentication Response Time"
derives_from:
- "SCEN-001"
is_satisfied_by:
- "SYSARCH-001"
---
# Authentication Response Time
EOF
cat > docs/sara/SYSARCH-001.md <<'EOF'
---
id: "SYSARCH-001"
type: system_architecture
name: "Authentication Architecture"
satisfies:
- "SYSREQ-001"
---
# Authentication Architecture
EOF
sara validate
sara query SYSREQ-001 --upstream
sara query SYSREQ-001 --downstream
|
この時点で、リンク切れや循環依存があると sara validate が落ちます。PR（Pull Request）でこれが動くと、ドキュメントの「壊れ」を早めに潰せます。
1. プロジェクト初期化
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| # sara.toml を作成
cat > sara.toml <<EOF
[repositories]
paths = [
"./docs/requirements",
"../shared-specs"
]
[validation]
strict_orphans = false
[output]
colors = true
emojis = true
EOF
|
2. 要件ドキュメント作成
1
2
3
4
5
6
7
| # 新しい要件ファイルを作成
sara init docs/requirements/auth-response-time.md
# 対話的にメタデータを入力
# ID: SYSREQ-001
# Type: system_requirement
# Name: Authentication Response Time
|
生成されたファイル:
1
2
3
4
5
6
7
8
9
| ---
id: "SYSREQ-001"
type: system_requirement
name: "Authentication Response Time"
---
# Authentication Response Time
[ここに要件の詳細を記述]
|
3. CI/CDでの自動検証
CI/CD（継続的インテグレーション/継続的デリバリー）で、要件の整合性チェックを自動化できます。
GitHub Actions
での例（PRで sara validate を必須化）:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
| name: Validate Requirements
on:
pull_request:
paths:
- 'docs/requirements/**'
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- uses: Swatinem/rust-cache@v2
- name: Install SARA
run: |
cargo install --git https://github.com/cledouarec/sara --tag sara-cli-v0.4.0 --locked sara-cli
- name: Validate knowledge graph
run: |
sara validate --strict
- name: Generate coverage report
run: |
sara report coverage --format json > coverage.json
- name: Upload report
uses: actions/upload-artifact@v4
with:
name: coverage-report
path: coverage.json
|
4. リリース前の差分確認
1
2
3
4
5
6
7
8
9
10
| # main ブランチと現在のブランチで要件の変更を比較
sara diff main HEAD
# 出力例:
# Added:
# + SWREQ-042: OAuth2 Token Refresh
# Modified:
# ~ SYSREQ-001: Response time changed (500ms → 300ms)
# Removed:
# - HWREQ-999: Deprecated sensor requirement
|
どんなチームに刺さるか
SARAが特に有効なケース:
✅ 向いているチーム
- 複数リポジトリで開発: マイクロサービス、モノレポ、チーム横断プロジェクト
- Git運用が成熟: PRレビュー、ブランチ戦略、CI/CDが整備されている
- トレーサビリティが必須: 医療機器、自動車、航空宇宙、金融など規制産業
- ドキュメントがMarkdown: 既にREADME、ADR（Architecture Decision Record）、RFC（Request for Comments）をMarkdownで管理している
❌ 向いていないケース
- 非技術者が主体: Markdownに慣れていないステークホルダーが多い
- Gitを使わない: バージョン管理がない、またはGit以外のVCS（バージョン管理システム）
- 要件が少ない: 小規模プロジェクト（10件未満の要件）
- リアルタイム共同編集が必要: Notion、Confluenceのようなリッチエディタが必須
Mermaidとの組み合わせ
SARAの知識グラフは、Mermaid
（テキストから図を生成する記法）で可視化できます。
現時点では、SARAの出力をそのままMermaidに落とす機能は見当たりませんでした（少なくともREADME上は）。ただ、sara query の結果を見ながら、最低限の関係図をMermaidで残すのは現実的です。
graph LR
SCEN001[SCEN-001: User Login]
SYSREQ001[SYSREQ-001: Response Time]
SYSARCH001[SYSARCH-001: Auth Architecture]
SCEN001 -->|derives| SYSREQ001
SYSREQ001 -->|is_satisfied_by| SYSARCH001
まとめ
SARAは「要件をMarkdownで書く」という選択肢を、実用レベルに引き上げるツールです。
SARAを試すべき理由:
- ベンダーロックインなし: プレーンテキストなので、いつでも他ツールに移行可能
- Git統合: 既存のワークフロー（PR、レビュー、CI/CD）にそのまま乗る
- 自動検証: 人間が見落とすリンク切れや循環依存を機械的に検出
- チーム横断: 複数リポジトリの要件を一元管理
次のアクション:
- SARAのリポジトリをクローン
cargo install --path sara-cli でインストール- サンプルプロジェクト（
examples/smart-home）を試す - 自分のプロジェクトで
sara init を実行
要件管理を「Excelの呪縛」から解放したい方は、ぜひ試してみてください。
参考リンク