Vibe Coding - Findy Library

概要

Vibe Codingとは、つくりたいものを自然言語で伝え、生成AIのコーディングエージェントにコードを生成させながら、人間が方向づけ・検証・修正を対話的に繰り返していく開発手法です。この言葉は、生成されたコードを読まずに受け入れる、使い捨てのプロトタイプ向けの流儀を指すこともあります。本ページが扱うのはそちらではなく、チームで保守する本番のコードベースを対象に、人間が出力の検証に責任を持ちながら進める実践です。本ページでは、コーディングエージェントが力を発揮するために必要な土台、人間に残る検証の責務、そしてセッション・コンテキスト・カスタムインストラクションの扱い方を解説します。

前提

コーディングエージェントの出力品質は、作業対象のコードベースとプロセスの質に大きく左右されます。AI活用が成果につながらないとき、原因はツールの使い方ではなく土台の不足の可能性があります。コーディングエージェントには一貫して模倣できる対象がなく、誤りを受け止めるガードレールもない状態では、成果を期待できません。規約・テスト・設計の知識はコーディングエージェントによって不要になるのではなく、コーディングエージェントが走るための土台であり、その出力を判断するための拠り所です。結果を求める前に土台を整えます。

統一されたコーディング規約

コーディングエージェントは目にしたコードを模倣します。公開されているスタイルガイドの採用など、一貫したスタイルに従うコードベースは生成を均質な出力へ導き、スタイルが混在したコードベースは混在した結果を生みます。

テストコード

テストは2つの役割を担います。コーディングエージェントが仕様を把握するための重要な情報源であり、誤った出力を人間より先に検出するガードレールでもあります。

ドキュメントとカスタムインストラクション

READMEや設計ドキュメント、コーディングエージェント向けの指示ファイル（AGENTS.mdやツール固有の設定など）は、プロンプトに貼り付けなくても毎回のセッションでコーディングエージェントに渡る常設のコンテキストです。

プルリクエストとレビュー文化

小さく焦点の絞られたプルリクエストを保つ習慣が、コーディングエージェントの出力をレビュー可能な大きさに保ちます。検証しきれない大きさの変更が届くなら、生成の速さに価値はありません。

使われていないコードは上記すべての妨げになります。コーディングエージェントはそれが不要なコードだと判断できず、模倣の対象にしてしまいます。不要コードの削除もコードベース整備の一部です。

検証と人間の責務

Vibe Codingで変わるのはコードの書き手であって、変更に対する責任の所在ではありません。生成された変更の作成者は、それを依頼した人間です。レビューに出す前に、自分がすべての行を説明できる状態にします。説明できない変更を量産する生成の速さは生産性を上げず、コストを「書く」から「レビューする」へ移して、そこで膨らませるだけです。検証を人間の目視だけに頼らないことも重要です。テストコード・ビルド・リンターのような合否を返すチェックをコーディングエージェントに渡し、チェックが通るまで繰り返すよう指示します。そのうえで、コーディングエージェントには成功を主張させるのではなく、テスト出力や実行したコマンドとその結果という証拠を示させます。

セッションを意図的に管理する

セッションを「コンテキストの単位」として扱います。関連する変更は同一セッションで進めて共有コンテキストを保持させます。たとえば横展開では、まず1箇所だけ動く状態にして検証し、検証済みの実装がコーディングエージェントから見えている同一セッションで残りの箇所へ展開します。検証済みの1実装が、繰り返し作業にとっての仕様書として機能します。

横展開の指示の例

今 UserCard に入れたのと同じパターンを、ProductCard と OrderCard にも適用して

無関係なタスクは新しいセッションで始め、古い履歴を混ぜません。セッションの履歴には人間の短期記憶と同じ制約があり、無関係な内容が多いほど、関係する部分が確実には使われなくなります。実践的な目安として、同じ問題で2回修正指示を出したら、それ以上の修正はやめます。コンテキストには失敗した試行がすでに蓄積され、出力を引っ張り続けるためです。新しいセッションを開始し、失敗から学んだことを織り込んだプロンプトで再開します。整理されたセッションと研ぎ澄まされたプロンプトの組み合わせは、修正を積み重ねた長いセッションを上回ります。

軌道修正のコストを抑える

コーディングエージェントはコード生成が速く、つまり間違ったコードを生むのも速いです。誤った方向に気づいたときの修正コストを抑えるには、どの1ステップも捨てるコストが安くなるように作業を構造化し、細かい粒度でコミットします。コミットはプルリクエストよりも細かい、意味のまとまった単位で行い、いつでも戻れる安全地点を確保します。データモデルの変更を例にすると、モデルを定義 → 検証 → migrationを生成という順序で進めます。

進め方の例：テーブルの追加

モデルファイルだけを作成してコミットする
フィールド名を検証し、誤りを修正する（例: last_name → family_name）
migration ファイルを生成して実行する

この順序なら、フィールド名の誤りに気づいた時点で修正するのはモデルファイル1つだけです。migrationまで一気に生成した後で気づくと、rollbackや複数ファイルにまたがる修正が必要になります。

必要十分なコンテキストだけを渡す

出力品質を左右する最大の要因は、コーディングエージェントに渡すコンテキストの大きさと焦点です。あれもこれもと盛り込んだ多岐にわたる依頼はコーディングエージェントの注意を分散させて精度を落とし、適切な参照を添えた絞り込まれたタスクは狙いどおりのきれいなコードを生みます。目標は、仕事をこなすのに十分でありながら、可能なかぎり小さいコンテキストを渡すことです。

悪い例：多すぎる

検索まわりがバグってるので直して。念のため search.ts と query-parser.ts と
index.ts の全文を貼っておく（計1,500行）。前に似た問題があったときの
Slack のやり取りも下に貼る。あと、ついでに気になったところがあれば
リファクタもお願い

悪い例：足りない

検索が壊れてるので直して

良い例：必要十分

検索で 500 エラーになることがある。エラーログ:

  2026-07-07T10:23:45.812Z ERROR GET /api/search?q=東京　カフェ 500 (12ms)
  TypeError: Cannot read properties of undefined (reading 'split')
      at parseQuery (src/search/query-parser.ts:27:35)
      at searchHandler (src/api/search.ts:18:24)
      at Layer.handle [as handle_request] (node_modules/express/lib/router/layer.js:95:5)

まず失敗を再現するテストを書き、そのうえで修正して

1つ目は情報としては足りていますが、大半がノイズとして注意を薄め、「ついでにリファクタ」で関心事も混ざっています。2つ目は最小ですが、場所も症状の詳細もないため際限のない探索を招きます。3つ目は、症状・実際のエラーログ・進め方という、行動に必要な情報だけを渡しています。原因の見立ては書いていません。ログには失敗したリクエストと発生箇所が事実として含まれており、そこから原因（全角スペースを含むキーワード）を突き止めるのはコーディングエージェントの仕事です。構造も重要です。目的、制約、具体的な参照先という階層で整理された指示は、区切りのない長文よりも確実に解釈されます。

だめな例

ユーザーの権限を更新できる API を追加して。ついでに画面からも権限を変えられるように
して、認可チェックもちゃんと入れて、バリデーションは既存のコードに合わせていい感じに
お願い

構造化された指示の例

目的: ユーザーの権限を更新する API を追加する

制約:
- 対象は PUT /api/users/:id/role のみ。画面の変更はこのタスクに含めない
- 認可チェックは既存のミドルウェアを使う

参照:
- ルーティングと入力検証は src/api/users.ts の updateUser を参考にする
- 権限チェックは src/middleware/authorize.ts の requireRole を使う

Issue・ライブラリのドキュメント・デザインデータなど、コーディングエージェントが見えない外部データが必要なときは、チャットに大量に貼り付けるのではなくModel Context Protocol（MCP）サーバー経由で提供します。

カスタムインストラクションを活用する

カスタムインストラクションは、コーディングエージェントが毎回のセッション開始時に読み込む指示ファイルです。ビルドやテストのコマンド、デフォルトと異なるスタイルルール、リポジトリの慣習、既知の落とし穴を記述します。前述の土台の「ドキュメントとカスタムインストラクション」を具体化したものです。

AGENTS.md

# コマンド
- ビルド: npm run build
- 型チェック: npm run typecheck
- リント: npm run lint（自動修正: npm run lint -- --fix）
- 単一ファイルのテスト: npm run test -- path/to/file.test.ts（全件実行より優先）
- 開発サーバー: npm run dev（http://localhost:3000）

# コードスタイル
- ES modules（import/export）を使う。CommonJS（require）は使わない
- named export を使う。default export を追加しない
- import は可能なら分割代入で書く（例: import { foo } from 'bar'）
- 新しい UI コンポーネントは src/components/Button/ の構成に従う（テストと story を同居させる）

# テスト
- テストフレームワークは Vitest。Jest の API は使わない
- テストはソースファイルの隣に <name>.test.ts として置く
- モックは可能なかぎり避け、tests/fixtures/ のフィクスチャを使う

# リポジトリの作法
- ブランチ命名: feature/<issue番号>-<slug>
- コミットメッセージは Conventional Commits（feat: / fix: / chore:）に従う
- プルリクエストを開く前に npm run typecheck と npm run lint を実行する

# アーキテクチャ
- API アクセスはすべて src/lib/api-client.ts を経由する。fetch を直接呼ばない
- 状態管理は TanStack Query。Redux を導入しない

# 環境の癖
- 開発サーバーの起動には .env.local が必要。.env.example からコピーする
- Node 22 を使う（mise で管理）。Node 18 では npm install が静かに失敗する

gitにコミットしてチームで共有し、短く保ちます。長すぎるファイルでは個々のルールが埋もれ、遵守率が下がります。特定のタスクやドメイン知識などは、毎セッションを占有せずオンデマンドで読み込まれるSkillに切り出します。

Agentic Workflow

対話しながら作るVibe Codingに対し、実装をコーディングエージェントに委譲して並列にスケールさせる実践です。

Skill

繰り返すワークフローをSkillとして一度定義し、何度でも呼び出せるようにする仕組みです。

​概要

​前提

統一されたコーディング規約

テストコード

ドキュメントとカスタムインストラクション

プルリクエストとレビュー文化

​検証と人間の責務

​セッションを意図的に管理する

​軌道修正のコストを抑える

​必要十分なコンテキストだけを渡す

​カスタムインストラクションを活用する

​関連ページ

Agentic Workflow

Skill

概要

前提

検証と人間の責務

セッションを意図的に管理する

軌道修正のコストを抑える

必要十分なコンテキストだけを渡す

カスタムインストラクションを活用する

関連ページ