Viserysとは？
Viserysは、AIコーディングエージェント向けの、自己完結型のエンジニアリングワークフロー集です。エージェントがリクエストごとにプロセスを考案する代わりに、再利用可能なMarkdownの指示、レビュアー人格、共有リファレンス、ライフサイクルコマンド、評価用フィクスチャ、検証スクリプトを提供します。
このプロジェクトでは、ソフトウェア開発を次の6段階のライフサイクルに整理しています。
DEFINE -> PLAN -> BUILD -> VERIFY -> REVIEW -> SHIP各ワークフローはSKILL.mdファイルに記述され、手順、終了条件、合理化を防ぐための指針が含まれています。スキルはプレーンなMarkdownで記述されているため、スキル対応のコーディングエージェントで読み込めるほか、単独の指示として直接読むこともできます。
主な機能
- ライフサイクル全体をカバー: 要件定義、計画、実装、テスト、レビュー、リリース準備のワークフローを網羅します。
- 26個のパッケージ済みスキル:
skills/ディレクトリに、再利用可能なエンジニアリングワークフローが含まれています。 - レビュアー人格: 専門エージェントがコード品質、テスト、セキュリティ、Webパフォーマンスを評価します。
- OpenCode連携: プライマリーモードのViserysエージェントが含まれており、グローバル設定なしでスキルを読み込みます。
- 共有リファレンス: チェックリストをエージェントのコンテキストに常時配置せず、必要なときに読み込めます。
- 検証と評価: Node.jsスクリプトが、スキル、コマンド、成果物のパス、リファレンスリンク、バージョン、評価ケースを検査します。
リポジトリ構成を理解する
skills/にはスキルのワークフローが含まれています。agents/には4つの専門レビュアー人格が含まれています。references/には、必要なときに利用できる共有チェックリストがあります。commands/ではライフサイクルコマンドを定義しています。evals/にはスキルの評価ケースとフィクスチャが含まれています。scripts/には検証ツールと評価ランナーが含まれています。hooks/にはセッションのライフサイクルフックがあります。docs/には内部ドキュメントが含まれています。.opencode/agent/viserys.mdではOpenCodeエージェントを定義しています。.opencode/opencode.jsonではOpenCode向けのスキルパスを登録しています。
インストールとセットアップ
方法1: OpenCodeでViserysを有効にする
- GitでViserysリポジトリをクローンします。
- クローンしたリポジトリのフォルダーをOpenCodeで開きます。
Tabを押してエージェントセレクターを開きます。viserysを選択します。
付属のViserysエージェントはプライマリーモードで動作するため、OpenCodeのエージェント一覧に表示されます。プロンプトはリクエストを処理する前に適用可能なスキルを確認し、プロジェクトのライフサイクルに沿って作業を進めます。リポジトリレベルのOpenCode設定でパッケージ済みの全スキルが登録されるため、グローバル設定は必要ありません。
方法2: 別のスキル対応エージェントでViserysを使う
Claude Code、Cursor、または再利用可能なスキルに対応する別のエージェントで、リポジトリのskills/ディレクトリを参照するように設定します。または、そのディレクトリをツール固有のスキル保存場所にコピーします。
正確な配置先はコーディングエージェントによって異なります。ViserysのMarkdownワークフローを別の形式に変換する必要はありませんが、ホストツールがワークフローの検出場所を認識している必要があります。
方法3: スキルをプレーンなコンテキストとして使う
エージェントにネイティブのスキルシステムがない場合は、関連するSKILL.mdファイルを開き、その内容をコンテキストとして提供します。すべてのスキルは単独で機能するよう設計されているため、手順に従って手動で作業したり、エージェントに手順を実行させたりできます。
適切なワークフローを選ぶ
どのワークフローを適用すべきか分からない場合は、メタスキルusing-agent-skillsから始めます。それ以外の場合は、現在のライフサイクル段階に応じてスキルを選択します。
DEFINE: 作業を明確にする
- 概念が曖昧で、体系的な検討が必要な場合は
idea-refineを使います。 - 要件を一度に1つずつ質問して収集する必要がある場合は
interview-meを使います。 - 仕様のない状態でプロジェクト、機能、または大きな変更を始める前に
spec-driven-developmentを使います。 - 品質基準が存在しない場合や、ビルドを通すためだけにチェックを抑制している場合は
constraint-driven-developmentを使います。
PLAN: 仕様をタスクに変換する
要件が固まったら、planning-and-task-breakdownを使います。仕様を、受け入れ基準付きの順序付けられた検証可能なタスクに変換します。
BUILD: 意図を持って実装する
- 複数ファイルにまたがる変更を小さな単位で反映するには、
incremental-implementationが役立ちます。 - ロジックの実装、バグ修正、動作変更には
test-driven-developmentを適用します。 - セッションの初期化、タスクの切り替え、出力品質が低下した際の復旧には
context-engineeringが役立ちます。 - 最新の公式ドキュメントに正確性が依存する場合は
source-driven-developmentが適しています。 - 影響が大きく、後でデバッグするより今すぐ確認するほうが安い場合は、
doubt-driven-developmentが検証を促します。 - ユーザー向けインターフェースの開発には
frontend-ui-engineeringを使います。 - API、モジュール境界、公開インターフェースの設計には
api-and-interface-designが役立ちます。
VERIFY: 変更が機能することを証明する
- ブラウザベースの実装やデバッグには
browser-testing-with-devtoolsを使います。 - テストが失敗した場合、ビルドが壊れた場合、または実行時の動作が予期しない場合は
debugging-and-error-recoveryを使います。
REVIEW: 品質とリスクを評価する
- 変更をマージする前に、
code-review-and-qualityを使用します。 - 動作するコードでも理解や保守が難しい場合は、
code-simplificationが役立ちます。 - ユーザー入力、認証、データ保存、外部連携には
security-and-hardeningを適用します。 - パフォーマンス要件がある場合や、性能劣化が疑われる場合は
performance-optimizationを適用します。
SHIP: 本番環境に向けて準備する
git-workflow-and-versioningは、コード変更とバージョン管理の指針となります。ci-cd-and-automationは、ビルドおよびデプロイパイプラインの変更を支援します。deprecation-and-migrationは、古いシステムの廃止やユーザーの移行に役立ちます。documentation-and-adrsは、アーキテクチャ上の決定事項や公開 API の変更を記録します。observability-and-instrumentationは、ログ、メトリクス、トレース、アラートを扱います。shipping-and-launchは、本番デプロイの最終準備を支援します。
基本的な使用例
たとえば、AI コーディングエージェントに新しい認証済み API エンドポイントの追加を依頼するとします。実装にすぐ着手するのではなく、ライフサイクルに沿って順番に進めます。
- Define: 認証ルール、入力、レスポンスが不明確な場合は
interview-meを実行します。次にspec-driven-developmentを使って、期待される動作を明確にします。 - Plan:
planning-and-task-breakdownを適用し、順序付けられたタスクと受け入れ基準を作成します。 - Build: エンドポイントの契約には
api-and-interface-designを、動作の実装にはtest-driven-developmentを使用します。複数のファイルを変更する必要がある場合は、incremental-implementationも使用します。 - Verify: テストに失敗した場合やエンドポイントが予期せず動作する場合は、
debugging-and-error-recoveryに従います。 - Review: この機能は認証と入力を扱うため、
code-review-and-qualityとsecurity-and-hardeningを適用します。 - Ship: 本番デプロイの前に、適切な Git、ドキュメント、オブザーバビリティ、ローンチのワークフローを使用します。
OpenCode 統合を有効にすると、Viserys エージェントはまず一致するスキルを確認するよう設計されています。プレーンコンテキストの構成では、この選択を自分で行い、選択した各 Markdown ワークフローに従うようエージェントに指示します。
レビュアーペルソナを使う
Viserys には、agents/ に 4 つのレビュアーペルソナが含まれています。これらは、ライフサイクルのスキルを補完する、焦点を絞った視点を提供します。
agents/code-reviewer.mdは、スタッフエンジニアの承認基準に基づき、5 つの軸でレビューします。agents/test-engineer.mdは、prove-it パターンを使ってテスト戦略とカバレッジを検証します。agents/security-auditor.mdは、脆弱性の検出、脅威モデリング、OWASP 評価を担当します。agents/web-performance-auditor.mdは、quick または deep モードで Core Web Vitals を監査します。
変更に伴うリスクに応じてペルソナを選択します。たとえば、認証機能にはセキュリティ監査担当と security-and-hardening を組み合わせ、ユーザー向けインターフェースを変更した後には Web パフォーマンス監査担当を使います。
ワークフローパックを検証する
スキル、コマンド、リファレンス、バージョン、評価用フィクスチャを変更した後は、付属の Node.js スクリプトを実行します。
node scripts/validate-skills.js
node scripts/validate-commands.js
node scripts/validate-artifact-paths.js
node scripts/validate-reference-links.js
node scripts/validate-versions.js
node scripts/run-evals.jsこれらのコマンドは、パックの内部構造を検証し、評価スイートを実行します。既存のワークフローを利用するだけでなく Viserys を拡張する場合に、特に重要です。
高度なヒント
ライフサイクルのゲートを省略せずにスキルを組み合わせる
1 つのタスクに複数のスキルが必要になる場合があります。たとえばブラウザ機能では、frontend-ui-engineering、test-driven-development、browser-testing-with-devtools を組み合わせられます。ワークフローを追加しても無秩序なプロンプトにならないよう、各スキルの終了基準を常に確認できる状態にしておきます。
必要なときだけリファレンスを読み込む
references/ ディレクトリは、必要に応じて読み込む共有チェックリスト用です。これにより、詳細なガイダンスへのアクセスを維持しながら、エージェントのアクティブなコンテキストを集中させられます。
バージョン依存の作業には公式ソースを使う
実装の詳細が最新のドキュメントに依存する場合は、source-driven-development を適用します。もっともらしくても誤った仮定が大きな損失につながる場合は、doubt-driven-development と組み合わせます。
エージェントの品質が低下したときに回復する
長いセッションで一貫性が失われた場合は、context-engineering を使用します。これは、セッションの設定、タスクの切り替え、出力品質が低下した状況を対象としています。
付属ドキュメントを参照する
docs/README.mdは、パックとライフサイクルマップについて説明します。docs/skill-anatomy.mdは、SKILL.mdの形式を定義します。evals/README.mdは、スキル評価の仕組みを説明します。
ワークフローを追加または再構成する前にスキル構造の仕様を読み、その後バリデーターと評価を実行して結果を確認します。
まとめ
Viserys は、AI 支援開発を再現可能なエンジニアリングプロセスに変えます。まず skills/ ディレクトリを互換性のあるエージェントに接続するか、OpenCode で付属の Viserys エージェントを選択します。次に、DEFINE、PLAN、BUILD、VERIFY、REVIEW、SHIP の各段階を、専門家ペルソナや有用な検証スクリプトと組み合わせながら、着実に進めます。