✍️ 필사 모드: 良いチケットの書き方:人間とAIエージェント両方のためのIssue作成の技術

「コードは一度書かれ百回読まれる。チケットは一度書かれ、それが生んだコードと同じだけ長く生きる。」

プロローグ — チケットが即スペックである

ソフトウェアチームには、最も頻繁に書くのに最も教えない文書があります。チケットです。Jira Issue、GitHub Issue、Linear タスク — 名前は違っても本質は同じです。誰が何をなぜ作るべきかを書いた文書です。

チケットを軽く見る人は多いです。「どうせ口で説明すればいい」「コードを見ればわかる」と。しかし現実は違います。チケットはスペックです。 開発者がPRを開くとき頭の中に持っている唯一の契約書であり、レビュアーが「これで合っているか」を判断する基準であり、6か月後に誰かが git blame をたどって入ってきたときに出会う最後の手がかりです。

悪いチケットは悪い結果を生みます。曖昧なチケットは曖昧なPRを、スコープが隠れたチケットはレビュー不可能な diff を、受け入れ条件のないチケットは「全部できました」と「まだまだですが」が衝突する会議を生みます。

そして2026年、この問題は2倍に大きくなりました。 チケットを読むのはもはや人間だけではないからです。

AIエージェントもチケットを読む

コーディングエージェントに作業を任せるとき、入力は結局チケットです。人間の同僚は曖昧なチケットを受け取ると Slack で聞き返し、文脈を推測し、隣の席に行って尋ねます。エージェントはそれをしません。エージェントはチケットに書かれたことだけで作業します。書かれていないものはハルシネーションするか、無視するか、最もそれらしいデフォルトで埋めます。

つまり、チケットの品質が結果の品質の上限です。人間には「聞けばいい」というセーフティネットがありましたが、エージェントにはありません。良いチケットを書く技術は、協業スキルを超えてAIを扱う中核スキルになりました。

良い知らせは、人間にとって良いチケットはエージェントにとっても良いということです。明示的な文脈、検証可能な受け入れ条件、狭いスコープ — この3つは人間とAI両方に同じように効きます。この記事は、その3つをどう文書に落とすかの実践ガイドです。

この記事で扱う内容:

1章 · 良いチケットの解剖学

良いチケットには5つの構成要素があります。覚えておけばどのトラッカーでも通用します。

1.1 5つの構成要素

この5つが埋まったチケットはそれ自体で自己完結します。作業者が Slack を漁らなくても、隣の席に聞かなくても始められます。そして自己完結するチケットは、まさにAIエージェントが必要とするものです。

1.2 文脈:まず「なぜ」

文脈は最も頻繁に省略され、最も高い代償を払う部分です。「ボタンの色を青に変えてください」は指示であって文脈ではありません。作業者が知るべきはなぜです。

ブランドリニューアルで一次アクションの色が紫から青に変わりました(デザインシステム v3 参照)。このボタンは決済フローの主要 CTA なので新しい色に従う必要があります。

この一文があれば作業者は似た他のボタンも一緒に見るべきか判断でき、エージェントは「一次アクションの色」というトークンベースの変更なのか、単発のハードコードなのかを推論できます。

1.3 問題:症状ではなく事実

問題記述は観察可能な事実であるべきです。解釈や推測を混ぜないでください。

• 悪い:「ログインがたまにおかしい」
• 良い:「パスワードに + 記号を含むユーザーがログインすると 401 を受け取る。URL エンコードの欠落と推測されるが未確認。」

良いバージョンは再現条件(+ を含むパスワード)、観察された結果(401)、そして推測と事実の分離(「推測」「未確認」)をしています。

2章 · チェックボックス形式の受け入れ条件

受け入れ条件(Acceptance Criteria、AC)はチケットで最も重要な部分です。AC がやることは単純です。作業開始前に「完了」の定義を釘付けにすること。

2.1 なぜチェックボックスか

AC は散文ではなくチェックボックスのリストで書くべきです。理由は明確です。

## 受け入れ条件

- [ ] `+` を含むパスワードでログインすると 200 を返す
- [ ] `&`、`=`、空白を含むパスワードも同じく動作する
- [ ] 不正なパスワードは依然として 401 を返す(回帰防止)
- [ ] このケースをカバーする統合テストが追加される

チェックボックスが効く理由:

最後の行が肝です。エージェントは散文から「これくらいで十分だろう」を推論できません。しかし - [ ] X が Y を返す はそのまま検証ループになります。コードを書き、その行が真か確認し、違えばまた書きます。

2.2 良い AC の条件

良い AC 一行は以下を満たします。

• 検証可能 — 真偽を客観的に判定できる
• 観察可能な振る舞いを述べる — 実装ではなく結果を述べる
• 1つの事実だけを含む — 「かつ」で2つを束ねない

例の比較:

最後の行を見てください。「コードをきれいにする」は検証不可能です。AC ではなく作業ノートか別のリファクタリングチケットに出すべきです。

2.3 Given-When-Then のバリエーション

複雑な振る舞いは Given-When-Then 形式が曖昧さを減らします。

## 受け入れ条件

- [ ] **Given** カートに在庫切れの商品があるとき
      **When** 決済ボタンを押すと
      **Then** モーダル「在庫不足の商品があります」が出て決済は進行しない
- [ ] **Given** すべての商品の在庫が十分なとき
      **When** 決済ボタンを押すと
      **Then** 決済確認ページに移動する

この形式は人間にはシナリオを明確にし、エージェントにはほぼそのままテストコードの骨格を提供します。

3章 · スコープ設定 — 1チケット = 1 PR

良いチケット作成で最も強力なのに最も頻繁に無視される原則です。

1つのチケットは1つのレビュー可能な PR で終わるべきである。

3.1 「レビュー可能」の意味

レビュー可能な PR とは、1人が一度で最後まで読み、自信を持って承認できる diff です。経験則で変更行数 400 行前後、コアファイル 10 個前後。この線を超えるとレビュアーは読むのを諦めて「LGTM」を押します — するとレビューは無意味になります。

チケットがこのサイズに合わせられると、連鎖的に良いことが起きます。

最後の行が AI 時代の新しい理由です。巨大なチケットはエージェントのコンテキストを溢れさせます。作業の半ばで前半を「忘れて」一貫性を失います。小さなチケットは始めから終わりまで1つの文脈に入ります。

3.2 大きなチケットを分割する方法

「ユーザー認証の実装」はチケットではなくエピックです。分割が必要です。

エピック: ユーザー認証
├─ #101 メール/パスワードのサインアップ(DB スキーマ + エンドポイント)
├─ #102 ログイン + セッショントークン発行
├─ #103 パスワードリセットフロー(メール送信含む)
├─ #104 ログイン UI コンポーネント
└─ #105 認証ミドルウェアで保護ルートを適用

分割の基準:

• 垂直スライス優先 — 「バックエンド全部」のような水平分割より「サインアップ機能を最後まで」が良い
• 各スライスが独立デプロイ可能か — #102 が #101 なしで意味がないなら依存を明示
• 各スライスに自前の AC があるか — 無ければまだ大きすぎる

3.3 「隠れたスコープ」という罠

チケットのタイトルは小さく見えるのに本文がそっと大きくなる場合が最も危険です。

タイトル: ヘッダーにダークモードトグルを追加 本文: ...トグルを追加して、ついでにデザイントークンシステムも整理して、色変数を全部 CSS 変数に移行してください。

トグル1つが全社的な色移行に化けました。こうしたチケットは2つに割るべきです。トークン移行は別チケット、トグルはその上に依存として乗せます。

4章 · バグチケットのテンプレート

バグチケットには決まった形があります。空の欄が1つでもあると作業者は推測を始め、推測は時間を燃やします。

4.1 バグチケットの必須欄

4.2 Before / After

Before — 推測を強いるバグチケット:

タイトル: 決済ができない 決済ページでエラーが出ます。確認お願いします。

作業者が知らないこと:どの決済手段か、どの金額か、どのエラーか、どの環境か、常にか、再現手順は。このチケットは事実上「あなたが突き止めてください」です。

After — すぐデバッグできるバグチケット:

## 概要
クレジットカード決済で 5万円超の金額のとき 500 エラーが発生

## 再現手順
1. カートに 6万円分の商品を入れる
2. 決済ページに進み、クレジットカードを選択
3. カード情報を入力して「決済する」をクリック

## 期待結果
決済承認後、注文完了ページに移動

## 実際の結果
トースト「一時的なエラーが発生しました」、決済未完了

## 環境
- デプロイ環境: production
- ブラウザ: Chrome 124、Safari 17 どちらも再現
- 発生開始: 5月12日 14:00 のデプロイ以降と推測

## 証拠
- サーバーログ: `PaymentError: amount exceeds limit (50000)`
- リクエスト ID: req_8f2a91c
- スクリーンショット: 添付

## 頻度
5万円超のとき常に再現(100%)

After バージョンは作業者が30秒で原因仮説を立てられます — 5月12日のデプロイで入った金額上限の検証が疑わしいです。エージェントならログのエラーメッセージとリクエスト ID を手がかりに、すぐ該当のコードパスにたどり着きます。

4.3 スタックトレースはコードブロックに

スタックトレースやログを貼るときは必ずコードブロックの中に入れてください。散文にそのまま貼ると読みにくく、トラッカーによってはマークダウンで崩れます。

## 証拠

```
TypeError: Cannot read properties of undefined (reading 'id')
    at resolveUser (src/auth/resolver.ts:42:18)
    at processRequest (src/server/handler.ts:118:9)
```

ファイルパスと行番号(src/auth/resolver.ts:42)が入ったトレースは、人間にもエージェントにも最高の入り口です。

5章 · 機能チケットのテンプレート

機能チケットはバグチケットと構造が違います。バグは「何が壊れたか」を扱いますが、機能は「何を新しく作るか」を扱います。核は受け入れ条件とスコープ境界です。

5.1 機能チケットの必須欄

スコープ外 の欄を特に強調します。何をやらないかを書くことは、何をやるかを書くのと同じくらい強力です。この欄が隠れたスコープの増殖を止めます。

5.2 Before / After

Before — 曖昧な機能チケット:

タイトル: 検索機能を改善 検索がもっと賢くなってほしいです。ユーザーが欲しいものをうまく見つけられません。

「賢い」「うまく」は検証不可能です。作業者はオートコンプリートを作るのか、タイポ修正を入れるのか、ランキングを変えるのか分かりません。

After — 作業可能な機能チケット:

## 背景
商品検索でユーザーが正確な商品名を知らないと結果が0件になる。
先週の検索ログで 38% が0件結果で終わった。

## 提案する変更
検索語に対して商品名の部分一致 + タイポ修正(編集距離 1)を適用する。

## 受け入れ条件
- [ ] 「マックブック」で検索すると「MacBook Pro 16」が結果に含まれる
- [ ] 「マックブック」のタイポ「マッグブック」で検索しても同じ結果が出る
- [ ] 結果がないとき「こんな商品はどうですか」の推薦5件が表示される
- [ ] 検索 API の p95 レスポンスタイムが 300ms 以下を維持する

## スコープ外
- 音声検索
- 検索結果のランキングアルゴリズムの変更(別チケット #210)
- カテゴリフィルタ UI

## 制約
- 既存の `/api/search` エンドポイントのレスポンススキーマは変えない
- 検索インデックスの再インデックスは無停止で可能であること

## 参照
- デザイン: Figma リンク
- 0件結果の分析: Notion ドキュメントリンク
- 関連コード: `src/search/query-builder.ts`

After バージョンは作業者に明確な終了線を与え、エージェントには各 AC がそのまま検証ステップになります。スコープ外 の欄は「ランキングも一緒にやるべきか」という30分の悩みを0秒にします。

6章 · AI-ready チケット vs 人間専用チケット

すべてのチケットがエージェントに渡すのに向いているわけではありません。あるチケットは人間だけが扱うべきで、あるチケットは少し手を入れればエージェントが終えられます。この区別をラベルで明示すれば、チーム全体が同じ基準を共有します。

6.1 何がチケットを AI-ready にするか

核となる洞察:AI-ready チケットは実はよく書けたチケットです。別の種ではありません。人間のために明確に書けばエージェントも扱えます。逆に、エージェントが迷うチケットは普通、人間の新人も迷います。

6.2 ラベル戦略

トラッカーのラベルで意図をシグナルしてください。例のスキーム:

needs-refinement が重要です。このラベルは「このチケットはまだ誰にも渡せない」という正直なシグナルです。グルーミング会議でこのラベルが付いたチケットを磨き、agent-ready または human-only に卒業させます。

6.3 エージェントに渡す前のチェック

チケットに agent-ready を付ける前に確認すること:

- [ ] 受け入れ条件がすべてチェックボックスで検証可能か
- [ ] 関連するコードパス/ファイルが参照に書かれているか
- [ ] 「スコープ外」の欄で境界が引かれているか
- [ ] 既存コードのどのパターンに従うべきか明示したか
- [ ] 結果を確認するテスト方法があるか
- [ ] 高リスク領域(認証、決済、マイグレーション)ではないか

この6行を通過しなければ、まだ needs-refinement です。

7章 · リンク、トレーサビリティ、Issue グラフ

チケットは孤島ではありません。良いチームのトラッカーはグラフです — チケット同士が、そしてコードと、つながっています。

7.1 つなぐべき5つのリンク

Closes #102 のようなキーワードは GitHub/GitLab で PR マージ時に Issue を自動で閉じてくれます。この小さな習慣1つが「閉じ忘れた」ゾンビチケットをなくします。

7.2 トレーサビリティの価値

6か月後に誰かが奇妙なコードを見つけたとします。トレーサビリティが生きていれば、経路はこうです。

奇妙なコード一行
  -> git blame -> コミット
  -> コミット -> PR
  -> PR -> チケット #102
  -> チケット -> エピック + RFC リンク
  -> 「ああ、だからこう書いたのか」

この鎖が切れていると、そのコードは永遠に謎のまま残り、誰も触るのが怖くなります。チケット-PR-コミットのリンクは、未来の自分への手紙です。

7.3 AIエージェントと Issue グラフ

エージェントに #102 を任せるとき、依存リンクがあればエージェントは #101 の成果物(スキーマ、エンドポイント)を文脈として引き込めます。リンクがなければエージェントは #102 だけを孤島として見て、すでに存在するものを作り直したり一貫性を壊したりします。Issue グラフはエージェントのコンテキスト地図です。

8章 · チケット作成のアンチパターン

良いチケットの反対側を知れば、より速く良くなります。現場で最も頻繁に見るアンチパターンです。

8.1 曖昧な動詞

「改善する」「最適化する」「整理する」「もっと良くする」 — これらの動詞は検証不可能です。常に測定可能な結果に変えてください。

8.2 隠れたスコープ

3章で扱いました。タイトルは小さいのに本文がそっと大きくなるパターン。「ついでに」「合わせて」が本文に見えたら、ほぼ常に別チケットのシグナルです。

8.3 受け入れ条件の欠落

「完了」の定義なしに始まるチケット。終わりに「これで全部できたんですよね」会議が開かれます。AC のないチケットは始めるべきではありません。

8.4 1チケットに複数の作業

「ログインのバグを直して、サインアップ UI も整えて、ロギングも追加」のように束ねられたチケット。レビューが不可能で、1つが詰まると全部が詰まります。

8.5 解決策を指示して問題を隠す

「users テーブルにインデックスを追加」 — なぜ?どのクエリが遅い?問題がなければ作業者はそれが正しい解決策か検証できず、より良い解決策を提案することもできません。問題を書き、解決策は提案程度に。

8.6 アンチパターン要約表

9章 · コピーして使うテンプレート集

以下のテンプレートをリポジトリの .github/ISSUE_TEMPLATE/ またはトラッカーのテンプレートにそのまま入れてください。

9.1 バグレポートのテンプレート

## 概要
{一文で何が壊れたか}

## 再現手順
1.
2.
3.

## 期待結果
{何が起きるべきだったか}

## 実際の結果
{何が起きたか}

## 環境
- デプロイ環境: {production / staging / local}
- ブラウザ/ランタイム: {バージョン}
- アプリのバージョン/コミット: {バージョンまたは SHA}

## 証拠
```
{スタックトレース / ログ / リクエスト ID}
```
{スクリーンショット添付}

## 頻度
{常に / たまに(N回中M回) / 一度}

9.2 機能リクエストのテンプレート

## 背景
{どのユーザー/ビジネスの問題を解くか、可能ならデータとともに}

## 提案する変更
{何を作るか — 実装ではなく振る舞いのレベルで}

## 受け入れ条件
- [ ] {検証可能な結果 1}
- [ ] {検証可能な結果 2}
- [ ] {回帰防止の項目}
- [ ] {テスト追加の項目}

## スコープ外
- {今回やらないこと 1}
- {今回やらないこと 2}

## 制約
- {パフォーマンス予算 / 互換性 / 触ってはいけないもの}

## 参照
- デザイン:
- 関連コード:
- 先行チケット:

9.3 タスクのテンプレート(リファクタリング・雑務用)

## 何を
{一文の作業説明}

## なぜ
{なぜ今これが必要か}

## 受け入れ条件
- [ ] {結果 1}
- [ ] {既存の振る舞いが壊れないことを確認する項目}

## スコープ外
- {拡張の誘惑を明示的にブロック}

## 参照
-

9.4 エージェント委任チェックリスト(PR の説明またはチケットコメント用)

## エージェント委任前の点検
- [ ] AC がすべてチェックボックスで検証可能
- [ ] 関連するコードパスが参照に明示されている
- [ ] 「スコープ外」で境界が引かれている
- [ ] 従うべき既存パターンを指定
- [ ] 結果の検証方法(テスト)がある
- [ ] 高リスク領域ではない(認証/決済/マイグレーション)

ラベル: {agent-ready / agent-assisted / human-only / needs-refinement}

9.5 テンプレート運用のヒント

• テンプレートは出発点であって足かせではありません。使わない欄は削除し、5つの構成要素(文脈・問題・AC・制約・参照)は残してください。
• 欄の中の {placeholder} ガイド文は、作成者が埋めながら削除すべきです。空のまま提出された {placeholder} は、それ自体で「このチケットはまだ未完成」というシグナルです。
• チームの Wiki に良いチケットの例3つを貼り付けておいてください。新人もエージェントも、それを基準点にします。

エピローグ — 良いチケットは未来への投資である

チケットはソフトウェアで最もレバレッジの大きい文書です。一度よく書けば、それが生んだコードと同じだけ長く価値を出します。一度うまく書けなければ、その費用をすべての後続ステージが分け合います — そして AI 時代には、その費用は2倍です。人間には「聞けばいい」というセーフティネットがありましたが、エージェントにとってはチケットがすべてだからです。

しかし結論は単純です。人間のために明確に書けばエージェントも扱えます。 別の技術ではなく、同じ技術への2倍の報酬です。

良いチケットのチェックリスト

1. 文脈 — 「なぜ今これをやるのか」が一段落で書かれている
2. 問題 — 症状ではなく観察可能な事実として書かれている
3. 受け入れ条件 — 検証可能なチェックボックスのリストである
4. 1つの事実 — AC 一行に「かつ」で2つを束ねていない
5. スコープ — 1つのレビュー可能な PR で終わるサイズである
6. スコープ外 — 今回やらないことが明示されている
7. 制約 — 触ってはいけないもの、パフォーマンス予算が書かれている
8. 参照 — 関連するコードパス、デザイン、先行チケットがリンクされている
9. トレーサビリティ — エピック・依存チケット・PR が双方向につながっている
10. ラベル — agent-ready / human-only などで意図がシグナルされている

避けるべきアンチパターン

• 曖昧な動詞 — 「改善/最適化/整理」を測定可能な結果に変える
• 隠れたスコープ — 「ついでに」が見えたらチケットを割る
• AC の欠落 — 「完了」の定義なしに作業を始めない
• 複数の作業 — 1チケットに複数の PR 分を束ねない
• 解決策の指示 — 問題を隠して解決策だけを書かない
• 空の placeholder — テンプレートのガイド文を削除しないまま提出しない

次回予告

次の記事は**「良い PR 説明の書き方 — レビュアーとエージェントが5分で承認するようにする方法」**です。チケットが作業の入力なら、PR の説明は作業の出力です。何をなぜ変えたか、どう検証したか、レビュアーがどこから見るべきかを書く技術 — そしてそれが AI コードレビュアーともどう噛み合うかを扱います。

良いチケットを書くのにかかる10分は、間違って作ったものを戻す10時間を防ぎます。その10分は、未来のチームと未来の自分への投資です。