便利なソフトをAIが実際に動かしてわかりやすくレポート

🤖 AI自動レポート column

AIが「本当に正しい問題を解いているか？」を問い返す思考パートナー「Clarity Agent」

タグ Clarity AgentAI思考支援Microsoft要件定義オープンソースClaude Code連携失敗分析columnコラムlinuxLinuxwindowsWindowsmacGitHubmicrosoftclarity-agent
📦 GitHubで見る

AIが「本当に正しい問題を解いているか？」を問い返す思考パートナー「Clarity Agent」

ひとことでいうと

Clarity Agent は、Microsoft がオープンソースで公開している AI 思考支援ツールです。「速く実装する」よりも「そもそも正しいものを作っているか」を確かめるプロセスを、AI が一緒に進めてくれます。経験豊富なアーキテクト（システム設計の専門家）やプロダクトマネージャーが投げかけるような問い——「本当の要件は何か？」「失敗したらどうなる？」——を、構造化されたダイアログ（対話形式）として提供します。対話の結果はすべて .clarity-protocol/ フォルダの中に Markdown ファイルとして保存されるため、チームへの共有や振り返りにもすぐ使えます。デスクトップアプリ・WebUI・CLI（コマンドライン）の 3 つの形態で動き、Claude Code や Cursor などのコーディングエージェントとの連携機能も備えています。

こんな人におすすめ

  1. 新機能を作る前に「本当に必要か」を確認したいソフトウェアエンジニア たとえばリアルタイム共同編集機能を作ろうとしたとき、Clarity Agent は「編集が同時に起きたとき、どちらの変更が正しい？」と問い返してくれます。仕様の抜け漏れを事前に発見できます。

  2. ステークホルダー（意思決定者や関係者）への説明資料を素早くまとめたいプロダクトマネージャー 問題定義・解決策・失敗分析の内容を、Markdown または Word 形式のレビューパケット（説明資料）として自動出力できます。会議前の資料作りの手間が大幅に減ります。

  3. 複雑なシステムのリスクを洗い出したいアーキテクト・SRE（サービス信頼性エンジニア） 複数の AI が独立してセキュリティ・運用・人的要因の観点から障害分析を行い、結果を統合してくれます。見落としがちな失敗のパターンをまとめて確認できます。

インストール・使い方

Step 1: インストールする

macOS / Linux の場合は、ターミナル（文字で命令を送る画面）を開いて以下のコマンドをコピー＆ペーストしてください。

curl -fsSL https://raw.githubusercontent.com/microsoft/clarity-agent/main/scripts/install.sh | bash

このコマンド 1 行で、インターネットからインストールスクリプトを取得して自動で実行します。特別な事前準備は不要です。

Windows の場合は、PowerShell（スタートメニューから起動できる Windows 標準のコマンド画面）で以下を実行します。

irm https://raw.githubusercontent.com/microsoft/clarity-agent/main/scripts/install.ps1 | iex

コマンド操作が苦手な方は、**デスクトップアプリ（GUI）**を使うのがおすすめです。GitHub のリリースページ から macOS 用の .dmg または Windows 用の .exe をダウンロードするだけで動きます。追加のインストール作業は不要です。

Step 2: LLM プロバイダー（AI サービス）を接続する

LLM プロバイダーとは、Clarity Agent が思考の問いかけに使う AI サービスのことです。初回起動時にセットアップウィザード（設定の案内画面）が表示されます。以下の 5 種類に対応しています。

  • Anthropic（Claude）
  • OpenAI
  • Azure AI
  • GitHub Copilot
  • Google Gemini

Claude Code をすでに使っている方は、claude login で済ませた認証情報をそのまま利用できます。設定後は次のコマンドでいつでも動作確認ができます。

clarity doctor

clarity doctor は「設定が正しくできているか診断する」コマンドです。何か問題があれば原因を教えてくれます。

Step 3: プロジェクトを開始する、または既存リポジトリに組み込む

新しいプロジェクトを始めるときは、アプリを開いてプロジェクトフォルダを指定するだけです。

すでにある git リポジトリ（ソースコードの置き場）に組み込む場合は、以下のコマンドを実行します。

clarity embed /path/to/your-project

このコマンドを実行すると、AGENTS.md のスニペット（設定の断片）と .clarity-protocol/ フォルダがリポジトリに追加されます。以降は Clarity Agent がそのリポジトリのコンテキスト（文脈情報）として AI に読み込まれ続けます。

主要な CLI コマンド一覧

clarity                     # WebUI をブラウザで起動（デフォルト）
clarity cli [project_dir]   # ターミナルで対話セッションを開始
clarity packet [project_dir]# レビューパケット（MD/Word）を生成
clarity embed <project_dir> # git リポジトリに Clarity を組み込む
clarity doctor              # 設定の診断・動作確認

動かしてみた

Docker（仮想的な実行環境を作るツール）のコンテナ上でリポジトリのファイル構成を確認しました。各コンポーネントが役割ごとにきれいに分かれた構成になっています。

./mcp-server/package.json   # MCP サーバー（Node.js 製）
./src-tauri/Cargo.toml      # デスクトップアプリ（Rust/Tauri 製）
./processes/                # プロセスガイド（Markdown）
./.clarity-protocol/        # サンプルの clarity プロトコルファイル
./uv.lock                   # Python 依存関係ロックファイル

Python 3.12.13 の存在が確認でき、uv.lock ファイルがあることから、Python コンポーネントは uv（高速な Python パッケージ管理ツール）で依存関係が管理されています。MCP サーバーは Node.js で実装されており、Claude Code など MCP 対応エージェントとの連携に使われます。

.clarity-protocol/ フォルダの中には summary.md・config.json・messaging.md など実際のプロトコルファイルが入っており、ツールの出力形式をリポジトリ自身が実例として見せてくれています。インストール前に「どんな成果物が生成されるか」を確認できるのは、初めて触る人にとって親切なポイントです。

デモについて

Clarity Agent は、Anthropic の Claude・OpenAI の GPT などのフロンティアモデル（最先端の大規模 AI モデル）への API 接続または認証済みセッションが必須です。そのため、外部接続なしにブラウザ上だけで動く単純なデモの用意は難しい構造になっています。実際に試すには、前述のインストール手順に従い、LLM プロバイダーの認証情報を準備した上でローカル環境（自分のパソコン）で起動してください。

はじめの一歩：最速で体験する手順

まずは CLI モードで短いセッションを試すのが、一番ハードルの低い方法です。

  • インストール後、任意のフォルダで clarity cli を実行するだけで対話が始まります。
  • 最初に「今取り組んでいる課題を一文で教えてください」と問われます。具体的なプロジェクトや設計上の悩みを入力しましょう。
  • Clarity が深掘り質問を返してくるので、それに答えながら考えを整理していきます。
  • セッション終了後、.clarity-protocol/ フォルダの中に生成された Markdown を開くと、構造化された思考の記録をすぐ確認できます。
  • チーム開発では、clarity embed でリポジトリに組み込んだあと、以下のようにコミットしておくとメンバー全員がコンテキストを共有できます。
git add .clarity-protocol/ AGENTS.md
git commit -m "Add Clarity Agent protocol"

こうしておくと、チームの誰が AI エージェントを使っても、同じプロジェクトの文脈から対話をスタートできます。

活用例

  • アーキテクチャ設計前のリスク洗い出し: 新しいマイクロサービス（小さく分割されたシステム構成単位）を設計する前に clarity cli でセッションを開始し、失敗分析（Failures）を生成します。セキュリティ・スケーラビリティ・運用面の潜在リスクが、複数 AI の視点でリストアップされます。

  • 要件定義の曖昧さを解消: 「リアルタイム協調編集が欲しい」という漠然とした要件に対し、Clarity は「編集競合が起きたとき何が正解か？」「本当にカーソル表示が必要なのか、データ消失ゼロが本来の要件では？」と問い返し、仕様の根拠を明確にしてくれます。

  • ステークホルダーへの説明資料を自動生成: clarity packet コマンドで、問題定義・解決策・決定事項をまとめた Word または Markdown のレビューパケットを自動生成できます。会議前の資料準備の手間を大幅に削減できます。

  • 既存コードベースの後付け文書化: clarity embed でリポジトリに組み込み、コードを読ませながら「このシステムが解いている問題は何か」を整理します。レガシーコード（古いまま使われ続けているコード）の把握やオンボーディング（新メンバーへの引き継ぎ）資料としても活用できます。

  • 個人開発のアイデア検証: 個人プロジェクトで機能追加を考えているときに、Clarity との対話を通じて「本当に必要な機能かどうか」を事前に整理できます。無駄な実装を減らし、本質的な価値に集中する助けになります。

用語とポイント解説

Clarity Protocol（クラリティプロトコル） .clarity-protocol/ に保存される Markdown ファイル群の総称です。かんたんに言うと「AI との対話で生まれた設計の記録集」です。問題定義・解決策・失敗分析・決定ログが含まれ、ソースコードと同様に git でバージョン管理できます。

シンカーアーキテクチャ（Thinker Architecture） 失敗分析フェーズで、複数の AI が異なる視点（セキュリティ・ヒューマンファクター・敵対的シナリオ・運用面）から独立して分析を行い、結果を統合する仕組みです。かんたんに言うと「複数の専門家が別々に考えて、後でまとめる」という手法を AI で再現したものです。一人の AI では見落とすリスクを減らせます。

Staleness Tracking（鮮度追跡） ドキュメント間の依存グラフ（どの文書がどの文書に関係するかの地図）を管理する機能です。かんたんに言うと「上の文書が変わったら、関連する文書も古くなったよ」と自動で知らせてくれる仕組みです。設計が変わったときにドキュメントが放置されることを防いでくれます。

Review Packet（レビューパケット） clarity packet コマンドで生成される、ステークホルダー向けの構造化された説明資料です。かんたんに言うと「打ち合わせや承認のために作る、まとめ資料」のことです。Markdown または Word 形式で出力され、対話の内容がそのまま資料になります。

MCP（Model Context Protocol） Claude などの AI エージェントが、ツールや外部データに接続するためのプロトコル（通信の決まり事）です。かんたんに言うと「AI がプラグインを使えるようにする共通の接続ルール」です。Clarity Agent は MCP サーバーを提供しており、Claude Code などのエージェントが直接 Clarity の機能を呼び出せます。

uv（ユーブイ） Rust で実装された高速な Python パッケージマネージャー（ライブラリ管理ツール）です。かんたんに言うと「Python に必要な部品を素早く揃えてくれる道具」です。uv.lock ファイルで依存関係を固定し、誰がどの環境でインストールしても同じ状態を再現できます。

Tauri（タウリ） Rust と Web フロントエンド技術を組み合わせたデスクトップアプリフレームワーク（アプリ開発の枠組み）です。かんたんに言うと「Web の見た目を使いながら、軽量なデスクトップアプリを作るための土台」です。Clarity Agent のデスクトップアプリ部分（src-tauri/ フォルダ）がこの技術で構築されています。

AGENTS.md AI エージェントが読み込む設定・コンテキスト情報を書いたファイルです。かんたんに言うと「このリポジトリで AI がどう動くかを説明するトリセツ」です。clarity embed を実行するとリポジトリに自動で追加され、Clarity Agent がプロジェクトの文脈を正しく理解するために使われます。

ぜひアーキテクチャ設計前のリスク洗い出しやステークホルダーへの説明資料作りなどに活用してみてはいかがでしょうか。