write-issue

GitHub issue の作成と維持

tldraw/tldraw における issue の標準。

タイトルの標準

• 文頭のみ大文字 - 最初の単語と固有名詞のみを大文字にする
• タイププレフィックスを付けない - Bug:、Feature:、[Bug] などではなく、GitHub の issue タイプを使用する
• 機能強化には命令形 - 「Add padding option」であって「Adding padding option」ではない
• バグには説明的に - 症状を記述する:「Arrow bindings break with rotated shapes」
• 具体的に - issue 本文を開かなくても読めるようにする

良いタイトル

• Arrow bindings break with rotated shapes
• Add padding option to zoomToFit method
• Pinch zoom resets selection on Safari

悪いタイトル

• Bug: arrow bug（プレフィックス、曖昧）
• [Feature] Add new feature（プレフィックス、曖昧）
• Not working（曖昧）

タイトル整理の変換

1. プレフィックスを削除: Bug: X → X
2. 大文字化を修正: Add Padding Option → Add padding option
3. 命令形を使用: Adding feature X → Add feature X
4. 具体的にする: Problem → [Describe the actual problem]
5. 英語以外のタイトルを英語に翻訳する

issue タイプ

issue の作成後に GitHub GraphQL API 経由で設定します（--type フラグは確実にはサポートされていません）:

タイプ	用途
Bug	期待どおりに動作していないもの
Feature	新機能または改善
Example	新しい SDK サンプルのリクエスト
Task	内部タスクまたは雑務

ラベル

メタデータとして控えめに使用してください（issue ごとに 1～2 個）。分類のためではありません。

一般的なラベル

ラベル	用途
good first issue	新規参加者向けに範囲が明確な issue
More Info Needed	追加情報が必要
sdk	tldraw SDK に影響する
dotcom	tldraw.com に関連する
a11y	アクセシビリティ
performance	パフォーマンス改善
api	API の変更

自動化ラベル（手動で適用しないでください）

keep、stale、update-snapshots、publish-packages、major、minor、skip-release、デプロイトリガー

issue 本文の標準

バグ報告

1. 何が問題なのかの明確な説明
2. 再現手順
3. 期待される動作と実際の動作
4. 関連する場合の環境の詳細（ブラウザ、OS、バージョン）
5. 該当する場合のスクリーンショット／録画

機能リクエスト

1. 問題の記述 - これはどのような問題を解決しますか？
2. 提案する解決策 - どのように動作すべきですか？
3. 検討した代替案
4. ユースケース

サンプルのリクエスト

1. どの API／パターンを実演するか
2. なぜそれが有用なのか
3. 提案するアプローチ
4. どのサンプルカテゴリに属するか

エージェントが作成した issue (問題の読み戻しと未解決の質問)

/issue スキルによって作成された issue は、短い問いかけを通じてユーザーの意図を捉えます。そのため、逐語的な説明の下に見出しのない読み戻しの段落が入り、その後に未解決の質問と、最後に確信度のステータス行が続きます。

• 問題の読み戻し - 問題、期待される動作、およびスコープに対するエージェントの解釈を述べる、簡潔で見出しのない段落です。ユーザーが簡単に訂正できるものである必要があります。製品に即した内容に保ってください。コードブロック、長い実装分析、ファイルパス、関数名、行番号、およびユーザーが明示的に求めない限り修正手順は含めないでください。
• 未解決の質問 - 意図やコンテキストにおける具体的な不足点のうち、まだユーザーに尋ねる価値があるものを番号付きリストにしたものです。ユーザーが回答すると、各質問の下に回答が書かれ、読み戻しは各ラウンドで改訂されます。Critical: が前に付いた質問は真にブロッカーであり、回答されるまでその issue に取り組むことはできません。ほとんどの issue にはこれがありません。ユーザーが回答しないことを選んだ非クリティカルな質問は、_Deferred by user; not blocking implementation._ とマークされます。
• 確信度の行 - セクション見出しではなく、下部にあるプレーンテキストの行で、たとえば Confidence: 84%, ready to get started. や Confidence: 42%, still need more information. のようになります。これは、最終的な修正に対する確信度ではなく、その issue に取り組むのに十分なユーザーの意図とコンテキストがあるかどうかを反映します。

問いかけが完了したら、読み戻し、未解決の質問、および確信度の行は issue に残してください。回答済みの質問は、その issue を生み出した議論の記録であるため、削除せずに残してください。質問はその場で解決済みとしてマークし、最終的な読み戻しは issue の簡潔な問題記述として保持してください。

トリアージワークフロー

新しい issue

1. 対応するのに十分な情報があることを確認する
2. 適切な issue タイプを設定する
3. 必要に応じてタイトルを整理する
4. 詳細が不足している場合は More Info Needed ラベルとコメントを追加する
5. 適切であれば good first issue を追加する

古い issue

1. まだ関連があるか確認する
2. もはや該当しない場合はクローズする
3. 開いたままにすべき場合は keep ラベルを追加する
4. 情報待ちの場合は更新を依頼する

重要

• issue が AI ツールに直接関係する場合を除き、AI の帰属表示を決して含めないでください
• 説明にタイトルケースを決して使用しないでください - センテンスケースを使用してください