Vibe Coding について

AI（Claude Code など）と一緒に開発を進めるための心得です。

考え方（マインドセット）

  • コードの品質管理は、人間のチーム開発と同じ。AI は優秀な仲間
  • AI がきれいなコードを書ける「環境」をつくる PM になるのが目標
  • AI はコードを書きすぎる傾向がある
    • メンテしやすく、人間が読める実装に導く

プログラミング以外にも使う

  • ドキュメント作成や、定期的に実行するツールにも使う
  • LLM を「実行レイヤー」と捉え、CLI や Web API を組み合わせて多様なタスクに使う

環境への投資

  • まずは $200 プラン（Max）に課金する
    • 利用制限を気にせず使えることが、そのまま生産性につながる
  • モニタの枚数はできる限り増やす
  • 基本は terminal で、ローカル環境で使う（エンジニア限定)
  • local LLM でケチる、のような無駄な設定・最適化に時間を使わない
    • 設定で消耗するより、素直に良い環境にお金を払うほうが速い

ツール選定（枯れたツールを使う）

  • ネットにドキュメントが多いツール ＝ AI がよく知っている
    • なので、枯れた（成熟した）ツールを選ぶと AI の精度が上がる

AI を過信しない・最新情報を追う

  • AI の知識を鵜呑みにしない。必ず検索させて裏を取る
  • 今日の日付が必要なときは、必ず date コマンドで取得する（モデルの内部知識に頼らない）
  • 公式ドキュメントを読む（読ませる）
  • 数ヶ月でノウハウが変わる。できる限り新しい情報をキャッチアップする

わからないことは AI に聞く

  • AI を過信しないのと同時に、わからないことは遠慮なく AI に聞く
  • 自分が理解できるまで徹底的に聞く。AI は何度でも答えてくれる
    • 「わかったふり」で進めると、後でコードが読めなくなる
    • 人間相手だと聞きづらい初歩的な質問こそ AI に向いている
  • 裏取り（前セクション）とセットで使う：AI に聞いて理解し、重要なこと・内容に確信を持てない時は裏を取る

テキストで残す・git で管理する

  • text がすべて。気になったこと・作業ログも、できる限り text で残す
  • prompt は捨てずに残す（prompt = context）
    • 後で作り直すときの材料にもなる
  • チャットは消える。重要な情報は残す場所を決めておく
    • 課題 → GitHub issue ／ 計画 → plans/ ディレクトリ
    • 設計判断 → commit メッセージ・PR ／ 重要な議論 → issue・PR コメント
  • CLAUDE.md なども含め、すべてリポジトリ（git）で管理する
    • git で管理していないもの ＝ 管理できていない、と考えるべき
  • 独自ツールは長期の存続が不確実。Markdown + GitHub のようなテキストベースが最も長持ちする

CLAUDE.md / md ファイルの書き方

  • .claude/CLAUDE.md をきちんと書く
    • プロジェクトのルール・規約・コーディングスタイルをここに集約する
  • md ファイルは 80行くらいが最もよく効く
    • 長いのはダメ。150行を超えたら、できる限り分割する
    • 長く書くと、AI が見落とす（読み飛ばす）箇所が出る
    • この行数の目安は AI が読む md（CLAUDE.md・参照 md）の話。人間向けドキュメントには当てはまらない
  • CLAUDE.md から参照する md を書いておけば、必要に応じて参照してくれる
    • 詳細は別 md に切り出し、CLAUDE.md 本体は短く保つ
  • 2回指摘したことは CLAUDE.md に落とし込む（同じ指示を繰り返さない）

設定（settings.json）

  • ~/.claude/settings.json の permission を書いておく
    • よく使うコマンドを許可しておくと、毎回の確認が減る
  • hooks/PostToolUse も設定する
    • ファイル編集の後に format / lint を自動で走らせる、といった使い方ができる

定型タスクは skill 化する

  • 繰り返し行う手順（リリース、PR レビュー対応など）は skill / command にまとめる
  • パラメータ化して再利用できるようにしておくと、毎回指示し直さなくて済む
  • プログラム化できるタスクは、unit test 付きのコードにする
  • プログラム化できないタスクは、コード + LLM を組み合わせた skill にする

進め方（ワークフロー）

  • まずは plan をつくる
  • ドキュメントを継続的にメンテする
  • git は rebase ではなく merge（履歴より、コードを綺麗に保つ → git.md）
  • 品質維持のため、PR の粒度は細かくする
  • Web アプリなら Playwright で実際に動かして確認させる
  • Claude Code / Codex などで相互レビューさせる

本番コードと使い捨てコードで使い分ける

  • 本番コード：粒度を細かく指示し、出力をコードレビューする
    • AI レビューツール（CodeRabbit など）の指摘を Claude に戻して直させる
    • レビュー承認後にマージする
  • プロトタイプ / 使い捨てツール：粗い指示でよい
    • 動作確認 ＋ 簡単な PR レビューで十分

ライブラリ / Web API を作るとき

  • 利用者（開発者）の AI が読む md を提供する
  • サンプルコード・test・API doc をそろえる
    • AI がこれらを読んで、正しく使えるようにする

コード品質（最重要）

  • 型のある言語は、型をきちんと定義して使う
  • 関数・コードはできるだけ短くする。いざというとき人間が把握できるように
  • AI は放っておくと DRY にならない。ライブラリ／モジュール構成を先に指定し、そこへ集約させる
  • lint / unit test / typecheck を必ず回す
  • CI を整備する。CI の bot（レビュー bot など）も活用する
  • unit test はできる限り書かせる
    • そのために unit test しやすいコードを書く = pure 関数に分割する
    • 副作用を分離しておくと、テストも AI の理解も楽になる
    • edge case / corner case / 境界値など、「際」のケースをたくさん書く
  • 定期的に refactor する：unit test 追加 / ライブラリ化 / DRY / 不要コードの削除

発展編（慣れてきたら）

  • 並列で動かす：複数の Claude Code を同時に走らせる
    • 独立したタスクなら、片方の AI を待っている間にもう片方を進められる
    • ただし、人間側の認知負荷も上がるので、PR の粒度や進捗管理を丁寧に
    • 別ディレクトリ（git worktree など）を使うと、作業が混ざらず安全
  • 人間はこまめに時間を取る：AI が長時間自走できるようになったら、人間側はまとめて長時間確保するより、短い時間を何度も取るほうが進みが良い
    • AI の自走中は別作業ができる
    • 「10分だけやる」でも着手できる
    • 食事の前に 少し時間をとって、AI に依頼する

合わせて読む