plugin-dev-workflow

プラグイン開発ワークフロー

このリポジトリは Elixir/Phoenix Claude Code プラグインです。プラグインファイルを編集する際は、品質を確保するために次のワークフローに従ってください。

始める前に

make help を実行して、利用可能なコマンドをすべて確認してください。

make eval          # Quick: lint + score changed skills/agents
make eval-all      # Full: all 51 skills + 26 agents
make eval-fix      # Auto-fix + show failures
make test          # 220 pytest tests for eval framework and port tooling
make ci            # Full CI pipeline

個別ファイルのスコアリング（CLI）

重要：必ず -m モジュール構文を使用してください。scorer.py を直接実行しないでください。

# Score ONE skill (use -m, NOT direct file path)
python3 -m lab.eval.scorer plugins/elixir-phoenix/skills/verify/SKILL.md

# Score ONE skill with pretty output
python3 -m lab.eval.scorer plugins/elixir-phoenix/skills/verify/SKILL.md --pretty

# Score all skills
python3 -m lab.eval.scorer --all

# Score ONE agent
python3 -m lab.eval.agent_scorer plugins/elixir-phoenix/agents/verification-runner.md

# Score all agents
python3 -m lab.eval.agent_scorer --all
make ci            # Full CI pipeline

スキルを編集する場合（plugins/elixir-phoenix/skills/*/SKILL.md）

1. CLAUDE.md の規約（サイズ制限、フロントマターの要件）を確認します
2. 変更を加えます
3. make eval を実行します。変更されたスキルを自動検出してスコアリングします
4. FAIL の場合：失敗した評価項目を確認して修正します
5. make lint を実行して、Markdown の書式を確認します
6. コミットします

スキルの要件（eval ですべて確認します）：

• フロントマター：name、description、effort。description は動作を表す動詞で始まり、「Use when...」を含める必要があります
• 1 項目以上の番号付きリストを含む Iron Laws セクション
• 185 行未満（コマンドスキル）または 150 行未満（リファレンススキル）
• 45 行を超えるセクションがないこと
• すべての /phx: 参照先が既存のスキルであること
• すべての references/*.md パスが存在すること
• Iron Laws セクション以外に危険なコードパターンがないこと
• コード例が含まれていること（フェンス付きコードブロックが 1 つ以上）
• トリガーの精度を高めるため、description に「Use when...」が含まれていること

エージェントを編集する場合（plugins/elixir-phoenix/agents/*.md）

1. 変更を加えます
2. make eval-agents を実行して、すべてのエージェントをスコアリングします
3. エージェントの要件：
   • permissionMode を使用しないこと（プラグインのエージェントでは無視されます。プラグインディレクトリでは bypassPermissions が失敗します）
   • レビュー／分析エージェントには disallowedTools: Write, Edit, NotebookEdit を指定すること
   • effort に合ったモデルを指定すること：haiku=low、sonnet=medium、opus=high
   • 300 行未満（スペシャリスト）または 535 行未満（オーケストレーター）

Eval フレームワークを編集する場合（lab/eval/*.py）

1. 変更を加えます
2. make test を実行します。すべての pytest テストが合格する必要があります
3. make eval-all を実行して、スキルやエージェントの品質が低下していないことを確認します
4. 新しいマッチャーを追加する場合：lab/eval/tests/test_matchers.py にテストを追加します

フックを編集する場合（plugins/elixir-phoenix/hooks/scripts/*.sh）

1. 変更を加えます
2. make lint を実行します（フックのコメント内の Markdown を確認します）
3. フックを手動でテストします（フックは Edit/Write/Bash イベントで実行されます）
4. CLAUDE.md のフックに関するドキュメントが正確であることを確認します

Autoresearch（自己改善ループ）

make eval-fix で失敗が表示された場合、autoresearch コマンドが提案されます。

# Copy-paste the suggested command from eval-fix output
claude -p 'Run autoresearch. Score all skills...' --allowedTools 'Edit,Read,Write,Bash,Glob,Grep'

これは autoresearch ループを実行します：最も弱いスキルを見つける → 問題を 1 つ修正する → 再スコアリングする → 変更を保持または元に戻す。

コミット前のチェックリスト

プラグインの変更をコミットする前に、次を確認してください。

• make lint が合格する
• make eval が合格する（変更したファイル）
• make test が合格する（eval フレームワークを変更した場合）
• CHANGELOG.md を更新する（ユーザーに見える変更の場合）
• plugin.json のバージョンを更新する（リリースする場合）

参考資料

• CLAUDE.md — 規約、サイズ制限、チェックリストの全文
• lab/eval/ — スコアリングフレームワーク（24 個のマッチャー、8 つの評価項目）
• lab/autoresearch/ — 自己改善ループ
• lab/findings/interesting.jsonl — 興味深い発見をここに記録します