git-workflow

従来型コミット、セマンティックなブランチ命名、PR テンプレート、マージ戦略を網羅する包括的な git ワークフロースキルです。すべてのプロジェクトで一貫性を強制し、レビューの負荷を軽減し、変更履歴の自動生成を可能にします。

このスキルは worktree-manager-skill（並行開発を処理するスキル）を補完し、それらのワークツリー内でのコミットと PR の規約を提供します。

<quick_start> 従来型コミットの形式:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

タイプ: feat、fix、docs、style、refactor、perf、test、build、ci、chore

例:

git commit -m "feat(auth): add JWT refresh token rotation

Implements automatic token refresh 5 minutes before expiry.
Closes #123"

ブランチ命名: <type>/<ticket>-<short-description>

git checkout -b feat/AUTH-123-refresh-tokens

</quick_start>

<success_criteria> Git ワークフローは次の場合に成功です:

• すべてのコミットが従来型コミット形式に従っている
• ブランチ名が <type>/<ticket>-<description> パターンに従っている
• PR が概要、テスト計画、チェックリストを含む一貫したテンプレートを使用している
• マージ戦略がブランチタイプと一致している（機能には squash、リリースには merge）
• コミット履歴が変更内容を明確に物語っている
• チームの明示的な合意なしに main/master への force push を行わない </success_criteria>

<conventional_commits>

従来型コミットの仕様

conventionalcommits.org に基づいています

コミットタイプ

タイプ	説明	変更履歴セクション	バージョンアップ
feat	新機能	機能	マイナー
fix	バグ修正	バグ修正	パッチ
docs	ドキュメントのみ	-	-
style	フォーマット、コード変更なし	-	-
refactor	コード変更、機能/修正なし	-	-
perf	パフォーマンス改善	パフォーマンス	パッチ
test	テストの追加/修正	-	-
build	ビルドシステムの変更	-	-
ci	CI 構成	-	-
chore	メンテナンス作業	-	-

破壊的変更

タイプの後に ! を追加するか、フッターに BREAKING CHANGE: を追加します:

# Method 1: Bang notation
feat(api)!: change response format to JSON:API

# Method 2: Footer
feat(api): change response format to JSON:API

BREAKING CHANGE: Response structure changed from { data } to { data, meta, links }

スコープのガイドライン

スコープは任意ですが推奨されます。プロジェクトごとに一貫したスコープを使用してください:

# Good scopes
auth, api, ui, db, config, deps

# Examples
feat(auth): add OAuth2 support
fix(api): handle null response from external service
docs(readme): add installation instructions

コミットメッセージの構造

<type>(<scope>): <subject>
│       │         │
│       │         └─> Summary in present tense, no period, max 50 chars
│       │
│       └─> Component/area affected (optional)
│
└─> Type: feat, fix, docs, style, refactor, perf, test, build, ci, chore

[blank line]
[optional body - explain what and why, not how]
[blank line]
[optional footer(s) - breaking changes, issue references]

良い例と悪い例

悪い例	良い例	理由
fixed bug	fix(auth): prevent token expiry race condition	具体的でスコープがある
updates	refactor(api): extract validation middleware	変更内容を説明している
WIP	feat(ui): add loading skeleton (WIP)	意図が明確
misc changes	chore: update dependencies to latest versions	タイプがあり意味がある
</conventional_commits>

<branch_naming>

ブランチ命名規約

パターン

<type>/<ticket-id>-<short-description>

ブランチタイプ

タイプ	用途	例
feat/	新機能	feat/AUTH-123-oauth-login
fix/	バグ修正	fix/API-456-null-response
hotfix/	緊急の本番修正	hotfix/PROD-789-payment-failure
docs/	ドキュメント	docs/README-update
refactor/	コードの再構成	refactor/cleanup-legacy-api
test/	テストの追加	test/add-auth-integration
chore/	メンテナンス	chore/update-deps
release/	リリースブランチ	release/v2.1.0

命名規則

1. 小文字のみ - feat/auth-login であり feat/Auth-Login ではない
2. スペースにはハイフン - fix/null-response であり fix/null_response ではない
3. 可能な場合はチケット ID を含める - feat/JIRA-123-description
4. 短く保つ - タイプ接頭辞を含めて最大 50 文字
5. 説明的にする - feat/user-profile であり feat/feature1 ではない

保護されたブランチ

ブランチ	保護	マージ戦略
main	PR + レビューを必須	Squash マージ
develop	PR を必須	マージコミット
release/*	PR + CI 通過を必須	マージコミット

例

# Feature work
git checkout -b feat/PROJ-123-user-authentication

# Bug fix
git checkout -b fix/PROJ-456-login-redirect-loop

# Hotfix (from main)
git checkout main
git checkout -b hotfix/PROJ-789-payment-timeout

# Documentation
git checkout -b docs/api-endpoint-reference

# Chore
git checkout -b chore/upgrade-node-20

</branch_naming>

<pr_templates>

プルリクエストのテンプレート

標準 PR テンプレート

## Summary

-

## Type of Change

- [ ] feat: New feature
- [ ] fix: Bug fix
- [ ] docs: Documentation
- [ ] refactor: Code restructuring
- [ ] test: Test coverage
- [ ] chore: Maintenance

## Test Plan

- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing completed

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated (if needed)
- [ ] No console.log or debug code
- [ ] No sensitive data exposed

## Related Issues

Closes #

## Screenshots

最小限の PR テンプレート（小さな変更向け）

## What


## Why


## Test


Closes #

リリース PR テンプレート

## Release v{VERSION}

### Changes Since Last Release


### Breaking Changes


### Migration Guide


### Deployment Notes


### Rollback Plan

</pr_templates>

<merge_strategies>

マージ戦略

ブランチタイプ別の戦略

ブランチタイプ	戦略	理由
feat/*	スカッシュ	main にクリーンな単一コミットを作成します
fix/*	スカッシュ	main にクリーンな単一コミットを作成します
hotfix/*	マージ	hotfix の履歴を保持します
release/*	マージ	release のコミットを保持します
refactor/*	スカッシュまたはリベース	コミット数によって異なります

Git コマンド

# Squash merge (recommended for features)
git checkout main
git merge --squash feat/my-feature
git commit -m "feat(scope): description"

# Merge commit (for releases)
git checkout main
git merge --no-ff release/v2.0.0

# Rebase (for clean linear history)
git checkout feat/my-feature
git rebase main
git checkout main
git merge feat/my-feature

# Interactive rebase (clean up before PR)
git rebase -i HEAD~5

スカッシュとマージの判断ツリー

Is this a feature or fix branch?
├── Yes → Squash merge
└── No → Is this a release or hotfix?
    ├── Yes → Merge commit (preserve history)
    └── No → Consider context

</merge_strategies>

<commit_hooks>

コミットフック（任意の強制）

commitlint の設定

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor',
      'perf', 'test', 'build', 'ci', 'chore'
    ]],
    'scope-case': [2, 'always', 'lowercase'],
    'subject-case': [2, 'always', 'sentence-case'],
    'subject-max-length': [2, 'always', 72],
    'body-max-line-length': [2, 'always', 100],
  }
};

Husky のセットアップ

# Install
npm install -D husky @commitlint/cli @commitlint/config-conventional

# Initialize
npx husky init

# Add commit-msg hook
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg

コミット前のチェック

# .husky/pre-commit
#!/bin/sh
npm run lint
npm run test -- --run

</commit_hooks>

## セマンティックバージョニング

バージョン形式

MAJOR.MINOR.PATCH
  │     │     │
  │     │     └─> Bug fixes (fix:)
  │     │
  │     └─> New features (feat:)
  │
  └─> Breaking changes (feat!: or BREAKING CHANGE:)

バージョン更新ルール

コミットタイプ	例	バージョンの変更
fix:	fix: null check	1.0.0 → 1.0.1
feat:	feat: new endpoint	1.0.1 → 1.1.0
feat!:	feat!: new API format	1.1.0 → 2.0.0

自動バージョニング

# Using standard-version
npx standard-version

# Using semantic-release (CI)
npx semantic-release

<workflow_examples>

ワークフローの完全な例

機能開発

# 1. Create feature branch
git checkout main
git pull origin main
git checkout -b feat/PROJ-123-user-profile

# 2. Make commits (conventional format)
git add .
git commit -m "feat(ui): add profile avatar component"
git commit -m "feat(api): add profile update endpoint"
git commit -m "test(profile): add integration tests"

# 3. Rebase if needed
git fetch origin
git rebase origin/main

# 4. Push and create PR
git push -u origin feat/PROJ-123-user-profile
gh pr create --title "feat(profile): add user profile page" \
  --body "## Summary\n- Add profile avatar\n- Add update endpoint\n\nCloses #123"

# 5. After approval, squash merge
gh pr merge --squash

ホットフィックスのフロー

# 1. Create from main
git checkout main
git pull origin main
git checkout -b hotfix/PROD-456-payment-timeout

# 2. Fix and commit
git commit -m "fix(payment): increase timeout to 30s

Production payments timing out during high load.
Closes PROD-456"

# 3. Push and merge (no squash to preserve hotfix history)
git push -u origin hotfix/PROD-456-payment-timeout
gh pr create --title "hotfix: payment timeout" --body "Emergency fix"
gh pr merge --merge

リリースのフロー

# 1. Create release branch
git checkout develop
git checkout -b release/v2.1.0

# 2. Version bump
npm version minor
git commit -am "chore(release): v2.1.0"

# 3. Merge to main
git checkout main
git merge --no-ff release/v2.1.0
git tag v2.1.0

# 4. Back-merge to develop
git checkout develop
git merge release/v2.1.0

</workflow_examples>

## Git ワークフローのチェックリスト

各コミットの前：

• コミットメッセージが規約に沿った形式になっている
• タイプが正確である（feat/fix/docs など）
• スコープが影響を受けるコンポーネントと一致している
• 件名が命令形で、現在形になっている
• 破壊的変更に ! またはフッターで印が付いている

PR の作成前：

• ブランチ名が規約に沿っている
• 最新の main/develop にリベースされている
• すべてのコミットに意味がある（fixup をスカッシュする）
• PR テンプレートに漏れなく記入されている
• 関連する issue がリンクされている

マージ前：

• すべての CI チェックに合格している
• 必要なレビューを受けている
• マージコンフリクトがない
• 適切なマージ戦略が選択されている

詳細なパターンについては、適切なリファレンスを読み込んでください：

トピック	リファレンスファイル	読み込むタイミング
コミットメッセージの例	reference/commit-examples.md	さらに例が必要な場合
PR テンプレートの種類	reference/pr-templates.md	プロジェクト固有のテンプレートを確認する場合
Git フックのセットアップ	reference/git-hooks.md	強制ルールを設定する場合

読み込み方法： 特定のトピックを指定するか、コンテキストから必要な内容を確認してください。

結果サイドカーの出力

~/.claude/skill-analytics/last-outcome-git-workflow.json に書き込みます： {"ts":"[UTC ISO8601]","skill":"git-workflow","version":"1.0.0","variant":"default","status":"[success|partial|error]","runtime_ms":[ms],"metrics":{"commits_created":[n],"prs_opened":[n],"branches_managed":[n]},"error":null,"session_id":"[YYYY-MM-DD]"}