AIエージェント向けGitHub Issue Formの作り方：受け入れ条件・検証コマンド・禁止操作を分ける

このテーマをもう少し広げて見るなら、チーム向けAGENTS.mdテンプレート：Codex・Claude Code・Cursorで権限とテスト手順をそろえる と AIエージェントPRテンプレートの作り方：Summary・Tests run・Not run・Risksを固定する も合わせて確認してください。Issue Formで集める受け入れ条件や禁止操作を、agentが読む恒久ルールへ落とす導線になる。

3行まとめ

Scope

触ってよい範囲と対象外を分けます。

Done

受け入れ条件を確認可能にします。

Guard

禁止操作とsecret確認を必須にします。

Issue Formは、AIへの依頼をレビュー可能な作業単位に変えます。

• AIコーディングエージェントにIssueを任せるなら、自由記述だけでなく、目的、対象範囲、対象外、受け入れ条件、検証コマンド、禁止操作、secret確認を分けて入力させるIssue Formが役に立ちます。
• GitHub Issue FormsはYAMLでフォームを定義でき、入力欄、textarea、dropdown、checkboxes、必須項目、label、assigneeなどを設定できます。ただし、フォームは入力の型であり、権限やレビュー責任を自動で保証するものではありません。
• agentがPRを作っても、mergeしてよいかは別です。フォーム入力どおりの範囲か、受け入れ条件を満たすか、指定コマンドが通ったか、未検証項目が残っているかを人間が確認します。

本文の事実確認には、GitHub Issue Formsの公式Docs、GitHub form schemaの公式Docs、GitHub Copilot coding agentの公式Docsを使っています。Xで伸びているAI agent向けIssueテンプレートやCopilot assignmentの投稿は需要シグナルとして扱い、本文の根拠にはしていません。

この記事でわかること

8項目

目的、範囲、対象外、再現、完了、検証、禁止、secretを分けます。

YAML

GitHub Issue Formsの形へ落とします。

レビュー

agent PRで見る項目を決めます。

改善

失敗したIssueをテンプレートへ戻します。

フォームを作るだけでなく、PRレビューまでつなげます。

• AI agent向けIssue Formに入れる8項目
• MarkdownテンプレートよりIssue Formが向く場面
• 受け入れ条件をテスト可能な文にする方法
• 対象外、禁止操作、secret確認を必須項目にする理由
• GitHub Issue FormのYAML例
• agentが作ったPRで人間が確認すること

IssueをAIに渡すとき、入力が曖昧だと出力も広がります。「このバグ直して」だけでは、どこまで触ってよいか、どのテストで合格か、何をしてはいけないかが見えません。

Issue Formは、この曖昧さを減らすための道具です。AIに優しいフォームは、人間にも優しいフォームです。目的、範囲、完了条件が分かれていれば、PR author、reviewer、agentの全員が同じ線を見やすくなります。

前提知識

項目	内容	見方
Issue Forms		YAML formをISSUE_TEMPLATEへ置く仕組みです。
Form schema		input、textarea、dropdown、checkboxesなどを確認します。
Copilot agent		IssueからPR作成を依頼する流れを確認します。
Review		PRは人間が確認してmergeします。

Issue Formは入力の型であり、実行権限の制御ではありません。

GitHub Issue Formsの公式Docsでは、.github/ISSUE_TEMPLATE配下にYAML form definition fileを置くことで、入力欄を持つIssue作成フォームを作れると説明されています。GitHub form schemaでは、入力要素のtype、attributes、validationsなどを定義します。

Issue Formsでは、input、textarea、dropdown、checkboxes、markdownなどを使えます。top-levelにはname、description、bodyが必要で、必要に応じてtitle、labels、assigneesなども使えます。

GitHub Copilot coding agentの公式Docsでは、IssueなどからCopilotに作業を依頼し、Pull Requestを作らせる流れが案内されています。つまりIssue本文は、人間だけでなくagentへの作業入力にもなります。

Issue Formは安全境界ではない

Issue Formを作ると、入力の抜け漏れは減らせます。しかし、実行権限、secret管理、branch protection、人間レビューを置き換えるものではありません。

条件

最初は、AI agentに任せるIssueだけ専用フォームにします。通常の問い合わせ、仕様相談、運用申請まで同じフォームに詰め込まないほうが扱いやすいです。

注意点

フォーム項目を増やしすぎると、利用者が雑に埋めるようになります。必須項目は、agentが作業するために本当に必要な情報に絞ります。

AI agent向けIssue Formで分ける8項目

項目	内容	見方
目的		何を変えるIssueか。
範囲		触ってよいpathやmodule。
対象外		今回触らないもの。
完了条件		確認可能な受け入れ条件。
検証		実行するコマンド。
禁止		やってはいけない操作。
secret		機密情報がないことの確認。
レビュー		PRで人間が見る観点。

自由記述を1つにまとめるほど、agentの解釈差が大きくなります。

AI agent向けのIssue Formでは、最低限8つを分けます。

項目	目的	例
目的	何を変えるか	ログイン失敗時の表示を改善する
対象範囲	触ってよい場所	frontend/auth/*
対象外	触らない場所	API仕様、認証フロー全体
再現手順	現象を確認する方法	入力、操作、期待しない結果
受け入れ条件	Doneの判定	エラー表示、既存テスト、戻り値
検証コマンド	実行する確認	npm run test -- LoginForm
禁止操作	やってはいけないこと	依存追加、本番API、広いrefactor
secret確認	機密情報を入れない確認	token、cookie、顧客ログなし

1つのtextareaに全部書かせない

自由記述欄が1つだけだと、重要な情報が混ざります。agentは、目的、制約、完了条件、禁止事項をすべて同じ強さの文章として受け取りがちです。

checkboxで確認を強制する

secret確認や禁止操作の理解は、checkboxに向いています。たとえば「このIssueにはAPI key、cookie、顧客ログを含めていません」「本番deployやsecret変更は依頼していません」のように、投稿者に明示的に確認してもらいます。

MarkdownテンプレートよりIssue Formが向く場面

Bugfix

再現手順と期待結果を必須にできます。

Test追加

対象コマンドと合格条件を固定できます。

Agent依頼

禁止操作や対象外をcheckboxにできます。

Triage

label、assignee、typeを揃えやすくなります。

曖昧な依頼を減らしたい時は、フォーム化が効きます。

Markdownテンプレートにも良さがあります。自由度が高く、慣れているチームでは速く書けます。一方で、AI agentへ渡すIssueでは、Issue Formのほうが向く場面があります。

場面	Issue Formが向く理由
Bugfix	再現手順、期待結果、実際の結果を必須にできる
Test追加	対象コマンドと合格条件を固定できる
Agent依頼	対象外、禁止操作、secret確認をcheckboxにできる
Triage	label、assignee、typeを揃えやすい
初心者のIssue	書く順番をフォームで誘導できる

Markdownで足りるIssueもある

設計相談、調査メモ、長い背景説明、RFCに近いIssueは、Markdownテンプレートのほうが向く場合もあります。すべてをIssue Formにする必要はありません。

agentへ渡すIssueだけフォームを分ける

おすすめは、通常のbug reportとは別に「AI agent task」用のIssue Formを作ることです。AIに渡す前提なら、対象範囲、対象外、検証コマンド、禁止操作を必須にできます。

受け入れ条件はテスト可能な文にする

1. 1要望

   ユーザーが困っていることを整理します。

2. 2期待

   どうなればよいかを書く。

3. 3確認

   テスト、画面、APIで確認します。

4. 4未検証

   できない確認はPRに残します。

Doneが曖昧だと、agent PRの合否も曖昧になります。

受け入れ条件は、agent PRの合否を決める軸です。ここが曖昧だと、PRが完成したように見えても、reviewerが判断できません。

悪い例と良い例

曖昧な条件	確認しやすい条件
エラー表示をいい感じにする	ログイン失敗時にフォーム下へ「メールアドレスまたはパスワードが違います」を表示する
テストを直す	npm run test -- LoginForm が通る
UIを改善する	390px幅でボタン文言が折り返しても高さが崩れない
型エラーをなくす	npm run typecheck が通る

未検証項目を書けるようにする

すべてのIssueでE2Eや手動確認ができるとは限りません。だから、Issue Formには「未検証でよい項目」ではなく「PRで未検証として報告してほしい項目」を書く欄を用意します。

条件

agentに任せるIssueでは、受け入れ条件を3つから5つに絞ります。条件が多すぎる場合は、Issueを分けます。

注意点

受け入れ条件に「コード品質を上げる」「保守性を改善する」だけを書くと、差分が広がります。品質改善を任せる場合も、対象ファイル、許可する変更、確認コマンドを限定します。

対象外と禁止操作を必須項目にする

Out of scope

今回触らない機能やファイル。

No refactor

不要な設計変更を避けます。

No deps

依存追加を人間確認にします。

No deploy

本番操作やCI/CD変更を止めます。

やることより、やらないことがPRサイズを決めます。

AI agentへの依頼では、やることと同じくらい、やらないことが重要です。対象外を書かないIssueは、agentが親切に広げてしまうことがあります。

対象外に書くもの

• 今回触らない画面
• API仕様変更
• DB migration
• 認証や課金の挙動変更
• 依存関係更新
• 大きなrefactor
• CI/CD設定変更

禁止操作に書くもの

• secretや環境変数の表示
• 本番APIへの接続
• deployやrelease操作
• force pushや履歴破壊
• lockfile以外の広い依存更新
• unrelated fileの整形

人間確認が必要な操作も分ける

完全禁止ではなく、人間確認が必要な操作もあります。依存追加、権限設定変更、外部通信、MCP tool追加、CI/CD変更などは、「自動実行せず提案だけ」と書いておくと扱いやすくなります。

secretや本番情報を入れない設計

項目	内容	見方
API key		token、cookie、private keyを書きません。
本番ログ		顧客情報やDB dumpを入れません。
内部URL		公開repoでは詳細な内部URLを避けます。
権限変更		admin設定やsecret変更は人間確認へ戻します。

Issue Formはsecretを集めるフォームにしないことが重要です。

Issue Formでやってはいけないのは、再現に必要だからといって本番情報を集めることです。AI agentに渡るIssue本文には、secretや顧客情報を入れない前提で設計します。

入れない情報

情報	理由
API key / token	モデル入力、ログ、PR本文へ混ざる可能性がある
cookie / session	認証情報そのもの
private key / certificate	漏えい時の影響が大きい
顧客ログ	個人情報や契約情報を含む可能性
DB dump	本番データを含む可能性
内部URL	公開repoや外部agentで扱いにくい

redacted logを使う

再現にログが必要なら、値を伏せたログを使います。必要なのは、status code、error code、発生条件、再現手順、対象versionです。secretの実値ではありません。

secret確認をcheckboxにする

Issue Formには、次のようなcheckboxを入れます。

• API key、token、cookie、private keyを含めていません
• 顧客情報や本番DB dumpを含めていません
• 本番deployやsecret変更は依頼していません
• 必要な場合はfixtureまたはredacted logを使っています

この考え方は、Copilot Coding AgentにIssueを任せる前にで扱ったIssue入力の整理とも同じです。Issueは作業依頼であり、秘密情報の置き場ではありません。

Issue FormのYAML例

項目	内容	見方
input		短いタイトルや対象pathに使います。
textarea		再現手順や完了条件に使います。
dropdown		作業種別やリスク分類に使います。
checkboxes		secret確認や禁止操作の同意に使います。

必須入力を増やしすぎず、agentに必要な情報へ絞ります。

GitHub Issue Formは、YAMLで定義します。実際のrepositoryに入れるときは、.github/ISSUE_TEMPLATE/agent-task.ymlのようなファイル名にします。

name: AI agent task
description: Request a small task for an AI coding agent
title: "[agent] "
labels: ["agent-task", "needs-triage"]
body:
  - type: input
    id: goal
    attributes:
      label: Goal
      description: What should change?
      placeholder: Show an error message under the login form.
    validations:
      required: true

  - type: textarea
    id: scope
    attributes:
      label: Scope
      description: Paths or modules the agent may edit.
      placeholder: frontend/auth/LoginForm.tsx
    validations:
      required: true

  - type: textarea
    id: out_of_scope
    attributes:
      label: Out of scope
      description: Areas the agent must not change.
      placeholder: API behavior, auth flow, dependencies
    validations:
      required: true

  - type: textarea
    id: done
    attributes:
      label: Done when
      description: Acceptance criteria that can be checked.
      placeholder: npm run test -- LoginForm passes
    validations:
      required: true

  - type: textarea
    id: checks
    attributes:
      label: Checks to run
      description: Commands the PR should report.
      placeholder: npm run typecheck
    validations:
      required: true

  - type: checkboxes
    id: safety
    attributes:
      label: Safety checks
      options:
        - label: This issue contains no API keys, tokens, cookies, or private keys.
          required: true
        - label: This issue does not request deploys, secret changes, or production access.
          required: true
        - label: Any logs are redacted or use fixtures.
          required: true

YAML例は最小から始める

最初から大きなフォームにしないほうがよいです。目的、範囲、対象外、Done、Checks、Safetyだけで始め、失敗したIssueから項目を足します。

labelsとassigneesは運用に合わせる

labelsやassigneesは便利ですが、存在しないlabelは期待どおり付かない場合があります。repository側のlabel運用と合わせて確認します。

agent PRで確認すること

Scope

対象範囲外の変更がないか。

Done

受け入れ条件を満たすか。

Test

指定コマンドが通ったか。

Risk

未検証やリスクが説明されているか。

フォームが良くても、merge判断はPRで行います。

Issue Formが整っていても、PRレビューは必要です。agentが作ったPRでは、フォームの入力が守られたかを見ます。

確認	見ること
目的	IssueのGoalに沿っているか
範囲	Scope外のfileを触っていないか
対象外	Out of scopeを破っていないか
Done	受け入れ条件を満たしているか
Checks	指定コマンドを実行したか
Safety	secretや本番情報が混ざっていないか
未検証	実行できなかった確認が書かれているか

PR本文にフォーム項目を引き継ぐ

agent PRには、Issue Formの項目と対応する形で、Summary、Scope、Commands run、Not run、Risksを残します。差分だけでは、フォームを守ったか分かりにくいからです。

人間レビューを残す

agent PRは、自動mergeのための成果物ではありません。人間reviewerが、差分、テスト、未検証、対象外変更、secret疑いを確認します。

導入初週の進め方

1. 1日目

   bugfix用の1フォームだけ作ります。

2. 2日目

   docsやtest追加Issueで試します。

3. 3日目

   agent PRの差分と説明を確認します。

4. 5日目

   足りない入力項目を直します。

5. 7日目

   任せるIssue種別を決めます。

最初はフォーム数より、1つのフォームの品質を上げます。

最初の1週間は、フォームを増やすより1つのフォームを育てます。

1日目: bugfix用フォームだけ作る

AI agent向けに、bugfix用のIssue Formを1つ作ります。フォームには、目的、再現手順、範囲、対象外、Done、Checks、Safetyを入れます。

2日目: docsやtest追加で試す

低リスクなIssueで試します。agent PRがフォームの項目を守っているか、PR本文に未検証項目が残るかを見ます。

3日目: 小さなbugfixで試す

対象pathを限定したbugfixを任せます。範囲外の変更、不要なrefactor、テスト未実行がないか確認します。

5日目: 足りない入力項目を直す

失敗したPRからフォームを直します。たとえば対象外が足りない、検証コマンドが曖昧、secret確認が弱い、といった項目です。

7日目: 任せるIssue種別を決める

docs、test、small bugfix、型修正など、任せるIssueを決めます。認証、課金、DB migration、CI/CD、本番操作は最初の対象から外します。

失敗時に見直す条件

大差分

対象外と禁止操作が足りません。

未検証

検証コマンドが曖昧です。

誤解

完了条件が確認可能になっていません。

機密

secret確認の導線が弱いです。

agentの失敗を、入力フォームの改善材料にします。

agent PRが期待どおりにならないとき、agent性能だけを疑う前にフォームを見直します。

失敗	見直す項目
大差分になった	Scope、Out of scope、禁止操作
テストがない	Checks、Done when
仕様を誤解した	Goal、再現手順、期待結果
対象外を触った	Out of scopeの必須化
secret疑いが出た	Safety check、redaction手順
PR説明が薄い	PR template、Doneの粒度

フォーム項目を増やす前に言葉を直す

項目を増やすより、既存項目の説明を短く具体的にするほうが効くことがあります。たとえば「テストを書く」ではなく「PR本文に実行したコマンドと結果を書く」にします。

失敗ログをテンプレート改善に使う

失敗したIssueは、フォーム改善の材料です。どの入力が足りなかったか、どの制約が伝わらなかったかを見て、次のIssueで同じ失敗を減らします。

FAQ

フォームだけ

レビューと権限設計も必要です。

必須項目

増やしすぎると使われません。

Markdown

自由記述で足りるIssueもあります。

自動merge

人間レビューを残します。

迷ったら、agentに必要な情報と人間が確認する情報を分けます。

Issue Formを作ればAI agentは安全に動きますか

いいえ。Issue Formは入力を整える道具です。権限、secret管理、branch protection、人間レビューは別に必要です。

必須項目は多いほどよいですか

多すぎると使われにくくなります。最初は目的、範囲、対象外、Done、Checks、Safetyに絞り、失敗から増やします。

Markdownテンプレートではだめですか

だめではありません。自由記述が必要なIssueはMarkdownでも十分です。AI agentへ渡す小さな実装Issueでは、Issue Formのほうが入力の抜け漏れを減らしやすいです。

Copilot以外のagentにも使えますか

使えます。Codex、Claude Code、社内agentでも、目的、範囲、Done、Checks、禁止操作、secret確認が分かれているIssueは扱いやすくなります。

agent PRは自動mergeしてよいですか

最初は避けます。agentがPRを作ることと、mergeしてよいことは別です。人間review、CODEOWNERS、required checksを残します。

---

次に読むなら

参照した主な情報源

• https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms
• https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema
• https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/assign-copilot-to-an-issue
• https://docs.github.com/en/copilot/concepts/prompting/response-customization
• https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions

次に読むなら

更新履歴

1. 2026年5月31日

   GitHub Issue Forms、GitHub form schema、Copilot coding agent公式Docsを確認して初版を作成しました。

導入時には最新Docsと組織設定を再確認してください。

• 2026年5月31日: GitHub Issue Forms、GitHub form schema、Copilot coding agent公式Docsを確認し、初版を作成しました。