3日で読んでも、必要な章だけ開いても大丈夫です
初回は第1〜10章を順番に読み、第11章以降は実習日に開くのがおすすめです。すぐ作りたい方も、安全の章だけは飛ばさないでください。
1日目:仕組みを知る
第1〜6章。AIエージェント、OpenCode、OpenRouter、GLM-5.3-Flash、APIキーの関係を理解します。
2日目:安全に接続する
第7〜12章。専用フォルダ、料金上限、インストール、接続、最初の小さな作業を体験します。
3日目:作品を作る
第13章を読んだあと、Chrome拡張機能(第14章)かMacアプリ(第15章)のどちらか1つを選びます。第16章で保存地点を確認したら、3日間の基礎コースは完了です。
第17章以降は、初作品のあとに進む発展・参照編です。サブエージェント、上位モデル、料金分析、安全監査、トラブル対応は、必要な日に1章ずつ開いてください。3日間ですべてを終わらせる必要はありません。
始める前に必要なもの
- アプリを導入できるMacの利用者権限と、安定したインターネット接続
- OpenRouterのアカウント、API利用料に充てる少額の支払い手段
- Chrome拡張機能の章へ進む場合は、最新版へ更新できるGoogle Chrome
- Macアプリの章へ進む場合は、Macに対応するXcodeと、追加部品を含めて導入できる十分な空き容量
会社や学校が管理するMacでは、アプリの導入や開発者モードが制限されている場合があります。その場合は管理者の方針を優先し、制限を回避しないでください。Xcodeの対応macOSは版によって変わるため、Mac App StoreまたはApple公式ページで利用中のMacとの互換性を確認します。
PART 1 何ができるのかを、難しい言葉なしでつかむ
日本語で相談すると、AIがMacの作業フォルダで手を動かします
この仕組みの一番大きな価値は、コードの答えを受け取るだけでなく、相談→作成→確認→修正を同じ場所で繰り返せることです。
普通のチャットAIに「タイマーアプリを作って」と頼むと、多くの場合はコードが文章として返ってきます。利用者はそのコードをコピーし、正しいファイルへ貼り、エラーが出たら再びチャットへ持ち帰ります。これは、料理研究家からレシピだけを受け取り、台所での作業は自分がすべて行う形です。
OpenCodeのようなAIコーディングエージェントは、作業フォルダの中を見られます。許可された範囲でファイルを作り、変更し、テスト用の命令を実行できます。料理にたとえるなら、レシピを考えるだけでなく、台所で材料を確認し、調理し、味見の結果から直せる助手です。
普通のチャットAI
説明やコード例を返すのが中心です。ファイルへの反映と確認は、利用者が別に行います。
AIコーディングエージェント
対象フォルダを調べ、ファイルを編集し、検査を実行して、結果をもとに次の修正へ進みます。
「AIが自由にMac全体を操作する」と考えないでください。作業場所と権限を狭くし、重要な操作は確認を求める設定にします。優秀な助手でも、初日から家中の鍵を渡す必要はありません。
4つの役割を分けると、仕組みは驚くほど単純です
あなたが店長、OpenCodeが作業場、OpenRouterが案内所、GLM-5.3-Flashが考える担当です。名前を一度に覚えなくても、役割が分かれば迷いません。
OpenCodeは「仕事をする場所と道具」です
OpenCodeは、ターミナル画面やデスクトップアプリで使える、オープンソースのAIコーディングエージェントです。公式資料では、ファイル操作、コマンド実行、複数セッション、モデル提供会社との接続などを扱います。自分で考える頭脳そのものではなく、AIモデルがMac上で安全に仕事をするための作業場です。
OpenRouterは「1枚の会員証で複数のAIへ行ける案内所」です
AIモデルごとに別々の契約と接続方法を覚える代わりに、OpenRouterのAPIキー1つで多くのモデルへ接続できます。OpenCodeから見れば、OpenRouterは統一された入口です。後からレビュー担当だけ別モデルへ変えたいとき、接続を作り直さずに済むのが大きな利点です。
GLM-5.3-Flashは「普段の開発を担当する頭脳」です
Z.aiが2026年8月26日に公開したGLM-5.3-Flashは、コーディングや道具の操作、長い作業を想定したAIモデルです。OpenRouterでの正式なモデルIDはz-ai/glm-5.3-flash。OpenCodeの設定では、接続先を含めてopenrouter/z-ai/glm-5.3-flashと表す場面があります。
z-ai/glm-5.3-flashです。住所の1文字が違うと「モデルが見つかりません」と表示されます。コピーするときは前後に空白を入れないでください。
深掘り:なぜOpenRouterを間に入れるのですか
GLMだけを使うならZ.aiへ直接接続する方法もあります。それでもOpenRouterを使う理由は、請求とモデル選択を1か所へまとめ、同じOpenCodeの中で別会社のモデルへ切り替えやすくするためです。また、同じモデルを複数の設備提供者が扱う場合、OpenRouterは利用可能な提供者へ振り分けられます。
反対意見もあります。中継サービスが増えるほど、設定箇所とデータの通過点も増えます。そのため、機密性が高い仕事では、直接契約や社内指定の経路が適切な場合があります。本書は個人の学習と小規模開発を想定し、個人情報や秘密情報を送らない前提で説明します。
AIは「賢い自動操縦」ですが、責任者はいつも人間です
AIは速く大量に試せます。一方で、もっともらしい間違いも作ります。速さはAI、目的と最終確認は人間と分担してください。
AIモデルは、文章やコードの続きを予測しながら答えを組み立てます。辞書のように正解を取り出しているわけではありません。知っているように見える言い方で、存在しない機能名や古い手順を出すことがあります。この現象を「幻覚」と呼ぶことがありますが、超初心者の段階では「自信のある言い間違い」と理解すれば十分です。
| AIが得意 | 人が受け持つ |
|---|---|
| たたき台を速く作る | 何を作るか、誰のためかを決める |
| 複数ファイルの関係を調べる | 見せてよいファイルか判断する |
| テストを何度も実行する | テスト項目が目的を満たすか確認する |
| エラーから修正案を出す | 変更範囲と副作用を承認する |
| 別の実装案を比較する | 料金、期限、利用者への影響を決める |
「動いた」は「正しい」の一部にすぎません
アプリが開けば第一関門は通過です。しかし、データを勝手に外へ送っていないか、他の画面を壊していないか、再起動後も使えるか、知らない人でも操作できるかは別の確認です。完成の意味を、AIと人で共有する必要があります。
最小の変更
テストと画面
原因に絞る
元の機能も確認
この4段階を一周で終わらせず、新しい証拠が出るまで回します。テスト結果、画面の表示、エラーメッセージ、変更差分などが「新しい証拠」です。AIの「大丈夫です」という文章だけは証拠になりません。
専門用語は、開発室の道具に置き換えると覚えられます
最初に覚える言葉は10個ほどです。すべてを正確に暗記するより、何のためにあるかを先につかんでください。
| 用語 | やさしい意味 | たとえ |
|---|---|---|
| ターミナル | 文字でMacへ指示を出すアプリ | Macと会話する受付窓口 |
| コマンド | ターミナルに入力する短い命令 | 「この棚を見せて」の一言 |
| フォルダ/ディレクトリ | ファイルをまとめる場所。ほぼ同じ意味 | 作業ごとの部屋 |
| プロジェクト | 1つの作品に必要なファイル一式 | 1軒分の設計図と材料 |
| API | ソフト同士が決まった方法で話す入口 | 注文票を渡す窓口 |
| APIキー | 利用者と支払い先を識別する秘密の文字列 | 暗証番号つきの会員証 |
| モデル | 文章やコードを考えるAI本体 | 担当者の頭脳 |
| トークン | AIが文章を数える細かな単位 | 郵便料金を決める文字の小包 |
| コンテキスト | AIがその時点で参照している会話やファイル | 机に広げた資料 |
| リポジトリ | 変更履歴も含めて管理するプロジェクト | 設計図と改訂記録を保つ書庫 |
| ビルド | コードを実行できる形に組み立てる作業 | 設計図から製品を組み立てる工程 |
| テスト | 期待した動作か自動・手動で確かめること | 出荷前の検品 |
入力トークンと出力トークンで料金が分かれます
AIへ送る依頼文、会話履歴、読み込ませたコードが「入力」です。AIが返す説明やコードが「出力」です。モデルページでは、通常「100万トークンあたり何ドル」と表示されます。長いコードを何度も読み直す作業では、目に見える質問が短くても入力が大きくなります。
コンテキストが大きくても、無限に覚えているわけではありません
GLM-5.3-Flashは長い情報を扱えるモデルですが、毎回すべてを詰め込めばよいわけではありません。机が広くても、不要な書類を山積みにすれば探しにくくなります。プロジェクトを分け、古いログや巨大ファイルを必要なときだけ読むほうが、料金と精度の両方に効きます。
用語が分からなくなったときの質問文
いま出てきた「○○」という言葉を、
1. 何のためにあるか
2. 身近なたとえ
3. このプロジェクトでの具体例
の順で、中学生にも分かるように説明してください。
説明だけにして、ファイルは変更しないでください。
OpenCodeは手足、GLMは頭脳、権限設定はドアの鍵です
AIの能力だけでなく、どの道具を使えるかが結果を決めます。権限は不便を増やす壁ではなく、間違いを小さくするドアの鍵です。
OpenCodeには、読む、編集する、コマンドを実行する、Webを調べる、別のエージェントを呼ぶ、といった道具があります。公式資料では、操作ごとにask(毎回確認)、allow(許可)、deny(禁止)を設定できます。
ask
ドアの前で毎回呼び鈴を押します。初心者の編集やコマンド実行は、まずこの考え方が安全です。
allow
合鍵を渡します。頻繁で安全性を理解した操作だけに絞ります。
deny
そのドアは開きません。レビュー担当の編集禁止などに向きます。
PlanとBuildを使い分けます
OpenCodeには、分析や計画向けのPlanと、実際の開発を進めるBuildという考え方があります。ターミナル版ではTabキーで主担当を切り替えられます。画面の担当名がPlanになったことを確認してから計画の依頼を貼り、納得した後にもう一度Tabを押してBuildへ切り替えます。
Planは作業コードの編集を抑える役割ですが、版や設定によっては計画ファイルの作成やコマンド実行の確認が出ます。「読み取りだけ」を望む場面では、許可画面の対象を読み、編集やコマンド実行を承認しないでください。Buildへ移る前に図面を見る、という順番を守ります。
外部フォルダと秘密ファイルは、特に慎重に扱います
現在のOpenCode公式資料では、プロジェクトの外を読む操作や、.envのような秘密情報を置きやすいファイルは、確認対象として扱う設計が示されています。ただし設定やバージョンで動作は変わり得ます。画面に許可の質問が出たら、意味を読まずに承認しないでください。
GLM-5.3-Flashを普段の主担当にし、上位モデルは節目だけ使います
GLM-5.3-Flashを普段の担当にし、難しいレビューだけ別会社の上位モデルへ任せると、費用・速度・見落とし対策のバランスを取りやすくなります。
この構成では、日常のファイル調査、実装、テストをGLM-5.3-Flashへ任せます。公式発表でもコード作業と道具の操作を想定した性能が示され、OpenRouterでは低い料金で提供されています。ただし、評価値はあなたの作品の成功を保証しません。
深掘り:モデルの規模と公式評価値
Z.ai公式発表によると、GLM-5.3-Flashは合計3200億のパラメータのうち、処理時に180億を動かす設計です。パラメータはAI内部の調整値で、「学習した判断のつまみ」のようなものです。すべてを毎回動かさないため、大きなモデルでありながら計算量を抑えます。
同社は、コード作業の評価であるTerminal Bench 2.1を84.3、DeepSWE v1.1を63.4と公表しています。画像や動画を入力できるマルチモーダル機能と、長いコンテキストも特徴です。これらはZ.aiの公表値で、本書が再測定した結果ではありません。
なぜ「Flash」なのですか
一般にFlashという名前は、速度や費用を重視した系列に付けられます。GLM-5.3-Flashも、最上位のGLM-5.3より計算を軽くし、普段使いしやすくする位置づけです。すべての難問で上位モデルに勝つという意味ではありません。
反論:最初から最強モデルだけを使えば簡単では?
確かに、難しい設計や複雑な不具合では上位モデルが早く解決し、結果として安くなる場合があります。ただし、ファイル名の変更、文言修正、簡単な画面作成、テスト追加まで毎回高価なモデルへ頼むと、費用が読みにくくなります。
再反論:普段はGLM-5.3-Flash、詰まった場面と最終レビューだけ上位モデルにする運用なら、能力が必要な場所へ費用を集中できます。選ぶ基準はモデルの格付けより、仕事の難しさと失敗時の影響です。
反論:同じGLMをレビューにも使えば、さらに安いのでは?
費用は下がります。しかし、同じ系列のモデルは似た思い込みを持つ可能性があります。作った担当と違う会社のモデルに読ませると、別の角度から欠点を見つけやすくなります。
再反論:すべての変更に別モデルは不要です。公開前、課金処理、個人情報、ファイル削除、権限追加など、失敗の影響が大きい変更だけに絞れば、レビュー費用は管理できます。
PART 2 Macを安全な開発室に整える
準備は「専用フォルダ・バックアップ・秘密を分ける」の3点です
インストール前に安全な作業場所を作ります。失敗しても作品フォルダだけを戻せる状態なら、試すことが怖くなくなります。
pwdとlsを練習してから戻ってください。複数行のコード欄は、特に「まとめて貼る」と書いていない限り、上から1行ずつ実行します。1行ごとに表示を確認し、エラーが出たら次へ進みません。
実習前の5枚扉
第20章で詳しく扱いますが、最初の実習前にも次の5点を確認します。秘密を入れない、専用フォルダだけを対象にする、変更前にバックアップを取る、外部通信と権限を説明させる、公開は別の承認にする。この5点のどれかが曖昧なら、Buildへ進みません。
作品ごとに専用フォルダを作ります
ここでは、書類フォルダの中にAI-Projectsを作り、その中へ作品を1つずつ置きます。日本語や空白を含むフォルダ名でもMacは扱えますが、最初は半角英数字とハイフンにすると、コマンドの入力が楽です。
mkdir -p "$HOME/Documents/AI-Projects"
cd "$HOME/Documents/AI-Projects"
mkdir my-first-project
cd my-first-project
pwd
mkdirはフォルダを作り、cdは作業場所を移し、pwdは現在地を表示します。二重引用符は、パスに空白があっても1つの場所として扱う囲いです。
Time Machineか別の複製を用意します
Mac全体はTime Machine、作品はGitという変更履歴の道具で守るのが理想です。Gitは後の章で使います。初日は、少なくとも作品フォルダを別名で複製できる状態にしてください。ただし、複製を同じ作業フォルダの中へ置くとAIが両方を編集する可能性があるため、バックアップは作業場所の外へ置きます。
秘密をコードから分けます
APIキー、パスワード、個人情報は、コードの中へ直接書きません。画面共有、スクリーンショット、AIへの依頼文にも入れません。OpenCodeの/connectが表示する専用入力欄へ貼り付けます。
最初の安全チェック
iTerm2は文字でMacと話すための、見やすく頼れる仕事机です
iTerm2はターミナルを快適にする人気のMacアプリです。本書では魅力だけを紹介し、インストール手順は藤川さんの専用解説へ任せます。
Macには標準の「ターミナル」アプリがあります。それでもiTerm2が好まれるのは、画面を分割して片側でOpenCode、もう片側でテスト結果を見る、検索で過去の表示へ戻る、色や文字を読みやすく整える、といった長時間作業に便利だからです。大きな机に、道具を使いやすく並べられる感覚です。
ターミナルで最初に覚える4つ
| 入力 | 意味 | 安全な使い方 |
|---|---|---|
pwd | いまいる場所を表示 | OpenCodeを起動する前に毎回確認 |
ls | 現在の場所の中身を表示 | 編集対象が合っているか確認 |
cd フォルダ | そのフォルダへ移動 | パスに空白があれば引用符で囲む |
| Control + C | 実行中の処理を止める | 止まらない・怖いと感じたら使う |
pwd、次にlsを実行してください。ファイルは何も変わりません。表示された場所を見て、「いま私はどの部屋にいるか」を言葉にできれば十分です。
OpenCodeは公式の方法で入れ、バージョン表示まで確認します
インストールは「入れたつもり」で終えず、opencode --versionで確認します。表示された番号が、MacからOpenCodeを呼び出せる証拠です。
OpenCode公式は複数の導入方法を案内しています。まずbrew --versionを1行だけ実行してください。番号が表示された方は方法Aへ進みます。command not foundと出た方は、Homebrewをこのためだけに入れず、方法Bかデスクトップ版を選べます。
方法A:Homebrewを使う
brew install anomalyco/tap/opencode
OpenCode公式は、Homebrewチームが管理する通常の式より、OpenCode側のタップのほうが新しい版へ早く追いつくと説明しています。brew: command not foundと出る場合はHomebrewがありません。分からないまま別サイトの命令を貼らず、公式のインストール方法へ戻ってください。
方法B:OpenCode公式のインストールスクリプトを使う
curlはWebから内容を受け取り、bashは受け取った内容を命令として実行します。短く便利ですが、Webの内容をそのまま実行する強い方法です。実行直前に、URLが公式資料と同じhttps://opencode.ai/installであることを確認してください。
curl -fsSL https://opencode.ai/install | bash
別サイトで似た命令を見つけても流用しません。意味が不安なら、OpenCodeの公式ダウンロードページからデスクトップ版を選びます。
導入できたか確認します
opencode --version
バージョン番号が表示されれば成功です。command not foundなら、ターミナルを一度終了して開き直します。それでも直らない場合は、第21章の「opencodeが見つからない」を参照してください。
デスクトップ版から始める選択肢
OpenCodeにはmacOS向けデスクトップアプリもあります。公式のOpenRouter連携資料では、Homebrew Caskのbrew install --cask opencode-desktop、またはApple Silicon用・Intel用DMGのダウンロードが案内されています。ターミナル版とデスクトップ版は同じ設定と保存済み認証を読みます。
本書はiTerm2で仕組みを理解することを主軸にしています。あとでデスクトップ版へ移っても、OpenRouterとモデルの関係は変わりません。
OpenRouterでは、少額入金・専用APIキー・利用上限の順に準備します
最初から自動入金を有効にせず、学習用の専用キーへ小さな上限を付けると、料金への不安を小さくできます。
1. 公式サイトでアカウントを作ります
OpenRouter公式サイトへ進み、アカウントを作ります。URLの綴りを確認してください。検索広告や似た名前のサイトからAPIキーを作らないようにします。
2. クレジットを少額だけ追加します
OpenRouterのクレジットは、AI利用料へ充てる前払い残高です。公式FAQでは米ドルが基準通貨で、モデルごとに入力・出力の料金が異なると説明されています。クレジット購入時には、確認日時点で5.5%、最低0.80ドルの手数料があります。税や決済条件を含む最終額は、購入画面で確認してください。
初回は学習で使い切れる少額から始めます。自動入金は便利ですが、設定を理解する前は無効のままにします。残高が足りなくなれば作業は止まりますが、意図しない追加購入を避けられます。
3. OpenCode専用のAPIキーを作ります
- OpenRouterのAPI Keys画面を開きます。
- 新しいキーを作り、名前を
Mac-OpenCode-Learningのように用途が分かるものにします。 - 可能なら、学習用に小さな米ドル上限を設定します。
- 表示されたキーを一時的にコピーします。APIキーの平文は再表示できない場合があります。
- 次章のOpenCode専用入力欄へ貼り付けたら、メモアプリへ平文で残さないようにします。
4. Privacy設定を確認します
OpenRouter公式によると、プロンプトと回答の保存は標準で無効です。ただし、実際の推論では選ばれたAI提供者へ内容が送られます。提供者ごとに保存や学習の方針が異なるため、Privacy画面で「学習に使う可能性のある提供者を許可するか」を確認します。
秘密情報を送らないことが第一です。そのうえで、必要に応じてデータ収集をしない提供者だけに絞る設定や、保存ゼロの提供者へ限定するZDR(Zero Data Retention)を検討します。制限を厳しくすると、利用できる提供者が減り、エラーや価格の変化につながる場合があります。
/connectでOpenRouterをつなぎ、/modelsでGLMを選びます
接続作業は4段階です。専用フォルダへ移動→OpenCode起動→OpenRouter接続→GLM-5.3-Flash選択。APIキーは会話欄へ書きません。
作業場所を確認してから起動します
cd "$HOME/Documents/AI-Projects/my-first-project"
pwd
ls
opencode
pwdの最後がmy-first-projectなら、正しい部屋にいます。ホームフォルダや書類フォルダ全体が表示された場合は、OpenCodeを起動する前に移動し直してください。
OpenRouterを接続します
- OpenCodeの入力欄へ
/connectと入力します。 - 一覧から
OpenRouterを探して選びます。 - 専用入力欄が出たら、先ほど作ったAPIキーを貼り付けます。
- 接続後、会話欄へ
/modelsと入力します。 - 検索欄で
GLM-5.3-Flashまたはz-ai/glm-5.3-flashを探し、OpenRouter側のモデルを選びます。
GLM-5.3とGLM-5.3-Flashは別モデルです。本書の主力はFlashです。提供元の表示が複数あるときは、OpenRouterを経由していることと、モデルIDがz-ai/glm-5.3-flashであることを確認します。
発展:再起動してもモデルが一覧に出ない場合
ここからは応急的な設定です。初回実習では飛ばして構いません。まずOpenCodeを終了して再起動し、/modelsをやり直します。それでも出ないときだけ、作品フォルダ直下のopencode.jsonを確認します。このファイルは、OpenCodeへ接続先や既定モデルを伝える設定メモです。
すでにopencode.jsonがある場合は、次の例で丸ごと上書きしないでください。Finderで複製を作り、既存の項目を残したまま必要な項目を統合します。JSONは括弧やカンマの位置にも意味があるため、統合方法が分からなければ、この設定を使わず第21章の相談情報をそろえます。
{
"$schema": "https://opencode.ai/config.json",
"model": "openrouter/z-ai/glm-5.3-flash",
"provider": {
"openrouter": {
"models": {
"z-ai/glm-5.3-flash": {}
}
}
}
}
保存後にOpenCodeを終了して開き直し、/modelsで選択を確認します。設定形式はOpenCodeの更新で変わる可能性があります。エラーが出たら、手当たり次第に項目を足さず、公式のProvidersとTroubleshootingを確認してください。
最初の会話は「読めるか」だけを試します
Tabキーで担当をPlanへ切り替え、画面にPlanと表示されたことを確認します。次の依頼中に編集やコマンド実行の許可が出ても承認しません。
このフォルダの中身を読み取り専用で確認してください。
まだファイルの作成・変更・削除、コマンド実行はしないでください。
現在地と、見つかったファイル数だけを日本語で教えてください。
空のフォルダなら「ファイルはない」と返れば正常です。ここでは作品を作りません。接続と対象範囲の確認だけで一度成功を作ります。
最初の実習は、1枚の自己紹介ページを「計画してから」作ります
いきなりMacアプリへ進まず、3ファイルだけのWebページでAIと一緒に作る流れを体験します。目的はHTMLの暗記ではなく、確認の習慣です。
完成条件を先に決めます
作品は「Hello AI」という見出し、自己紹介文、押すと挨拶が変わるボタンを持つ1ページです。インターネットへ公開しません。外部の画像やライブラリも使いません。必要なファイルはindex.html、style.css、script.jsの3つです。
pwdで現在地を確認し、秘密情報がないことを確かめます。
最初はPlanで相談します
Tabキーを押し、画面にPlanと表示されたことを確認してから、次の依頼文を貼ります。編集やコマンド実行の許可が出た場合は承認せず、計画の説明だけを受け取ります。
この空のフォルダに、学習用の自己紹介Webページを作りたいです。
まだファイルは作らず、次の完成条件を満たす最小の計画だけを出してください。
完成条件:
- 見出しは「Hello AI」
- 自己紹介の短い文章がある
- ボタンを押すと挨拶文が変わる
- index.html、style.css、script.jsの3ファイルだけ
- 外部ライブラリ、外部画像、通信は使わない
- スマートフォン幅でも読める
計画には、作るファイル、各ファイルの役割、確認方法、想定される危険を含めてください。
計画に知らない外部サービスや追加ソフトが入っていたら、「なぜ必要ですか。なしで作れますか」と聞きます。この課題では3ファイルだけで作れるため、追加の導入は不要です。
納得したらBuildへ移ります
計画に問題がなければ、TabキーでBuildへ切り替えます。画面にBuildと表示されたことを確認してから、次の依頼文を貼ります。
計画を確認しました。実装してください。
変更はこのフォルダ内の3ファイルだけに限定してください。
実装後に、作成したファイル一覧と、私がSafariまたはChromeで確認する手順を説明してください。
ブラウザで実物を見ます
- Finderで
my-first-projectを開きます。 index.htmlをダブルクリックします。- 見出しと自己紹介が読めることを確認します。
- ボタンを押し、挨拶が変わることを確認します。
- ブラウザの幅を狭くし、文字がはみ出さないか見ます。
変更内容を説明させます
作業結果を初心者向けに説明してください。
1. 何を作ったか
2. 3ファイルがどう協力するか
3. 確認できたこと
4. まだ確認していないこと
5. 元に戻すなら何を削除するか
の順に答えてください。追加の変更はしないでください。
PART 3 AIへの頼み方を「仕事の仕様書」に変える
良い依頼は、目的・範囲・禁止・確認・終了条件の5点を持ちます
長い魔法の呪文は不要です。誰の何を楽にするか、どこまで触ってよいか、何を証拠に完成とするかを渡します。
| 要素 | 質問 | 例 |
|---|---|---|
| 目的 | 誰の、どんな困りごとを解くか | 長い記事のタイトルとURLを1クリックで保存したい |
| 範囲 | どのフォルダ・ファイルを触るか | この作品フォルダ内だけ |
| 禁止 | してほしくないことは何か | 外部通信、課金、削除、公開をしない |
| 確認 | 何を実行・表示して確かめるか | Chromeへ読み込み、ボタン操作、エラー欄確認 |
| 終了条件 | 何がそろえば完了か | 3つの操作が通り、未確認事項を報告したら終了 |
悪い例は短いから悪いのではありません
曖昧な依頼
便利なChrome拡張を作って。「便利」の意味、対象、権限、完成条件がなく、AIが勝手に設計を補う割合が大きくなります。
判断しやすい依頼
いま開いているページのタイトルとURLを、
ボタン1回でクリップボードへコピーする
個人用Chrome拡張機能を作りたいです。
まず計画だけを出してください。
通信・履歴の読み取り・全サイト常時アクセスは使わず、
必要最小限の権限にしてください。
完成後はChromeへ読み込む手順と確認項目を示してください。作る→確認する→直す→再確認する
AIへの依頼を一度で完成させようとすると、長大な指示になり、途中の誤解に気づけません。小さな変更を作り、新しい証拠を取り、原因に絞って直し、元の機能も含めて再確認します。
次の1回の作業だけを行ってください。
【目的】
(誰の何を楽にするか)
【今回の範囲】
(触ってよいフォルダ・ファイル)
【禁止】
- 指定外ファイルの変更
- 依存ソフトの追加
- 外部送信、公開、削除
- APIキーや個人情報の表示
【進め方】
1. 現状を読む
2. 計画を説明する
3. 私の確認後に最小変更を行う
4. テストを実行する
5. 変更ファイル、テスト結果、未確認事項を報告する
【完了条件】
(目で見る結果と自動テストの両方)
書けたら見本答案を開く
目的:自分用の短いメモを、Macだけに保存して後から探したい。
範囲:この作品フォルダ内のMacアプリだけ。
禁止:外部通信、アカウント作成、クラウド同期、確認なしの削除をしない。
確認:メモを1件追加し、アプリ再起動後も残り、削除前に確認が出る。
終了条件:追加・再表示・削除の3操作が成功し、未確認事項が報告される。
5項目中4項目を書けたら次へ進めます。3項目以下なら、直前の表を見て不足した項目だけを足してください。
PART 4 Chrome拡張機能を、小さく安全に作る
最初のChrome拡張機能は「ページ情報をコピーする」だけに絞ります
Manifest V3、ポップアップ、最小権限を学ぶため、いま開いているページのタイトルとURLをコピーする個人用ツールを作ります。外部通信は使いません。
Chrome拡張機能は、小さなアプリの箱です
Googleの公式資料では、すべての拡張機能の根にmanifest.jsonが必要です。これは、名前、版、使う機能、必要な権限をChromeへ伝える名札兼申請書です。現在の基本形式はManifest V3です。
専用フォルダを作ります
cd "$HOME/Documents/AI-Projects"
mkdir page-info-copy
cd page-info-copy
pwd
opencode
この4行も上から1行ずつ実行します。最後のpwdがpage-info-copyで終わることを確認してからOpenCodeを使います。空フォルダなので既存作品はありませんが、完成後に機能を足す前には第16章の保存地点を作ります。
計画を頼みます
TabキーでPlanへ切り替え、画面の表示を確認してから貼ります。
個人学習用のChrome拡張機能を作りたいです。
まだ実装せず、計画と必要権限だけを説明してください。
目的:
ツールバーのボタンを押すと小窓が開き、
現在のタブのページタイトルとURLを表示し、
「コピー」ボタンで両方をクリップボードへコピーする。
条件:
- Manifest V3
- 外部通信なし
- データ保存なし
- 履歴、Cookie、全サイト常時アクセスは要求しない
- 必要最小限の権限を使う
- ライブラリやビルド作業は使わない
- manifest.json、popup.html、popup.css、popup.jsだけ
計画には、各ファイルの役割、必要な権限と理由、
Chromeでの確認手順、想定されるエラーを含めてください。
この課題では、利用者が拡張機能を押した現在のタブへ一時的にアクセスするactiveTabと、タブ情報を扱うための最小構成を検討します。AIが<all_urls>や広いhost_permissions(常時アクセスを許すWebサイトの範囲)を提案したら、必要性を説明させてください。目的に対して広すぎる権限は採用しません。
実装を許可します
計画と権限に納得したら、TabキーでBuildへ切り替え、表示を確認してから貼ります。
計画を確認しました。必要最小限の権限で実装してください。
このフォルダ内の4ファイルだけを作成してください。
外部通信、外部ライブラリ、分析用コードは追加しないでください。
実装後にmanifest.jsonの各項目を初心者向けに説明し、
Chromeへ読み込む手順を示してください。
Chromeへ「パッケージ化されていない拡張機能」として読み込みます
- Chromeのアドレス欄へ
chrome://extensionsと入力します。 - 右上の「デベロッパー モード」を有効にします。これは自作拡張機能を試すための開発者向け表示です。
- 「パッケージ化されていない拡張機能を読み込む」を押します。
page-info-copyフォルダを選びます。中のファイルではなく、4ファイルを入れたフォルダそのものです。- 拡張機能をツールバーへ固定し、通常のWebページで押します。
5項目を人の目で確かめます
エラーは「赤い文字をそのまま渡す」と解決しやすくなります
chrome://extensionsの拡張機能カードに「エラー」が出たら開き、表示された文章を省略せずコピーします。ポップアップを右クリックして「検証」を開くと、Console(エラーの詳しい記録欄)も確認できます。秘密情報がないことを確認してから、OpenCodeへ貼ります。
Chromeへの読み込みで次のエラーが出ました。
まだ修正しないでください。
原因候補を最大3つに絞り、最も可能性が高い順に説明してください。
その後、確認するファイルと行を示してください。
【エラー全文】
ここへ貼る
発展課題:保存機能を足す前に設計する
次はコピー履歴を3件だけ保存する機能を考えられます。ただし、どこへ保存するか、個人情報を含むURLをどう扱うか、削除ボタンをどう作るかを先に決めます。「機能を足して」だけでは進めません。新しい権限が必要かをAIへ説明させ、追加前後のmanifest.jsonを比較します。
PART 5 XcodeとOpenCodeを組み合わせてMacアプリを作る
MacアプリはXcodeで器を作り、OpenCodeで中身を育てます
最初のMacアプリは「30秒休憩タイマー」です。Xcodeが組み立て工場、Swiftが材料の言葉、SwiftUIが画面の書き方、OpenCodeが開発助手です。
XcodeはApple公式の開発道具一式です
Xcodeにはコードを書く場所、画面のプレビュー、アプリの組み立て、エラー表示が入っています。Apple公式の「Develop in Swift」では、XcodeとSwiftUIを使って画面や動くアプリを学べます。Xcodeは容量が大きく、導入と追加部品の準備に時間がかかることがあります。十分な空き容量と電源を確保し、初回起動時の利用条件への同意と追加部品の導入が終わってから進みます。
BreakTimer、InterfaceをSwiftUI、LanguageをSwiftにします。保存場所は~/Documents/AI-Projectsです。画面の項目名はXcodeの版で少し変わる場合があります。
最初にXcodeの▶︎でHello Worldを動かします
AIで変更する前に、Xcodeが作った初期アプリを実行します。上部の実行先が「My Mac」になっていることを確認し、▶︎を押します。空のウィンドウや「Hello, world!」が表示されれば、開発環境そのものは動いています。ここが基準点です。
BreakTimerフォルダを選び、command + Dで複製し、BreakTimer-before-AIと名付けます。複製先は元のBreakTimerの外です。次に元のBreakTimerをXcodeで開き直します。Gitを使える方は、第16章の基準コミットでも構いません。
プロジェクトの場所へ移動してOpenCodeを起動します
cd "$HOME/Documents/AI-Projects/BreakTimer"
pwd
ls
opencode
この4行は上から1行ずつ実行します。pwdの最後がBreakTimerであることを確認し、違っていればopencodeを実行しません。
BreakTimer.xcodeprojやSwiftファイルが見えれば、対象は合っています。Xcodeを閉じる必要はありません。ただし、XcodeとOpenCodeで同じファイルを同時に編集すると表示が更新されるため、変更中はどちらで保存したかを意識します。
最初の依頼は調査だけです
TabキーでPlanへ切り替え、表示を確認します。編集や書き込みコマンドの許可が出た場合は承認しません。
このXcodeプロジェクトを読み取り専用で確認してください。
まだ変更やコマンド実行はしないでください。
初心者向けに、
1. アプリの入口となるSwiftファイル
2. 最初の画面を作るSwiftファイル
3. Xcodeが生成した主要フォルダ
4. 30秒休憩タイマーを作るなら変更が必要な最小ファイル
を説明してください。
完成条件を決めて計画させます
30秒の休憩タイマーを作りたいです。まだ実装せず、計画だけを出してください。
完成条件:
- 初期表示は30秒
- 「開始」を押すと1秒ずつ減る
- 0秒で止まり「休憩終了」と表示する
- 「リセット」で30秒へ戻る
- 開始中は二重に開始できない
- ウィンドウを閉じても外部へデータを送らない
- 外部ライブラリを追加しない
- 変更は必要最小限のSwiftファイルだけ
計画に、状態の持ち方、タイマー停止処理、確認項目、
想定される不具合を含めてください。
小さく実装し、Xcodeと自動ビルドの両方で確認します
計画を確認したら、TabキーでBuildへ切り替え、表示を確認してから次の依頼文を貼ります。
計画を確認しました。まず最小の画面とタイマー動作だけを実装してください。
指定外ファイル、プロジェクト設定、署名設定、権限設定は変更しないでください。
外部ライブラリは追加しないでください。
実装後は、利用可能ならxcodebuildでビルド確認してください。
コマンドを実行する前に、実行する内容と目的を1行で示してください。
最後に、変更ファイル、ビルド結果、Xcodeで私が確認する操作を報告してください。
OpenCodeがプロジェクト名やScheme(どのアプリを組み立てるかの指定)を調べ、適切なxcodebuildを提案できます。分からないまま長いコマンドを手入力するより、実行前に説明を読んで承認してください。
人の目で8つを確認します
Gitを使うと、AIの変更を「保存地点」まで戻せます
Gitは作品の変更履歴を残す道具です。AIに変更させる前の状態を保存しておくと、失敗を恐れずに試せます。
普通の「取り消す」は、アプリを閉じたり変更が増えたりすると戻れない場合があります。Gitは、ファイルのまとまりごとに保存地点を作ります。この保存地点をコミットと呼びます。ゲームのセーブポイントに近いものです。
最初の保存地点を作ります
新しい学習用プロジェクトで、秘密情報が入っていないことを確認してから進みます。既存の仕事用プロジェクトでは、チームの運用ルールを先に確認してください。最初にgit statusを実行し、すでに状態が表示された場合はgit initを重ねません。「not a git repository」と出た学習用フォルダだけでgit initを使います。
git status
git init
この2行は条件つきです。1行目で既存のGitを確認し、Gitがない場合だけ2行目を実行します。git initは履歴管理を始めます。
秘密やMac固有の一時ファイルを除外します
.gitignoreは、Gitに保存させない名前を書く除外表です。テキストエディタで作品フォルダ直下に.gitignoreという名前の標準テキストを作り、次の内容を保存します。先頭のピリオドを忘れないでください。
.DS_Store
.env
.env.*
!.env.example
xcuserdata/
次にgit status --shortで候補を見ます。最初は現在地以下を全部追加するgit add .を使わず、内容を確認したファイル名だけを指定します。次の例は第12章の3ファイルです。別の作品では、実在し内容を確認した名前へ置き換えます。
git status --short
git add .gitignore index.html style.css script.js
git status --short
git commit -m "最初の動作確認後"
git addは指定したファイルを次の保存対象へ入れ、git commitが名前付きの保存地点を作ります。2回目のgit status --shortで、意図したファイルだけが保存対象になったことを見ます。
git config user.name "自分の表示名"とgit config user.email "自分のメールアドレス"を、自分の情報へ置き換えて実行します。会社や公開プロジェクトでは、指定された表示名とメールを使ってください。
AIの変更後は差分を読みます
git status
git diff
差分は、削除された行を-、追加された行を+で示します。コードを全部理解できなくても、予定外のファイルが変わっていないか、APIキーらしき長い文字列が入っていないか、大量削除がないかは確認できます。
戻し方は、対象を確定してから選びます
Gitには複数の戻し方があります。初心者が意味を知らずにreset --hardのような強い命令を実行すると、未保存の作業を失うことがあります。まずAIへ「読み取り専用で現在の変更と保存地点を説明して。まだ戻さないで」と頼み、対象を特定します。
現在のGitの状態を読み取り専用で確認してください。
まだファイルや履歴を変更しないでください。
1. 保存済みの最新コミット
2. 保存されていない変更ファイル
3. 変更を残したまま退避する方法
4. 特定ファイルだけ戻す方法
を説明し、実行候補のコマンドと失われる可能性のある内容を示してください。
PART 6 1人のAIを、役割の違う小さなチームへ育てる
サブエージェントは、別室で限定された仕事をする専門担当です
主担当が全部を抱えるより、調査・レビュー・セキュリティ確認を別の文脈へ分けると、会話が整理され、権限も狭くできます。
普段会話する主担当を、OpenCode公式ではPrimary agentと呼びます。必要なときだけ呼ぶ専門担当がSubagentです。サブエージェントは主担当から呼ばれるほか、利用者が@で指定して呼べます。本書では、まず調査担当のExploreだけを使います。ほかの標準担当名は、今は覚えなくて構いません。
主担当:GLM-5.3-Flash
要件整理・実装・テスト
調査担当
読み取り中心
同じGLMでもよい
レビュー担当
編集禁止
別会社の上位モデル
安全確認担当
権限・秘密・削除を点検
最初から大人数にしないでください
サブエージェントが増えると、同じコードを何度も読み、料金と時間が増えます。指摘が重複し、どの意見を採用するかの仕事も人へ戻ります。最初は主担当と読み取り専用レビュー担当の2役で十分です。
標準のPlanとExploreを先に使います
自作担当を増やす前に、Planで変更前の分析を行い、Exploreでコードの場所や関係を調べる使い方を覚えます。調査担当には編集権限を渡さず、「どこに何があるか」「原因候補は何か」までで止めます。
@explore この不具合に関係するファイルと処理の流れを、
読み取り専用で調べてください。
ファイル変更やコマンドによる書き込みはしないでください。
根拠となるファイル名と箇所を示し、原因候補を最大3つに絞ってください。
仕事を分ける基準
| 状況 | 主担当のまま | サブエージェントへ |
|---|---|---|
| 文言や色の小変更 | ○ | 不要 |
| 大きなコード内の場所探し | 可能 | Exploreへ分けると整理しやすい |
| 公開前の品質確認 | 自己確認も行う | 読み取り専用レビューを追加 |
| 個人情報・課金・権限 | 実装 | 安全確認と別モデルレビューを推奨 |
| 同じ修正を2回失敗 | 一度止める | 原因調査を別文脈へ分ける |
レビュー担当は、編集禁止・別会社の上位モデル・根拠必須にします
レビュー担当の目的は「賛成すること」ではありません。変更せずに、見落としと確認不足を根拠つきで示すことです。
上位モデルは「難しい場面だけ呼ぶ顧問」です
主担当のGLM-5.3-Flashで普段の開発を進め、節目で別会社の上位モデルへレビューを頼みます。別会社を選ぶのは、同じ学習傾向や思い込みを少しでも分散するためです。どのモデルを上位とするかは変化が速いため、OpenRouterのモデル一覧で、コーディング能力、ツール利用、料金、入力上限、データ方針を利用時に確認してください。
公式の対話式作成機能を使うと安全です
opencode agent create
OpenCode公式によると、この命令は保存場所、説明、役割、モデル、許可する道具を順に聞きます。作品専用ならproject-specificを選びます。名前はreview、モードはsubagent、編集と書き込みコマンドは拒否します。
レビュー担当へ渡す役割文
あなたは読み取り専用のコードレビュー担当です。
ファイルを作成・変更・削除しないでください。
公開、送信、インストール、設定変更も行わないでください。
次の順でレビューしてください。
1. 利用者の完成条件を満たしているか
2. 明確なバグと再現手順
3. セキュリティ・プライバシー・権限の過不足
4. MacまたはChrome固有の仕様違反
5. テストで確認できていない部分
6. 修正の優先順位
各指摘には、対象ファイルと根拠を付けてください。
推測は「推測」と明記してください。
問題が見つからない場合も、確認した範囲と未確認範囲を分けてください。
Markdownファイルで作る場合の見本
OpenCode公式では、全体用の担当を~/.config/opencode/agents/、作品専用を.opencode/agents/へ置けます。ファイル名が担当名になります。次は作品専用の.opencode/agents/review.mdの概念例です。
---
description: 変更を加えずに品質と安全性を確認するレビュー担当
mode: subagent
model: ここにopencode modelsで確認した完全なID
temperature: 0.1
permission:
edit: deny
external_directory: deny
webfetch: deny
task: deny
bash:
"*": deny
"git status*": allow
"git diff*": allow
"git log*": allow
---
あなたは読み取り専用のコードレビュー担当です。
完成条件、バグ、権限、秘密情報、テスト不足を確認してください。
各指摘には対象ファイルと根拠を付け、ファイルは変更しないでください。
model:の値は説明用の空欄です。opencode modelsまたはモデル選択画面に表示される完全なIDで、値の部分を丸ごと置き換えてください。自分でopenrouter/を足しません。価格と提供状況は変わるため、本書で固定しません。
レビュー結果は自動採用しません
レビュー担当も間違えます。指摘を「直す」「確認してから直す」「今回は残す」に人が分けます。互いに矛盾する指摘が出たら、完成条件と実際のテスト結果へ戻ります。AI同士の多数決は、正しさの証明にはなりません。
@review 現在の未コミット差分を読み取り専用でレビューしてください。
今回の完成条件は次のとおりです。
(完成条件を貼る)
ファイルは変更しないでください。
重大度を「公開を止める」「早めに直す」「改善候補」の3段階に分け、
各指摘へ根拠と再現手順を付けてください。
PART 7 料金と安全を、感覚ではなく仕組みで管理する
料金は「入力×単価+出力×単価」で見積もり、実績で補正します
1回の質問の短さだけでは料金は読めません。エージェントは会話やコードを何度も入力するため、OpenRouterのActivityで実績を見ることが欠かせません。
2026年8月27日時点の料金スナップショット
OpenRouterのGLM-5.3-Flashページには、確認時点で複数の提供者が並んでいます。50%割引表示の提供者は、入力100万トークン0.075ドル、出力100万トークン0.25ドル、キャッシュ読み取り100万トークン0.015ドルです。通常価格の提供者例は入力0.15ドル、出力0.50ドル、キャッシュ0.03ドル。📍割引の理由と終了日は、確認時点の公式ページからは判断できません。
OpenRouterは、利用可能性、価格、速度、要求した機能、データ方針などの条件に合う提供者へ依頼を振り分けます。ZDRや障害時の代替先を使うと、実際の経路と単価が変わる可能性があります。Activityに記録された実績を最終値として確認してください。
計算例1:1回のまとまった作業
入力20万トークン、出力3万トークンと仮定します。割引表示の提供者を使えた場合は次の計算です。
入力 200,000 ÷ 1,000,000 × $0.075 = $0.0150
出力 30,000 ÷ 1,000,000 × $0.25 = $0.0075
合計 $0.0225
通常価格の提供者例なら0.045ドルです。これはモデル利用料だけの単純例です。クレジット購入手数料、別モデル、Web検索などの追加機能は別に考えます。
計算例2:20回の往復で長いコードを読み直す
各回で平均10万入力、1万出力なら、合計は200万入力、20万出力です。割引表示では0.20ドル、通常料金では0.40ドルになります。1回ごとは小さくても、往復と再読込が増えると積み上がります。
割引表示:2.0 × $0.075 + 0.2 × $0.25 = $0.20
通常料金:2.0 × $0.15 + 0.2 × $0.50 = $0.40
料金を抑える7つの習慣
- 作品ごとに会話とフォルダを分ける。
- 「全部読んで」ではなく、目的に関係する場所から調べさせる。
- 同じ失敗を2回繰り返したら実装を止め、原因調査へ切り替える。
- 大きな画像、動画、生成物、依存フォルダを必要なく読ませない。
- レビュー担当は節目だけ呼ぶ。
- APIキーへ小さな上限を付ける。
- OpenRouterのActivityで、モデル・APIキー・期間ごとのSpendを毎週見る。
反論:GLMが安いなら、料金確認は不要では?
単価が低くても、無限ループ、巨大なファイル、上位モデルのレビュー、複数サブエージェントが重なると増えます。安さは監視を不要にする理由になりません。
再反論:初期上限とActivity確認を仕組みにすれば、毎回おびえる必要もありません。「止める上限」と「振り返る日」を決め、日々は作品づくりへ集中します。
安全対策は、秘密・範囲・変更・通信・公開の5枚扉で考えます
事故を1つの注意力で防ごうとせず、複数の小さな扉を置きます。1枚を通り抜けても、次の扉で止まる設計です。
扉1:秘密を最初から作業机へ置きません
APIキー、パスワード、秘密鍵、顧客名簿、診療情報、未公開契約書、写真の位置情報を練習へ使いません。秘密を検出してから隠すより、最初から対象外にするほうが確実です。
扉2:作業範囲を作品フォルダへ閉じます
OpenCodeを起動する前にpwdとlsを見ます。外部フォルダへアクセスする許可が出たら、「なぜ必要か」「読み取りだけか」「どのパスか」を確認します。理由が説明できないなら拒否します。
扉3:変更前後をGitとテストで挟みます
動いている状態をコミットし、AIには小さな差分だけを作らせます。変更後はgit diffとテストを確認します。大量のファイルが変わったら、機能追加を続けず、範囲が広がった理由を調べます。
扉4:外部通信と権限を機能ごとに説明させます
Chrome拡張機能のhost_permissions、Macアプリのネットワークやファイル権限、追加ライブラリの通信を確認します。「便利だから」では理由になりません。どの機能が、どのデータを、どこへ送るかまで言葉にします。
扉5:公開と配布は別の承認にします
GitHubへのpush、Chrome Web Store、App Store、Vercelなどへの公開は外部状態を変えます。作成の依頼と公開の依頼を分け、公開直前に秘密、ライセンス、権限、料金、説明文、スクリーンショットを人が確認します。
見知らぬプロジェクトは、書かれた指示も疑います
ダウンロードしたプロジェクト内のAGENTS.mdや説明ファイルには、AIへ強い操作をさせる文章が含まれる可能性があります。知らないプロジェクトを開いたら、最初は読み取り専用で構成と指示ファイルを確認します。内容を理解する前にBuildで起動しません。
AIが危険な提案をしたときの返し方
その操作はまだ実行しないでください。
読み取り専用の確認へ戻ります。
1. 操作の目的
2. 正確な対象
3. 失われる・公開される・課金される可能性
4. 元に戻す方法
5. より狭く安全な代替案
を説明してください。
PART 8 止まったときの道しるべ
エラーは「どの層で止まったか」を分けると解けます
OpenCode、OpenRouter、モデル、作品、Macの5層を一度に直さないでください。最後に成功した場所を見つけ、次の1層だけ確認します。
opencode: command not found → 導入場所を確認
- ターミナルを完全に閉じ、開き直します。
opencode --versionを再実行します。- Homebrewを使ったなら
brew list | grep opencodeで導入済みか確認します。 - 導入方法を混ぜた場合は、どの方法を残すか決めてから整理します。
401 / Unauthorized → APIキーの認証問題
キーの前後に空白がないか、OpenRouter用キーか、無効化されていないかを確認します。APIキー全文をエラー報告へ貼らないでください。必要なら古いキーを無効化し、新しい専用キーで/connectをやり直します。
402 / insufficient credits → 残高か利用上限
OpenRouterの残高、APIキー上限、期間上限を確認します。残高を増やす前にActivityを見て、意図した利用かを確かめます。身に覚えのない使用があれば、先にキーを無効化します。
429 / rate limit → 混雑または回数制限
少し間を置き、同じ依頼を連打しません。無料モデルは制限が低く、開発用途に向かない場合があります。有料残高があっても、提供者側の混雑や上限で一時的に止まることがあります。
ProviderModelNotFoundError → モデルIDを確認
OpenCode公式のトラブル資料では、モデル指定は<providerId>/<modelId>の形です。本書の組み合わせならopenrouter/z-ai/glm-5.3-flash。opencode modelsでアクセスできるモデル一覧を確認します。
モデル一覧にGLM-5.3-Flashがない → 再起動と設定追加
OpenCodeを終了して再起動し、/modelsを再確認します。公開直後は一覧反映の差があり得ます。第11章の設定例を使う場合も、OpenRouterモデルページでIDを再確認します。
OpenCodeが同じ修正を繰り返す → 実装を止めて原因調査
同じ種類の修正が2回失敗したので、実装を止めます。
これ以上ファイルを変更しないでください。
現在のエラー、変更履歴、テスト結果を読み取り専用で整理し、
原因候補を最大3つに絞ってください。
各候補を区別するための最小の確認方法を示してください。
Chromeで「Manifest file is missing or unreadable」→ 選んだ階層を確認
manifest.jsonを含むフォルダを選んでいるか、ファイル名が正確かを確認します。manifest.json.txtになっていないかも見ます。Finderで拡張子が隠れている場合があります。
Chromeの小窓が空 → エラー画面を見る
chrome://extensionsで対象カードの「エラー」を開きます。ポップアップを右クリックして「検証」を開く方法もあります。Consoleに出る赤いメッセージと、対象ファイル・行番号をOpenCodeへ渡します。
XcodeでBuild Failed → 最初の赤いエラーから見る
連鎖したエラーでは、上の1件が直ると残りも消えることがあります。最初のエラー全文、ファイル名、行番号を渡し、まず原因説明だけを求めます。Xcodeの推奨修正を意味を読まずにすべて適用しません。
予定外の大量変更 → その場で止める
- Control + Cで実行を止めます。
git statusとgit diff --statで規模を見ます。- まだ保存・公開・削除をしません。
- 対象ファイルを特定し、必要な変更と不要な変更を分けます。
- 戻す前に、未保存の自分の作業がないか確認します。
APIキーを誤って表示した → 直ちに無効化
画面を閉じるだけでは足りません。OpenRouterで該当キーを無効化し、新しいキーを作ります。Gitへ入れた場合は、公開状況と履歴を確認します。秘密を履歴から消す作業は複雑なので、公開済みならセキュリティに詳しい人へ相談してください。
30日で「AIに作らせる人」から「AI開発を管理できる人」へ進みます
毎日長時間は不要です。週ごとに、観察→小変更→作品→レビューと負荷を上げます。できなかった日は飛ばして構いません。
第1週:Macの現在地と変更を読めるようにする
| 日 | 課題 | できた証拠 |
|---|---|---|
| 1 | pwdとlsを使う | 現在地を言葉で説明 |
| 2 | 専用フォルダを3つ作る | 作品ごとに部屋を分けた |
| 3 | OpenCodeを読み取り専用で起動 | ファイル数だけ答えた |
| 4 | Planで計画だけを作る | 変更が0件のまま |
| 5 | 1行だけ変更する | 変更前後を説明できる |
| 6 | git statusとgit diff | 予定外変更がない |
| 7 | 料金Activityを確認 | 1週間のSpendを記録 |
第2週:小さなWeb作品で確認ループを回す
第12章の自己紹介ページを作り、色変更、ボタン文言、入力欄追加を1日1変更で行います。毎回、計画、差分、ブラウザ確認、コミットの順に進めます。2つ以上の機能を同日にまとめないでください。
第3週:Chrome拡張機能を育てる
第14章のコピー拡張機能を完成させます。権限一覧を自分の言葉で説明し、通常ページ、長いタイトル、日本語URL、コピー失敗の場面を試します。機能追加より、エラーを再現して説明する練習に時間を使います。
第4週:Macアプリとレビュー担当へ進む
休憩タイマーを作り、二重開始、0秒、リセット、再起動を確認します。Gitの保存地点を作り、読み取り専用レビューを1回だけ呼びます。指摘をそのまま採用せず、完成条件と実物に照らして仕分けます。
卒業制作の条件
pwdとlsを1回ずつ実行する。2. 第7章の専用フォルダを作る。3. 第11章の読み取り専用確認まで進む。作品づくりは別の日で構いません。
APPENDIX 必要なときに引く資料
用語集は、分からない言葉へ戻るための索引です
- AIエージェント
- 目的に向けて、調査、ファイル操作、コマンド実行、確認を複数段階で進めるAIの仕組み。
- OpenCode
- ターミナルやデスクトップアプリで使えるオープンソースのAIコーディングエージェント。Mac上の作業場と手足を受け持つ。
- OpenRouter
- 多くのAIモデルへ統一した方法で接続し、料金と利用状況をまとめるサービス。
- GLM-5.3-Flash
- Z.aiが2026年8月26日に公開した、コーディング、エージェント作業、画像などの入力に対応するAIモデル。本書の主担当。
- モデルID
- 機械がモデルを特定する住所。OpenRouterでは
z-ai/glm-5.3-flash。 - API
- ソフト同士が決められた形式で依頼と結果を交換する入口。
- APIキー
- 利用者、権限、請求先を識別する秘密情報。パスワードと同じように扱う。
- プロンプト
- AIへ渡す依頼文。本書では目的、範囲、禁止、確認、終了条件を含める。
- トークン
- AIが入力と出力を数える単位。料金計算に使われる。
- コンテキスト
- AIがその回答で参照する会話、ファイル、指示などの情報一式。
- ターミナル
- 文字の命令でMacを操作するアプリ。iTerm2は高機能な選択肢。
- TUI
- Terminal User Interfaceの略。ターミナル内に表示される操作画面。
- CLI
- Command Line Interfaceの略。文字のコマンドで道具を使う方式。
- ディレクトリ
- フォルダの技術的な呼び名。本書ではほぼ同じ意味。
- リポジトリ
- Gitで変更履歴を管理するプロジェクト。
- Git
- ファイルの変更と保存地点を記録し、比較や復元を助ける道具。
- コミット
- Gitに作る名前付きの保存地点。
- 差分
- 変更前と変更後の違い。
git diffで確認できる。 - ビルド
- コードと素材を、実行できるアプリへ組み立てる処理。
- テスト
- 期待した結果になるか確かめる作業。自動テストと人の操作確認がある。
- 依存ライブラリ
- 作品が利用する外部のコード部品。便利だが、更新、ライセンス、安全性の管理が増える。
- Manifest V3
- 現在のChrome拡張機能で使う基本仕様。
manifest.jsonへ情報を書く。 - Swift
- Appleプラットフォームのアプリ開発で使うプログラミング言語。
- SwiftUI
- Swiftで画面と動作を組み立てるAppleの仕組み。
- Xcode
- Apple公式のアプリ開発環境。編集、プレビュー、ビルド、エラー確認を行う。
- Primary agent
- 利用者が直接会話する主担当のAI。
- Subagent
- 調査やレビューなど、限定した仕事を別の文脈で行う専門担当。
- ZDR
- Zero Data Retention。提供者が入力を保持しない方針。利用可能な提供者が減る場合がある。
困ったときは、完成済みの依頼文から始められます
1. 変更前の安全確認
このプロジェクトを読み取り専用で調べてください。
まだファイル変更、コマンド実行、インストール、通信はしないでください。
目的に関係するファイル、現在の動作、想定される変更範囲、危険な点を説明してください。2. 計画だけを作る
次の目的を達成する最小の計画を作ってください。
まだ実装しないでください。
【目的】
ここに書く
【完成条件】
- ここに書く
計画には、変更ファイル、変更理由、確認方法、戻し方、未確定事項を含めてください。3. 最小実装
確認済みの計画に沿って、最小の変更だけを実装してください。
指定外ファイル、依存ライブラリ、設定、外部通信は変更しないでください。
変更後にテストを行い、変更ファイル、結果、未確認事項を報告してください。4. エラーの原因調査
次のエラーを調査してください。まだ修正しないでください。
原因候補を最大3つに絞り、根拠と確認方法を示してください。
秘密情報が含まれている場合は表示せず、存在だけ知らせてください。
【期待した結果】
ここに書く
【実際の結果】
ここに書く
【エラー全文】
ここに貼る5. 修正後の再確認
修正した問題だけでなく、影響を受ける既存機能も再確認してください。
実行したテスト、成功した結果、失敗した結果、実行できなかった確認を分けて報告してください。
「問題ありません」だけで終わらず、証拠を示してください。6. 読み取り専用レビュー
現在の差分を読み取り専用でレビューしてください。
ファイルは変更しないでください。
完成条件、明確なバグ、セキュリティ、プライバシー、権限、テスト不足を確認し、
各指摘へ対象ファイル、根拠、再現手順、重大度を付けてください。7. 作業終了時の引き継ぎ
ここで作業を終了します。追加変更はしないでください。
次回のために、目的、完了したこと、変更ファイル、テスト結果、未解決、次の安全な一手を整理してください。
APIキーや秘密情報は書かないでください。8. 料金が増えたとき
これ以上の実装を止め、料金を抑える観点で現在の作業を整理してください。
重複して読んでいる可能性のあるファイル、不要な長い履歴、繰り返している失敗、
安価なモデルで続けられる部分、上位モデルが必要な部分を分けてください。変わりやすい情報は、公式一次情報へ戻って確認できます
本書は2026年8月27日に以下の公式資料を確認して作成しました。価格、モデル提供、画面、設定形式は変わります。利用時点の公式ページを最終判断にしてください。
- OpenCode公式ドキュメント — 導入、基本概念、設定。
- OpenCode Providers — OpenRouterの
/connect、/models、追加モデル設定。 - OpenCode Agents — Primary/Subagent、権限、Markdown担当、
opencode agent create。 - OpenCode Troubleshooting — モデルID形式、ProviderModelNotFoundError。
- OpenCode Rules —
AGENTS.mdとプロジェクト指示。 - OpenRouter公式 OpenCode Integration — ターミナル版・デスクトップ版の接続手順。
- OpenRouter GLM-5.3-Flashモデルページ — 正式ID、料金、コンテキスト、提供者、機能。
- Z.ai公式 GLM-5.3-Flash発表 — 設計、評価、公開情報。
- OpenRouter FAQ — クレジット、購入手数料、料金、認証、ログ。
- OpenRouter Data Collection — 入力・出力保存、任意設定、メタデータ。
- OpenRouter Provider Logging — 提供者ごとのデータ方針。
- OpenRouter Zero Data Retention — ZDRの意味と制限。
- OpenRouter Activity Export — Spend、Tokens、Requestsの確認。
- Chrome for Developers: Manifest file format — Manifest V3の基本。
- Chrome for Developers: Declare permissions — 権限と任意権限。
- Chrome for Developers: Protect user privacy — 最小権限と利用者データ。
- Apple Developer: Welcome to SwiftUI — Xcode、Swift、SwiftUIの公式入門。
- Apple Developer: Develop apps for Apple platforms — Apple公式の体系的な学習コース。
- fujikawa.com: iTerm2 — iTerm2のインストールと設定。
本文中の料金計算はコードで検算済みです。ベンチマーク値はZ.aiの公表値であり、本書が独自に再測定した結果ではありません。実習の画面名は製品更新や言語設定により変わる場合があります。
30日コースと今日の3手へ戻る ページの先頭へ戻る