/tags/ai/ Recent content in AI on 怠惰技術ブログ Hugo -- 0.147.7 ja Sat, 28 Mar 2026 10:00:00 +0900 /posts/2026-03-28-write-agents-rules/ Sat, 28 Mar 2026 10:00:00 +0900 /posts/2026-03-28-write-agents-rules/ <h1 id="ai-コーディングエージェントを飼い慣らす最強のagentsmdの書き方">AI コーディングエージェントを飼い慣らす：最強の「AGENTS.md」の書き方</h1> <p>近年、Gemini、Claude、Aider といった「自律型 AI コーディングエージェント」が開発現場に浸透しつつあります。彼らは指示一つでファイル構成を理解し、コードを書き、テストを実行して修正まで行います。</p> <p>しかし、エージェントを使い始めた多くのエンジニアが直面するのが、**「AI エージェントの暴走」**です。</p> <ul> <li>型定義を面倒くさがって <code>any</code> を連発する</li> <li>プロジェクト独自のディレクトリ構造を無視して勝手に <code>utils/</code> を作る</li> <li><code>vitest --watch</code> などの終了しないコマンドを叩いてフリーズする</li> <li>指示していないリファクタリングを始めて関係ないファイルを壊す</li> </ul> <p>これらの問題を防ぎ、エージェントを「熟練のペアプロ相手」に変える魔法のファイル、それが <strong><code>AGENTS.md</code></strong> です。本記事では、AI エージェントに守らせるべきルールを定義する <code>AGENTS.md</code> の書き方と、その設計思想を徹底解説します。</p> <hr> <h2 id="なぜ-agentsmd-が必要なのか">なぜ <code>AGENTS.md</code> が必要なのか</h2> <p>AI エージェントは、人間が数年かけて培った「プロジェクトの阿吽の呼吸」を知りません。 エージェントに与えられるコンテキスト（ファイル内容や履歴）は有限であり、その中で彼らは「最も確率的に正しそうな推論」を行います。その結果、彼らはしばしば**「最も楽な道（＝技術的負債を生む道）」**を選んでしまいます。</p> <p><code>AGENTS.md</code> をプロジェクトのルートに配置する理由は、**「エージェントの推論空間に強制的な制約（ガードレール）を設けるため」**です。</p> <h3 id="なぜその設計にしたか外部メモリとしての役割">なぜその設計にしたか：外部メモリとしての役割</h3> <p>エージェントは毎回ゼロベースで思考するわけではありませんが、多くのファイルを見すぎることで逆に重要なルールを見失う（ロスト・イン・ザ・ミドル現象）ことがあります。<code>AGENTS.md</code> という明確なルールブックを定義し、エージェントの起動時やタスク開始時に必ず読み込ませることで、思考のブレを最小限に抑えることができます。</p> <hr> <h2 id="agentsmd-に書くべき内容の-4-つの分類"><code>AGENTS.md</code> に書くべき内容の 4 つの分類</h2> <p>効果的な <code>AGENTS.md</code> は、以下の 4 つのセクションで構成するのがベストプラティスです。</p> <ol> <li><strong>禁止事項 (Prohibitions):</strong> 致命的なエラーや環境のハングを防ぐ</li> <li><strong>命名規則・コーディング基準 (Standards):</strong> コードの品質を一定に保つ</li> <li><strong>アーキテクチャ原則 (Architecture):</strong> システムの整合性を維持する</li> <li><strong>テスト・検証方針 (Testing):</strong> 修正の正しさを担保する</li> </ol> <p>それぞれのセクションについて、具体的な記述例を見ていきましょう。</p> <hr> <h2 id="1-禁止事項-prohibitions">1. 禁止事項 (Prohibitions)</h2> <p>エージェントが最もやりがちな「環境破壊」を防ぐための最重要セクションです。</p> <table> <thead> <tr> <th style="text-align: left">ルール</th> <th style="text-align: left">理由（なぜその設計にするか）</th> </tr> </thead> <tbody> <tr> <td style="text-align: left"><strong>インタラクティブコマンドの禁止</strong></td> <td style="text-align: left"><code>npm init</code> や <code>git commit</code> (メッセージ入力待ち) など、ユーザー入力を待つコマンドは CLI エージェントをフリーズさせます。</td> </tr> <tr> <td style="text-align: left"><strong>Watch Mode の禁止</strong></td> <td style="text-align: left"><code>vitest --watch</code> 等はプロセスが終了しないため、エージェントが「完了」を検知できなくなります。</td> </tr> <tr> <td style="text-align: left"><strong><code>any</code> 型の原則禁止</strong></td> <td style="text-align: left">AI は型の整合性を取るのが面倒になると <code>any</code> で逃げようとします。これは長期的な保守性を著しく低下させます。</td> </tr> <tr> <td style="text-align: left"><strong>勝手な依存関係の追加禁止</strong></td> <td style="text-align: left"><code>package.json</code> を書き換えて新しいライブラリを入れる行為は、セキュリティやビルドサイズに影響するため、人間の許可を必須にします。</td> </tr> </tbody> </table> <h3 id="実例コード">実例コード</h3> <div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-markdown" data-lang="markdown"><span style="display:flex;"><span><span style="color:#75715e">## 禁止事項 </span></span></span><span style="display:flex;"><span><span style="color:#75715e"></span><span style="color:#66d9ef">-</span> **コマンド実行**: </span></span><span style="display:flex;"><span> <span style="color:#66d9ef">-</span> <span style="color:#e6db74">`vi`</span>, <span style="color:#e6db74">`nano`</span>, <span style="color:#e6db74">`top`</span> などのインタラクティブなコマンドは実行しない。 </span></span><span style="display:flex;"><span> <span style="color:#66d9ef">-</span> <span style="color:#e6db74">`npm start`</span>, <span style="color:#e6db74">`vitest --watch`</span> などの終了しないプロセスは背景実行 (<span style="color:#e6db74">`&amp;`</span>) するか、単発実行モードを使用すること。 </span></span><span style="display:flex;"><span><span style="color:#66d9ef">-</span> **TypeScript**: </span></span><span style="display:flex;"><span> <span style="color:#66d9ef">-</span> <span style="color:#e6db74">`any`</span> 型の使用は厳禁。どうしても必要な場合はコメントで理由を明記すること。 </span></span><span style="display:flex;"><span><span style="color:#66d9ef">-</span> **Git**: </span></span><span style="display:flex;"><span> <span style="color:#66d9ef">-</span> ユーザーの明示的な指示なしに <span style="color:#e6db74">`git commit`</span> や <span style="color:#e6db74">`git push`</span> を行わない。 </span></span></code></pre></div><hr> <h2 id="2-命名規則コーディング基準-standards">2. 命名規則・コーディング基準 (Standards)</h2> <p>プロジェクトの「見た目」と「一貫性」を守るためのルールです。ここを疎かにすると、エージェントは自分の得意なスタイル（多くの場合、学習データで最も多いスタイル）で書き始めてしまいます。</p> /posts/2026-01-31-gemini-cli-history/ Sat, 31 Jan 2026 19:30:00 +0900 /posts/2026-01-31-gemini-cli-history/ GEMINI.mdファイルを使ってAI（Gemini）にコーディングルールと開発履歴を管理させる手法を紹介します。AIが自分で学習・改善していくドキュメント駆動開発の実践例。 /posts/2026-01-31-gemini-cli-expo/ Sat, 31 Jan 2026 19:00:00 +0900 /posts/2026-01-31-gemini-cli-expo/ Gemini CLI を使って Expo の Todo アプリを開発した体験記。GEMINI.md でルールを管理し、段階的に機能を追加していく方法を紹介します。