概要

仕様を残す方法として、

Markdownで方針や例外をまとめること
コードコメントで処理の意図を説明すること

自体は、開発で知られているやり方です。

今回の記事は

この二つを組み合わせてみるのはどうでしょうか？

という提案をする趣旨の記事です。

前書き

AIにコードを直してもらったとき、以前決めた仕様を忘れたように

ここはおかしいから直しておこう

と、意図した動作まで変更されることが私個人の経験としてあります。

今まで指示したプロンプトを全て反映して欲しい！

というのは、実行に移そうとすると入力トークンが大きくなる可能性があります。

そのため、すべての指示を毎回反映するのが難しくなるのは、ある程度やむを得ない面があると思います。

最近出た、圧倒的に安いと感じる gpt-6-luna を使って開発している中でも、かなり前に決めた仕様が会話の流れから抜けてしまうことがあります。

一般的ではなくても、ユーザーにとって分かりやすく使いやすい

と考えて採用した仕様が、AIには不具合に見える場合があります。

仕様一覧とコードコメントを併用する

仕様を残す方法として、下記の2種類の手法をカスタム指示で指示します。

仕様一覧のMarkdown作成：作業方針を決めるときに、プロジェクト全体の例外的な仕様を把握する手がかりにする
コード内コメント記載：該当箇所を書き換えるとき、意図した仕様だと気付く可能性を上げる

Markdownには仕様の背景や理由をまとめ、コード側にはその箇所で必要な意図を短く記します。二つは同じ説明を重複させるためではなく、AIが仕様を見落としやすい異なる場面を補うものです。

この方式のカスタム指示の例

たとえば、次のようなカスタム指示を使えます。

Document unusual specs in a Markdown file and add nearby code comments.

仕様一覧が作業時に参照され、コードコメントが変更箇所の近くにあれば、意図しない変更を防ぐ手がかりになります。

もちろん、これだけで変更を完全に防げるわけではありませんが、会話履歴だけに頼らず、両方の方法を試す価値はあると思います。

おまけ：私のカスタム記事

参考のため、現時点の私のカスタム指示を載せておきます。

ハルシネーション回避よりも、実用性を重視しています。

私の現時点のカスタム指示(797文字)

* Use polite Japanese.
* Flag logical issues first; ignore typos.
* For HTML/CSS, use @layer; put unlayered CSS in base, comment each layer’s changes, and avoid !important.
* Use Base64 for embedded HTML if escaping may break it.
* Use String.raw for HTML regex.
* Build the site in one HTML file.
* Don't reformat minified HTML.
* Prefer URL fragments over query params in HTML when possible.
* Don't use localStorage; use IndexedDB instead.
* Keep header images simple and text-based.
* If sending multiple files, zip them and send only the ZIP.
* Please zip any JS files before sending.
* For files, just give one download link; no preview needed.
* Avoid trademark-like words.
* On mobile, be as detailed as on desktop.
* Document unusual specs in a Markdown file and add nearby code comments.