AI エージェントに開発を頼むときによく出る用語を、何を指すか・取り消せるか・どう頼むかで並べました。各カードの「つまり」は、専門用語を使わずに実際に何が起きるかを書いたものです。「頼み方」の文は、そのままコピーしてエージェントに渡せます。初めての人は、下の「はじめての一本」の順に言っていけば、ゼロから公開まで進めます。2周目からは「バイブコーディングの流れ」の輪を回し、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 からと同じ順で確かめる。 → プル・ブランチ・回帰テスト
上の「はじめての一本」は、ゼロから公開までの一直線でした。ここは、AI エージェントと機能を1つずつ足していくときに回す輪です。段の数や名前は原文ごとに違うので、複数の原文が共通して書いている段で組みました（違う所は下の「原文によって違う所」）。各段の「原文では」は調べた原文の要点と出典、「持ち主のやり方」はこのページを作った人が普段やっている形です（出典なし・本人の設定から）。「バイブコーディング」の元の意味（コードを読まずに作る）とは違い、ここでは見直しと検査を入れた進め方を扱います（→ バイブコーディング・エージェンティック・エンジニアリング）。
原文では指示ファイル（AGENTS.md）・検査・フック・スキルを先に用意する。指示ファイルは短い目次にし、必ず守らせたいことはフックやリンターで止める。claude-code-best-practices-docs.md:222〜240, :302, :304 ／ openai-2026-harness-engineering-ja.md:68 ／ hashimoto-2026-ai-adoption-journey.md:217, :224
持ち主のやり方全リポジトリ共通の決まり（グローバルの CLAUDE.md）と、リポジトリごとの AGENTS.md の2段に分けている。作業の型はスキル（設計 → 計画 → 実装 → 検証 → 仕上げ）で持ち、文体を確かめる Stop フックと、特定のデプロイを止める PreToolUse フックを入れている。
原文では大きな機能は、AI に自分へのインタビューをさせ、SPEC.md に仕様を書かせてから、新しい会話で実装に入る。仕様は人が読んで直す。claude-code-best-practices-docs.md:421, :429, :431 ／ github-2025-spec-kit.md:39, :47 ／ kiro-2025-chat-to-specs.md:114
持ち主のやり方知らない分野は、作る前に /imozuru で原文を集めて調べる（このページもそうして作った）。作るものは brainstorming のスキルで質問させて決める。
原文ではplan モードで、まずファイルを読ませるだけにし、次に計画を出させる。差分を1文で言える小さな直しなら飛ばしてよい。claude-code-best-practices-docs.md:123, :170 ／ github-2025-spec-kit.md:41
持ち主のやり方writing-plans のスキルで計画を書かせ、読んで承認してから作らせる。共有の知識ベース（knowledge コマンド）で過去の知見を先に引く。
原文では一度に頼むのは機能1つだけ。一気に作らせると、途中で文脈が尽きたり、少しできた所で「全部できた」と言ったりする。anthropic-long-running-harnesses.md:55, :57, :96 ／ huntley-ralph.md:75 ／ github-2025-spec-kit.md:43, :45
持ち主のやり方既存の構成に合わせて最小の差分で作らせ、依存は増やさない。独立した作業はサブエージェントや別のセッションに分ける。
カード1回に1つ・並行作業とワークツリー・コミット
原文ではテスト・ビルド・スクリーンショットなど、合否が出る検査を AI 自身に走らせ、通るまで直させる。検査が無いと人が検査係になる。claude-code-best-practices-docs.md:89, :91, :106, :108 ／ anthropic-long-running-harnesses.md:104, :106
持ち主のやり方「できた」と言う前に、検証のコマンドを走らせて出力を見せる決まり（verification-before-completion のスキル）にしている。画面はブラウザで開いて確かめさせる。
原文では書いたエージェントとは別のエージェントに、新しい文脈で差分を判定させる。自分の作品は甘く採点するため。指摘は正しさと要件に関わるものだけ拾う。claude-code-best-practices-docs.md:629, :640 ／ anthropic-2026-harness-design-long-running.md:63, :65 ／ osmani-2026-loop-engineering.md:104
持ち主のやり方強いモデルの助言役（advisor）と、コードレビューのスキルに見せてから仕上げる。
原文では区切りごとにコミットし、進捗ファイルに済んだこと・次にやることを書く。人は差分と検査の証拠を見て、説明できないコードは入れない。anthropic-long-running-harnesses.md:98 ／ openai-2026-harness-engineering-ja.md:108 ／ willison-2025-not-all-vibe-coding.md:39 ／ claude-code-best-practices-docs.md:113
持ち主のやり方最後に「変えたファイル・理由・確かめ方・確かめていないこと」を報告させる。コードは GitHub に push して保全し、Cloudflare には Mac から wrangler で直接デプロイする。
原文では同じ失敗が繰り返されたら、成果物ではなく仕組み（AGENTS.md・検査・フック・道具）を直して、次から起きないようにする。hashimoto-2026-ai-adoption-journey.md:210 ／ boeckeler-2026-harness-engineering.md:105 ／ morris-2026-humans-and-agents-loops.md:67 ／ openai-2026-harness-engineering-ja.md:180
持ち主のやり方繰り返し使える知見だけを知識ベースに足し、AGENTS.md は最小の差分で直して、何を変えたかを報告させる。
| 点 | 違い |
|---|---|
| 段の数と名前 | Claude Code 公式は「探索・計画・実装・コミット」の4段、Spec Kit は「仕様・計画・作業・実装」の4段、Kiro は requirements.md・design.md・tasks.md の3つのファイル、Anthropic の長時間の実験は「初期化役」と「実装役」の2役（のちに計画役・作る役・判定役の3役）。claude-code-best-practices-docs.md:123 ／ github-2025-spec-kit.md:35 ／ kiro-2025-chat-to-specs.md:114〜118 ／ anthropic-long-running-harnesses.md:47 ／ anthropic-2026-harness-design-long-running.md:51 |
| 人が確かめる所 | Spec Kit は各段で人が確かめる。OpenAI のチームは人のレビューを必須にせず、エージェントどうしのレビューに移した。Willison は説明できないコードはコミットしない。github-2025-spec-kit.md:47 ／ openai-2026-harness-engineering-ja.md:42 ／ willison-2025-not-all-vibe-coding.md:39 |
| 計画を飛ばすか | Claude Code 公式は、差分を1文で言える直しなら計画を飛ばしてよいと書く。Huntley の Ralph は、何を作るかの選択もエージェントに任せる。claude-code-best-practices-docs.md:170 ／ huntley-ralph.md:75 |
ハーネスは、AI のモデル以外の、エージェントを動かす仕組みの全部です（→ ハーネス）。Claude Code で自分のプロジェクトに足せる部品を、何の係かで並べました。「先回り」は動く前に導くもの、「後追い」は動いた後に確かめるもの（→ ガイドとセンサー）。
| 部品 | 係 | 置き場所 | 先回り／後追い | カード |
|---|---|---|---|---|
| 決まりごと | 毎回読ませる約束（コマンド・禁止事項） | AGENTS.md・CLAUDE.md | 先回り | AGENTS.md・CLAUDE.md |
| 手順書 | 仕事の種類ごとのやり方 | スキル（SKILL.md） | 先回り | スキル |
| 検査 | 合否がはっきり出るもの | テスト・リント・型チェック・スクリーンショット | 後追い（機械） | 検証の仕組み・リント |
| 必ず動く処理 | 例外なく走らせる・止める | フック | 後追い（機械） | フック |
| 確認役 | 書いた本人とは別の目 | サブエージェント・別のセッション | 後追い（AI の判断） | 作る役と判定する役・サブエージェント |
| 外の道具 | イシュー・データベース・ブラウザにつなぐ | MCP・CLI（gh など） | — | MCP |
| 記録 | 次の会話への申し送り | 進捗ファイル・git の履歴 | — | 進捗ファイル |
| 繰り返し | 定期に回す・終わるまで回す | /loop・/goal・予定実行 | — | ループエンジニアリング |
| 囲い | 触ってよい範囲 | 許可モード・サンドボックス | — | YOLO モード・許可モード |
osmani-2026-loop-engineering.md:19〜68 ／ osmani-2026-agent-harness-engineering.md:25〜37 ／ boeckeler-2026-harness-engineering.md:85〜97 ／ claude-code-best-practices-docs.md:226〜390
AI は「終わったように見える」所で止まる。合否が出る検査を渡しておけば、AI が自分で直し続けられ、人は結果の証拠を見るだけで済む。
claude-code-best-practices-docs.md:89, :91, :113全部を1つの大きなファイルに書くと、文脈を圧迫し、全部が「重要」になって何も効かなくなり、すぐ古くなる。短い入口から詳しい文書へ案内する。1行ずつ「消したら AI が間違えるか」で削る。
openai-2026-harness-engineering-ja.md:56, :58, :62, :64, :68 ／ claude-code-best-practices-docs.md:240指示ファイルは助言にとどまる。例外なく守らせたいことはフックで止め、決まりはリンターや構造のテストで機械的に確かめる。文書で足りなければ、ルールをコードに昇格させる。
claude-code-best-practices-docs.md:304 ／ openai-2026-harness-engineering-ja.md:134, :148やる前に導くガイドだけだと効いたか分からない。やった後に確かめるセンサーだけだと同じ失敗を繰り返す。リンターのエラー文に直し方を書くと、AI がそれを読んで直せる。
boeckeler-2026-harness-engineering.md:69, :71, :73 ／ openai-2026-harness-engineering-ja.md:140テスト・リンター・型は速く安く確実。AI のレビューは遅く高くぶれるが、意味の判断ができる。速いものほど手元で早く、重いものは後で回す。
boeckeler-2026-harness-engineering.md:79, :81, :115, :117自分の作品を評価させると、出来が平凡でも自信満々にほめる。別のエージェントに判定させ、作る前に「何ができたら完了か」を取り決めておく。
anthropic-2026-harness-design-long-running.md:63, :65, :113失敗をモデルのせいにして次の版を待つのではなく、AGENTS.md に1行足す・道具を作る・フックで止める。成果物を手で直すより、成果物を作った仕組みを直す。
hashimoto-2026-ai-adoption-journey.md:210, :217, :224 ／ osmani-2026-agent-harness-engineering.md:7, :51 ／ morris-2026-humans-and-agents-loops.md:67ハーネスは人の経験を外に書き出す試みだが限界がある。人の関与をなくすのではなく、一番大事な所（何を作るか・正しいか）に向ける。
boeckeler-2026-harness-engineering.md:141, :193 ／ osmani-2026-loop-engineering.md:124, :126強いモデルでは、ハーネスありの方が費用が約7倍で結果は同じだった実験がある。費用を抑えたモデルでは、ハーネスありで成功が10回中3回から10回に増えた。何を作るか・どのモデルかで見合うかが変わる。
jain-2026-are-harnesses-worth-the-cost.md:5, :43| 形 | 人がやること | 向いているもの |
|---|---|---|
| バイブコーディング（人はループの外） | 何を作るかだけ言い、コードは読まない | 使い捨て・失敗しても困らない試作willison-2025-not-all-vibe-coding.md:29, :63 ／ morris-2026-humans-and-agents-loops.md:29 |
| 人がループの中 | AI が書いたものを1行ずつ検め、自分で直す | 小さくて大事な変更、AI が迷走している所morris-2026-humans-and-agents-loops.md:47, :51, :53 |
| 人がループの上（エージェンティック・エンジニアリング） | 仕組み（ハーネス）を作り、結果が悪ければ仕組みを直す | 続けて育てる製品morris-2026-humans-and-agents-loops.md:61, :67 ／ willison-2026-what-is-agentic-engineering.md:39, :41 |
| ループエンジニアリング | 指示を出す仕組みごと設計し、定期に回す | 決まった種類の仕分けや直しosmani-2026-loop-engineering.md:13, :114, :116 |
「ハーネスエンジニアリング」を言い出した人は、原文によって書き方が違う。Hashimoto は自分がそう呼ぶようになったと書き、Osmani は Viv Trivedy が名付けたと書き、Böckeler は OpenAI の記事が Hashimoto に影響されたのかもしれないと書く。どれが正しいかはここでは決めない。hashimoto-2026-ai-adoption-journey.md:209 ／ osmani-2026-agent-harness-engineering.md:13 ／ boeckeler-2026-harness-engineering-memo.md:17
| 組 | 違い |
|---|---|
| 作業ツリー ／ ワークツリー | 作業ツリー＝いま編集中のファイルそのもの。ワークツリー（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/ にある原文の行を指します（「バイブコーディングとハーネス」の章と、上の「バイブコーディングの流れ」「ハーネスの組み立て方」は、話題 vibe-coding-harness の 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（各道具・決まりごとの公式文書）／ Anthropic Engineering・OpenAI（エージェントを作った側の記事）／ Simon Willison・Mitchell Hashimoto・Addy Osmani・Geoffrey Huntley（AI で開発している本人の記事）／ Birgitta Böckeler・Kief Morris・Naresh Jain（martinfowler.com の連載 Exploring Gen AI）
姉妹ページ UI用語と動きの図鑑 ↗ — 画面の部品（モーダル・トースト・ボトムシート…）と動き（イージング・スタッガー・画面遷移…）の名前を、動く図つきで並べたページ。こちらが「どこまでやるか」、あちらが「何を作るか」です。
| 困りごと | 言うこと | 見るカード |
|---|---|---|
| 「ログインして」と言われた（gh auth login、wrangler login） | 「ログインの手順だけ教えて。ブラウザでのログインは私がやる。パスワードは渡さない」 | wrangler・シークレット |
| エージェントが頼んでいない所まで進めた（勝手にプッシュした、など） | 「プッシュとデプロイの前は必ず私に確認して。AGENTS.md にもそう書いて。もう送った分は revert で打ち消して」 | 確認を求める操作・リバート・AGENTS.md |
| 自動検査が落ちた（PR に × が出た、「CI failed」のメールが来た） | 「どのステップで落ちたかログを見て直して。直せなければ直前のコミットを戻して」 | CI・ステータスチェック |
| 「プッシュが拒否された」と言われた | 「先に pull して最新にしてから、もう一度プッシュして。コンフリクトがあれば見せて」 | プッシュ・プル |
| 「コンフリクト」と言われた | 「どの行がぶつかっているか見せて。判断が要るところは私に聞いて」 | コンフリクト |
| http://localhost:… が開かない | 「開発サーバーが動いているか、ポート番号が合っているか確かめて。だめなら別のポートで立ち上げ直して」 | 開発サーバー |
| 本番が壊れた | 「まず直前の版にロールバックして。原因を調べるのはその後」 | ロールバック・ホットフィックス |
| 秘密の値（API キー）をコミットしてしまった | 「どの画面でキーを作り直すか教えて。作り直しは私がやる。古いキーを無効にして。履歴の書き換えが要るなら、やる前に説明して」 | シークレット・.gitignore |
| 前は動いていたのに動かない | 「再現する手順を書いて、それを回帰テストにしてから直して」 | 回帰テスト |
| AI が同じ間違いを何度も繰り返す | 「同じ間違いが2回目。AGENTS.md・テスト・フックのどれで防げるか提案して、直して」 | ハーネスエンジニアリング |
| 何をされたか分からない | 「差分をファイルごとに日本語で要約して」 | 差分 |
| 話が長くなって、前に言ったことを忘れる（/compact は自分で入力欄に打つ。決まりごとは AGENTS.md に書いておく） | 「/compact 決まりごとは残して」 | コンテキスト・AGENTS.md |
| 「Dependabot」のメールが来た／npm install のあとに vulnerabilities と出た | 「警告を一覧にして、深刻なものから直す案を出して。更新はテストを通してから」 | 脆弱性の警告・ロックファイル |
| デプロイしたのに画面が変わらない | 「デプロイの一覧で最新が本番（main）になっているか確かめて。ブラウザの再読み込み（キャッシュ）も疑って」 | デプロイ・Pages・wrangler |
| 専門用語が分からない | 「分からない言葉を使わずに、実際に何が起きるかで言い直して。— このページでは、上の検索欄で引いてカードの「つまり」を読む」 | はじめての一本 |