AI エージェントに開発を頼むときによく出る用語を、何を指すか・取り消せるか・どう頼むかで並べました。各カードの「つまり」は、専門用語を使わずに実際に何が起きるかを書いたものです。「頼み方」の文は、そのままコピーしてエージェントに渡せます。初めての人は、下の「はじめての一本」の順に言っていけば、ゼロから公開まで進めます。
姉妹ページ UI用語と動きの図鑑 ↗ — 画面の部品と動きの名前（モーダル・トースト・イージング…）はあちらに。「何を作るか」はあちらの名前で、「どこまでやるか」はこのページの言い方で頼みます。
右へ進むほど取り消しにくくなります。エージェントには「どこまでやるか」をこの順で言い切ると、範囲が食い違いません。「何を作るか」（画面の部品や動きの名前）は UI用語と動きの図鑑 の名前で言うと、1つの依頼で両方がそろいます。
| 言い方 | エージェントがやること | 取り消し |
|---|---|---|
| 「直して（ファイルの変更まで）」 | ファイルを書き換える。コミットはしない | 手元だけ |
| 「コミットまで」 | 変更を履歴に記録する。プッシュはしない | 手元だけ |
| 「プッシュまで」 | 記録を GitHub などの共有の場所へ送る | チームに影響 |
| 「PR を作って」 | 変更をまとめて、取り込んでほしいと提案する | チームに影響 |
| 「マージして」 | PR の変更を main などの本線に取り込む（main のマージで自動公開する設定なら、ここが公開になる） | チームに影響 |
| 「プレビューに出して」 | 本番は変えずに、確認用の URL に出す（URL は既定で誰でも開ける） | 公開に影響 |
| 「デプロイして」 | 本番やステージングの環境に反映する | 公開に影響 |
初めてでも、この順に言えば一通り動くものを公開できます。「言うこと」はコピーしてそのまま渡せます。「確かめること」は、エージェントではなく自分の目で見る項目です。色の印は、その段で起きることの取り消しやすさです。
確かめることGitHub と Cloudflare のアカウント、Node.js、Claude Code が入っている。ログインの画面は自分で操作する（パスワードはエージェントに渡さない）。 → wrangler・シークレット
確かめることGitHub にリポジトリが見える。「Private」の表示がある。 → リポジトリ・.gitignore
確かめること自分で AGENTS.md を開いて、分かる言葉で書いてあるか読む。 → CLAUDE.md と AGENTS.md・確認を求める操作
確かめること先に Shift+Tab（デスクトップはモードの選択欄）で plan モードにして、表示が plan になったのを見る。計画に「何を・どのファイルに・どう確かめるか」が書いてある。分からない言葉はこのページで引く。 → プランモード・許可モード
確かめること自分でも http://localhost:… を開いて触る。画面の部品の名前は姉妹ページで引く。 → 開発サーバー
確かめることリポジトリに .github/workflows/ のファイルができている。次の段でプッシュすると、PR のページの下に ✓ か × が出るようになる。 → GitHub Actions・CI
確かめることPR のページを開く。下のほうに自動検査の ✓（通った）が付いている。× なら「落ちた原因を直して」。 → プッシュ・プルリクエスト・ステータスチェック
確かめることCloudflare の画面にプロジェクトが見える。「main にマージしたら自動で公開される？」と聞いて「いいえ（直接アップロードなので人が出す）」と返るのを確かめる。 → Cloudflare Pages・wrangler・CD
確かめることURL をスマホでも開く。見せたくない内容なら鍵をかける（Access）。 → プレビューデプロイ・Access
確かめることmain に入ったこと、自動検査が ✓ のこと。一人ならスカッシュでよい（PR 1つが記録1つになり、戻しやすい）。 → マージの方法・マージ
確かめることplan モードにしてから頼む。計画を読んで承認したら、5 からと同じ順で確かめる。 → プル・ブランチ・回帰テスト
| 組 | 違い |
|---|---|
| 作業ツリー ／ ワークツリー | 作業ツリー＝いま編集中のファイルそのもの。ワークツリー（git worktree）＝その作業ツリーを、別のブランチでもう1つ別のフォルダに作る仕組み（Git の文書では、作業ツリーと管理情報をまとめたものを worktree と呼ぶ） |
| npm ci ／ CI | npm ci の ci は clean install の略で、借りてきた部品を一覧表どおりに入れ直すコマンド。CI（継続的インテグレーション）は自動の検査の仕組み。綴りが同じだけ |
| ステージング ／ プレビュー | どちらも本番の前に確かめる場所。ステージングは本番そっくりの環境を別に持つ。プレビューは Pages が PR やブランチごとに自動で作る URL。小さなサイトではプレビューがステージングの役をする |
| ステージ ／ ステージング | ステージ（git add）は次のコミットに入れる変更の置き場。ステージング（環境）は本番そっくりの確認用の環境。名前は似ているが無関係 |
| フェッチ ／ プル | フェッチは取ってくるだけ。プルは取ってきて、今のブランチに混ぜる（コンフリクトが起きうる） |
| マージ ／ リベース | マージは合流点を作って両方の履歴を残す。リベースは自分のコミットを付け直して一直線にする（プッシュ済みにはしない） |
| リバート ／ リセット | リバートは打ち消すコミットを足す（共有済みにも安全）。リセットは履歴そのものを戻す（手元だけ） |
| reset --soft ／ --hard | --soft はコミットだけ取り消して変更はファイルに残す。--hard は変更も捨てる（戻せないことがある） |
| 継続的デリバリー ／ 継続的デプロイ | デリバリーは「いつでも出せる状態」を保つ（出すかは人が決める）。デプロイは通った変更が自動で本番に出る |
| ロールバック ／ リバート | ロールバックは本番で動く版を前に戻す操作。リバートはコードの変更を打ち消すコミット。障害時はまずロールバック、原因を直すのはリバートや修正のコミット |
| クローン ／ フォーク | クローンは手元へのコピー。フォークは自分のアカウント（GitHub 上）へのコピー |
| ビルド ／ デプロイ | ビルドは動くものに変換する処理（手元だけ）。デプロイはそれを置いて使える状態にする（公開に影響） |
| Git フック ／ Claude Code のフック | Git フックは commit や push のときに Git が走らせる。Claude Code のフックはエージェントがファイルを編集したときなどに走る |
| イシュー ／ PR | イシューは課題や提案の記録。PR は変更そのものの提案。PR の説明に「Closes #番号」と書くとつながる |
| Pages ／ Workers | Pages は置くだけのファイルの棚。Workers は裏側のプログラムの置き場（静的ファイルも配れる）。新規は Workers を勧めるのが Cloudflare の方針 |
| D1 ／ KV ／ R2 | D1 は表（帳簿）、KV は名前→値の小さなメモ（付箋）、R2 はファイルそのもの（倉庫） |
| マイグレーション（DB）／ 移行（一般） | このページのマイグレーションは、データベースの形を変える手順のこと。言語や環境の乗り換え全般を指す「移行」とは別 |
| やったこと | 取り消し方 | 注意 |
|---|---|---|
| ファイルの変更（コミット前） | 変更を捨てる（git restore）か stash | 捨てた変更は戻せないことがある |
| コミット（プッシュ前） | reset --soft で記録だけ取り消す／新しいコミットで直す | 手元だけなので安全 |
| プッシュ | revert のコミットを作ってプッシュ | 履歴を消す（reset ＋ force push）のは避ける |
| main へのマージ | revert の PR を作ってマージ | 取り消したことも履歴に残る |
| デプロイ | 前の版へロールバック | 出ていた間に見られたことは消えない |
| 秘密の値の流出 | キーを作り直して古いキーを無効にする | コミットを消しても、すでにコピーされているかもしれない |
出典の ファイル名:行 は、調べものの話題 agent-dev-terms の sources/ にある原文の行を指します。「出典なし」の印は、今回集めた原文に定義が無かった語です。
主な出典の名前: Pro Git・git-scm.com（Git の公式の本と文書）／ GitHub Docs（GitHub の公式文書）／ Martin Fowler（martinfowler.com。CI・デリバリー・リファクタリングの定義を書いた人）／ Google SRE Book（Google の運用の本）／ Cloudflare Docs（Pages・Workers・D1 などの公式文書）／ Claude Code docs（Claude Code の公式文書）／ npm・Playwright・semver.org・12-factor（各道具・決まりごとの公式文書）
姉妹ページ UI用語と動きの図鑑 ↗ — 画面の部品（モーダル・トースト・ボトムシート…）と動き（イージング・スタッガー・画面遷移…）の名前を、動く図つきで並べたページ。こちらが「どこまでやるか」、あちらが「何を作るか」です。
| 困りごと | 言うこと | 見るカード |
|---|---|---|
| 「ログインして」と言われた（gh auth login、wrangler login） | 「ログインの手順だけ教えて。ブラウザでのログインは私がやる。パスワードは渡さない」 | wrangler・シークレット |
| エージェントが頼んでいない所まで進めた（勝手にプッシュした、など） | 「プッシュとデプロイの前は必ず私に確認して。AGENTS.md にもそう書いて。もう送った分は revert で打ち消して」 | 確認を求める操作・リバート・AGENTS.md |
| 自動検査が落ちた（PR に × が出た、「CI failed」のメールが来た） | 「どのステップで落ちたかログを見て直して。直せなければ直前のコミットを戻して」 | CI・ステータスチェック |
| 「プッシュが拒否された」と言われた | 「先に pull して最新にしてから、もう一度プッシュして。コンフリクトがあれば見せて」 | プッシュ・プル |
| 「コンフリクト」と言われた | 「どの行がぶつかっているか見せて。判断が要るところは私に聞いて」 | コンフリクト |
| http://localhost:… が開かない | 「開発サーバーが動いているか、ポート番号が合っているか確かめて。だめなら別のポートで立ち上げ直して」 | 開発サーバー |
| 本番が壊れた | 「まず直前の版にロールバックして。原因を調べるのはその後」 | ロールバック・ホットフィックス |
| 秘密の値（API キー）をコミットしてしまった | 「どの画面でキーを作り直すか教えて。作り直しは私がやる。古いキーを無効にして。履歴の書き換えが要るなら、やる前に説明して」 | シークレット・.gitignore |
| 前は動いていたのに動かない | 「再現する手順を書いて、それを回帰テストにしてから直して」 | 回帰テスト |
| 何をされたか分からない | 「差分をファイルごとに日本語で要約して」 | 差分 |
| 話が長くなって、前に言ったことを忘れる（/compact は自分で入力欄に打つ。決まりごとは AGENTS.md に書いておく） | 「/compact 決まりごとは残して」 | コンテキスト・AGENTS.md |
| 「Dependabot」のメールが来た／npm install のあとに vulnerabilities と出た | 「警告を一覧にして、深刻なものから直す案を出して。更新はテストを通してから」 | 脆弱性の警告・ロックファイル |
| デプロイしたのに画面が変わらない | 「デプロイの一覧で最新が本番（main）になっているか確かめて。ブラウザの再読み込み（キャッシュ）も疑って」 | デプロイ・Pages・wrangler |
| 専門用語が分からない | 「分からない言葉を使わずに、実際に何が起きるかで言い直して。— このページでは、上の検索欄で引いてカードの「つまり」を読む」 | はじめての一本 |