Bagaimanakah anda menggunakan AI untuk menulis dokumentasi teknikal, changelog, dan mesej commit?

Question

Accepted Answer

Kuncinya ialah **memberikan bahan mentah kepada AI** — diff atau kod sebenar — dan meminta format khusus dan konvensional. AI bagus dalam menukar perubahan kepada prosa yang jelas, tetapi hanya jika ia dapat melihat apa yang berubah.

## Aliran kerja yang baik

- **Berikannya diff**, bukan penerangan yang kabur: `git diff --staged | <your AI tool>`.
- **Minta konvensi yang diketahui** — Conventional Commits (`feat:`, `fix:`, `docs:`), atau gaya changelog anda.
- **Kekalkan ia tepat dan padat** — baris subjek di bawah ~50 aksara, badan yang menerangkan *mengapa*.
- **Sahkan ia sepadan dengan diff.** AI boleh mencipta perubahan yang tiada di sana; anda mesti menyemak.

## Sebelum / selepas

Mesej commit yang malas:

```text
fixed stuff
```

Selepas memberikan diff dan meminta gaya 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.
```

Versi kedua memberitahu penyemak *apa* yang berubah dan *mengapa* — jauh lebih berguna dalam `git log` enam bulan kemudian.

## Apa yang AI bagus di sini

- **Docstring dan README** — meringkaskan tujuan dan penggunaan modul.
- **Changelog** — mengumpulkan commit ke dalam bahagian Added / Fixed / Changed.
- **Mesej commit** — menukar diff kepada mesej konvensional yang kemas.

Sentiasa **baca hasilnya berbanding perubahan sebenar**. AI tidak tahu niat anda — hanya kod yang ditunjukkan kepadanya — jadi ia boleh tersilap melabel `fix` sebagai `feat` atau mendakwa kesan sampingan yang tidak wujud.

## Mengapa ia penting

Mesej commit dan dokumentasi yang baik ialah cara diri masa depan anda dan rakan sepasukan memahami *mengapa* kod itu wujud. AI menghapuskan geseran menulisnya dengan baik, tetapi ketepatan terletak pada anda: changelog yang salah dengan yakin adalah lebih teruk daripada tiada langsung. Berikannya input sebenar, tuntut konvensi sebenar, dan sahkan sebelum anda melakukan commit.