どうもおはようございます、「zenncast」パーソナリティのマイクです。
今日は二千二十六年八月七日、金曜日の朝七時をまわったところですね。みなさん、いかがお過ごしでしょうか。通勤・通学中の方も、これから一日が始まるよ〜という方も、ゆるっとお付き合いください。
この「zenncast」では、エンジニアのみなさんに刺さりそうな、Zenn のトレンド記事をピックアップしてご紹介していきます。今日はどんな知見に出会えるのか、一緒に見ていきましょう。
さて今日は、全部で五本の記事をご紹介していきます。どれも「AI時代の開発どうしてく？」みたいなテーマが共通していて、がっつり考えさせられるラインナップになっています。それぞれ、できるだけ噛み砕いてお話ししていきますね。
まず一つ目。
これは「CLI ツールを AI エージェントと仲良くさせるには、どう設計するといいのか」という、かなり実践的なお話です。
ポイントは、コマンドラインツールのヘルプとかログの中に、「coding agent 向けメッセージ」を最初から仕込んでおく、という発想なんですね。
つまり、人間ユーザーだけじゃなくて、GitHub Copilot みたいなエージェントがこの CLI を触ってくることを前提にしておく。
具体的には、「AI はいきなり危ないコマンドを実行しないで、まず docs コマンドを叩いてから質問に答えてね」と、ヘルプやログで誘導しておきます。
たとえば「このコマンドは対話が必要なので、人間に実行してもらってね」とか、「secret は絶対に標準出力やログに出さないよ」といったポリシーも、はっきり書いておく。
ドキュメント自体は、リポジトリの中でトピックごとに Markdown で管理していて、その説明文を YAML の description に書いておくんですが、この description を「エージェントにも伝わりやすい要約」として設計するのがミソです。
ここで面白いのが、人間用とエージェント用のドキュメントを分けないってところ。同じ文章を、人も AI も読めるようにしておく。二重管理を避けつつ、両方に優しい形にするわけですね。
さらに、`docs list` とか `docs show <name>` みたいなサブコマンドを用意しておいて、ドキュメントの一覧と本文を、CLI からいつでも引っ張り出せるようにしておく。
このドキュメントは実行ファイルに埋め込んでおいて、CLI のバージョンとドキュメントがずれないようにしているのも、かなり堅実です。
README や `--help`, `--version`、それからエラーメッセージにも、この docs コマンドへの導線をいっぱい仕込んでおく。そうすることで、エージェントが自律的に「お、このツールには docs コマンドがあるぞ」と気づいて、Web検索に行く前に `ghtkn docs` を叩いてくれるようになる、という実験結果が出ているんですね。
さらに、Agent Skill も「一個だけ」に絞る。
その一個のスキルの中身は、単に docs コマンドを呼ぶだけにしておくことで、メンテナンスを極限まで軽くして、CLI 本体とのバージョンずれも抑える設計になっています。
実際に動かしてみると、導線さえ十分あれば、エージェントはちゃんと docs を読みに行って、Web検索より先に「正しい使い方」を学んでからトラブルシュートしてくれる、と。
「AI 時代の CLI ドキュメント設計ってこうだよね」という、一つの答えを見せてくれている記事でした。
。。.。。.。.
続いて二つ目。
こちらは、Google Labs が出している「DESIGN.md」というデザイン仕様ファイルを、オピニオン強めに解説・検証した記事です。
DESIGN.md って何かというと、プロジェクトごとに「色」「フォント」「デザインの意図」みたいなものを書き残しておくファイルなんですね。
AI に UI を作らせると、毎回色味やフォントが微妙に違っちゃう、あの問題を防ぎましょう、というアイデアです。
筆者はまず、「DESIGN.md という発想そのものは有効だ」と評価しています。
特に、色やフォントの値が毎回ブレないようにするとか、WCAG のコントラストチェックに使えるとか、Tailwind や CSS 変数の出力先としても便利、というあたりは実際に役立つと。
ただ、致命的なのが「DESIGN.md に書いた仕様どおりに実装されているか、誰も検証してないよね？」という点。
DESIGN.md は値や意図を記録してくれるけれど、実際のコードや画面を一切チェックしない。
なので、lint が通って CI がグリーンでも、「見えている画面が本当に意図どおりか」は保証されないまま、という指摘なんです。
筆者はなんと、七十四件の実例を調べています。
その結果わかったのは、公式サンプルみたいにちゃんと数値が書かれた DESIGN.md って実は少数派で、多くは「値をほぼ書かずに、文章で方向性だけ示している」使い方だったこと。
つまり、「青系で爽やかに」とか「アクセシビリティを意識」といった、ふわっとしたことだけが書かれているパターンが結構多いんですね。
さらに、公式サンプルはそういう実例とかけ離れすぎていて、あんまり手本にならない。
仕様どおりに書いたのに、値が黙って消えてしまう不具合があったり、ボタン一個分のスタイルすら、DESIGN.md 単体では完全に表現しきれないなど、結構な限界も見えてきたと報告しています。
そこで筆者が主張しているのは、「DESIGN.md はあくまでデザイン意図とトークンの記録にとどめよう」というスタンスです。
本当に信頼できるプロセスにするには、CSS や画像を使った「別の検証レイヤー」が必要だし、さらに AI にも「分からないときは分からないと言う」仕組みを組み込まないとダメだと。
つまり、「DESIGN.md を置けば全部解決！」じゃなくて、
・意図や値の“メモ帳”としての DESIGN.md
・画面が仕様通りかチェックするための CSS／画像ベースのテスト
・AIが曖昧なときにちゃんと『分からない』と返せる仕組み
この三つが揃って、ようやく安心して運用できるよね、というバランス感のある提案になっています。
。。.。。.。.
三つ目の記事です。
これは「AI と一緒に開発していると、実装もドキュメントもどんどん増えるけど、何が本当に守られているのかだんだん分からなくなるよね」という問題に対して、「保証駆動開発」、略して GDD というアプローチを紹介しているお話です。
AI を使うと、コードの実装量はガンガン増やせるんですけど、その分手戻りも増えがち。
テストは「自動で実行されるけど、人間にはちょっと読みにくい」し、
逆に README や仕様書は「人間には読めるけど、実行されないので本当に合ってるか分からない」。
この“テストとドキュメントのギャップ”が大きくなるのが悩みだ、と。
そこで筆者は、リポジトリの“成長段階”ごとに、扱うドキュメントを変えようと言っています。
立ち上げ期は、軽量な PLAN.md と、判断の履歴を残す JUDGE.md だけで、サクッと作る。
で、プロジェクトが安定期に入ってきたら、中心に据えるのを「保証台帳」に切り替えるんですね。
この保証台帳というのが、docs/guarantees.md というファイルで、
「テストが守っている約束だけを、人間が読める自然言語に抜き出したもの」です。
ここには、外から観測できる API や CLI の振る舞いだけを「保証」として箇条書きにしていきます。
たとえば、「このエンドポイントは、こういう入力に対して必ずこういうレスポンスを返す」とか、「この CLI コマンドは、失敗した場合は必ず非ゼロの終了コードを返す」といった具合ですね。
そして、それぞれの保証がどのテストに対応しているか、索引をきちんと付けておく。
運用も工夫されていて、変更のたびにまず Issue で「新しく宣言する保証」と「維持する保証」を先に決めてしまうんです。
この「約束の一覧」を裁可してから、実装とテストと保証台帳をまとめて更新する。
そうすることで、機能追加やバグ修正をしても、「どの範囲までを壊さないことにするのか」が、チーム全体で共有しやすくなるわけですね。
ここで頼りにしているのが AI です。
AI が、テストと保証台帳の“二重管理コスト”をけっこう肩代わりしてくれる前提で、人間側は「何を約束するのか」という意思決定にフォーカスする。
そして、保証台帳を起点に「ここは壊しちゃダメ」「ここはまだ変えられる」といった“壊してはいけない領域”を、チーム全員で共有しながら開発を進めていく。
そんな、新しい開発のやり方が具体的に示されている記事でした。
。。.。。.。.
四つ目、ここからはコードコメントのお話です。
テーマは「AI がコードにやたら長いコメントを書きがちなのはなぜか？ そしてどう付き合うか？」というもの。
筆者はまず、Claude に「なんでそんなに長いコメントを書くの？」と直接聞いてみています。
すると分かったのが、「長文コメントは AI 自身の理解にはあまり役立っていない」、むしろ「コンテキスト、つまりモデルが一度に読める範囲を圧迫するので不利になっている」ということ。
じゃあなんで長くなるのかというと、
・丁寧に説明しようとする“クセ”
・自信がない部分を、言葉数で埋めにかかる傾向
この二つが大きいらしいんですね。
ここで重要なのが、「コメントがやたら多いところは、不確実さのサインになっているかもしれない」という指摘です。
つまり、「よく分かってないから、つい説明を盛りまくっている」可能性がある、と。
そこで筆者のチームでは、「コードから復元できない情報だけコメントに書こう」というルールを導入してみました。
たとえば、変数名や処理の流れを読めば分かることは書かない。そうではなくて、仕様の背景とか、周辺の事情みたいな「コードだけでは読み取れない情報」に絞る。
これをやると、コメント全体の量はかなり減ったんですが、四行以上あるような“長いコメントの塊”は、あんまり減らなかったそうです。
なぜかというと、その長文ゾーンには「クライアントの細かい仕様」や「過去の障害の教訓」など、本当に有用な情報が詰まっていて、さすがに削れなかったから、と分析しています。
そこで最終的にルールをもう一歩進めて、「情報が有用かどうか」ではなく、「この情報の置き場所として、コードコメントが正しいのか？」を基準に見直すようにしたんですね。
たとえば、
・変更履歴は git や Pull Request に任せる
・タスクIDやチケット番号は issue 側に残す
といったものは、コメントから追い出す。
そのうえで、コードコメントには「現在の仕様」や「隠れた制約」など、「今このコードを読んでいる人にとって必要な WHY だけを書く」というグローバルルールをチームで決めています。
そして、実際にコメントの量や長さのメトリクスをとって、効果を検証していくという、かなり実証的な姿勢を見せているのが印象的でした。
。。.。。.。.
そして五つ目、ラストの記事です。
こちらは、LLM 向けのプロンプトを「テスト駆動で少しずつ鍛えていく」手法を紹介した、サービス紹介寄りの内容になっています。
ベースになっているのは、mizchi さんの「empirical-prompt-tuning」という考え方で、これを GitHub Copilot 上で実践したレポートになっています。
題材は、あえて品質を落としておいた「正規表現生成スキル」。
これに対して、テストケースに沿って少しずつプロンプトを改善していく、という流れです。
面白いのは、毎回「まっさらな新規 Copilot チャット」を“実行者”として使うところです。
同じチャットに履歴がたまっていくと、プロンプトの改善なのか、履歴効果なのか分からなくなるので、毎回白紙の状態からスタートする。
で、spec に書かれた match / no-match の例文だけを使って、正規表現が合っているかどうかを判断します。
うまくいったケースでも、「これはたまたま通っているだけでは？」というのをちゃんと疑って、False Positive として次のテストケースに反映していくのも特徴です。
つまり、「一回成功したから終わり」ではなく、「本当に一般化できているか」を例文ベースで攻めていくわけですね。
プロンプト改善の中で特に効いたのが二つあって、
ひとつは、プロンプトに「必ず match/no-match の例で検証せよ」という一行を足したこと。
もうひとつは、「特徴を考える」といったふんわりした指示をやめて、「構造を分解し、各部品の値の範囲を決める」といった、より具体的な作業手順に言い換えたことです。
この二つを取り入れた結果、それまで成功率が四十〜五十パーセントくらいだったスキルが、最終的には成功率百パーセントまで到達した、と報告されています。
しかも、そのスキルを別のシナリオに持っていっても崩れずに使えた、というのが大きいポイントですね。
この記事を通して伝えたいのは、「LLM の出力そのものだけをいじるんじゃなくて、『どう考えさせるか』をちゃんと設計して、テストしながら改善していこう」という姿勢の重要性です。
プロンプトも一種のプログラムとして、テスト駆動で育てていく。そんな実践例として、とても参考になる内容でした。
。。.。。.。.
というわけで、今日の「zenncast」、お届けしてきた五本の記事を、最後にちょっとだけおさらいしておきましょう。
まずは一つ目、CLI の help やログに「coding agent 向けメッセージ」を仕込んで、AI がまず docs コマンドを叩くように誘導する話。ドキュメントを CLI に埋め込んで、Agent Skill は一個だけに絞る、という“AI フレンドリーな CLI 設計”が紹介されていました。
二つ目は、Google Labs の DESIGN.md を七十四件も検証して、「意図とトークンの記録としては有用だけど、実装検証がないと危ういよね」という指摘。CSS や画像による別レイヤーの検証と、「分からない」と言える仕組みが大事だ、というお話でした。
三つ目は、AI時代のドキュメントとテストのギャップに対して、「保証台帳」こと docs/guarantees.md を中心に据える GDD、保証駆動開発。テストが守っている約束だけを自然言語で抜き出して、「壊してはいけない領域」をチームで共有しよう、という提案でした。
四つ目は、AI が長いコメントを書きがちな理由を掘り下げて、「コメント量は不確実さのサインかも」としつつ、「コードから復元できない WHY だけをコメントに残す」ルールに切り替えた話。情報の置き場所を整理して、コメントをスリムにしていこうという実践でした。
そして五つ目は、LLM プロンプトをテスト駆動で鍛えていく empirical-prompt-tuning の実践レポート。match/no-match 例で必ず検証させること、指示を具体的な作業に落とし込むことで、正規表現スキルの成功率を百パーセントまで伸ばした、という内容でした。
気になった記事があれば、このあとショーノートに詳しい情報を載せておきますので、ぜひ原文もチェックしてみてください。
この番組「zenncast」では、みなさんからの感想や質問もお待ちしています。
「こんなテーマを掘り下げてほしい」とか、「うちのチームではこうしてるよ」といった現場の声も、どしどし送ってください。番組作りの参考にさせていただきます。
それでは、そろそろお別れの時間です。
今日も一日、無理しすぎず、でもちょっとだけ新しいことにチャレンジしてみる、そんな日にしていきましょう。
お相手は、マイクでした。
また次回の「zenncast」でお会いしましょう。さようなら〜。