ハーネスのテストと検証 — drift 検出・CI バリデーション

読了 10分＋実践 40分

ハーネスの三層構造（CLAUDE.md・shared/・.claude/）を理解しており、設定の整合性を継続的に保ちたい方。[Memory システム設計](./memory) までのトピックを先に読むことを推奨します。

シムリンクの概念・`npm run harness:sync` の基本操作・GitHub Actions の YAML 構文の基礎

ハーネスは設定ファイルの集合体であるため、アプリケーションコードと異なり単体テストが書きにくい性質があります。しかし、シムリンクが壊れたり設定が drift したりすると Claude は期待通りに動かなくなります。このページでは、drift の検出方法・harness:check コマンドの仕組み・CI への組み込み方を順番に学びます。

ハーネスのテストが必要な理由

drift（ドリフト）とは、ハーネスの実際の状態が期待される状態から乖離していることを指します。コードでいえばビルドエラーや型エラーに相当しますが、ハーネスの場合は drift が発生しても即座にエラーが発生しません。Claude が「なんとなくルールを守らない」「特定のスキルが機能しない」という形で症状が現れます。

明示的な検証ステップがないと、次のような問題が切り分けられません。

Claude のモデルの問題なのか、設定の問題なのか
特定のスキルが正しく登録されているのか、シムリンクが壊れているだけなのか
CLAUDE.md に書いたルールへの参照が正しいパスを指しているのか

ハーネスの検証は「Claude の動作が意図通りかどうかをコントロールできる状態を維持する」ために必要です。

よくある drift パターン

問題	原因	検出方法
シムリンク切れ	`shared/` を移動・削除したが `.claude/` を更新していない	`ls -la .claude/`
スキルが反映されない	`shared/skills/` に追加したが `harness:sync` を実行していない	`npm run harness:check`
ルールが効いていない	CLAUDE.md から参照先のルールファイルへのリンクが壊れている	`npm run verify-links`
権限設定が古い	`settings.json` の `allow` リストが実際の必要コマンドと乖離している	手動確認

drift は「設定を変更したタイミング」ではなく「しばらく使い続けた後」に顕在化するケースが多くあります。定期的な検証が予防的なメンテナンスとして機能します。

仕組み: harness:check コマンドの詳細

npm run harness:check は以下の項目をチェックします。

シムリンクの確認

.claude/agents・.claude/commands・.claude/workflow がシムリンクとして存在し、参照先（shared/agents・shared/commands・shared/workflow）が実際に存在するかを確認します。シムリンクが存在していても参照先が削除されていると「壊れたシムリンク」として検出されます。

ファイルパスの存在確認

CLAUDE.md に記載された shared/rules/*.md や shared/skills/*/SKILL.md などのパスが実際のファイルシステムに存在するかを確認します。CLAUDE.md のパスが古いまま放置されている場合に検出できます。

JSON 構文チェック

.claude/settings.json が有効な JSON として解析できるかを確認します。設定を手動編集したときに発生しやすいシンタックスエラーを早期に検出します。

既知の危険な設定パターンの検出

settings.json の allow リストに npm run build が含まれていないかなど、安全性に影響する設定パターンを検出します。本番デプロイが誤って実行されるリスクをシステムレベルで防ぎます。

verify-links との役割分担

npm run verify-links はドキュメント内のリンク（Markdown の [text](url) 形式）が有効な URL またはファイルパスを指しているかを確認します。harness:check がハーネス設定の構造的整合性を検証するのに対し、verify-links はコンテンツ内のリンク切れを検出するという役割分担になっています。

ベストプラクティス

PR のたびに harness:check を実行する

ハーネス設定の変更は PR で管理し、CI で harness:check を自動実行します。「手元では動いていた」という状態のまま main に入るのを防げます。

shared/ を編集したら必ず harness:sync を実行する

シムリンクを手動で確認する代わりに、npm run harness:sync を習慣的に実行します。shared/ の変更が .claude/ に反映されているかを毎回目視確認するのはヒューマンエラーの原因になります。

# shared/ を編集するたびに実行するパターン
npm run harness:sync && npm run harness:check

設定変更は PR でレビューを経る

settings.json の権限設定やルールファイルの変更は、直接 main にコミットするのではなく PR を通じて他者がレビューできる状態にします。セキュリティに関わる設定ミスを早期に発見できます。

「壊れた状態」を意図的に作る演習を行う

実際に問題が発生したときに素早く診断できるよう、シムリンクを意図的に削除して検出フローを体験しておきます。以下の実践演習で一度体験しておくことを推奨します。

実践演習

Step 1: 現在の状態を確認する

プロジェクトルートで次のコマンドを実行し、ハーネスの現在の状態を確認します。

npm run harness:check

出力例:

✓ symlinks valid
✓ CLAUDE.md paths resolved
✓ settings.json valid JSON
✓ no dangerous patterns found
✓ harness:check passed

✅ 確認: harness:check passed が表示されれば、現在のハーネスに drift がないことが確認できました。エラーが表示された場合は、出力メッセージに従って問題を修正してから次のステップへ進んでください。

Step 2: シムリンクを意図的に壊して検出を体験する

壊れたシムリンクが正しく検出されるかを確認するために、一時的にシムリンクを削除します。

# テスト用にシムリンクをバックアップ名でリネームする
mv .claude/commands .claude/commands-backup

# harness:check を実行してエラーを確認する
npm run harness:check

期待される出力例:

✗ symlink missing: .claude/commands
harness:check failed

エラーが検出されたことを確認したら、シムリンクを元に戻します。

# シムリンクを元の名前に戻す
mv .claude/commands-backup .claude/commands

# 修復後に正常に戻ることを確認する
npm run harness:check

✅ 確認: harness:check failed が表示された後、元に戻して harness:check passed が表示されれば、検出フローが正しく機能しています。

Step 3: リンク切れを確認する

npm run verify-links

出力にリンク切れが含まれる場合は、src/content/docs/ のドキュメント内で参照しているファイルパスまたは URL を修正します。

✅ 確認: verify-links がエラーなく完了すれば、ドキュメント内のリンクは全て有効です。

Step 4: CI ワークフローを作成する

次の内容で .github/workflows/harness-check.yml を作成します。

# .github/workflows/harness-check.yml
name: Harness Check
on: [push, pull_request]

jobs:
  harness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm ci
      - run: npm run harness:check
      - run: npm run verify-links

ファイルを作成後、Git にコミットして push すると、次の PR から自動的に検証が走るようになります。

✅ 確認: GitHub の Actions タブで Harness Check ワークフローが表示され、緑のチェックが付けば CI への組み込みが完了です。

まとめ

drift はハーネス設定が期待される状態から乖離することで、Claude の動作不全として現れる
npm run harness:check はシムリンク・ファイルパス・JSON 構文・危険パターンを一括確認する
npm run verify-links はドキュメント内のリンク切れを検出する。harness:check とは役割が異なる
shared/ を編集したら必ず npm run harness:sync && npm run harness:check を実行する
CI に harness:check を組み込むことで、設定ミスが main に入るリスクを継続的に防ぐ

次のステップ

Marketplace 公開 — 構築したハーネスをコミュニティと共有する方法へ進む

よくある質問

Q: harness:check はどの程度の頻度で実行すべきですか？

A: shared/ ディレクトリを編集した後、および CI で PR ごとに自動実行するのが推奨パターンです。日常的な Claude Code の利用中は毎回実行する必要はありませんが、「Claude の動作がおかしい」と感じたときのファーストステップとして実行する習慣を持つと診断が早まります。

Q: harness:check でエラーが出たが、Claude は正常に動作しています。どうすればよいですか？

A: エラーの内容を確認してください。シムリンク切れや危険な設定パターンの検出は、Claude の動作に即座に影響しない場合でも潜在的なリスクを示しています。「今は動いている」という状態でも、設定の整合性を保つために修正することを推奨します。放置すると次の harness:sync や依存関係の更新時に問題が顕在化します。

Q: CI で harness:check が失敗した場合、どのように修正すればよいですか？

A: CI のログで出力されたエラーメッセージを確認し、対応する修正をローカルで行います。シムリンク切れなら npm run harness:sync で修復を試みます。CLAUDE.md のパス参照エラーなら該当するファイルパスを修正します。修正後にローカルで npm run harness:check を実行してエラーが解消されたことを確認してから push します。

Q: verify-links と harness:check を両方 CI に入れる必要がありますか？

A: 両方入れることを推奨します。harness:check はハーネス設定の構造的整合性を検証し、verify-links はドキュメントコンテンツのリンク切れを検出します。目的が異なるため、どちらか一方では検出できない問題があります。

このページの外部仕様・背景情報は、参考文献を参照してください。[1][2]

参考文献

Anthropic, Claude Code documentation
Anthropic, Claude API documentation

クイズ

Marketplace 公開 — スキル・エージェントをコミュニティと共有する

Memory システム設計 — ユーザー・プロジェクト・参照メモリの設計指針