clj-skill-eval

Clojure スキル評価フレームワーク

Clojure スキルの評価には、仮定ではなく、測定可能な動作の違いが現れる実際のプロジェクトが必要です。このスキルでは、同一のタスクに対するスキルありとスキルなしの開発を比較する、厳密な評価手法を採用します。

基本原則

スキルが重要なのは、実際の動作を変える場合に限られます。

評価方法：

1. 分離したプロジェクトを2つ作成する（スキルあり／なし）
2. 両方で同一の実際の開発タスクを実行する
3. コード品質、開発時間、ドキュメントの深さ、テストの網羅性を比較する
4. コンテキストログを分析し、動作の違い（REPL の使用、探索パターン、デバッグ手法）を確認する

---

フェーズ 1：評価計画

評価するスキルを定義する

入力：

• スキル名とパス（例：clj-discover、clj-debug）
• スキルによってどのような動作を変えるべきか（例：「ログベースのデバッグから REPL ベースのデバッグに切り替える」）

出力：

• 明確な評価仮説（曖昧な想定ではない）
• 測定する、観察可能な動作の違いの一覧

現実的な開発タスクを設計する

要件：

• 実際のプロジェクトを想定したシナリオ — おもちゃの例や作為的な問題ではない
• 具体的な要件 — 曖昧な仕様ではなく、明確な成功基準
• 中程度の複雑さ — スキルの価値を示せる程度で、単純すぎない（各バージョンで 5～15 分）
• タスクの多様性 — タスクの種類を変えることで、スキルの異なる強みが明らかになります：
  • 探索タスク：「不慣れなライブラリ／API を使って機能を実装する」（clj-discover を検証）
  • デバッグタスク：「既存のシステムのバグを修正する」（clj-debug を検証）
  • 調査タスク：「マクロの動作を理解して変更する」（clj-discover を検証）
  • 統合タスク：「相互運用機能を使って Java ライブラリを使用する」（clj-discover を検証）

タスクの例：

Implement GET /system-stats API endpoint that returns CPU usage and memory info.
- Use OSHI library for system statistics
- Return JSON with cpu-usage (0.0-1.0) and memory-info {total, available}
- Include at least one passing test

評価基準を作成する

定量的な基準：

• 実行時間（秒、分）
• トークン使用量
• コード行数
• ドキュメントファイル数
• テストカバレッジ

定性的な基準：

• API の選択（最適な方法か、基本的な方法か）
• コード品質（コメント、明瞭さ、型安全性）
• テストの堅牢性（どのようなシナリオがカバーされているか）
• ドキュメントの深さ（判断の理由が説明されているか、結果だけか）
• 動作パターン（REPL を使用したか、ログを追加したか、ファイルを読んだか）

---

フェーズ 2：プロジェクトのセットアップ

分離したプロジェクトを2つ作成する

neil を使って、同一の Clojure Stack Lite プロジェクトを生成します。

neil new io.github.abogoyavlensky/clojure-stack-lite my-test-without-skill
neil new io.github.abogoyavlensky/clojure-stack-lite my-test-with-skill

次に、それぞれのプロジェクトで以下を実行します。

cd my-test-without-skill && neil add nrepl
cd my-test-with-skill && neil add nrepl

分離する理由：

• 状態や設定を共有しない
• 互いに干渉せず並行して実行できる
• それぞれに、(reset) を使ったクリーンな Integrant システムが用意される

タスクの説明を作成する

両方のプロジェクトに、同一の要件を記載した TASK.md を作成します。

# Task: [Implementation Task Name]

## Objective
[Clear, concrete objective]

## Requirements
[Bullet points with specific requirements]

## Success Criteria
✓ Criterion 1
✓ Criterion 2

---

フェーズ 3：サブエージェントによる並列実行

重要な権限設定

Claude Code でサブエージェントを実行する場合、権限の制約によるブロックを避けるため、--dangerously-skip-permissions を使用します。

claude --dangerously-skip-permissions [your-claude-code-command]

これが必要な理由： スキルでは、明示的な権限が必要なツール（brepl、WebSearch、ファイル操作など）を使う場合があります。このフラグを指定しないと、タスクを完了せずに「permission constraints」でサブエージェントが中断することがあります。

両方のバージョンを並行して起動する

所要時間を比較できるよう、同じターンで2つのサブエージェントを同時に作成します。

サブエージェント 1（スキルなし）：

Execute this task in /path/to/my-test-without-skill:

1. Read TASK.md to understand requirements
2. Complete the implementation task
3. Save all final code files to outputs/
4. Record your approach in outputs/APPROACH.md:
   - How did you discover what to do?
   - What APIs/libraries did you choose and why?
   - What debugging/exploration did you do?
   - How much time was spent coding vs exploring?
5. DO NOT use any Clojure skills

Focus: Complete the task efficiently.

サブエージェント 2（スキルあり）：

Execute this task in /path/to/my-test-with-skill:

1. Read TASK.md to understand requirements
2. Complete the implementation task
3. Save all final code files to outputs/
4. Record your approach in outputs/APPROACH.md:
   - Which skills did you use and when?
   - How did each skill influence your decisions?
   - What exploration patterns did you use?
   - Did you use REPL-based debugging or log-based?
5. Use these Clojure skills as they become relevant:
   - clj-discover (understanding APIs, Java interop, macros)
   - clj-debug (interactive debugging via brepl)
   - clj-replace (structural code replacement)

Focus: Complete the task with skill guidance.

重要： 所要時間を比較できるよう、両方を同じターンで起動してください。

---

フェーズ 4：詳細な比較分析

コード品質の比較

生成されたコードファイル（ハンドラー、ルート、テスト）を比較します。

API の選択：

• スキルなしの場合、最初に思いつく方法を選んだか
• スキルありの場合、より最適または標準的な API の使い方を見つけたか
• 調査した形跡があるか、それともすぐにコーディングを始めたか

型安全性：

• 明示的な型変換を行っているか、それとも暗黙の前提に依存しているか
• 複雑な箇所を説明するコメントがあるか
• エラー処理があるか、それとも正常系のみか

テストの堅牢性：

• 基本的なアサーションのみか、それとも包括的にカバーしているか
• エッジケースに対応しているか
• ビジネスロジックを検証しているか（例：available ≤ total）

ドキュメントの比較

APPROACH.md と生成されたドキュメントを比較します。

スキルなしの場合に示される内容：

• 「調査せずに直接実装」
• 最小限の意思決定に関する説明
• 迅速な成功

スキルありの場合に示される内容：

• 「実装前にライブラリを調査」
• 「アプローチを検証するために REPL でテスト」
• API の選択理由が明確
• より包括的なドキュメント

行動パターンの分析

APPROACH.md から、以下のパターンを特定します。

パターン	スキルなし	スキルあり	意義
REPL の使用	なし／最小限	対話型テストを頻繁に実施	スキルによってデバッグが可能になったことを示す
ファイルの読み取り	散発的な探索	対象を絞った調査	何を確認すべきかについてのスキルによるガイダンス
デバッグの方法	ログ／println	対話型 brepl	中核となる行動の変化
ドキュメント	最小限	理由を含む詳細な内容	スキルが徹底的な検討を促している

時間とトークンのデータ

サブエージェントの通知から以下を記録します。

• 実行時間（スキルなしのほうが速い一方、品質は低いはずです）
• 総トークン数（スキルありのほうが多く調査します）
• 品質に対する時間の比率

---

フェーズ 5：結論を導く

スキルの有効性を評価する

各スキルについて、以下を推定します。

• 使用度：スキルは実際にどの程度有効化されましたか？（⭐ スケール）
• 行動への影響：開発アプローチに変化がありましたか？（はい／いいえ）
• 適用可能性：どのような種類のタスクで役立ちますか？

評価レポートを作成する

構成：

# Evaluation Report: [Skill Name]

## Executive Summary
One sentence: Did the skill improve development outcomes?

## Task Executed
[Task description and success criteria]

## Key Findings

### Quantitative Comparison
- Time: [without-skill] vs [with-skill]
- Tokens: [without-skill] vs [with-skill]
- Code quality metrics

### Behavioral Differences
- API choices: [specific example]
- Testing approach: [specific example]
- Documentation depth: [specific example]

### Skill Activation Analysis
- Which skills were used: [list with ⭐ ratings]
- Permission issues: [if any]
- Unexpected patterns: [if any]

## Recommendations
- Is the skill valuable? [YES/NO with justification]
- In what scenarios is it most useful?
- What could be improved?

---

フェーズ 6：反復と改善

スキルの有効性が不明確な場合：

1. スキルに適したタスクを設計する

   • clj-discover が起動しなかった場合：未知の API の調査が必要なタスクを追加します
   • clj-debug が使われなかった場合：対話型デバッグが必要なタスクを追加します

2. 新しいタスクで評価を再度実行する

3. 複数のタスクのパターンを比較し、スキルがいつ、なぜ起動するかを把握します

---

避けるべきアンチパターン

❌ 禁止事項：

• 仮定の質問をする（「このスキルは X に役立ちますか？」）
• スキルを「知識の伝達」で評価する（スキルは情報を提供するだけでなく、行動を変えるべきです）
• 「スキルが読み込まれたが実行されなかった」ことを成功とみなす
• スキルの価値が示されない単純なタスクだけを実行する
• ベースラインと比較せずに評価する

✅ 推奨事項：

• スキルあり／なしの条件で同一のタスクを実行する
• 実際の行動の変化（REPL の使用、探索パターン、デバッグの方法）を測定する
• スキルが起動した、または起動しなかった理由を分析する
• 複数の種類のタスクでテストし、スキルが特に効果を発揮する場面を見つける
• コードやドキュメントの具体的な違いを記録する

---

タスクの種類に関するリファレンス

以下を参考に、さまざまな評価タスクを設計してください。

1. 発見タスク（clj-discover を起動）

「未知のライブラリを使って機能を実装する」

• 例：「auth0 ライブラリを使って JWT 認証を追加する」
• スキルの価値：試行錯誤せずに未知の API を把握できます

2. デバッグタスク（clj-debug を起動）

「複数コンポーネントで構成されたシステムのバグを修正する」

• 例：「ユーザーからログイン失敗の報告があります。Integrant システムのライフサイクルをデバッグしてください」
• スキルの価値：ログベースのデバッグから、対話型 REPL デバッグへの移行を促します

3. マクロ／メタタスク（clj-discover を起動）

「マクロの動作を理解し、変更する」

• 例：「新しいパターンに対応するよう defroutes マクロを拡張する」
• スキルの価値：マクロ展開とメタパターンを説明します

4. Java 連携タスク（clj-discover を起動）

「Java ライブラリを統合する」

• 例：「OSHI ライブラリを使ってシステム監視を追加する」（テスト済みのタスク）
• スキルの価値：Java API の調べ方とメソッドの選択を明確にします

---

覚えておくこと

スキルに意味があるのは、生成するコードだけでなく、Claude のコード開発の方法を変える場合に限ります。

評価でスキルによる行動の変化が確認できなかったとしても、それは有益なデータです。次のいずれかを意味しています。

1. スキルの起動条件を調整する必要がある
2. スキルの内容を見直す必要がある
3. タスクがスキルの強みを活かせるものではない

いずれも解決できます。しかし、それを知るには行動の変化を測定するしかありません。