Gentle AI — ブランチ & PR スキル は何をしますか？
使用タイミング
以下の作業が必要な場合に、このスキルをロードしてください。
- 新しい修正や機能のためのブランチを作成する
- Gentleman-Programming/gentle-ai でプルリクエストをオープンする
- レビューのために変更を準備する
重要なルール
- すべての PR は承認済み Issue にリンクする必要があります — PR 本文に
Closes/Fixes/Resolves #<N>を含め、その Issue にはstatus:approvedラベルが付与されている必要があります。これがない PR は CI によって自動的に却下されます。 - 通常の
type:*分類 — CI は、type ラベルがゼロまたは複数の場合を拒否します。正規の Issue 作成ワークフロー契約に従ってください。現在の直接的な人間の指示が正確なターゲット/アクションを指定し、ターゲットホストの機能が検証され、1 つの bounded mutation とターゲットホストの読み戻しを使用する必要があります。それ以外の場合は、変更を行わずに待機します。 - 保護されたポリシーラベル —
status:approvedまたはsize:exceptionラベルを追加または削除するには、ターゲットホストリポジトリのメンテナーまたはリポジトリ承認者からの検証済みポリシー権限 (正確なターゲット/アクションに対するもの)、および認証されたアクターのターゲットホストviewerPermissionがMAINTAINまたはADMINであることが必要です。size:exceptionには、さらに予算超過の理由を文書化する必要があります。 - 400行のレビュー予算 — PR の変更行数 (
additions + deletions) は 400 行以内に保つか、size:exceptionラベルに必要な理由を文書化します。 - 自動チェックが合格している必要があります — 下記の自動チェックテーブルを参照してください。
Co-Authored-Byトレーラーは禁止 — コミットに AI の帰属を決して追加しないでください。- main/master への force-push は禁止 — 保護されたブランチです。
ワークフロー
1. Issue に status:approved が付いていることを確認する
gh issue view <N> --repo Gentleman-Programming/gentle-ai
2. 以下の命名規則に従い、main からブランチを作成する
3. 仕様と設計に従って変更を実装する
4. ローカルでチェックを実行する（フォーマット + 単体テスト + E2E）
5. Conventional Commits 形式でコミットする
6. Issue を参照する PR をオープンする
→ PR 本文に 1 つの type:* 結果を宣言する
→ PR ラベル変更の前に、正規の Issue 作成ワークフロー契約を使用する
→ テンプレートを使用して PR 本文を記入する
7. マージ前にすべての自動チェックが合格していること
ブランチ命名規則
ブランチ名は以下のパターンに一致する必要があります:
^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$
| タイプ | 例 |
|---|---|
feat/ | feat/user-login |
fix/ | fix/duplicate-observation-insert |
docs/ | docs/api-reference-update |
refactor/ | refactor/extract-query-sanitizer |
chore/ | chore/bump-bubbletea-v0.26 |
style/ | style/fix-linter-warnings |
perf/ | perf/optimize-catalog-loading |
test/ | test/add-pipeline-coverage |
build/ | build/update-goreleaser-config |
ci/ | ci/add-e2e-docker-job |
revert/ | revert/undo-model-picker-change |
ルール:
- すべて小文字
- 区切り文字にはハイフン、ドット、アンダースコアを使用 (スペース、大文字は不可)
- 説明は短く説明的にすること
PR 本文フォーマット
PR 本文は、.github/PULL_REQUEST_TEMPLATE.md のテンプレートに従う必要があります。特記がない限り、すべてのセクションが必要です。
## 🔗 リンクされた Issue
Closes #<N>
## 🏷️ PR タイプ
- [ ] `type:bug` — バグ修正 (問題を修正する非互換性のない変更)
- [ ] `type:feature` — 新機能 (機能を追加する非互換性のない変更)
- [ ] `type:docs` — ドキュメントのみ
- [ ] `type:refactor` — コードリファクタリング (機能変更なし)
- [ ] `type:chore` — ビルド、CI、またはツールの変更
- [ ] `type:breaking-change` — 互換性を破る変更
## 📝 概要
<!-- この PR が何を行い、なぜそれを行うのかを明確に説明してください。 -->
## 📂 変更内容
| ファイル / エリア | 変更内容 |
|-------------|-------------|
| `path/to/file` | 簡単な説明 |
## 🧪 テスト計画
**単体テスト**
\`\`\`bash
go test ./...
\`\`\`
**Go フォーマット**
\`\`\`bash
go run ./internal/gofmtcheck
\`\`\`
**E2E テスト** (Docker が必要)
\`\`\`bash
cd e2e && ./docker-test.sh
\`\`\`
- [ ] 単体テスト合格 (`go test ./...`)
- [ ] Go フォーマット合格 (`go run ./internal/gofmtcheck`)
- [ ] E2E テスト合格 (`cd e2e && ./docker-test.sh`)
- [ ] ローカルで手動テスト済み
## ✅ コントリビューター確認リスト
- [ ] PR は `status:approved` の Issue にリンクされている
- [ ] PR の変更行数は 400 行以内、または `size:exception` の理由と検証済みポリシー権限が文書化されている
- [ ] API 読み戻しにより、この PR に適切な `type:*` ラベルが正確に 1 つ適用されていることを確認
- [ ] 単体テスト合格 (`go test ./...`)
- [ ] E2E テスト合格 (`cd e2e && ./docker-test.sh`)
- [ ] 必要に応じてドキュメントを更新した
- [ ] コミットは Conventional Commits 形式に従っている
- [ ] コミットに `Co-Authored-By` トレーラーは含まれていない
自動チェック
これらのチェックはすべての PR で実行され、マージ前にすべて合格する必要があります:
| チェック | 検証内容 | 修正方法 |
|---|---|---|
| PR の認知的負荷をチェック | PR の変更行数 (additions + deletions) が 400 行以内、または size:exception ラベルが付与されている | PR を分割するか、size:exception の理由を文書化し、その正規ワークフローアクションの前にポリシー権限を確認する |
| Issue 参照をチェック | PR 本文に Closes/Fixes/Resolves #N が含まれている | PR 本文に Closes #<N> を追加する |
Issue に status:approved があるかをチェック | リンクされた Issue に必要なラベルが付与されている | 現在の直接的な指示とターゲットホストの機能が正確なアクションを許可する場合にのみ、正規の Issue 作成ワークフロー契約を使用する。それ以外の場合は待機する |
PR に type:* ラベルがあるかをチェック | PR に type:* ラベルが正確に 1 つ適用されている | 現在の直接的な指示とターゲットホストの機能が正確なアクションを許可する場合にのみ、正規の Issue 作成ワークフロー契約を使用する。それ以外の場合は待機する |
| 単体テスト | go test ./... が合格すること | プッシュ前に失敗するテストを修正する |
| Go フォーマット | go run ./internal/gofmtcheck が合格すること | プッシュ前にフォーマット違反の Go ファイルを修正する |
| E2E テスト | cd e2e && ./docker-test.sh が合格すること | プッシュ前に失敗する E2E シナリオを修正する |
Conventional Commits
コミットメッセージは以下のパターンに一致する必要があります:
^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+
フォーマット
<type>(<optional-scope>)!: <description>
[optional body]
[optional footer]
許可されるタイプ
| タイプ | 目的 | PR ラベル |
|---|---|---|
feat | 新機能 | type:feature |
fix | バグ修正 | type:bug |
docs | ドキュメントのみ | type:docs |
refactor | コード変更 (動作変更なし) | type:refactor |
chore | メンテナンス、依存関係、ツール | type:chore |
style | フォーマット、リンター (ロジック変更なし) | type:chore |
perf | パフォーマンス改善 | type:feature |
test | テストの追加または更新 | type:chore |
build | ビルドシステムまたは外部依存関係 | type:chore |
ci | CI 設定 | type:chore |
revert | 以前のコミットを取り消す | 取り消されたタイプに一致 |
互換性を破る変更
タイプ/スコープの後に ! を追加します:
feat(cli)!: rename --config flag to --config-file
BREAKING CHANGE: the --config flag has been renamed to --config-file.
互換性を破る変更は、type:breaking-change ラベルにマッピングされます。
例
feat(tui): add progress bar to installation steps
fix(agent): correct Claude Code detection on macOS
docs: update contributing guide
chore(deps): bump bubbletea to v0.26
refactor(pipeline): extract step executor
style: fix linter warnings in catalog package
perf(system): cache OS detection result
test(installer): add coverage for catalog step execution
build: update goreleaser config for arm64
ci: split unit and e2e test jobs
revert: undo model picker redesign
feat(cli)!: change default config path
コマンド
セットアップ
# 開始前に Issue が承認されていることを確認する
gh issue view <N> --repo Gentleman-Programming/gentle-ai
# ブランチを作成する
git checkout main && git pull
git checkout -b fix/<short-description>
ローカルテスト
# 単体テスト
go test ./...
# Go フォーマット
go run ./internal/gofmtcheck
# 単体テスト — 特定のパッケージ
go test ./internal/tui/...
# 単体テスト — 詳細出力
go test -v ./...
# E2E テスト (Docker が実行中である必要があります)
cd e2e && ./docker-test.sh
PR をオープンする
gh pr create \
--repo Gentleman-Programming/gentle-ai \
--title "fix(agent): correct Claude Code detection on Linux" \
--body "$(cat <<'EOF'
## 🔗 リンクされた Issue
Closes #42
## 🏷️ PR タイプ
- [x] \`type:bug\` — バグ修正 (非互換性のない変更)
## 📝 概要
Claude Code バイナリの検出が Linux 上で HOME が設定されていない場合に失敗する問題を修正します。
## 📂 変更内容
| ファイル / エリア | 変更内容 |
|-------------|-------------|
| \`internal/agents/claude.go\` | HOME 環境変数のフォールバックを追加 |
## 🧪 テスト計画
- [x] 単体テスト合格 (\`go test ./...\`)
- [x] E2E テスト合格 (\`cd e2e && ./docker-test.sh\`)
- [x] ローカルで手動テスト済み
## ✅ コントリビューター確認リスト
- [x] PR は \`status:approved\` の Issue にリンクされている
- [x] PR の変更行数は 400 行以内、または \`size:exception\` の理由と検証済みポリシー権限が文書化されている
- [x] API 読み戻しにより、この PR に適切な \`type:*\` ラベルが正確に 1 つ適用されていることを確認
- [x] 単体テスト合格 (\`go test ./...\`)
- [x] E2E テスト合格 (\`cd e2e && ./docker-test.sh\`)
- [x] 必要に応じてドキュメントを更新した
- [x] コミットは Conventional Commits 形式に従っている
- [x] コミットに \`Co-Authored-By\` トレーラーは含まれていない
EOF
)"
PR ステータスの確認
gh pr checks --repo Gentleman-Programming/gentle-ai <PR-number>
gh pr view --repo Gentleman-Programming/gentle-ai <PR-number>