SARA: Markdown要件を知識グラフで管理するCLI

「要件定義書はどこ？」「この設計、どの要件から来てるの？」「あれ、このリンク切れてる…」

チームが大きくなると、要件や設計ドキュメントが散らばり始めます。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分で試す（最小構成）

まずはローカルで、小さな要件セットを作って動かしてみます。

前提:

Rustが入っていること（未導入ならrustup ）

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の呪縛」から解放したい方は、ぜひ試してみてください。

Fragments of verbose memory

冗長な記憶の断片 - Web技術のメモをほぼ毎日更新