technical docs、changelog、commit message を書くために AI をどう使いますか？

Question

Accepted Answer

重要なのは、AI に**raw material**、つまり実際の diff や code を渡し、specific で conventional な format を求めることです。AI は change を clear prose に変えるのが得意ですが、何が変わったかを見られる場合に限ります。

## 良い workflow

- vague な説明ではなく **diff を渡す**: `git diff --staged | <your AI tool>`。
- **known convention を求める** — Conventional Commits（`feat:`、`fix:`、`docs:`）や project の changelog style。
- **accurate and concise に保つ** — subject line はおよそ 50 chars 未満、body は *why* を説明。
- **diff と一致しているか verify する**。AI は実際にはない change を invent することがあります。

## Before / after

怠い commit message:

```text
fixed stuff
```

diff を渡して Conventional Commit style を求めた後:

```text
fix(auth): reject expired tokens in session middleware

The middleware only checked token signature, not expiry, so expired
sessions stayed valid. Added an `exp` claim check that returns 401.
```

2 つ目は reviewer に *what* と *why* を伝えます。6 か月後の `git log` でもはるかに有用です。

## ここで AI が得意なこと

- **Docstrings and READMEs** — module の purpose と usage を summarize。
- **Changelogs** — commit を Added / Fixed / Changed に group。
- **Commit messages** — diff を clean で conventional な message に変える。

常に **actual change と照合して読む**こと。AI はあなたの intent を知りません。見せられた code だけを知っています。そのため `fix` を `feat` と誤分類したり、実際にはない side effect を主張したりします。

## なぜ重要なのか

良い commit message と docs は、future self と teammate が code の *why* を理解する方法です。AI はそれを書く friction を下げますが、accuracy はあなたの責任です。自信満々に間違った changelog は、ないより悪いことがあります。real input を渡し、real convention を求め、commit 前に verify します。