testing

テストスキル — 検証＋日次ヘルスチェックとリグレッション分析

規約： テストを実行してから一括変更するパターンについては、conventions/quality.md を参照してください。このスキルでは、プロジェクト独自のテストスイート全体にこのパターンを適用します。

2 つのモード

このスキルには、関連しつつも異なる 2 つのモードがあります。

1. スキル適合性の検証 — gbrain 独自の適合基準（当初の 1.0 の範囲）です。すべてのスキルに SKILL.md とフロントマターがあること、すべての参照先が存在すること、マニフェストとリゾルバーの網羅性が双方向に一致することを検証します。

2. プロジェクトのテストスイートの健全性（v0.25.1 の拡張） — プロジェクトの階層化されたテストスイートを実行し、リグレッションを分類したレポートを生成します。日次 cron、コンテナー再起動時のブートストラップ、「テストはどうですか」というプロンプトで使用します。

トリガーに応じてモードを選択してください。

モード 1：スキル適合性の検証

契約

このモードでは、次のことを保証します。

• すべてのスキルディレクトリに SKILL.md ファイルがある
• すべての SKILL.md に有効な YAML フロントマター（name、description）がある
• すべての SKILL.md に test/skills-conformance.test.ts で定められた必須セクションがある
• skills/manifest.json にすべてのスキルディレクトリが記載されている
• skills/RESOLVER.md がマニフェスト内のすべてのスキルを参照している
• openclaw.plugin.json の skills[] と、マニフェストおよびリゾルバーの内容が双方向に一致する
• openclaw.plugin.json に、OpenClaw のインストールに必要なネイティブプラグインフィールド（id、オブジェクト型の configSchema、該当する場合は contracts.contextEngines）が維持されている
• MECE 違反（スキル間のトリガーの重複）がない

フェーズ

1. スキルディレクトリを確認します。 SKILL.md を含むすべてのサブディレクトリを一覧表示します。
2. フロントマターを検証します。 YAML を解析し、必須フィールドを確認します。
3. セクションを検証します。 必須の見出しがあることを確認します。
4. マニフェストを確認します。 すべてのスキルディレクトリが manifest.json に含まれている必要があります。
5. リゾルバーを確認します。 マニフェスト内のすべてのスキルに RESOLVER の行が必要です。
6. 双方向の一致を確認します。 RESOLVER のトリガー ↔ フロントマターのトリガーを確認します。
7. 結果を報告します。

自動化

bun test test/skills-conformance.test.ts test/resolver.test.ts test/openclaw-plugin-manifest.test.ts

CI のゲートとなるチェックは、package.json の test スクリプトです。

出力形式

Skill Validation Report
========================
Skills found:        N
Conformance:         N/N pass
Manifest coverage:   N/N
Resolver coverage:   N/N
Round-trip:          N/N
MECE violations:     N

Issues:
- <skill>: <issue>

モード 2：プロジェクトのテストスイートの健全性（v0.25.1）

使用するタイミング

• 日次テスト cron が実行されたとき
• ユーザーから「テストを実行して」「テストはどうですか」「何が壊れていますか」と尋ねられたとき
• 大幅なコード変更後（多くの場合、cross-modal-review を使用）
• コンテナー再起動後（ブートストラップ）
• 何かがおかしいと感じ、システムの健全性を確認したいとき

テスト階層

階層	実行内容	実行時間	ゲート
ユニット	bun test（決定的、外部呼び出しなし）	<2s	すべてのコミット
評価	LLM による判定、または品質評価	~60s	毎日
統合	実際の Postgres に対する E2E テスト	~5m	リリース前＋毎晩
システムヘルス	ディスク／メモリ／CPU／サービスの稼働状況	<10s	毎日

日次実行プロトコル

cron が実行されたとき（またはユーザーから依頼されたとき）は、以下をすべて行います。

1. ユニットテストを実行します

bun test 2>&1

解析する内容：合格数、失敗数、スキップ数の合計、およびファイル単位の結果。

2. 評価を実行します（プロジェクトに評価設定がある場合）

# Adapt to the project's eval config
bun test --filter eval 2>&1

同じ形式で解析します。フレーク（コードの不具合ではなく、API タイムアウトが原因で失敗するテスト）があれば記録します。

3. システムヘルスチェックを実行します

• ディスク／メモリ／CPU
• gbrain：gbrain doctor --fast --json
• データベース接続（該当する場合）
• 重要なファイル（CLAUDE.md、AGENTS.md など）の存在確認

4. Git の差分を分析します（重要 — リグレッション分析）

# What changed since last test run?
git log --oneline --since="24 hours ago"

失敗したテストごとに、次の点を確認します。

1. テスト自体が最近変更されたか（リグレッションではなく、テストの変更かどうか）。
2. テスト対象のコードが最近変更されたか（リグレッションの可能性）。
3. 既知のフレークかどうか（API タイムアウト、サービス停止）。
4. 依存関係（gbrain、bun など）が更新されたかどうか。

5. 各失敗を分類する

分類	マーカー	対応
REGRESSION — コードが変更され、テストが失敗した	🔴	失敗の原因となったコミットを示します
STALE — テストが古い動作を想定している。コードは正しい	🟡	コードではなくテストを修正します
FLAKE — API タイムアウト、サービス停止、LLM のばらつき	⚠️	注意事項として記録し、警告はしません。1 回再試行します
NEW — テストが追加されたばかりで、まだ成功していない	🟢	意図したものか確認します
INFRA — コンテナーの再起動で状態が消去された	🛠	ブートストラップを実行し、再テストします

6. レポート形式

🧪 Daily Tests — YYYY-MM-DD

Unit:   X/Y passed (Z skipped)
Evals:  X/Y passed
System: [health summary]

REGRESSIONS:
  🔴 <test-name>: broke by commit <sha> "<commit message>"

STALE TESTS:
  🟡 <test-name>: expects X but code now does Y (commit <sha>)

FLAKES:
  ⚠️ <test-name>: timeout (retry passed)

✅ ALL CLEAR  (when applicable)

7. 自動修正プロトコル

自動修正するもの：

• 名前変更後、テストが古いファイルパスを想定している → テストを更新します
• テストが古いバージョン文字列を想定している → 更新します
• 意図的に削除されたファイルをテストが想定している → テストを削除します
• ファイルの移動によりインポートパスが壊れた → インポートを修正します

自動修正しないもの：

• テストが動作 A を想定しているのに、コードが動作 B をする → まず確認します。テストが正しく、コードにバグがある可能性があります。
• セキュリティテストの失敗 → 必ずエスカレーションし、自動修正はしません。
• テストが TODO 付きでスキップされている → 理由を理解せずにスキップを解除しません。

判断に迷う場合は、コードを変更したコミットメッセージを確認し、関連する PR や会話がないか調べます。それでも不明な場合はユーザーに尋ねます。

状態（リグレッション履歴）

傾向を追跡するため、結果を ~/.gbrain/test-state.json に記録します。

{
  "lastRun": "2026-04-16T13:37:00Z",
  "unit": { "passed": 1262, "failed": 31, "skipped": 8 },
  "evals": { "passed": 17, "failed": 0 },
  "system": { "doctor": "ok", "gbrain": "0.25.1" },
  "failureHistory": [
    { "test": "<name>", "since": "2026-04-14", "classification": "stale" }
  ]
}

これにより、次のことが可能になります。

• 傾向の追跡（改善しているか、悪化しているか）
• 不安定なテストの検出（同じテストが断続的に失敗するか）
• リグレッションの速度（変更後、どれくらいの速さで問題が発生するか）

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、または通知ブロックについては、エージェント運用者プロトコルに従ってください。このスキルに固有の対応は次のとおりです。

• API キーの不足または不安定なプロバイダーが原因でテストが失敗した場合は、コードの失敗ではなく環境の失敗として分類し、該当するキーを伝えます。
• セキュリティテストが失敗した場合は、必ずユーザーにエスカレーションします。自動修正はしません。
• gbrain doctor がブレインに接続できない場合（GBRAIN_DB_ACCESS）は、統合テストを実行する前に db-repair スキルに引き継ぎます。

アンチパターン

• ❌ 新しいスキルを追加した後に適合性の検証を省略する
• ❌ RESOLVER.md に追加せず、manifest.json にスキルを追加する
• ❌ 赤いテストをすべてリグレッションと見なす。まず分類してください。古いテストや不安定なテストも多くあります。
• ❌ スキップされた理由を理解せずにテストのスキップを自動解除する
• ❌ セキュリティテストの失敗を自動で「修正」する
• ❌ システムのヘルスチェックを実行せずに「問題なし」と報告する

契約

このスキルは次のことを保証します。

• ルーティングがフロントマターの正式なトリガーと一致していること。
• writes_to: に記載されたディレクトリに出力が書き込まれること（該当する場合）。
• 参照されている規約（quality.md、brain-first.md、_brain-filing-rules.md）に従っていること。
• プライバシー契約が維持されること。実名、フォーク固有のファイルシステムパスのリテラル、上流フォークへの言及は含めません。

動作に関する契約の全体は、上記の本文セクションに記載されています。このセクションは適合性テストのために設けられています。

出力形式

スキルの出力形式は、本文セクション（「Output」、「Brain page format」など）に記載されています。ここにあるセクション見出しは、適合性テスト（test/skills-conformance.test.ts）のために設けられています。