Scan to join WeChat groupGitHub Issue Improver
Overview
このスキルはGitHub Issueの品質を自動的に改善します。雑な記述のIssueを分析し、構造化されたAIが作業しやすい形式に変換します。Issueの種類を自動分類し、適切なテンプレートを適用して不足情報を指摘します。
Quick Start
基本的な使い方
# 単一のIssueを改善（コメントとして提案を追加）
python scripts/issue_improver.py --repo owner/repo --issue 123
# Issueを直接更新
python scripts/issue_improver.py --repo owner/repo --issue 123 --mode update --update-title --update-body --update-labels
# 複数のIssueを一括改善
python scripts/issue_improver.py --repo owner/repo --issues 123 124 125 --mode comment
# どのような改善がされるか確認（実際には変更しない）
python scripts/issue_improver.py --repo owner/repo --issue 123 --dry-run
# JSONファイルから一括適用
python scripts/apply_improvements.py --repo owner/repo apply --improvements-file improvements.json
# JSONファイルから適用内容をプレビュー
python scripts/apply_improvements.py --repo owner/repo --dry-run apply --improvements-file improvements.json
環境設定
方法1: .envファイルを使用（推奨）
# .envファイルを作成
echo "GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" >> .env
# .envファイルは自動的に読み込まれます
方法2: 環境変数
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
方法3: 直接指定
python scripts/issue_improver.py --repo owner/repo --issue 123 --token your_token
🆕 新機能
1. 自動.envファイル読み込み
.envファイルを複数の場所から自動検出- スクリプト実行ディレクトリ、カレントディレクトリ、プロジェクトルート
- python-dotenvがなくても動作（推奨）
2. 完全なDry-runモード
--dry-runで完全にオフラインで動作- GitHub APIコールなしで改善案を生成
- Token不要でテスト可能
3. JSONベースの一括改善
apply_improvements.pyでJSONファイルから改善を適用- 改善テンプレートの生成機能
- レビューと承認ワークフローに対応
Core Capabilities
1. Issue自動分析
- 種類分類: bug, feature, documentation, test, refactorなどを自動判定
- 重要度評価: critical, high, medium, lowの優先度を自動設定
- コンポーネント抽出: frontend, backend, apiなどの関連コンポーネントを特定
- 品質スコアリング: Issueの品質を0-1のスコアで評価
2. 標準化されたタイトル生成
- Coventional Commitsスタイルのプレフィックス付与
元: login fails
改善: Fix: Login fails with invalid credentials
3. 構造化された本文生成
- 種類に応じたテンプレート自動適用
- 不足情報の指摘と入力枠の追加
- マークダウン形式での整形
バグ報告の例:
## Bug Description
[自動生成された説明]
## Steps to Reproduce
1.
2.
3.
## Expected Behavior
[ここに期待される動作を記述]
## Actual Behavior
[ここに実際の動作を記述]
## Environment
- OS:
- Browser:
- Version:
機能要望の例:
## Feature Description
[自動生成された説明]
## Use Case
[ユーザーストーリーを記述]
## Acceptance Criteria
- [ ]
- [ ]
- [ ]
## Proposed Solution
[解決策の提案]
4. 適切なラベル付与
- 種類ラベル:
bug,feature,documentation - 優先度ラベル:
priority: critical,priority: high - エリアラベル:
area: frontend,area: backend
5. 不足情報の指摘
- 再現手順の欠如
- 期待する動作の記述漏れ
- 環境情報の不足
- 受け入れ条件の未設定
Workflow Decision Tree
1. 改善モードの選択
Commentモード（推奨）
- Issueに改善提案をコメントとして追加
- 元の内容を保持しながら提案を提示
- チームメンバーが改善内容を確認して適用可能
python scripts/issue_improver.py --repo owner/repo --issue 123 --mode comment
Updateモード
- Issueを直接更新
- 即座に改善が適用される
- 注意：元の内容が変更されます
python scripts/issue_improver.py --repo owner/repo --issue 123 --mode update --update-title --update-body
2. 更新対象の選択
--update-title: タイトルを標準化--update-body: 本文を構造化--update-labels: ラベルを適切に設定- 何も指定しない場合: 分析結果のみを表示
3. バッチ処理
複数のIssueを一括処理：
python scripts/issue_improver.py --repo owner/repo --issues 123 124 125 --mode comment
Scripts Usage
issue_improver.py
メインの改善スクリプト。GitHub API連携とIssue分析の統括。
# 基本構文
python scripts/issue_improver.py --repo OWNER/REPO --issue NUMBER [OPTIONS]
# 主なオプション
--mode {update,comment} # 改善適用モード（デフォルト: comment）
--update-title # タイトルを更新
--update-body # 本文を更新
--update-labels # ラベルを更新
--dry-run # 適用せずに改善内容を確認
--output {json,text} # 出力形式（デフォルト: text）
issue_analyzer.py
Issue内容を分析し、改善案を生成。
# Issue分析テスト
python scripts/issue_analyzer.py --title "bug found" --body "login is broken" --output json
github_client.py
GitHub APIとの連携処理。
# Issue取得テスト
python scripts/github_client.py --repo owner/repo --issue 123 --action get
# コメント追加テスト
python scripts/github_client.py --repo owner/repo --issue 123 --action comment --message "Test comment"
apply_improvements.py 🆕
JSONファイルからの改善適用とテンプレート生成。
# 改善テンプレートを生成
python scripts/apply_improvements.py --repo owner/repo template --issues 123 124 125
# JSONファイルから改善を適用
python scripts/apply_improvements.py --repo owner/repo apply --improvements-file improvements.json
# プレビュー（dry-run）
python scripts/apply_improvements.py --repo owner/repo --dry-run apply --improvements-file improvements.json
テスト用スクリプト
test_token_loading.py 🆕
Token読み込み機能のテスト。
# トークン読み込みのテスト
python test_token_loading.py
References
references/issue_templates.md
Issue種類ごとのテンプレートと品質ガイドライン。
- バグ報告、機能要望、ドキュメント更新のテンプレート
- タイトル命名規則
- ラベル付けガイドライン
- 品質チェックリスト
references/api_reference.md
GitHub Issues APIの詳細なリファレンス。
- 認証方法と必要な権限
- 主要なAPIエンドポイントと使用例
- レート制限とエラーハンドリング
- ベストプラクティス
Integration with Miyabi Framework
このスキルはMiyabiフレームワークの識学理論65ラベル体系と連携可能：
自動ラベル分類
- IssueAgentのラベル体系準拠
type:*,priority:*,state:*ラベルの自動付与- カテゴリー別自動分類：
frontend,backend,infra
Agent連携
- IssueAgent: Issue作成時の自動分析とラベル付与
- CodeGenAgent: 改善されたIssueからのコード生成
- PRAgent: Issue改善履歴を含むPR自動生成
Use Cases
1. 新規Issueの品質向上
# 新しく作られた雑なIssueを改善
python scripts/issue_improver.py --repo myorg/myrepo --issue 456 --mode update --update-title --update-body
2. バックログの一括整理
# 古い未整理Issueを一括改善
python scripts/issue_improver.py --repo myorg/myrepo --issues 100 101 102 103 --mode comment
3. Issueテンプレートの適用
# 特定のプロジェクトでIssue標準化を実施
for issue in $(gh issue list --repo myorg/myrepo --state open --limit 20 --json number | jq -r '.[].number'); do
python scripts/issue_improver.py --repo myorg/myrepo --issue $issue --mode update --update-labels
done
4. CI/CD連携
GitHub Actionsでの自動実行例：
name: Improve New Issues
on:
issues:
types: [opened]
jobs:
improve-issue:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up Python
uses: actions/setup-python@v2
with:
python-version: '3.9'
- name: Improve issue
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
python scripts/issue_improver.py --repo ${{ github.repository }} --issue ${{ github.event.issue.number }} --mode comment
Error Handling
共通エラーと対策
401 Unauthorized
- 原因: GITHUB_TOKENが無効または期限切れ
- 対策: 新しいPATを生成して設定
403 Rate Limit Exceeded
- 原因: APIレート制限超過
- 対策: 1時間待機するか、認証済みトークンを使用
404 Not Found
- 原因: リポジトリまたはIssueが存在しない
- 対策: リポジトリ名とIssue番号を確認
トラブルシューティング
# デバッグ用詳細出力
python scripts/issue_improver.py --repo owner/repo --issue 123 --output json
# 接続テスト
python scripts/github_client.py --repo owner/repo --issue 123 --action get
このスキルを使うことで、GitHub Issueの品質が大幅に向上し、開発チームの作業効率が改善されます。特にAIによるIssue処理の前処理として最適です。