semantic-git

Semantic Git

Conventional Commit 形式の簡潔なメッセージを使い、アトミックなコミットで Git のコミットを管理します。

このスキルは zagi 対応で、AI IDE（Cursor など）で適切に動作するよう設計されています。

ツール

• 推奨：zagi（エージェント向けのより優れた Git インターフェース）。
  • 次のいずれかに当てはまる場合、zagi がインストールされているものとします。
    • シェルで git が zagi にエイリアス設定されている、または
    • zagi バイナリが利用可能である。
  • 判断に迷う場合は、git が zagi 互換である可能性を考慮し、特殊なフラグの使用を避けてください。
  • zagi が利用可能な場合でも、通常の git コマンドを生成し、git → zagi の連携に処理を任せてください。
• 代替手段：zagi が利用できない場合は通常の git を使用します。

使用する場面

• Git に変更をコミットするとき
• コミットするファイルをステージングするとき
• コミットメッセージを作成するとき
• アトミックなコミットを管理するとき
• 変更をプッシュする前

基本原則

• アトミックなコミット：関連する変更をまとめてステージングし、コミットします。テストは実装コードと一緒にコミットします。
• ユーザーの確認：コミットする前、および次のコミットに進む前に、必ずユーザーに確認します。
• Conventional Commits 形式：別途指示がない限り、Conventional Commits 形式のコミットメッセージを使用します（feat、fix など）。
• 簡潔なメッセージ：メッセージは簡潔で要点を押さえたものにします。変更が複雑でない限り、説明は省略します。
• コマンドの透明性：実行する正確な git コマンド（エイリアス／ラッパーを介して zagi が処理する場合もあります）を必ず提示し、ユーザーに次のどちらを希望するか尋ねます。
  • 手動で実行する
  • エージェントに実行させる

コミットメッセージの形式

<type>[optional scope]: <subject>

[optional body]

[optional footer(s)]

タイプ

• feat：新機能
• fix：バグ修正
• docs：ドキュメントのみの変更
• style：コードの意味に影響しない変更（空白、フォーマット、セミコロンの不足など）
• refactor：バグを修正するものでも、機能を追加するものでもないコード変更
• perf：パフォーマンスを改善するコード変更
• test：不足しているテストの追加、または既存テストの修正
• build：ビルドシステムまたは外部依存関係に影響する変更
• ci：CI 設定ファイルとスクリプトの変更
• chore：メンテナンスタスク（ビルドタスク、依存関係などの更新。本番コードの変更を伴わないもの）
• revert：以前のコミットの取り消し

破壊的変更

破壊的変更を示すには、タイプ／スコープの後に ! を付けます。

• feat!: add new API
• fix(api)!: change response format

件名

• 命令形を使います。「added feature」や「adds feature」ではなく「add feature」とします。
• 先頭の文字は小文字にします（固有名詞で始まる場合を除く）。
• 文末にピリオドを付けません。
• 可能な限り 72 文字以内にします。

本文とフッター

• 変更が複雑であるか、説明が必要な場合を除き、本文は省略します。
• 必要な場合は簡潔にし、Issue、PR、ドキュメントを参照します。
• 破壊的変更にはフッターを使用します：BREAKING CHANGE: <description>

ワークフロー

1. アトミックな変更を実装する：コードとテストを一緒に変更します。
   • テストのみの変更には test: を使用します。
2. CI チェックを実行する：ステージングする前に、型チェック、テスト、リンティングがすべて通ることを確認します。
   • CI コマンドがある場合は、単一のコマンド（例：pnpm ci、npm run ci、just ci）を優先します。
   • CI コマンドがない場合は、チェックを個別に実行します（型チェック、テスト、リンティング）。
   • いずれかのチェックに失敗した場合は、停止して報告し、先に進まないでください。
3. アトミックな変更をステージングする：関連ファイル（実装とテスト）をまとめます。
4. コミットメッセージを提案する：変更内容に基づいて、Conventional Commits 形式のコミットメッセージを生成します。
5. コマンドを生成する：

   • git（zagi などのエイリアスやラッパーの場合もあります）を使った、明示的なシェルコマンドを作成します。例：

     git add path/to/file1 path/to/file2
     GIT_AUTHOR_DATE="YYYY-MM-DD HH:MM:SS" \
     GIT_COMMITTER_DATE="YYYY-MM-DD HH:MM:SS" \
     git commit -m "feat: add feature"
     

   • これらのコマンドは必ずユーザーに順番どおりに表示します。

6. 実行方法を確認する：
   • 以下のどちらを希望するか、ユーザーに確認します。
     • コマンドをコピーして貼り付け、自分で実行する
     • エージェントに実行させる
   • 明示的な承認を得てからコマンドを実行します。
7. コミットする：
   • 実行する場合は、表示したコマンドをそのまま正確に実行します。
   • タイムスタンプを遡らせる指定や追加フラグに関するユーザーの指示に従います。
8. 次のコミット：
   • 次の変更をステージングする前に、前のコミットが完了し、内容を理解していることをユーザーに確認します。

自動化モード

ユーザーが「X まで続けて」または「X まで自動化して」と依頼した場合：

• アトミックなコミットを自動的に進めますが、コマンドは引き続き表示します。
• コミットごとに：
  • ステージングとコミットのコマンドを提示します。
  • ユーザーの自動化依頼に応じて、任意でコマンドを自動実行します。
• X に達したら、確認を求めます。
• X には、特定のファイル、機能の完了、テストの合格などを指定できます。

停止して確認する状況

以下の操作を行う前に、停止してユーザーに確認します。

• 型チェックの無効化を追加する（@ts-ignore、# type: ignore など）。
• 抑制設定を追加する（ESLint disable、pylint disable など）。
• any 型または同様の型エスケープを使用する。
• 実装の進め方が不確かな場合。
• 要件が不明確な場合。
• 破壊的な git 操作（reset --hard、checkout .、clean -f、push --force）を提案する場合。より安全な代替手段を優先し、リスクを説明します。

例

シンプルな機能変更または動作変更：

feat: add user authentication

スコープを限定した機能：

feat(api): add user endpoint

バグ修正：

fix: resolve memory leak in cache

破壊的変更：

feat!: migrate to new API version

テストのみの変更：

test: improve unit tests for auth service

リファクタリング（動作の変更なし）：

refactor: extract validation logic into separate function

複雑な変更（本文あり）：

feat(api): add pagination support

Implements cursor-based pagination for large datasets.
See docs/api/pagination.md for details.

参考資料

詳しいガイダンスについては、以下を参照してください。

• references/conventional-commits.md – コミット形式と例
• references/ci-verification.md – CI チェックのパターンと検証
• references/co-authors.md – Co-Authored-By トレーラーの処理と zagi による共同作成者情報の削除