apm-waza-ops

APM / Waza Ops

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

APM のコマンド

Waza のコマンド

よくあるハマりどころ

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 の使い分け

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

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

推奨パターン:

• 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 の改善案を表で持っておく:

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 にする