The Engineering of Intent 第28章:ヒント集──日々の実践から生まれた100のメモ

本記事は、私の著書The Engineering of Intent(英語版)を1章ずつ読み解くシリーズの第28回です。前回の記事では、アンチパターンのカタログを一通り見ました。第28章はロングテールのアーカイブです──何年もかけて集めてきた、日々の実践から生まれた番号付きの100のヒントです。


気軽につまみ読みする。同意できないものには反論する。気に入ったものは盗む。

第28章はまるごと、番号付きの100のヒントでできています。些細なものから奥の深いもの、言われてみれば当たり前のものから直感に反するものまでさまざまです。私自身の実践と、一緒に働くエンジニアたちの実践から集めました。物語はありません。どの順番で読んでもかまいません。ここでは、読者が最もよく引用すると教えてくれた12個を紹介します。


まずはこの12個から

  • #2. エージェントが大量のコードを生成したら、まず1文の要約を求めましょう。それを読みます。要約が間違っていれば、コードも間違っています。
  • #4. エージェントに同じことを何度も伝えているなら、それはagents.mdに書きましょう。3回繰り返したら、それが境界線です。
  • #8. conventions.mdのすべての規約は、lint、型、レビューのいずれかで、何らかの形でテスト可能であるべきです。テストできない規約は腐ります。
  • #11. 失敗した試行をエージェントに見せてはいけません。それに引きずられて、失敗した方向へ偏ってしまいます。やり直すときは、まっさらな状態から始めましょう。
  • #15. 遅いテストがあれば、速くしましょう。遅いテストは実行されません。実行されないテストは、テストではありません。
  • #21. エージェントが「// TODO: handle edge case」というコメントを書いたら──マージしてはいけません。そのTODOは嘘です。
  • #25. 公開APIの名前をエージェントに決めさせてはいけません。命名は人間の責任です。
  • #34. 「かつて信じていた嘘」のドキュメントを書き続けましょう。architecture.mdに次いで、最も役に立つプロジェクトの資産になります。
  • #38. 沈黙はシグナルです。エージェントが何の留保もなく自信満々の答えを出したら、疑ってかかりましょう。
  • #40. エージェントのアウトプットと、自分が求めたものとの差分を取りましょう。そのギャップにこそ学びがあります。
  • #49. 「コードが自己文書化している」と言うエンジニアにならないでください。コードが記述するのは仕組みです。コメントが記述するのは意図です。
  • #56. エージェントを使った作業を、時間単位で見積もってはいけません。サイクル単位で見積もりましょう。
💡 私のお気に入りの3つ: 「『次のときのために覚えておこう』と思ったその瞬間こそ、書き留めるべき瞬間です。」 ── 「自分が賢いと感じたら、手を止めましょう。賢さは、将来の保守の苦痛を予告する先行指標です。」 ── 「ジュニアには辛抱強く接しましょう。今日あなたがいら立っているジュニアは、来年あなたが必要とするシニアです。」 この3つをチームに刻み込むことができたなら、どんなアーキテクチャの変更よりも多くの良いコードが生まれるでしょう。

「ここにあるヒントのすべてがあなたに響くわけではありません。それで当然です。100のヒントは教義ではありません──図書館です。響くのは、あなたが最近犯したミスに当てはまるものです。いま響かないものは、いずれ響くか、あるいは一生響かないかもしれません。どちらでもかまわないのです。」

⚠ 特に真剣に受け止めてほしいヒント: #20. バグに対するテストは、修正前には失敗し、修正後にはパスしなければなりません。そうならないなら、あなたが直したのは別のものです。修正が「明らかに」問題に対処しているからと、この確認を飛ばすエンジニアをよく見かけます。それが実は間違っていたという回数は、数え始める前の私には信じられなかったほど多いのです。

次回 ── 第29章「バックエンドのVibe Coding」 本書の第IX部:深掘りと拡張ケーススタディから、深掘りが始まります。続く5つの章では、一般的な実践を特定の領域──バックエンド、フロントエンド、データとML、プラットフォーム、そして個人のオペレーティングシステム──に当てはめていきます。第29章はバックエンドから始めます。


📖 さらに詳しく知りたい方へ

本章では、100のヒントすべてを紹介しています。読者からは、最もよく読み返す章だと言われています──数週間おきにさっと読み返すと、日々の実践がずれてきているところに気づけるのです。

The Engineering of Intent をAmazonで購入する →(英語版)

2026-05-14

下田 昌平

開発に関するインプットをアウトプットしています。