ベストプラクティス

kizamiを最大限に活用するための実践的なヒントです。

← ドキュメントトップへ

コード変更とドキュメントは同じコミットに含める

最も重要な習慣：ADRは、それが記録するコード変更と同じコミットに含めましょう。

# 良い例 — 意思決定と実装がgitの履歴上で紐付く
git add internal/db/db.go docs/decisions/2026-03-12-use-connection-pooling.md
git commit -m "feat: データベースアクセスにコネクションプールを追加"

# 避けるべき例 — 意思決定と実装が分離してしまう
git commit -m "feat: コネクションプールを追加"
git commit -m "docs: コネクションプールのADRを追加"

同じコミットに含めると、任意のソースファイルに対して git log を実行したときに、ADRとコード変更が一緒に現れます。数ヶ月後の調査がずっと楽になります。

## Related Files セクションは、kizami blame と kizami audit の精度を左右します。正確に書けば書くほど、後から得られる価値が大きくなります。

## Related Files

internal/db/db.go
internal/db/pool.go
internal/config/config.go

kizamiは kizami adr 実行時にステージ済みファイルを自動挿入しますが、コミット前に必ずリストを確認・補完しましょう。ステージしたファイルだけでなく、概念的に関連するファイルも含めるとよいでしょう。

ディレクトリを指定することもできます — その場合、配下の全ファイルが対象になります：

## Related Files

internal/db/

kizami review を定期的に実行する

kizami review を、チームの定期レトロや sprint planning の一部として実行しましょう。長期間更新されていないADRを洗い出し、「これは今でも正確か？」という問いかけのきっかけになります。

kizami review
# 180日以上更新されていないドキュメントを一覧表示（設定で変更可能）

特に、サードパーティサービス・インフラ・技術選定に関するADRは時間とともに変わりやすいため、定期的な見直しが効果的です。

CIで乖離検出を自動化する

kizami audit は自動実行したときに最も効果を発揮します。kizami init を使ってGitHub Actionsワークフローを生成しましょう：

kizami init
# → .github/workflows/kizami-audit.yml が生成される

生成されたワークフローは毎週実行され、乖離が検出された場合はGitHub Issueを自動作成します。手動で実行し忘れても見落としが発生しません。

auditの対象はMarkdownドキュメントだけでなく .kizami サイドカーファイルも含まれるため、サイドカーで管理しているMarkdown以外のファイルも自動的にカバーされます。

ADRは短く書く

誰にも読まれないADRは、ないよりも悪いです。2分以内で読める分量を目指しましょう。

  • Context: 問題を説明する2〜4文
  • Decision: 何を決めたかを述べる1〜3文
  • Consequences: トレードオフの箇条書き

目標は核心となる洞察を記録することです — コードだけから再現するのに30分かかる情報を残すこと。詳細な設計の探求には kizami design を使いましょう。

確信が持てる前にADRを書く

ADRを書く最良のタイミングは、決定を下した後ではなく、検討中です。2つのアプローチを比較しているなら、選択する前にADRの下書きをしましょう — トレードオフを言語化することで、決定そのものが楽になることがあります。

作成中のADRには Status: Draft を使います。

コードレビュー時に kizami blame を活用する

ファイルを変更するPRをレビューする際、そのファイルを参照しているADRを確認しましょう：

kizami blame internal/auth/middleware.go

現在の設計を形作った意思決定の歴史を浮かび上がらせます。過去の意思決定の意図を損なう変更を、mainに取り込む前に発見する効果的な方法です。

よくある質問

Q: ADRの数が多すぎる、ということはある？

固定の上限はありませんが、週に1〜2件以上作成しているなら、小さすぎる判断もADRにしていないか見直しましょう。目安：将来の開発者がコードのコンテキストだけからなぜを理解できるなら、ADRは不要かもしれません。

Q: 過去の決定を後からADRにしてもよい？

はい。特に今もコードベースに影響し続けている決定については、後から作成するADRは非常に価値があります。Date フィールドには実際の決定日（たとえ数年前でも）を使い、Context セクションに後から記録したものであることを明記しましょう。

Q: コードに関係しない決定にも使える？

はい。チームのプロセス・APIコントラクト・デプロイ戦略・データ保持ポリシーなど、保存する価値があり関連ファイルが存在する（あるいは省略できる）あらゆる重要な決定にkizamiは使えます。

Q: 古いADRに同意できない場合は？

削除しないでください — 新しい方向性を説明する新しいADRを作成し、古いADRを Superseded by <slug> にマークしましょう。意見の相違とその解決の歴史自体が、貴重なコンテキストです。