今までエージェントがした作業内容の確認をステージしながら行っていた関係で「コミットは私が行うので、明示的な指示がない限り絶対にコミットしないように」と伝えてきたのだけど、ローカル専用の作業を進めるブランチと対外的に見せるブランチを分ける、きれいなブランチはエージェントに作らせるという考え方はどうかな? と思った結果、説明が必要になった。それで書いた説明文章を共有しておきます。
あくまで自論、しかもバージョン1なので異議は認めます (つまり、ご意見をおまちしております)。
コミットの単位
コミットの適切な単位は「分割すれば分割するほどよい」とか「まとめればまとめるほどよい」のような単純なルールではありません。
- まとめすぎた場合: 「このコミットの中に、確認するべき内容が本当にあるのか」「あるのだとすればそれはどこだ」という困難が発生する。
- 分割しすぎた場合: 「このコミットも関係ない」を増やし「どこに目的のコミットがあるのか」という困難が発生する。
考え方:
- 一つの目的のための作業は一つのコミットにまとめたほうが、ツリーの枝を無駄に複雑にしなくて済む。
- 一つの目的でも差分が多すぎる場合は分野毎での分割を検討する。分野 (例: 表示部分とバックエンドロジック部分など) でコミットを分け、ファイル数を適切に保つ。
- 違う目的の作業でも一つの「些細な変更」と言える単位になるなら、履歴全体としての簡素さに寄与できる。ただし後述の revert 容易性 を失うなら分割する。
revert 容易性の観点:
コミットは「revert できる単位」であることにも着目する。revert したい可能性のある部分をコミット境界に分離できそうな場合、つまり関係ない変更を巻き込まない形にできる場合は分割を積極的に検討する。
コミットメッセージ
コミットメッセージは、歴史 (Git 履歴) を追う人が「そのコミットでの差分を詳細に見る必要があるか」を判断するための情報を書くべき。
記述するべき内容:
- Why ― 何のための作業か
- What ― どんな変更をしたのか
歴史をざっと追う人の視点を忘れないこと。複雑な文章は可能な限り避け、箇条書きに近い書き方で「詳細を追うべきか、それとも見なくていいか」の判断に役立つ情報を提供する。