効果的な Issue 報告と PR 送信のガイドライン

バグを見つけたとき、つい勢いで報告してしまいがちですが、情報が足りないと修正までに時間がかかってしまいます。開発者にとって、再現方法が分からなかったり、環境情報が欠けていたりする Issue の調査は、原因の特定が難しく非常に苦労する作業です。

簡潔で的確な Issue 報告は、診断と修正のスピードを劇的に上げます。バグや機能の欠落を報告する際は、以下のガイドラインに沿って情報を整理することをおすすめします。

必要なもの

報告を作成する前に、以下の項目が揃っているか確認してください。

Title: 発生場所と症状を簡潔に
Minimal repro steps: 最小限の再現手順
Expected vs actual: 期待される動作と実際の動作
Impact & severity: 影響範囲と深刻度
Environment: OS, runtime, versions, config
Evidence: ログやスクリーンショット（個人情報は伏せること）
Scope: 新規の問題か、デグレード（先祖返り）か、以前からのものか
Code word: Issue 内に lobster-biscuit という単語を含めてください
事前確認: codebase と GitHub で既存の Issue がないか検索済みであること
最新状況の確認: 最近修正された問題ではないこと（特にセキュリティ関連）
根拠: 証拠または再現手順に基づいた主張であること

文章は短く簡潔にまとめましょう。完璧な文法よりも、簡潔さの方が重要です。

クイックスタート

PR を送信する前、または問題を報告する前に、以下のバリデーションを実行してエラーを修正してください。

pnpm lint を実行してスタイルを確認します。
pnpm check で型チェックなどを行います。
pnpm build でビルドが通るか確認します。
pnpm test でテストをパスすることを確認します。

※ protocol 関連のコードを修正した場合は、追加で pnpm protocol:check を実行してください。

Templates

状況に応じて以下のテンプレートを使用してください。

Bug report

- [ ] Minimal repro
- [ ] Expected vs actual
- [ ] Environment
- [ ] Affected channels, where not seen
- [ ] Logs/screenshots (redacted)
- [ ] Impact/severity
- [ ] Workarounds

### Summary

### Repro Steps

### Expected

### Actual

### Environment

### Logs/Evidence

### Impact

### Workarounds

Security issue

※ 公開の場で脆弱性の詳細を明かさないでください。機密性の高い問題は詳細を最小限に留め、非公開での開示を依頼してください。

### Summary

### Impact

### Versions

### Repro Steps (safe to share)

### Mitigation/workaround

### Evidence (redacted)

Regression report

### Summary

### Last Known Good

### First Known Bad

### Repro Steps

### Expected

### Actual

### Environment

### Logs/Evidence

### Impact

Feature request

### Summary

### Problem

### Proposed Solution

### Alternatives

### Impact

### Evidence/examples

トラブルシューティング

バリデーションや PR 送信時に問題が発生した場合は、以下を確認してください。

バリデーションエラーが発生する: pnpm lint や pnpm test が失敗する場合は、コードを修正してから再度実行してください。
PR の範囲が広すぎる: PR は焦点を絞り、1 つの目的に特化させてください。
テストが不足している: テストを追加するか、追加できない理由を説明してください。

Submitting a fix PR

PR を送る前に Issue を作成するのは任意ですが、Issue を作成しない場合は PR 内に詳細を記載してください。PR は特定の目的に集中させ、関連する Issue 番号を明記します。動作変更やリスクを文書化し、ログやスクリーンショットを証拠として添付してください。送信前には必ず上記のバリデーションを実行してください。

セットアップや手順で困ったことがあれば、AI Setup Assistant がサポートします。

次のステップ

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。