どうも、おはようございます。マイクです。
ラジオ「zenncast」、六月二十一日、日曜日の朝七時台をお届けしていきます。
今日は、テック界隈でもかなりホットな「エージェント時代の開発スタイル」周りの記事がずらっと並んでいます。
この時間は、Zennで今日トレンドになっている記事を、ゆっくり噛み砕きながらご紹介していきますね。
さて、今日は全部で五本の記事をご紹介していきます。
エージェントとソフトウェア工学の基本、ローカルでのメモ術、ドメイン知識の置き場所、Markdown の賢い読み方、そして最後は「自分の開発スタイルをAIと一緒に掘り起こす」という、なかなか渋い一本まで、バラエティ豊かに揃ってます。
それでは、一つ目からいきましょう。
。。。。
まず一つ目は、「エージェントがコードを書く時代だからこそ、ソフトウェア工学の基本を捨てちゃダメだよ」という Tips 集の記事です。
今、コードを書いてくれるエージェントがだいぶ賢くなってきていて、テストを書かなかったり、設計をちゃんと考えなかったりしても、一見「開発がものすごいスピードで進んでるように見える」ことが増えてきてますよね。
でもこの記事の筆者は、そういう時代だからこそ、ソフトウェア工学の基本的な習慣をちゃんと守らないと、あとから地獄を見るよ…という話を、具体的なTipsの形で整理してくれています。
キーワードになっているのが、まず「検証可能な要求」。
Done、つまり「終わった」と言える状態を、あいまいな言葉じゃなくて、具体的なコマンドとか、確認できる結果で定義しよう、という話です。
例えば、「この機能が終わった」の代わりに、「このコマンドを叩いたら、このレスポンスが返ってくる」「このテストが全部パスしている」といった、機械的に確かめられる形で「Done」を決めておく。
エージェントに任せるときほど、こういうルールが効いてくるよね、という指摘ですね。
それから、「一つのプルリクエストに理由を一つだけ入れる」という、小さな変更の原則。
あれもこれもと詰め込まず、「このPRは、これをこう直したいから存在してる」という理由を一つに絞る。
こうすると、エージェントが出してきた変更に対しても、レビューやロールバックがすごくしやすくなります。
テストについては「契約」として必ず実行する、という表現をしていて、テストを単なるおまけじゃなくて、「このシステムはこう振る舞う」という約束事を確認する場として扱おう、と言っています。
さらに、権限とかファイルアクセスの範囲といった「境界」をちゃんと明示することも重要。
どこからどこまで触っていいのかを決めておかないと、エージェントが良かれと思って、変えてほしくないところまで書き換えちゃう、みたいな事故が起きちゃいます。
面白いのが、「設計判断をチャットで流さない」というポイント。
エージェントや人間とのやりとりって、ついチャットに書きっぱなしにしがちなんですけど、そこに重要な設計の判断が混ざっていることがありますよね。
この記事では、それを `_docs` ディレクトリとか、ADR的なドキュメントとしてリポジトリに残しておこう、という提案をしています。
リポジトリの中にきちんと「追跡可能性」を持たせることで、あとから来た人や、別のエージェントも、その判断の経緯を追えるようにしよう、というわけです。
他にも、ファイルやドキュメントごとに役割をちゃんと分けること、型チェックや静的解析を強制すること、エラーは握りつぶさずに、できるだけ早く、分かりやすく失敗させること。
それから、「将来のための抽象化」を安易に入れない、いわゆる YAGNI、「いらないものは今は作らない」っていう考え方。
さらに、CIで動かすコマンドと、ローカルで開発者が叩くコマンドをできるだけ一致させること。
そして、自動レビューは前処理として活用しつつ、最終判断は必ず人間が行うこと。
本番操作や危険な操作は、必ず人間の確認を通すこと、などなど、けっこう盛りだくさんのチェックリストになっています。
最後に、それらのルールや習慣を、AGENTSドットエムディーのようなガイドファイルだったり、SOP、 `_docs`、CIの設定ファイルなど、リポジトリの「正しい置き場」にちゃんと書き込んでいこう、とまとめています。
そうすることで、エージェントの速度は活かしつつも、「後からでも直しやすいコードベース」を維持していこう、という提案なんですね。
エージェントにがっつり仕事をさせているチームほど、刺さる内容じゃないかなと思います。
。。。。
続いて二つ目。
こちらはちょっと毛色が変わって、「ローカル環境でメモを書き散らしたいんだけど、ObsidianとかMarkdownだと、なんか構えちゃうんだよな」という悩みから始まる記事です。
筆者は、日々の作業メモをとるときに、Obsidianとか、普通のMarkdownエディタだと、多機能すぎたり、見た目を整える方向に意識がいってしまって、「とりあえず今日の作業を書き殴る」には向きにくいと感じているそうです。
そこで比較対象として出てくるのが「Cosense」というサービス。
ここでは、箇条書きをとにかくどんどん追加して、必要になったらページを分けていく、みたいな書き心地がすごく良いと評価しているんですね。
ただ、CosenseはSaaSなので、どうしてもネットワーク越しでちょっと遅かったり、業務利用の制約があったりして、「この感覚をローカル環境で再現できないかな」と考えた、と。
そこで筆者が自作したのが、VSCodeの拡張機能「vscode-scb」です。
この拡張では、「ドットエスシービー」という独自の拡張子を持ったファイル形式を用意していて、ルールはすごくシンプル。
一インデント一スペースの箇条書き、という決まりにして、余計な装飾はほぼなし。
さらに、カギカッコでリンクっぽく書いて、シフトプラスエンターを押すと、その名前の別ページへジャンプする、というCosense風の記法を実現しています。
このおかげで、例えば「二千二十六年六月二十一日」の作業ページをさっと作って、そこにガーッと書き殴る。
ある程度たまってきたら、「このタスクは専用ページに逃がそう」とリンクを作って、別ページに切り出す。
そういうラフな整理がしやすくなります。
さらに筆者は、ここに生成AI、たとえばClaudeのようなツールを組み合わせることで、「自分だけの一時的なワークスペース」を育てていけるんじゃないか、と考えています。
日々のメモを `.scb` で溜めていって、その一部をAIに投げて要約させたり、次のタスクを整理させたりする。
そんなふうに、「がっつりしたナレッジベース」ではなく、「作業中の頭の中」をそのまま支えてくれるメモ環境を、ローカルで軽く実現しよう、という試みですね。
作業ログをとるのが好きな人には、かなり刺さりそうな記事です。
。。。。
三つ目の記事は、また少し視点が変わって、「リファクタリングにはドメイン知識がめちゃくちゃ大事だよね」という話からスタートします。
でも、そのドメイン知識をどこに保存するかを間違えると、時間がたつにつれて情報が腐っていって、AIも人間も正しく判断できなくなる、と指摘しています。
ここで筆者が提案しているのが、開発に必要な知識を、「ハウ」「ホワット」「ホワイ」「ホワイノット」の四種類に分けて、それぞれ「腐りにくい場所」に分散して置こう、という整理です。
まず「ハウ」、どう動くか、どう実装されているか、という部分。
これは、なるべく自己説明的なコードの中に埋め込んでいきましょう、と。
つまり、「コードを読めば動きが分かる」状態を目指す、ということですね。
次に「ホワット」、何をすべきか。
これは実行して確かめられるテストコードに持たせるのが良い、としています。
この機能は、こういう入力に対して、こういう振る舞いをすべきだ、というのをテストに書いておけば、仕様が変わったときにも、自動的に「どこがずれたか」が分かります。
そして、「ホワイ」と「ホワイノット」。
なぜそういう設計にしたのか。
そして、別の案をなぜ採用しなかったのか。
この二つについては、書き換えない前提のADR、アーキテクチャ・ディシジョン・レコードに記録しておこう、と提案しています。
これによって、過去の判断や、却下された案も含めて、「そのときどう考えていたのか」を後から追いかけることができます。
逆に、「やらないほうがいいよ」とされているのが、自然言語で長々と書いた仕様書や、「ハウ」を説明するドキュメントを、唯一の正解として扱うこと。
コードから導き出せることを、別のドキュメントにも書いてしまうと、必ずどこかで更新漏れが起きて、ズレが発生します。
そういうものを「正本」、つまり「唯一信じる情報源」にしてしまうのは危険だと、この記事では強調しています。
エージェントを活用する時代になると、この問題はさらに大きくなります。
AIのコーディングエージェントは、テキストやコードを大量に読み込んで判断しますが、その元になる知識が腐っていると、当然アウトプットもおかしくなってしまいます。
そこで筆者は、テストや型、ADRのように、機械的に検証できたり、比較的構造化されていて解釈しやすい形で知識を配置することが、ドメイン知識を長期的に守る鍵になる、と締めくくっています。
「知識をどう書くか」だけじゃなくて、「どこに置くか」が重要だよ、というメッセージですね。
ドキュメントを書きがちな人ほど、一度立ち止まって考えたくなる内容だと思います。
。。。。
四つ目は、Markdownの世界から。
「でかい仕様書とかREADMEを、LLMが読むときのコストをどう減らすか」という、これもまたエージェント時代っぽい話題です。
ここで紹介されているのが、CLIツール「md2idx」。
Markdownの見出し構造をうまく利用して、「必要なセクションだけ、賢く読む」ための仕組みを提供してくれるツールです。
md2idxがやってくれることは、大きく二つ。
一つは、Markdownを解析して、見出しだけを集めた目次、インデックスをJSONとして出してくれること。
もう一つは、見出しごとに、その直下の本文ブロックを切り出して、「セクション」としてまとめたJSONを出してくれることです。
これによって、エージェントやLLMは、まず「目次だけ」を読んで、どのセクションが自分のタスクに関係ありそうかを判断できます。
そして、必要な番号のセクションだけを実際に取得して読み込む。
全部のMarkdownをまるっと投げるのに比べて、コンテキストのトークン使用量を、八〇パーセントから九十八パーセントくらいまで削減できた、という話も紹介されています。
余計な情報を読み込まない分、回答の精度も落ちにくくなる、というメリットもあります。
さらに、grepなどの単純なテキストツールでは扱いにくいケースも、専用ロジックで処理してくれます。
例えば、「この見出しから、どこまでが本文なのか」という範囲の取得。
シャープ記号で書かれた見出しだけじゃなくて、セットエックス形式の見出し──イコールやハイフンで下線を引くスタイルですね──にも対応。
コードブロックの中に出てくるハッシュ記号は、見出しとしてカウントしないようにする、といった細かな配慮も入っています。
また、目次用に書かれているインラインの記法を取り除いて、すっきりしたインデックスにしてくれる、という工夫もされています。
加えて、GitHub Skills経由で「md2idx-read」という仕組みを使うと、エージェントが大きなMarkdownに出会ったときに、自動でインデックスの取得とセクションの選択を行ってくれる構成も用意されています。
もしmd2idxが使えない環境だったとしても、そこではgrepと部分的な読み出しに自動でフォールバックするような設計になっていて、「どの環境でも、なるべく賢く読みたいところだけ読む」という動きを実現しようとしているんですね。
人間の開発者にとっても、大きなREADMEとか仕様書を読むときに、「とりあえず目次見て、必要なとこだけ開きたい」というのは同じなので、LLM向けの工夫がそのまま人間にも便利、というタイプのツールだなと感じました。
。。。。
そして最後、五つ目の記事です。
これは、ちょっとエッセイ寄りのオピニオン記事で、「自分の開発スタイルや考え方を、AIとのログから掘り起こしてみた」という内容になっています。
筆者は、Claude Codeとの会話ログを長い期間にわたって保存していて、そのセッション数が、なんと七百以上。
それらをまとめてAIに読み込ませて、「自分は普段、どんな原則にもとづいてフィードバックしたり、設計の判断をしているのか」を抽出させたそうです。
そこで浮かび上がってきたのが、いくつかの一貫したエンジニアリングの姿勢でした。
例えば、「調査はできるだけ広く行うけれど、アウトプットとして書くのは、本当に必要な部分だけに絞る」。
あるいは、「人の注意力に頼らず、型や静的チェックといった仕組みでミスを防ぐ」。
また、「議論ばかりするのではなく、とりあえず動かして確かめることを優先する」。
「試行錯誤用の場と、チームで共有される成果物の場を、ちゃんと分けておく」。
さらに、「文書やエラーメッセージは、常に受け手のために設計する。レビューする人や、将来の自分が読みやすいように意識する」といったポイントです。
これらは、筆者の中ではなんとなくの「好み」や「クセ」として存在していたものなんですが、AIに大量のログを読ませて、パターンとして抜き出させることで、「自分の無意識の判断基準」が、はっきりと言語化されてきた、と振り返っています。
その結果、「ぼんやりした信念」が整理されて、自分にとっての原則として見える化できた、というのが、この取り組みの一番の面白さだと語られています。
エージェントと一緒にコードを書く時代だからこそ、「自分は何を大事にしているエンジニアなのか」を改めて見直す、そんなきっかけになりそうな記事でした。
。。。。
というわけで、きょうのzenncastは、五本の記事をご紹介しました。
ざっとおさらいすると、まず一つ目は、エージェントがコードを書く時代でも絶対に捨てちゃいけない、ソフトウェア工学の基本的な習慣のTips集。
二つ目は、Cosense風の書き心地をローカルで再現するために、vscode-scbというVSCode拡張を自作した、作業メモ環境のお話。
三つ目は、ドメイン知識を「ハウ」「ホワット」「ホワイ」「ホワイノット」に分けて、コードやテスト、ADRにうまく分散して配置しよう、という知識設計の話。
四つ目は、Markdownの見出し構造を使って、LLMが必要なセクションだけを読むためのCLIツール、md2idxの紹介。
そして五つ目が、Claudeとの七百以上のログから、自分の開発スタイルをAIに言語化させてみた、というオピニオン記事でした。
それぞれの詳しい内容や、気になったポイントへのリンクは、ショーノートにまとめてありますので、気になった方はぜひ、あとでチェックしてみてください。
この番組「zenncast」では、皆さんからの感想や、「こんなテーマを取り上げてほしい」といったリクエストもお待ちしています。
番組を聞いて思ったことや、実際に記事を読んでみての気づきなんかも、ぜひ気軽に送ってください。
それでは、きょうはこのへんでお別れです。
ここまでのお相手は、マイクでした。
また次回のzenncastでお会いしましょう。お聞きいただき、ありがとうございました。