Clairvoyance

Clairvoyance

AI エージェントは動作するコードを書けますが、求められない限り、効果的な設計について立ち止まって検討することはありません。Clairvoyance は、John Ousterhout の A Philosophy of Software Design に着想を得たスキル集です。各スキルは、ソフトウェア設計に関する超感覚的な視点をエージェントに与え、実装やレビュー中に障害を予見するための具体的なテストを提供します。

仕組み

スキルは自動的に有効になり、次のような質問をエージェントに促します。

• このインターフェースは本当の複雑さを隠しているのか、それとも単に処理を受け渡しているだけなのか？
• 別のファイルにある別のメソッドを読まなくても、このメソッドを理解できるか？
• このモジュール自身で処理できる作業を、エラー処理によって呼び出し元に押し付けていないか？

スキルを直接呼び出すこともできます。/clairvoyance:red-flags で設計上の問題点をスキャンし、/clairvoyance:deep-modules でインターフェースの奥行きを確認し、/clairvoyance:design-it-twice で確定する前に代替案を比較できます。（skills.sh など、プラグインの名前空間なしでスキルをインストールするプラットフォームでは、clairvoyance: プレフィックスを省略してください。）

インストール

エージェントに Clairvoyance を追加しましょう：Claude Code、skills.sh、Codex、Cursor、OpenCode、Antigravity、Factory Droid、GitHub Copilot CLI、Kimi Code、Pi。

注： インストール方法はプラットフォームによって異なります。複数のプラットフォームを利用する場合は、それぞれに Clairvoyance をインストールしてください。

Claude Code

/plugin marketplace add codybrom/clairvoyance
/plugin install clairvoyance@clairvoyance-plugins

skills.sh

npx skills add codybrom/clairvoyance --skill '*'

Codex

Codex CLI ≥ 0.142.0 が必要です（codex --version）。Codex App と CLI は同じ設定を共有するため、これにより Clairvoyance が App の Plugins パネルにも表示されます。

codex plugin marketplace add codybrom/clairvoyance
codex plugin add clairvoyance@clairvoyance

古いバージョンの Codex では、手動でシンボリックリンクを作成して 16 個のスキルのみを利用できます。この代替手順と詳しいトラブルシューティングについては、.codex/INSTALL.md を参照してください。

Cursor

Cursor には、未掲載のプラグインを「GitHub URL からインストール」するワンライナーの手順がまだありません。そのため、リポジトリを Cursor のローカルプラグインフォルダーにクローン（またはシンボリックリンクを作成）してから、再起動してください。

git clone https://github.com/codybrom/clairvoyance.git ~/.cursor/plugins/local/clairvoyance

サイドバーの Customize パネルを確認し、Clairvoyance と 16 個のスキルが一覧に表示されていることを確認してください。

OpenCode

opencode.json（グローバルまたはプロジェクトレベル）の plugin 配列に Clairvoyance を追加します。

{
  "plugin": ["clairvoyance@git+https://github.com/codybrom/clairvoyance.git"]
}

OpenCode を再起動してください。シンボリックリンクやスキルパスの手動設定は不要です。バージョンの固定、トラブルシューティング、古いシンボリックリンクベースのインストールからの移行については、.opencode/INSTALL.md を参照してください。

Antigravity

agy plugin install https://github.com/codybrom/clairvoyance

Factory Droid

Droid は Claude Code のプラグイン形式を自動的に変換するため、Clairvoyance 専用のファイルは必要ありません。

droid plugin marketplace add https://github.com/codybrom/clairvoyance
droid plugin install clairvoyance@clairvoyance-plugins

GitHub Copilot CLI

copilot plugin marketplace add codybrom/clairvoyance
copilot plugin install clairvoyance@clairvoyance-plugins

Kimi Code

Kimi Code のプラグインマネージャー（/plugins）で Custom を選ぶか、次のコマンドを直接実行してください。

/plugins install https://github.com/codybrom/clairvoyance

公式に審査されたソースではないため、Kimi Code でサードパーティの信頼確認プロンプトが表示されます。続行するには確認してください。

Pi

pi install git:github.com/codybrom/clairvoyance

Pi は追加設定なしで skills/ ディレクトリを自動検出します。

llms.txt

LLM エージェント向けの機械可読なスキルインデックスです。

• clairvoyance.fyi/llms.txt — 説明付きの目次
• clairvoyance.fyi/llms-full.txt — すべてのスキルの全内容

MCP サーバー

エージェントにプラグインやスキルをインストールできなくても、MCP サーバーに接続できる場合は、Clairvoyance の読み取り専用 MCP サーバー https://clairvoyance.fyi/mcp を使用してください（Streamable HTTP、サインイン不要）。各スキルは、プラグイン内と同じ名前と説明を持つツールです。また、MCP プロンプトに対応しているクライアントでは、各スキルをスラッシュコマンドとしても利用できます。リクエストで指定するのはスキル名だけなので、サーバーにコード、ファイルパス、プロンプトが送信されることはありません。

• VS Code: code --add-mcp '{"name":"clairvoyance","type":"http","url":"https://clairvoyance.fyi/mcp"}'
• Cursor: ~/.cursor/mcp.json の "mcpServers" の下に "clairvoyance": { "url": "https://clairvoyance.fyi/mcp" } を追加します
• Claude Code: claude mcp add --transport http clairvoyance https://clairvoyance.fyi/mcp
• Codex: codex mcp add clairvoyance --url https://clairvoyance.fyi/mcp
• その他: https://clairvoyance.fyi/mcp をリモート（HTTP）MCP サーバーとして追加します。

公式 MCP Registry には fyi.clairvoyance/mcp として掲載されています。VS Code と Cursor のワンクリックボタンは clairvoyance.fyi/install にあります。エージェントがプラグインやスキルに対応している場合は、そちらをインストールしてください。プラグインは各スキルのツール制限も適用し、design-it-twice サブエージェント自体を実行します。

内容

構造とモジュール

スキル	対象
deep-modules	モジュールの深さ、浅いモジュール、クラス過多、単なる中継メソッド、インターフェースと実装
module-boundaries	統合と分割、密接に結合したメソッド、メソッドの分割、依存関係の最小化
information-hiding	情報漏えい、時間的な分解、部分的な隠蔽、見せかけのカプセル化
pull-complexity-down	呼び出し元の負担、設定パラメーター、中心的な非対称性

抽象化と汎用性

スキル	対象
abstraction-quality	真の抽象化と見せかけの抽象化、レイヤーの境界、デコレーター
general-vs-special	インターフェースの汎用性、汎用性と特殊性の混在、エッジケースの排除
error-design	エラーを存在しないものにする、例外のマスキング、集約、とにかくクラッシュさせる

明瞭さとコミュニケーション

スキル	対象
naming-obviousness	分離テスト、スコープと長さの原則、一貫性、余計な語の回避
comments-docs	コメントの種類、コメント先行のワークフロー、モジュール間のドキュメント

プロセスと進化

スキル	対象
strategic-mindset	戦略的な対応と戦術的な対応、投資の原則、戦術の竜巻
design-it-twice	代替案の生成、基準に基づく比較、統合
code-evolution	「このように設計した」という基準、繰り返し、技術的負債
complexity-recognition	変更の波及、認知負荷、未知の未知

診断

スキル	対象
red-flags	構造、境界、ドキュメント、命名、プロセスを対象とする設計上の問題点の確認
design-review	複雑さのトリアージから、構造、インターフェース、表層の確認までを行う体系的なレビューフロー
diagnose	決定木を使い、漠然とした症状や不満を最も関連性の高いスキルへ振り分ける

帰属表示

これらのスキルは、スタンフォード大学のコンピューターサイエンス教授である John Ousterhoutの教えと、著書 A Philosophy of Software Designを一部参考にしています。本プロジェクトは、John Ousterhout、スタンフォード大学、または A Philosophy of Software Design の出版社と提携、承認、後援関係にはありません。

これらのスキルが役に立った場合は、ぜひ本書を購入して読んでください。 このリポジトリのスキルは、決して本書を読むことの代わりにはなりません。本書はこれらの考え方を決定的に解説したものであり、開発者なら誰でも楽しく読めます。Amazonで購入できます（アフィリエイトリンクではありません）。ドイツ語版（O'Reilly、2021年）および中国語版（Posts and Telecommunications Press、2024年）もあります。

本プロジェクトのスキルとコードは、プロジェクトのコントリビューターが独自に作成したオリジナル作品です。論評、批評、教育を目的として、出典を明記したうえで、本書からの短い引用を使用する場合があります。商標および著作権は、それぞれの所有者に帰属します。

コントリビューション

インスピレーションの源となった資料にとどまらないコントリビューションも歓迎します。ただし、ソフトウェア設計について戦略的に考えるという中核的な理念を強化するものである必要があります。

コントリビューションの手順：

1. リポジトリをフォークします
2. ブランチを作成します
3. スキルの作成とテストには、Superpowersのwriting-skillsスキルに従ってください
4. skills/<skill-name>/SKILL.mdにスキルを追加し、必要に応じてreferences/ファイルも追加します
5. 変更をコミットしてPRを送信します

更新

• Claude Code： /plugin update clairvoyance
• skills.sh： npx skills update codybrom/clairvoyance
• Codex： codex plugin marketplace upgrade clairvoyance && codex plugin add clairvoyance@clairvoyance
• Cursor： cd ~/.cursor/plugins/local/clairvoyance && git pullを実行し、その後再起動します
• OpenCode： タグを固定している場合を除き、再起動しても自動更新されません。詳細は.opencode/INSTALL.mdをご覧ください
• Antigravity： agy plugin install https://github.com/codybrom/clairvoyanceを再実行します
• Factory Droid： droid plugin marketplace update clairvoyance-plugins && droid plugin update clairvoyance@clairvoyance-plugins
• GitHub Copilot CLI： copilot plugin update clairvoyance
• Kimi Code： Customタブからインストールコマンドを再実行します
• Pi： pi update --extensionsを実行します（参照先を固定している場合は、新しい参照先を指定してインストールを再実行します）
• MCP サーバー： 常に最新のスキルを提供するため、更新は不要です。
• llms.txt： clairvoyance.fyi/llms-full.txtで常に最新の状態を確認できます。

各バージョンの変更内容については、CHANGELOG.mdまたはGitHubのリリースをご覧ください。

ライセンス

MIT License © 2026 Cody Bromley