GitHubのIssueに計画書を残す：コメントに埋もれない作業の文脈
修正コードはPRにあっても、その理由は古いチャットに埋もれていることがあります。エージェントの調査まで別の場所にあると、次の担当者が同じ調査を繰り返しかねません。GitHubが10月28日に公開プレビューを発表したIssue artifactsは、こうした資料をIssueに直接紐付ける機能です。
会話と更新し続ける資料を使い分ける
Markdown文書、外部リンク、HTML文書をアーティファクトにできます。原因分析、試作品、SlackやTeamsの議論などが対象です。github.comでは作成・編集し、バージョン履歴も保持できます。ワークフロー実行の成果物であるGitHub Actions artifactsとは別の機能です。
架空の二重決済バグを考えてみましょう。コメントには新しい観察を、計画書には再試行キーの扱いや未検証の実験を残します。最初の画像は記事用に自作した例で、GitHubの画面ではありません。観察と仮説を分けると、推測が確定した要件として扱われるのを防ぎやすくなります。
ファイルを添付し、同じ資料を育てる
gh issue artifact createはIssue番号またはURLの後にファイルやリンクを指定します。gh issue artifact create 42 retry-plan.md -R OWNER/REPOは指定リポジトリのIssue 42にファイルを添付する例です。値は置き換え用で、実行すると書き込みが発生します。本記事では実行していません。
資料名にはファイル名や--nameを使えます。--body-fileは一つの文書の本文を読み込み、--attachは画像や動画を添付します。gh issue artifact edit 42 1 --body-file retry-plan.md -R OWNER/REPOで本文を置き換えられます。2枚目は構文例で、アップロード成功の記録ではありません。
最新の計画と変更の経緯を残す
editは名前や本文を変えますが、種類は変えません。--restore-versionは以前の名前と内容を新しいバージョンとして保存し、viewで編集履歴を確認できます。古い判断を消さずに現在の計画を維持できます。
決済の例なら、タイムアウトという仮説が重複キー処理へ絞られるかもしれません。計画を更新し、理由をコメントから辿れるようにするのは資料整理の提案で、自動機能の保証ではありません。添付文書だけでコードの正しさは証明できず、根拠も必要です。
HTMLは利用する画面によって対応が異なる
発表ではHTMLのプレビューとソースを切り替えられる一方、GitHub App内のHTML作成・閲覧は今後提供と説明されています。セッションで作った資料が自動添付されることと、どこでもHTMLが使えることは分けて理解したい点です。CLIもプレビューです。
大事なのは資料を増やすことより、次の人が文脈を見つけられる場所です。既存の計画書一つを紐付け、次の修正で履歴をつなぐところから試せます。現在の対応範囲は公式資料を確認してください。