你如何使用 AI 来编写技术文档、changelog 和 commit messages？

Question

Accepted Answer

关键是**给 AI 提供原始材料** — 实际的 diff 或代码 — 并要求它使用特定的、规范的格式。AI 擅长将一个改动转化为清晰的文字，但前提是它能看到实际改变了什么。

## 一个好的工作流

- **给它提供 diff**，而不是模糊的描述：`git diff --staged | <your AI tool>`。
- **要求遵循已知的约定** — Conventional Commits（`feat:`、`fix:`、`docs:`），或你的 changelog 风格。
- **保持准确和简洁** — subject line 约 50 字符以内，body 部分解释*为什么*。
- **验证它与 diff 匹配。** AI 可能会捏造实际不存在的改动；你必须检查。

## 之前/之后

一条懒散的 commit message：

```text
fixed stuff
```

在提供 diff 并要求使用 Conventional Commit 风格后：

```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.
```

第二个版本告诉 reviewer *改动了什么*以及*为什么* — 在六个月后的 `git log` 中要有用得多。

## AI 在这里擅长什么

- **Docstrings 和 READMEs** — 总结模块的目的和用法。
- **Changelogs** — 将 commits 分组为 Added / Fixed / Changed 部分。
- **Commit messages** — 将 diff 转化为简洁的、规范的 message。

始终**根据实际改动检查结果**。AI 不知道你的意图 — 它只能看到给它的代码 — 所以它可能会将 `fix` 错误标记为 `feat`，或声称存在实际并不存在的副作用。

## 为什么这很重要

好的 commit messages 和文档是你和你的团队成员理解*为什么*代码存在的方式。AI 消除了写好这些内容的摩擦，但准确性由你负责：一份充满自信的错误 changelog 比没有更糟。提供真实的输入，要求遵循真实的约定，并在提交前进行验证。