0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

# Copilot coding agent にスキル品質基準を設計させて、人間 × GPT × Copilot の 3 者でレビューした話(前編)

0
Posted at

TL;DR

  • SkillsBench 論文の知見をもとに、GitHub Copilot の「スキル」に品質基準を設けました
  • Copilot coding agent に Issue → PR まで自走させ、人間が GPT のレビュー観点で品質を担保しました
  • 結果:設計ドキュメント 4 本 + CI ワークフロー 1 本が約 30 分で着地しました
  • 人間の役割は「設計判断」と「レビュー観点の選定」だけで、コードはすべて Agent が書きました

背景:なぜスキル品質が問題になったのか

Copilot のスキルとは

GitHub Copilot coding agent は、リポジトリ内の skills/ 配下にある Markdown(例:skills/**/SKILL.md)を読み込み、タスク遂行の判断材料にします。
ざっくり言うと **「Agent が参照する指示書」**です。

Copilot coding agent とは(読者向け補足)

Copilot coding agent は、Issue に書かれた目的・制約・完了条件をもとに、実装案を立てて PR を作り、指摘を受ければ修正コミットを積み上げていくタイプのエージェントです。
(人間は Issue とレビューに集中し、コーディングや修正の実働は Agent に寄せられます)


現状の問題

私たちのリポジトリ(MCP セキュリティ監視)には 8 つのスキルがありましたが、SkillsBench 論文(arXiv:2602.12670)の観点で見ると アンチパターンに寄りがちな状態でした。

指標 現状
スキル総数 8
合計行数 1,608 行
推定トークン ~22,600
YAML frontmatter 0/8(全スキルに無い)
完了条件の記述 0/8
最大行数 285 行(evidence-capture)

SkillsBench が教えてくれたこと(ざっくり要点)

SkillsBench は、同じタスクを「スキルなし / 人間設計スキルあり / AIが自作したスキルあり」で多数回試行し、成功率を比較しています。

ここで言う「成功率」は、各タスクに対して 指定された完了条件(正答基準)を満たせた割合です。
(※論文内の定義やタスクごとの判定ロジックに依存します。ここでは「スキル有無で達成率が有意に変わり得る」という主張の根拠として参照しています)

特に刺さったのは次の方向性です。

  • 短く・絞ったスキルは効きやすい(逆に網羅的すぎると悪化し得る)
  • 同時に読ませるスキル数が増えるほど効き目が落ちたり、逆効果になったりし得る
  • 「スキルを増やせば良くなる」は成立しないケースがある

つまり「短く」「必要なときだけ」「少数を読む」が基本戦略になります。


やったこと:3 層の設計

今回の設計は 3 層です。

1. 設計層(何を守るか)

  • SKILL-AUTHORING.md:スキル設計の 5 原則
    • 1責務
    • description でルーティング(読み手=Agent前提)
    • Compact 優先
    • 手続き(how)より判断(what/when)中心
    • 完了条件を明示
  • SKILL-INDEX.md:フェーズ別に「遅延読み込み」するルーティングマップ

2. ゲート層(どう守るか)

  • skill-quality-check.yml:PR 時の自動チェック(D-1)
    • Check 1〜3:機械的に判定できるもの(frontmatter、行数、構造など)
    • Check 4〜5:将来 LLM 判定にしたいが、まずは段階導入(現時点は手動レビューで代替)

3. 検証層(本当に効くか)

  • D-2:Before/After の比較(初回のリファクタ時のみ)
    • ただし この記事時点では未実施です
    • まず D-1 の運用を回し、スキルを 1 本ずつリファクタしたタイミングで測る予定です

正直、D-2 まできっちりやって初めて「効いた」と言えるのですが、今回は「壊れにくい運用の土台」を先に作った、というフェーズです。


フェーズ別遅延読み込み(SKILL-INDEX)

Agent が最初に読むのは SKILL-INDEX.md だけにして、必要なスキルだけを遅延読み込みします。

フェーズ 目的 同時参照の目安
collect(収集) 外部/内部から材料を集める 2
analyze(分析) 差分検出・要約・根拠抽出 2〜3
output(出力) レポート生成・通知・PR化 2〜3

期待効果としては、最初に全部読む(~22,600 tokens)よりも、タスク単位で 5,000〜8,000 tokens 程度まで落とせる想定です(あくまで概算)。


独自の工夫:Load when / Avoid when

GitHub 公式の Agentic Workflows リポジトリ(github/gh-aw)を眺めると、スキルの「いつ読むべきか」を強く意識した書き方がありました。
そこで私たちは、各スキルに Load when(いつ読むか)を揃えたうえで、独自に Avoid when(いつ読まないか)も追加しました。

ポイントは「文章のうまさ」ではなく、定型ブロックで書式を固定することです。Agent にとってパースしやすくなります。

web-fetcher(例)

  • Phase: collect
  • Load when
    • URL からコンテンツを取得し Markdown に変換する必要があるとき
    • 複数 URL の並列取得が必要な場合
  • Avoid when
    • 既にローカルにデータがある場合
  • Estimated tokens: ~800

「Avoid when」は効くのか?

これは論文に直接ある主張ではなく、私の仮説です。
スキル選択ミスの多くは「読まなくていいものを読んで混乱する」パターンなので、使う条件だけでなく、使わない条件も固定化すると誤選択が減るのでは、という狙いです。


開発プロセス:人間 × GPT × Copilot

タイムライン(約 30 分)

時刻 アクター やったこと
13:28 Copilot agent Issue #76 を受けて initial plan 作成
13:36 Copilot agent ADR-002 / SKILL-AUTHORING.md / SKILL-INDEX.md / skill-quality-check.yml を一括生成
13:38 Copilot agent shellcheck warnings を自走修正
13:40 人間 GPT にレビュー観点を出させる
13:45 人間 GPT 観点 × 実ファイルを突き合わせ、改善コメント(M1〜M4)を PR に投稿
13:50 Copilot agent M1〜M4 を反映(フェーズ分類、Load/Avoid、fetch-depth、運用設定追記)
13:56 Copilot agent 具体例とガイダンスを追加・修正

※人間が書いたコードは 0 行です(判断とレビューはしています)。


3 者の役割分担

アクター 役割 具体的にやったこと
人間 設計判断・レビュー観点の選定 Issue 起票、GPT 出力の取捨選択、PR にレビューコメント
GPT 構造化されたレビュー観点の生成 4 観点(R1〜R4)で抜け漏れ検出、失敗パターン提示
Copilot agent 生成・修正の実行 ファイル生成、指摘反映、CI 破綻要因の修正

なぜ GPT をレビューに使ったのか

Copilot agent は「言われたことを実装する」のは得意ですが、設計意図からのズレを自分で検出するのは苦手です。
一方 GPT は「因果を分解してレビュー観点を列挙する」のが得意です。

実際、GPT の観点で PR を見たことで、次のような見落としを潰せました。

  • checkout の fetch-depth 未指定で、origin/main...HEAD の diff が失敗する可能性(CI 破綻)(R3)
  • Issue で決めたフェーズ分類が Index に反映されていない(ルーティングが弱い)(R2)
  • Required check の設定導線が ADR に無い(運用上、形骸化し得る)(R3)
  • Check 4/5(LLM 判定)が placeholder であることが明記されていない(誤解リスク)(R4)

迷った点(判断の痕跡)

最初、Copilot agent は SKILL-INDEX を「カテゴリ分類(データ収集/分析/通知...)」でまとめてきました。
一見わかりやすいのですが、私たちが狙っていたのは「collect → analyze → output」の 作業フェーズで遅延読み込みする設計です。

そこで人間側の判断として、

  • 「カテゴリ分類は残してもいいが、フェーズ分類を第一にする」
  • 「Agent の選択ミスを減らすために、Load when/Avoid when を定型化する」

という方向に寄せました。
このあたりは、出力をそのまま採用するのではなく「設計判断」を人間が持つべき部分でした。


学び

1. 「チェックリスト運用は破綻する」を前提に設計する

チェックリストは増えるほど見られなくなり、忙しくなるとスキップされます。
対策は CI でゲートにすることです。

  • Check 1〜3:機械判定で強制
  • Check 4〜5:いきなり自動 fail にせず、段階導入(手動レビュー → 将来 LLM 判定)

2. 段階導入が強い

最初から厳格にしすぎると運用が折れます。

  • 行数超過は warning に留める(最初は fail にしない)
  • LLM 判定は placeholder + 手動レビューで代替し、後で自動化する

厳しくするのは、運用が回り始めてからのほうが現実的です。

3. Agent への指示は「フォーマットを固定する」と壊れにくい

文章は揺れますが、構造は揺れません。

  • Phase / Load when / Avoid when / Skill file / Estimated tokens
  • Load when は最大 3、Avoid when は 1、などの制約も含めて固定

この「固定」が、エージェント運用の安定性に直結します。

4. 人間の仕事は「何を作るか」ではなく「何をレビューするか」

今回、人間が価値を出したのはコードではなく、

  • どの設計判断を採用するか
  • どの観点でレビューするか
  • どこを段階導入にするか

の選定でした。
判断と選定に集中できるのは、エージェント開発の良さだと感じました。


次のステップ

  1. PR #77 を最終確認して merge
  2. skill-quality-check を Required status check に設定
  3. 既存 8 スキルをリファクタ(まず 1 本だけ模範例を作ってから横展開)
  4. D-2(Before/After)を初回リファクタのタイミングで実施(タスク完了率・トークン消費など)

後編予告

後編では、8 スキルのリファクタ結果と、D-2 の Before/After(タスク完了率・トークン消費など) をまとめます。


参考

  • SkillsBench(arXiv:2602.12670)
  • PR #77(ADR-002 + skill-quality-check)
  • github/gh-aw(GitHub の Agentic Workflows 参考リポジトリ)
0
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?