apm-waza-ops

APM / Waza Ops

APM と Waza の運用ナレッジ集。本プロジェクトで使う設定パターンとハマりどころをまとめる。

APM のコマンド

コマンド	用途
apm init	apm.yml を生成
apm install	依存解決と .github/ .claude/ .cursor/ .agents/ への配布
apm install --target copilot	Copilot 向けに配布（0.12 系では skill が .agents/skills/ に集約される）
apm install --target copilot,agent-skills	Copilot ネイティブの .github/skills/ にも skill を配置したいときに併用
apm compile	AGENTS.md と CLAUDE.md を生成（Codex / Gemini 向け）
apm pack	依存解決後を .tar.gz に固める
apm audit	隠し Unicode の検出
apm update	依存パッケージと CLI の更新

Waza のコマンド

コマンド	用途
waza init <n>	プロジェクト初期化（GitHub Actions も生成）
waza new skill <n>	スキル追加
waza run <skill> -v	評価実行
waza check <skill>	スキル品質チェック（microsoft/skills 提出向け）
waza serve	Web ダッシュボード（http://localhost:3000）
waza compare a.json b.json	モデル間比較
waza tokens compare origin/main HEAD --strict	トークン予算チェック

よくあるハマりどころ

1. apm install で配布ファイルが出ない

• 原因候補: ローカルの .apm/ に同名ファイルがあり、依存側がコリジョンで skip されている
• 対処: 公式は「local content takes priority on collision」と明記。原本側を見る

2. クローン直後に Copilot がコンテキストを拾えない

• 原因候補: .github/ の展開後ファイルがコミットされていない
• 対処: apm.yml と apm.lock.yaml に加え、.github/、.claude/、.cursor/、.agents/ の配布物も必ずコミットする

3. skill が .github/skills/ に出ない（apm 0.12 系）

• 原因候補: apm install --target copilot を 0.11 系の感覚で叩いている
• 対処: 0.12 系では skill は cross-client な .agents/skills/ に集約される。Copilot ネイティブの .github/skills/ にも置きたい場合は --target copilot,agent-skills を併用する。CI のドリフト検出も .agents を含めるよう更新する

4. Codex / Gemini CLI でスキルが見えない

• 原因候補: apm compile が実行されていない
• 対処: apm compile で AGENTS.md を生成する。Copilot / Claude / Cursor は不要

5. waza run がモデル接続で失敗する

• 原因候補: Copilot CLI で未認証、または Copilot サブスクリプションのアクセス権限がない
• 対処: ローカル検証は executor: mock を使う。実モデル評価は ~/.copilot/ の Copilot 認証が必要（.env の OPENAI_API_KEY 等は Waza 0.31.0 では使われない）

6. CI のトークン使用量が読めない

• 原因候補: パスフィルタなしで全コミットに評価が走っている
• 対処: paths: で evals/** skills/** に絞る。fail_fast: true も有効

7. prompt グレーダーで無限にトークンを消費

• 原因候補: continue_session: true でジャッジがセッションを引き継ぎ、会話が長引いている
• 対処: まず continue_session: false で試す。必要時のみ true に

ドリフト検出の実装

.github/ .claude/ .cursor/ .agents/ の配布ファイルがコミット済みファイルと一致することを CI で確認する:

- name: Detect deployment drift
  run: |
    git diff --exit-code -- .github .claude .cursor .agents || {
      echo "::error::apm install の結果と一致しません"
      exit 1
    }

apm-action の使い分け

モード	用途
デフォルト	apm.yml を読んで install
isolated: true	apm.yml を無視し、inline 宣言だけで install
pack: true	依存解決後を .tar.gz にまとめる
bundle: <path>	.tar.gz から復元（APM なしで展開可能）
audit-report: true	隠し Unicode を SARIF で報告

大規模リポジトリで複数ジョブが同じ依存を使うなら、pack → bundle のフローで apm install の重複実行を避けられる。

グレーダーの組み合わせ設計

グレーダー	主な用途	コスト
text	キーワード / 正規表現チェック	低
file	ファイル存在と内容	低
diff	スナップショット照合	低
code	Python / JS のアサーション	低
json_schema	構造化出力の検証	低
behavior	ツール呼び出し回数、トークン数	低
action_sequence	ツール呼び出し順序	低
skill_invocation	スキル呼び出し履歴	低
tool_constraint	ツール許可 / 拒否リスト	低
prompt	LLM ジャッジ	高
program	外部コマンド実行	依存

推奨パターン:

• CI 常用は text / file / diff / behavior / skill_invocation を主軸にする
• 主観的な品質評価が必要なときだけ prompt を足す
• 「出力チェック」＋「振る舞いチェック」＋「スキル発火チェック」の 3 軸以上を重ねる（公式のベストプラクティス "Layer your checks"）

評価駆動ループの設計指針

スキルを評価駆動で改善するときの考え方。

1. グレーダーの種類を 3 軸以上に重ねる

1 つのグレーダーだけで合否判定すると、LLM の曖昧な出力で簡単にすり抜けます。最低でも次の 3 軸を重ねる:

• 出力内容（text / file / diff / json_schema）
• スキル発火（skill_invocation）
• 振る舞い（behavior / tool_constraint）

2. weight でグレーダーの優先度を表現する

各グレーダーに weight を指定できます。重要度を反映させると合成スコアでの比較がしやすくなります。

graders:
  - type: text
    name: detects_critical_risk
    weight: 3.0  # クリティカルなので 3 倍
    config:
      contains: ["shell=True"]
  - type: behavior
    name: efficiency
    weight: 0.5  # オマケなので 0.5 倍
    config:
      max_tool_calls: 5

ただし合否判定はあくまで「全グレーダーが通るか」で決まる点に注意。weight は加重スコアでのランキング指標です。

3. 失敗パターンと改善案をマッピングしておく

スキル開発では、Waza が落ちたときに「何を変えるか」の判断スピードが大事。失敗パターンと SKILL.md の改善案を表で持っておく:

失敗するグレーダー	想定原因	SKILL.md の改善案
出力チェック（特定キーワード未検出）	スキルがそのリスクを認識していない	レビュー観点に明記する
skill_invocation	description のトリガーワードが弱い	Triggers 行を拡充
efficiency	過剰なツール呼び出し	作業手順を簡潔化、DO NOT USE FOR を厳しく

4. モデル間の差を比較する

# 実モデル評価には eval.yaml の config.executor を copilot-sdk にしてから実行する
waza run my-skill --model gpt-5.4 -o gpt54.json
waza run my-skill --model claude-sonnet-4.6 -o sonnet.json
waza compare gpt54.json sonnet.json

スキルがモデルに過度に依存していないかを定期的にチェックする。Waza 0.31.0 の有効な engine は mock と copilot-sdk の 2 つだけで、--executor という CLI フラグはない。executor の切り替えは eval.yaml の config.executor で行う。

5. ローカル検証は executor: mock で API を呼ばない

config:
  executor: mock

評価フローのドライランだけしたい場合に、トークン消費せずに eval.yaml の構文チェックや CI 統合の検証ができる。

6. --cache で繰り返し評価のコストを下げる

waza run my-skill --cache --cache-dir .waza-cache

入力やコンフィグが変わっていないタスクはキャッシュから返るので、改善ループを高速に回せる。

Secret 管理

• .env.example にプレースホルダーを用意（プロジェクト固有のキーがある場合）
• Waza 0.31.0 のモデル呼び出しは Copilot サブスクリプション認証で動くため、OPENAI_API_KEY や ANTHROPIC_API_KEY を Waza 用に登録する必要はない
• CI で実モデル評価を走らせる場合は、Copilot CLI を事前にセットアップして認証する

関連 Quick Commands

# APM
apm install
apm install <owner>/<repo>#<tag>
apm compile
apm pack --target copilot
apm audit

# Waza
waza init my-skill-evals
waza new skill my-skill
waza run my-skill -v
waza check my-skill
waza serve

# ローカル評価（API を呼ばない）
# eval.yaml の config.executor を mock にする