create-issue スキル

issue 本文は、その時点で人間が合意した要求、意図、制約、観測、未決定事項を残す文書である。agent の推論、提案、調査結果を、合意済みの内容として本文へ混ぜてはならない。

このスキルの役割は、合意を完成させることではない。すでに合意されている意味を読みやすく整え、合意されていない内容を書かずに残すことである。

本文へ書くための条件

タイトルと本文の各記述は、次のどちらかを満たす場合だけ書いてよい。

1. 人間が、自分の要求、決定、観測、または未決定事項として明示した
2. agent が提示した具体的な内容を、人間がその内容を指して明示的に採用した

「明示した」と判断するには、どの発言が根拠かを会話から特定できなければならない。根拠となる発言を特定できない記述は、もっともらしくても本文に書かない。文章を自然につなぐための言い換えはよいが、条件、対象、理由、目的、優先順位、例外を足してはならない。

次のものは合意として扱わない。

• agent が文脈から推測した内容
• ユーザーが反対しなかっただけの内容
• 「方向性はよい」「だいたいよい」など、どの記述を採用したか特定できない反応
• 貼り付けられた文章、既存 issue、設計メモ、調査結果、レビューコメントに書かれているだけの内容
• コードや外部資料から agent が確認した事実

貼り付けられた素材について、人間が「この内容をそのまま採用する」「このうち A と B を要求とする」のように採用範囲を明示した場合、その範囲は合意として扱える。「これを参考に issue にして」のように、素材と合意の境界が分からない場合は、素材を合意済みの内容へ昇格させない。

合意と事実確認を分ける

人間が採用したことと、その内容が事実として確認できていることは別である。

• 「この操作で 500 が返った」と人間が報告した場合は、「この操作で 500 が返る」と一般化せず、「この操作で 500 が返ることを確認した」と観測の記録として書く
• 原因や現在のコード構造について人間が推測を述べても、確認済みの事実へ書き換えない
• agent が外部仕様を確認しても、人間が issue の制約や前提として採用していなければ本文に書かない
• 未検証の前提を人間が採用した場合は、「〜という前提で進める」のように、前提であることが分かる形で書く

人間が採用しても、原因分析や実装上の作業仮説は issue 本文へ残さない。これらは実装開始時に現在のコードで調べ直す。

agent が気づいた不足の扱い

agent が必要そうな条件や論点に気づいても、本文を完全に見せるために補ってはならない。

回答によって要求、制約、対象範囲、外部から見える振る舞いが変わる場合は、issue 草案の外で人間へ質問できる。人間が回答した内容だけを本文へ加える。回答が得られない場合は、その記述を本文から省く。

agent が考えた質問を、そのまま本文の「未決定事項」へ書いてはならない。「未決定事項」に書けるのは、人間が未決定だと明示した項目、または agent が示した問いを人間が未決定事項として残すことに同意した項目だけである。

実装者がコードを読んで決められる内部設計は、人間へ質問せず、issue にも書かない。たとえば、次の内容は実装時に判断する。

• DB のカラム名
• Repository のメソッド名
• 変更するファイル
• 内部 API の構造
• 関数の分割方法
• テストファイルの配置

本文へ書かない内容

誰の発言が元であっても、次の内容は issue 本文に書かない。

• 現在のコード構造の説明
• 原因の分析や仮説
• 変更するファイルの候補
• 実装方法や実装手順
• 調査の経緯やログ
• 実装時の作業仮説
• 実装者がコードを読んで決められる技術的選択

不採用案は、人間が要求または制約として今後も除外すると決めた場合だけ「やらないこと」に書く。単なる設計比較や一時的なコード事情は残さない。

issue 作成時の調査

issue を詳しく見せるためのコード調査はしない。原因の特定、実装方法の決定、変更ファイルの探索、コード構造の分析は、実装開始時の issue-agreement に委ねる。

調査してよいのは、問題の再現条件を確かめる場合と、ユーザーの要求が何を指しているか確認する場合だけであり、その目的に必要な最小限にとどめる。調査で分かった内容も、人間の合意なしに issue 本文へ加えてはならない。

issue の構成

次の 5 項目から、合意済みの内容がある項目だけを使う。空の項目や、内容を補うための定型文は書かない。

• 問題: 人間が示した困りごと。バグでは、人間が示した再現手順、期待する挙動、実際に観測した挙動
• 実現したいこと: この issue が閉じたときに実現していたいと人間が述べたこと
• 要求・制約・前提: 人間が決めた要求と制約、および前提だと分かる形で採用した前提
• やらないこと: 人間が対象外と決めた範囲
• 未決定事項: 人間が未決定だと明示した項目

タイトル

タイトルも本文と同じ条件で作る。合意済みの問題または実現したいことを短く言い換え、実装方法や、合意されていない目的を足さない。

避ける:
Add GitHubIssueRepository and webhook handler

望ましい:
Portal から作成した GitHub Issue の進捗を確認できるようにする

望ましい例に含まれる内容も、実際の依頼で人間が合意している場合に限って使える。

草案を作る手順

1. 依頼、会話、貼り付けられた素材から、本文へ入れる候補を文ごとに抽出する
2. 各候補について、合意の根拠となる人間の発言を特定する
3. 根拠を特定できない候補を捨てる。重要な不足だけは本文の外で質問する
4. 残った候補を、意味を足さずにタイトルと本文へ構成する
5. 草案の各文を根拠となる発言へもう一度対応づけ、対応しない文を削る
6. 次を確認する
   • agent の推論、提案、調査結果が確定事項として混ざっていないか
   • 人間の観測や仮説を、一般的な事実へ強めていないか
   • 条件、対象、理由、目的、優先順位、例外を補っていないか
   • agent が考えた質問を未決定事項へ入れていないか
   • 異なる要求や条件を一つにまとめて意味を変えていないか
   • 人間が全文を普通に読める長さか

合意の根拠との対応は、issue 本文に注釈として書かない。草案を作る agent が、余計な意味を入れていないか確認するために使う。

作成と更新の承認

対話できる場面では、タイトルと本文の全文を人間へ提示し、その全文で作成または更新してよいという明示的な承認を得てから GitHub へ書き込む。

すでに人間がタイトルと本文の全文を確認し、「この内容で作成して」「この本文へ更新して」のように承認している場合は、同じ内容について再確認しない。承認後に意味を変えた場合は、変更後の全文について承認を得直す。

人間が提示した完成済みのタイトルと本文を、そのまま作成または更新するよう明示した場合も、提示された内容を承認済みとして扱う。

次の状態は承認として扱わない。

• 草案の全文をまだ提示していない
• 一部だけを確認した
• 方向性だけに賛同した
• 人間が応答していない
• どの版を指すか分からない

対話できず、完成済みの全文に対する承認も確認できない場合は、GitHub へ書き込まず草案を返す。未決定事項が残っていても、人間がその状態の全文を承認していれば作成できる。

コメントの扱い

この基準を厳格に適用する対象は issue のタイトルと本文である。コメントには議論や判断の経緯を残せるが、agent が調査ログや実装メモを保存するためだけに長文コメントを追加しない。

議論によって合意が変わった場合は、変更後の全文について承認を得てから本文を更新し、本文が現在の合意を表す状態に保つ。

issue-agreement との分担

人間の要求・判断
    ↓
create-issue
    ↓
issue
    ↓
issue-agreement + 現在のコード
    ↓
合意メモ
    ↓
設計・実装

• create-issue: 人間が合意した要求、意図、制約、観測、未決定事項だけを、意味を増やさず issue に残す
• issue-agreement: 実装開始時に現在のコードを調査し直し、issue との違いや実装前に必要な判断を確認する