Macで始める、いちばんやさしいAI開発

はじめてのAI開発室

OpenCode、OpenRouter、GLM-5.3-Flashを組み合わせると、日本語で相談しながら、Mac上のファイルを読み、コードを書き、動作確認まで進める「AIの開発チーム」を持てます。この本は、AIもITも初めての方が、仕組みを理解し、安全にChrome拡張機能とMacアプリを作り始めるところまで、手を離さずに案内する教科書です。

対象:すべてのMacユーザー 前提知識:不要 形式:1ファイル完結 公式情報確認:2026年8月27日
最初に安心してほしいこと 分からない言葉が出てきても、そこで止まる必要はありません。本文中で毎回、先に役割を説明してから名前を紹介します。コマンドは「Macへの短い指示文」です。コードは「アプリの設計図」です。まずはその程度の理解で十分です。
READING GUIDE

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との互換性を確認します。

この本で到達する場所 「AIに全部お任せする人」ではなく、AIに計画を出させ、変更を確認し、テスト結果を見て、必要なら戻せる人を目指します。コードを暗記するより、良い仕事の頼み方と確認の仕方を身につけるほうが先です。

PART 1 何ができるのかを、難しい言葉なしでつかむ

CHAPTER 01

日本語で相談すると、AIがMacの作業フォルダで手を動かします

この仕組みの一番大きな価値は、コードの答えを受け取るだけでなく、相談→作成→確認→修正を同じ場所で繰り返せることです。

普通のチャットAIに「タイマーアプリを作って」と頼むと、多くの場合はコードが文章として返ってきます。利用者はそのコードをコピーし、正しいファイルへ貼り、エラーが出たら再びチャットへ持ち帰ります。これは、料理研究家からレシピだけを受け取り、台所での作業は自分がすべて行う形です。

OpenCodeのようなAIコーディングエージェントは、作業フォルダの中を見られます。許可された範囲でファイルを作り、変更し、テスト用の命令を実行できます。料理にたとえるなら、レシピを考えるだけでなく、台所で材料を確認し、調理し、味見の結果から直せる助手です。

普通のチャットAI

説明やコード例を返すのが中心です。ファイルへの反映と確認は、利用者が別に行います。

AIコーディングエージェント

対象フォルダを調べ、ファイルを編集し、検査を実行して、結果をもとに次の修正へ進みます。

「AIが自由にMac全体を操作する」と考えないでください。作業場所と権限を狭くし、重要な操作は確認を求める設定にします。優秀な助手でも、初日から家中の鍵を渡す必要はありません。

1分練習:自分の目的を一文にする 紙かメモアプリに「私は、Macで〇〇を作って、△△を楽にしたい」と書いてください。例:「私は、見ているWebページのタイトルを保存するChrome拡張機能を作って、情報整理を楽にしたい」。目的が一文になると、AIへの依頼が急に具体的になります。
CHAPTER 02

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と表す場面があります。

モデル名とモデルIDは少し違います 人が読む商品名は「GLM-5.3-Flash」、機械が接続先を特定する住所はz-ai/glm-5.3-flashです。住所の1文字が違うと「モデルが見つかりません」と表示されます。コピーするときは前後に空白を入れないでください。
深掘り:なぜOpenRouterを間に入れるのですか

GLMだけを使うならZ.aiへ直接接続する方法もあります。それでもOpenRouterを使う理由は、請求とモデル選択を1か所へまとめ、同じOpenCodeの中で別会社のモデルへ切り替えやすくするためです。また、同じモデルを複数の設備提供者が扱う場合、OpenRouterは利用可能な提供者へ振り分けられます。

反対意見もあります。中継サービスが増えるほど、設定箇所とデータの通過点も増えます。そのため、機密性が高い仕事では、直接契約や社内指定の経路が適切な場合があります。本書は個人の学習と小規模開発を想定し、個人情報や秘密情報を送らない前提で説明します。

CHAPTER 03

AIは「賢い自動操縦」ですが、責任者はいつも人間です

AIは速く大量に試せます。一方で、もっともらしい間違いも作ります。速さはAI、目的と最終確認は人間と分担してください。

AIモデルは、文章やコードの続きを予測しながら答えを組み立てます。辞書のように正解を取り出しているわけではありません。知っているように見える言い方で、存在しない機能名や古い手順を出すことがあります。この現象を「幻覚」と呼ぶことがありますが、超初心者の段階では「自信のある言い間違い」と理解すれば十分です。

AIが得意人が受け持つ
たたき台を速く作る何を作るか、誰のためかを決める
複数ファイルの関係を調べる見せてよいファイルか判断する
テストを何度も実行するテスト項目が目的を満たすか確認する
エラーから修正案を出す変更範囲と副作用を承認する
別の実装案を比較する料金、期限、利用者への影響を決める

「動いた」は「正しい」の一部にすぎません

アプリが開けば第一関門は通過です。しかし、データを勝手に外へ送っていないか、他の画面を壊していないか、再起動後も使えるか、知らない人でも操作できるかは別の確認です。完成の意味を、AIと人で共有する必要があります。

作る
最小の変更
確認する
テストと画面
直す
原因に絞る
再確認する
元の機能も確認

この4段階を一周で終わらせず、新しい証拠が出るまで回します。テスト結果、画面の表示、エラーメッセージ、変更差分などが「新しい証拠」です。AIの「大丈夫です」という文章だけは証拠になりません。

理解チェック AIが「実装は完了しました」と言いました。次に何を見ますか。答えは1つではありません。「変更したファイル」「実行したテスト」「実際の画面」「残った注意点」のうち、最低2つを自分の言葉で挙げられれば合格です。
CHAPTER 04

専門用語は、開発室の道具に置き換えると覚えられます

最初に覚える言葉は10個ほどです。すべてを正確に暗記するより、何のためにあるかを先につかんでください。

用語やさしい意味たとえ
ターミナル文字でMacへ指示を出すアプリMacと会話する受付窓口
コマンドターミナルに入力する短い命令「この棚を見せて」の一言
フォルダ/ディレクトリファイルをまとめる場所。ほぼ同じ意味作業ごとの部屋
プロジェクト1つの作品に必要なファイル一式1軒分の設計図と材料
APIソフト同士が決まった方法で話す入口注文票を渡す窓口
APIキー利用者と支払い先を識別する秘密の文字列暗証番号つきの会員証
モデル文章やコードを考えるAI本体担当者の頭脳
トークンAIが文章を数える細かな単位郵便料金を決める文字の小包
コンテキストAIがその時点で参照している会話やファイル机に広げた資料
リポジトリ変更履歴も含めて管理するプロジェクト設計図と改訂記録を保つ書庫
ビルドコードを実行できる形に組み立てる作業設計図から製品を組み立てる工程
テスト期待した動作か自動・手動で確かめること出荷前の検品

入力トークンと出力トークンで料金が分かれます

AIへ送る依頼文、会話履歴、読み込ませたコードが「入力」です。AIが返す説明やコードが「出力」です。モデルページでは、通常「100万トークンあたり何ドル」と表示されます。長いコードを何度も読み直す作業では、目に見える質問が短くても入力が大きくなります。

コンテキストが大きくても、無限に覚えているわけではありません

GLM-5.3-Flashは長い情報を扱えるモデルですが、毎回すべてを詰め込めばよいわけではありません。机が広くても、不要な書類を山積みにすれば探しにくくなります。プロジェクトを分け、古いログや巨大ファイルを必要なときだけ読むほうが、料金と精度の両方に効きます。

用語が分からなくなったときの質問文
いま出てきた「○○」という言葉を、
1. 何のためにあるか
2. 身近なたとえ
3. このプロジェクトでの具体例
の順で、中学生にも分かるように説明してください。
説明だけにして、ファイルは変更しないでください。
CHAPTER 05

OpenCodeは手足、GLMは頭脳、権限設定はドアの鍵です

AIの能力だけでなく、どの道具を使えるかが結果を決めます。権限は不便を増やす壁ではなく、間違いを小さくするドアの鍵です。

OpenCodeには、読む、編集する、コマンドを実行する、Webを調べる、別のエージェントを呼ぶ、といった道具があります。公式資料では、操作ごとにask(毎回確認)、allow(許可)、deny(禁止)を設定できます。

ask

ドアの前で毎回呼び鈴を押します。初心者の編集やコマンド実行は、まずこの考え方が安全です。

allow

合鍵を渡します。頻繁で安全性を理解した操作だけに絞ります。

deny

そのドアは開きません。レビュー担当の編集禁止などに向きます。

PlanとBuildを使い分けます

OpenCodeには、分析や計画向けのPlanと、実際の開発を進めるBuildという考え方があります。ターミナル版ではTabキーで主担当を切り替えられます。画面の担当名がPlanになったことを確認してから計画の依頼を貼り、納得した後にもう一度Tabを押してBuildへ切り替えます。

Planは作業コードの編集を抑える役割ですが、版や設定によっては計画ファイルの作成やコマンド実行の確認が出ます。「読み取りだけ」を望む場面では、許可画面の対象を読み、編集やコマンド実行を承認しないでください。Buildへ移る前に図面を見る、という順番を守ります。

やってはいけない開始方法 ホームフォルダ、デスクトップ全体、書類フォルダ全体を作業場所にしてOpenCodeを起動しないでください。AIが読む必要のない個人ファイルまで近くなります。作品ごとに空の専用フォルダを作り、その中で起動します。

外部フォルダと秘密ファイルは、特に慎重に扱います

現在のOpenCode公式資料では、プロジェクトの外を読む操作や、.envのような秘密情報を置きやすいファイルは、確認対象として扱う設計が示されています。ただし設定やバージョンで動作は変わり得ます。画面に許可の質問が出たら、意味を読まずに承認しないでください。

理解チェック:3色で考える 「ファイル一覧を見る」は緑、「作品フォルダ内のファイルを編集する」は黄、「外部フォルダを読む・削除する・公開する」は赤、と仮に色分けしてください。赤はその場で止まり、目的と対象を読み直します。
CHAPTER 06

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の公表値で、本書が再測定した結果ではありません。

公開直後の情報です GLM-5.3-Flashは2026年8月26日に公開され、本書の確認日は翌27日です。料金、提供者、割引、速度は変わりやすい時期です。本書の数値は「固定された約束」ではなく、確認日のスナップショットとして読んでください。

なぜ「Flash」なのですか

一般にFlashという名前は、速度や費用を重視した系列に付けられます。GLM-5.3-Flashも、最上位のGLM-5.3より計算を軽くし、普段使いしやすくする位置づけです。すべての難問で上位モデルに勝つという意味ではありません。

反論:最初から最強モデルだけを使えば簡単では?

確かに、難しい設計や複雑な不具合では上位モデルが早く解決し、結果として安くなる場合があります。ただし、ファイル名の変更、文言修正、簡単な画面作成、テスト追加まで毎回高価なモデルへ頼むと、費用が読みにくくなります。

再反論:普段はGLM-5.3-Flash、詰まった場面と最終レビューだけ上位モデルにする運用なら、能力が必要な場所へ費用を集中できます。選ぶ基準はモデルの格付けより、仕事の難しさと失敗時の影響です。

反論:同じGLMをレビューにも使えば、さらに安いのでは?

費用は下がります。しかし、同じ系列のモデルは似た思い込みを持つ可能性があります。作った担当と違う会社のモデルに読ませると、別の角度から欠点を見つけやすくなります。

再反論:すべての変更に別モデルは不要です。公開前、課金処理、個人情報、ファイル削除、権限追加など、失敗の影響が大きい変更だけに絞れば、レビュー費用は管理できます。

PART 2 Macを安全な開発室に整える

CHAPTER 07

準備は「専用フォルダ・バックアップ・秘密を分ける」の3点です

インストール前に安全な作業場所を作ります。失敗しても作品フォルダだけを戻せる状態なら、試すことが怖くなくなります。

ターミナルを初めて使う方へ この章の命令が初めてなら、先に第8章を読み、pwdlsを練習してから戻ってください。複数行のコード欄は、特に「まとめて貼る」と書いていない限り、上から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が表示する専用入力欄へ貼り付けます。

APIキーが見えたら、その時点で漏れたものとして扱います 誤ってチャット、GitHub、動画、ブログへ載せても、落ち着いて対処できます。まずOpenRouterで古いキーを無効化し、次に新しい専用キーを作り、最後にOpenCodeの接続を新しいキーへ替えます。画面上の文字を消すだけでは、過去のコピーや履歴に残る可能性があります。

最初の安全チェック

CHAPTER 08

iTerm2は文字でMacと話すための、見やすく頼れる仕事机です

iTerm2はターミナルを快適にする人気のMacアプリです。本書では魅力だけを紹介し、インストール手順は藤川さんの専用解説へ任せます。

Macには標準の「ターミナル」アプリがあります。それでもiTerm2が好まれるのは、画面を分割して片側でOpenCode、もう片側でテスト結果を見る、検索で過去の表示へ戻る、色や文字を読みやすく整える、といった長時間作業に便利だからです。大きな机に、道具を使いやすく並べられる感覚です。

インストールと初期設定はこちら fujikawa.com「iTerm2」解説を読む。重複を避けるため、本書ではiTerm2自体のインストール方法を繰り返しません。標準のターミナルを使う方も、以降の手順はほぼ同じです。

ターミナルで最初に覚える4つ

入力意味安全な使い方
pwdいまいる場所を表示OpenCodeを起動する前に毎回確認
ls現在の場所の中身を表示編集対象が合っているか確認
cd フォルダそのフォルダへ移動パスに空白があれば引用符で囲む
Control + C実行中の処理を止める止まらない・怖いと感じたら使う
3分練習 iTerm2または標準ターミナルでpwd、次にlsを実行してください。ファイルは何も変わりません。表示された場所を見て、「いま私はどの部屋にいるか」を言葉にできれば十分です。
CHAPTER 09

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の公式ダウンロードページからデスクトップ版を選びます。

どちらか1つだけで十分です 方法Aと方法Bを両方実行する必要はありません。更新元が二重になると、後で「どちらのOpenCodeが動いているか」が分かりにくくなります。

導入できたか確認します

opencode --version

バージョン番号が表示されれば成功です。command not foundなら、ターミナルを一度終了して開き直します。それでも直らない場合は、第21章の「opencodeが見つからない」を参照してください。

デスクトップ版から始める選択肢

OpenCodeにはmacOS向けデスクトップアプリもあります。公式のOpenRouter連携資料では、Homebrew Caskのbrew install --cask opencode-desktop、またはApple Silicon用・Intel用DMGのダウンロードが案内されています。ターミナル版とデスクトップ版は同じ設定と保存済み認証を読みます。

本書はiTerm2で仕組みを理解することを主軸にしています。あとでデスクトップ版へ移っても、OpenRouterとモデルの関係は変わりません。

CHAPTER 10

OpenRouterでは、少額入金・専用APIキー・利用上限の順に準備します

最初から自動入金を有効にせず、学習用の専用キーへ小さな上限を付けると、料金への不安を小さくできます。

1. 公式サイトでアカウントを作ります

OpenRouter公式サイトへ進み、アカウントを作ります。URLの綴りを確認してください。検索広告や似た名前のサイトからAPIキーを作らないようにします。

2. クレジットを少額だけ追加します

OpenRouterのクレジットは、AI利用料へ充てる前払い残高です。公式FAQでは米ドルが基準通貨で、モデルごとに入力・出力の料金が異なると説明されています。クレジット購入時には、確認日時点で5.5%、最低0.80ドルの手数料があります。税や決済条件を含む最終額は、購入画面で確認してください。

入金前に知る料金の目安 2026年8月27日のGLM-5.3-Flashページには、入力100万トークン0.075ドル、出力100万トークン0.25ドルの提供者と、入力0.15ドル、出力0.50ドルの提供者が表示されています。たとえば入力20万、出力3万なら、前者で0.0225ドル、後者で0.045ドルです。実際の経路、割引、データ方針、代替先で単価は変わり得ます。詳しい計算は第19章で行います。

初回は学習で使い切れる少額から始めます。自動入金は便利ですが、設定を理解する前は無効のままにします。残高が足りなくなれば作業は止まりますが、意図しない追加購入を避けられます。

3. OpenCode専用のAPIキーを作ります

  1. OpenRouterのAPI Keys画面を開きます。
  2. 新しいキーを作り、名前をMac-OpenCode-Learningのように用途が分かるものにします。
  3. 可能なら、学習用に小さな米ドル上限を設定します。
  4. 表示されたキーを一時的にコピーします。APIキーの平文は再表示できない場合があります。
  5. 次章のOpenCode専用入力欄へ貼り付けたら、メモアプリへ平文で残さないようにします。
上限はどのくらいですか 学習の頻度やレビュー用モデルで変わるため、万人に同じ正解はありません。最初は「失っても困らない小額」にし、1週間のActivity画面を見てから調整してください。上限を大きくする判断は、実績を見てからで十分です。

4. Privacy設定を確認します

OpenRouter公式によると、プロンプトと回答の保存は標準で無効です。ただし、実際の推論では選ばれたAI提供者へ内容が送られます。提供者ごとに保存や学習の方針が異なるため、Privacy画面で「学習に使う可能性のある提供者を許可するか」を確認します。

秘密情報を送らないことが第一です。そのうえで、必要に応じてデータ収集をしない提供者だけに絞る設定や、保存ゼロの提供者へ限定するZDR(Zero Data Retention)を検討します。制限を厳しくすると、利用できる提供者が減り、エラーや価格の変化につながる場合があります。

1%割引のためのデータ提供設定を、意味を読まずに有効にしない OpenRouterには、入力と出力の利用を許可する代わりに割引を受ける任意設定があります。学習中のコードでも、公開前のアイデアや個人情報が含まれる可能性があります。割引額よりデータの扱いを先に判断してください。
CHAPTER 11

/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を接続します

  1. OpenCodeの入力欄へ/connectと入力します。
  2. 一覧からOpenRouterを探して選びます。
  3. 専用入力欄が出たら、先ほど作ったAPIキーを貼り付けます。
  4. 接続後、会話欄へ/modelsと入力します。
  5. 検索欄でGLM-5.3-Flashまたはz-ai/glm-5.3-flashを探し、OpenRouter側のモデルを選びます。
似たモデル名に注意 GLM-5.3GLM-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と表示されたことを確認します。次の依頼中に編集やコマンド実行の許可が出ても承認しません。

このフォルダの中身を読み取り専用で確認してください。
まだファイルの作成・変更・削除、コマンド実行はしないでください。
現在地と、見つかったファイル数だけを日本語で教えてください。

空のフォルダなら「ファイルはない」と返れば正常です。ここでは作品を作りません。接続と対象範囲の確認だけで一度成功を作ります。

進捗チェック
CHAPTER 12

最初の実習は、1枚の自己紹介ページを「計画してから」作ります

いきなりMacアプリへ進まず、3ファイルだけのWebページでAIと一緒に作る流れを体験します。目的はHTMLの暗記ではなく、確認の習慣です。

完成条件を先に決めます

作品は「Hello AI」という見出し、自己紹介文、押すと挨拶が変わるボタンを持つ1ページです。インターネットへ公開しません。外部の画像やライブラリも使いません。必要なファイルはindex.htmlstyle.cssscript.jsの3つです。

Build前の共通関門 今回は空フォルダなので、失う既存作品はありません。既存プロジェクトで同じ練習をする場合は、先に第16章を読み、バックアップまたはGitの保存地点を作ってください。空フォルダでもpwdで現在地を確認し、秘密情報がないことを確かめます。

最初はPlanで相談します

Tabキーを押し、画面にPlanと表示されたことを確認してから、次の依頼文を貼ります。編集やコマンド実行の許可が出た場合は承認せず、計画の説明だけを受け取ります。

この空のフォルダに、学習用の自己紹介Webページを作りたいです。
まだファイルは作らず、次の完成条件を満たす最小の計画だけを出してください。

完成条件:
- 見出しは「Hello AI」
- 自己紹介の短い文章がある
- ボタンを押すと挨拶文が変わる
- index.html、style.css、script.jsの3ファイルだけ
- 外部ライブラリ、外部画像、通信は使わない
- スマートフォン幅でも読める

計画には、作るファイル、各ファイルの役割、確認方法、想定される危険を含めてください。

計画に知らない外部サービスや追加ソフトが入っていたら、「なぜ必要ですか。なしで作れますか」と聞きます。この課題では3ファイルだけで作れるため、追加の導入は不要です。

納得したらBuildへ移ります

計画に問題がなければ、TabキーでBuildへ切り替えます。画面にBuildと表示されたことを確認してから、次の依頼文を貼ります。

計画を確認しました。実装してください。
変更はこのフォルダ内の3ファイルだけに限定してください。
実装後に、作成したファイル一覧と、私がSafariまたはChromeで確認する手順を説明してください。

ブラウザで実物を見ます

  1. Finderでmy-first-projectを開きます。
  2. index.htmlをダブルクリックします。
  3. 見出しと自己紹介が読めることを確認します。
  4. ボタンを押し、挨拶が変わることを確認します。
  5. ブラウザの幅を狭くし、文字がはみ出さないか見ます。

変更内容を説明させます

作業結果を初心者向けに説明してください。
1. 何を作ったか
2. 3ファイルがどう協力するか
3. 確認できたこと
4. まだ確認していないこと
5. 元に戻すなら何を削除するか
の順に答えてください。追加の変更はしないでください。
ここで得た本当の成果 本当の成果は、計画を先に見た、変更範囲を限定した、実物を操作した、未確認事項を分けた、という4つの習慣です。この型はChrome拡張機能でもMacアプリでも変わりません。

PART 3 AIへの頼み方を「仕事の仕様書」に変える

CHAPTER 13

良い依頼は、目的・範囲・禁止・確認・終了条件の5点を持ちます

長い魔法の呪文は不要です。誰の何を楽にするか、どこまで触ってよいか、何を証拠に完成とするかを渡します。

要素質問
目的誰の、どんな困りごとを解くか長い記事のタイトルとURLを1クリックで保存したい
範囲どのフォルダ・ファイルを触るかこの作品フォルダ内だけ
禁止してほしくないことは何か外部通信、課金、削除、公開をしない
確認何を実行・表示して確かめるかChromeへ読み込み、ボタン操作、エラー欄確認
終了条件何がそろえば完了か3つの操作が通り、未確認事項を報告したら終了

悪い例は短いから悪いのではありません

曖昧な依頼

便利なChrome拡張を作って。

「便利」の意味、対象、権限、完成条件がなく、AIが勝手に設計を補う割合が大きくなります。

判断しやすい依頼

いま開いているページのタイトルとURLを、
ボタン1回でクリップボードへコピーする
個人用Chrome拡張機能を作りたいです。
まず計画だけを出してください。
通信・履歴の読み取り・全サイト常時アクセスは使わず、
必要最小限の権限にしてください。
完成後はChromeへ読み込む手順と確認項目を示してください。

作る→確認する→直す→再確認する

AIへの依頼を一度で完成させようとすると、長大な指示になり、途中の誤解に気づけません。小さな変更を作り、新しい証拠を取り、原因に絞って直し、元の機能も含めて再確認します。

次の1回の作業だけを行ってください。

【目的】
(誰の何を楽にするか)

【今回の範囲】
(触ってよいフォルダ・ファイル)

【禁止】
- 指定外ファイルの変更
- 依存ソフトの追加
- 外部送信、公開、削除
- APIキーや個人情報の表示

【進め方】
1. 現状を読む
2. 計画を説明する
3. 私の確認後に最小変更を行う
4. テストを実行する
5. 変更ファイル、テスト結果、未確認事項を報告する

【完了条件】
(目で見る結果と自動テストの両方)
練習問題 「メモアプリを作って」を5要素へ書き換えてください。完成後に本章の表と照らし合わせます。専門用語は不要です。「保存場所はこのMacだけ」「1件追加・削除できる」「削除前に確認」など、利用者の目に見える動作で書くのがコツです。
書けたら見本答案を開く

目的:自分用の短いメモを、Macだけに保存して後から探したい。
範囲:この作品フォルダ内のMacアプリだけ。
禁止:外部通信、アカウント作成、クラウド同期、確認なしの削除をしない。
確認:メモを1件追加し、アプリ再起動後も残り、削除前に確認が出る。
終了条件:追加・再表示・削除の3操作が成功し、未確認事項が報告される。

5項目中4項目を書けたら次へ進めます。3項目以下なら、直前の表を見て不足した項目だけを足してください。

PART 4 Chrome拡張機能を、小さく安全に作る

CHAPTER 14

最初のChrome拡張機能は「ページ情報をコピーする」だけに絞ります

Manifest V3、ポップアップ、最小権限を学ぶため、いま開いているページのタイトルとURLをコピーする個人用ツールを作ります。外部通信は使いません。

Chrome拡張機能は、小さなアプリの箱です

Googleの公式資料では、すべての拡張機能の根にmanifest.jsonが必要です。これは、名前、版、使う機能、必要な権限をChromeへ伝える名札兼申請書です。現在の基本形式はManifest V3です。

manifest.json名札・入口・権限
+
popup.html見える小窓
+
popup.jsボタンの動作
+
popup.css見た目

専用フォルダを作ります

cd "$HOME/Documents/AI-Projects"
mkdir page-info-copy
cd page-info-copy
pwd
opencode

この4行も上から1行ずつ実行します。最後のpwdpage-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へ「パッケージ化されていない拡張機能」として読み込みます

  1. Chromeのアドレス欄へchrome://extensionsと入力します。
  2. 右上の「デベロッパー モード」を有効にします。これは自作拡張機能を試すための開発者向け表示です。
  3. 「パッケージ化されていない拡張機能を読み込む」を押します。
  4. page-info-copyフォルダを選びます。中のファイルではなく、4ファイルを入れたフォルダそのものです。
  5. 拡張機能をツールバーへ固定し、通常のWebページで押します。

5項目を人の目で確かめます

エラーは「赤い文字をそのまま渡す」と解決しやすくなります

chrome://extensionsの拡張機能カードに「エラー」が出たら開き、表示された文章を省略せずコピーします。ポップアップを右クリックして「検証」を開くと、Console(エラーの詳しい記録欄)も確認できます。秘密情報がないことを確認してから、OpenCodeへ貼ります。

Chromeへの読み込みで次のエラーが出ました。
まだ修正しないでください。
原因候補を最大3つに絞り、最も可能性が高い順に説明してください。
その後、確認するファイルと行を示してください。

【エラー全文】
ここへ貼る
権限は機能を増やすほど広げない Googleは、必要な権限だけを要求し、任意機能は実行時に選べる「任意権限」を検討するよう案内しています。権限を減らすと、利用者の警告が減るだけでなく、拡張機能が攻撃された場合の被害範囲も小さくなります。
発展課題:保存機能を足す前に設計する

次はコピー履歴を3件だけ保存する機能を考えられます。ただし、どこへ保存するか、個人情報を含むURLをどう扱うか、削除ボタンをどう作るかを先に決めます。「機能を足して」だけでは進めません。新しい権限が必要かをAIへ説明させ、追加前後のmanifest.jsonを比較します。

PART 5 XcodeとOpenCodeを組み合わせてMacアプリを作る

CHAPTER 15

MacアプリはXcodeで器を作り、OpenCodeで中身を育てます

最初のMacアプリは「30秒休憩タイマー」です。Xcodeが組み立て工場、Swiftが材料の言葉、SwiftUIが画面の書き方、OpenCodeが開発助手です。

XcodeはApple公式の開発道具一式です

Xcodeにはコードを書く場所、画面のプレビュー、アプリの組み立て、エラー表示が入っています。Apple公式の「Develop in Swift」では、XcodeとSwiftUIを使って画面や動くアプリを学べます。Xcodeは容量が大きく、導入と追加部品の準備に時間がかかることがあります。十分な空き容量と電源を確保し、初回起動時の利用条件への同意と追加部品の導入が終わってから進みます。

先にXcodeだけで空のMacアプリを作ります Xcodeを開き、「Create New Project」からmacOSの「App」を選びます。Product NameをBreakTimer、InterfaceをSwiftUI、LanguageをSwiftにします。保存場所は~/Documents/AI-Projectsです。画面の項目名はXcodeの版で少し変わる場合があります。

最初にXcodeの▶︎でHello Worldを動かします

AIで変更する前に、Xcodeが作った初期アプリを実行します。上部の実行先が「My Mac」になっていることを確認し、▶︎を押します。空のウィンドウや「Hello, world!」が表示されれば、開発環境そのものは動いています。ここが基準点です。

AIで編集する前に、初期状態を複製します いったんXcodeを終了します。Finderで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つを確認します

署名、配布、App Store公開は別の工程です 自分のMacで学習用アプリを動かすことと、他の人へ安全に配ることは同じではありません。配布ではコード署名、権限、プライバシー説明、Appleの審査やDeveloper Programが関係します。最初の実習でAIに署名設定や公開処理まで任せないでください。
CHAPTER 16

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で、意図したファイルだけが保存対象になったことを見ます。

Author identity unknownと出た場合 Gitへ保存する名前とメールが未設定です。個人情報をAIへ送る必要はありません。この作品だけに設定するなら、git config user.name "自分の表示名"git config user.email "自分のメールアドレス"を、自分の情報へ置き換えて実行します。会社や公開プロジェクトでは、指定された表示名とメールを使ってください。

AIの変更後は差分を読みます

git status
git diff

差分は、削除された行を-、追加された行を+で示します。コードを全部理解できなくても、予定外のファイルが変わっていないか、APIキーらしき長い文字列が入っていないか、大量削除がないかは確認できます。

戻し方は、対象を確定してから選びます

Gitには複数の戻し方があります。初心者が意味を知らずにreset --hardのような強い命令を実行すると、未保存の作業を失うことがあります。まずAIへ「読み取り専用で現在の変更と保存地点を説明して。まだ戻さないで」と頼み、対象を特定します。

現在のGitの状態を読み取り専用で確認してください。
まだファイルや履歴を変更しないでください。

1. 保存済みの最新コミット
2. 保存されていない変更ファイル
3. 変更を残したまま退避する方法
4. 特定ファイルだけ戻す方法
を説明し、実行候補のコマンドと失われる可能性のある内容を示してください。
練習:小さな保存地点を作る Chrome拡張機能の読み込み成功後に1回、コピー動作成功後に1回、コミットを作ってください。「どこまで戻れるか」が名前だけで分かる短い日本語メッセージで構いません。

PART 6 1人のAIを、役割の違う小さなチームへ育てる

CHAPTER 17

サブエージェントは、別室で限定された仕事をする専門担当です

主担当が全部を抱えるより、調査・レビュー・セキュリティ確認を別の文脈へ分けると、会話が整理され、権限も狭くできます

普段会話する主担当を、OpenCode公式ではPrimary agentと呼びます。必要なときだけ呼ぶ専門担当がSubagentです。サブエージェントは主担当から呼ばれるほか、利用者が@で指定して呼べます。本書では、まず調査担当のExploreだけを使います。ほかの標準担当名は、今は覚えなくて構いません。

最初から大人数にしないでください

サブエージェントが増えると、同じコードを何度も読み、料金と時間が増えます。指摘が重複し、どの意見を採用するかの仕事も人へ戻ります。最初は主担当と読み取り専用レビュー担当の2役で十分です。

標準のPlanとExploreを先に使います

自作担当を増やす前に、Planで変更前の分析を行い、Exploreでコードの場所や関係を調べる使い方を覚えます。調査担当には編集権限を渡さず、「どこに何があるか」「原因候補は何か」までで止めます。

@explore この不具合に関係するファイルと処理の流れを、
読み取り専用で調べてください。
ファイル変更やコマンドによる書き込みはしないでください。
根拠となるファイル名と箇所を示し、原因候補を最大3つに絞ってください。

仕事を分ける基準

状況主担当のままサブエージェントへ
文言や色の小変更不要
大きなコード内の場所探し可能Exploreへ分けると整理しやすい
公開前の品質確認自己確認も行う読み取り専用レビューを追加
個人情報・課金・権限実装安全確認と別モデルレビューを推奨
同じ修正を2回失敗一度止める原因調査を別文脈へ分ける
CHAPTER 18

レビュー担当は、編集禁止・別会社の上位モデル・根拠必須にします

レビュー担当の目的は「賛成すること」ではありません。変更せずに、見落としと確認不足を根拠つきで示すことです。

上位モデルは「難しい場面だけ呼ぶ顧問」です

主担当の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
---

あなたは読み取り専用のコードレビュー担当です。
完成条件、バグ、権限、秘密情報、テスト不足を確認してください。
各指摘には対象ファイルと根拠を付け、ファイルは変更しないでください。
見本のモデルIDは、そのまま使えません model:の値は説明用の空欄です。opencode modelsまたはモデル選択画面に表示される完全なIDで、値の部分を丸ごと置き換えてください。自分でopenrouter/を足しません。価格と提供状況は変わるため、本書で固定しません。

レビュー結果は自動採用しません

レビュー担当も間違えます。指摘を「直す」「確認してから直す」「今回は残す」に人が分けます。互いに矛盾する指摘が出たら、完成条件と実際のテスト結果へ戻ります。AI同士の多数決は、正しさの証明にはなりません。

@review 現在の未コミット差分を読み取り専用でレビューしてください。
今回の完成条件は次のとおりです。
(完成条件を貼る)

ファイルは変更しないでください。
重大度を「公開を止める」「早めに直す」「改善候補」の3段階に分け、
各指摘へ根拠と再現手順を付けてください。

PART 7 料金と安全を、感覚ではなく仕組みで管理する

CHAPTER 19

料金は「入力×単価+出力×単価」で見積もり、実績で補正します

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に記録された実績を最終値として確認してください。

割引終了日を本書から推測しないでください 料金ページには確認時点で「50% off」とありますが、本書では終了日を確認できていません。計画は通常料金で作り、実際の利用直前にモデルページを見てください。

計算例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つの習慣

  1. 作品ごとに会話とフォルダを分ける。
  2. 「全部読んで」ではなく、目的に関係する場所から調べさせる。
  3. 同じ失敗を2回繰り返したら実装を止め、原因調査へ切り替える。
  4. 大きな画像、動画、生成物、依存フォルダを必要なく読ませない。
  5. レビュー担当は節目だけ呼ぶ。
  6. APIキーへ小さな上限を付ける。
  7. OpenRouterのActivityで、モデル・APIキー・期間ごとのSpendを毎週見る。

反論:GLMが安いなら、料金確認は不要では?

単価が低くても、無限ループ、巨大なファイル、上位モデルのレビュー、複数サブエージェントが重なると増えます。安さは監視を不要にする理由になりません。

再反論:初期上限とActivity確認を仕組みにすれば、毎回おびえる必要もありません。「止める上限」と「振り返る日」を決め、日々は作品づくりへ集中します。

毎週5分の料金点検 Activityで期間を1週間にし、Spend(利用額)、Tokens(処理量)、Requests(呼び出し回数)を見ます。最も費用が大きかったモデルとAPIキーを1つずつ確認し、「意図した作業だったか」をメモします。料金の絶対額より、説明できない増加を見つけることが目的です。
CHAPTER 20

安全対策は、秘密・範囲・変更・通信・公開の5枚扉で考えます

事故を1つの注意力で防ごうとせず、複数の小さな扉を置きます。1枚を通り抜けても、次の扉で止まる設計です。

秘密APIキー・個人情報を入れない
範囲専用フォルダだけ
変更計画・差分・Git
通信送信先と権限を確認
公開人の最終承認

扉1:秘密を最初から作業机へ置きません

APIキー、パスワード、秘密鍵、顧客名簿、診療情報、未公開契約書、写真の位置情報を練習へ使いません。秘密を検出してから隠すより、最初から対象外にするほうが確実です。

扉2:作業範囲を作品フォルダへ閉じます

OpenCodeを起動する前にpwdlsを見ます。外部フォルダへアクセスする許可が出たら、「なぜ必要か」「読み取りだけか」「どのパスか」を確認します。理由が説明できないなら拒否します。

扉3:変更前後をGitとテストで挟みます

動いている状態をコミットし、AIには小さな差分だけを作らせます。変更後はgit diffとテストを確認します。大量のファイルが変わったら、機能追加を続けず、範囲が広がった理由を調べます。

扉4:外部通信と権限を機能ごとに説明させます

Chrome拡張機能のhost_permissions、Macアプリのネットワークやファイル権限、追加ライブラリの通信を確認します。「便利だから」では理由になりません。どの機能が、どのデータを、どこへ送るかまで言葉にします。

扉5:公開と配布は別の承認にします

GitHubへのpush、Chrome Web Store、App Store、Vercelなどへの公開は外部状態を変えます。作成の依頼と公開の依頼を分け、公開直前に秘密、ライセンス、権限、料金、説明文、スクリーンショットを人が確認します。

絶対に自動承認しない操作 広い削除、履歴を書き換えるGit操作、外部公開、課金設定、アカウント作成、秘密の読み取り、署名設定、管理者権限、セキュリティ機能の無効化。これらが本当に必要なら、対象と影響を読み取り専用で確認したあと、別の操作として実行します。

見知らぬプロジェクトは、書かれた指示も疑います

ダウンロードしたプロジェクト内のAGENTS.mdや説明ファイルには、AIへ強い操作をさせる文章が含まれる可能性があります。知らないプロジェクトを開いたら、最初は読み取り専用で構成と指示ファイルを確認します。内容を理解する前にBuildで起動しません。

AIが危険な提案をしたときの返し方

その操作はまだ実行しないでください。
読み取り専用の確認へ戻ります。

1. 操作の目的
2. 正確な対象
3. 失われる・公開される・課金される可能性
4. 元に戻す方法
5. より狭く安全な代替案
を説明してください。

PART 8 止まったときの道しるべ

CHAPTER 21

エラーは「どの層で止まったか」を分けると解けます

OpenCode、OpenRouter、モデル、作品、Macの5層を一度に直さないでください。最後に成功した場所を見つけ、次の1層だけ確認します。

Mac/iTerm2コマンドを入力できるか
OpenCode起動できるか
OpenRouter認証・残高・上限
GLMモデルID・提供・制限
作品ビルド・実行・画面

opencode: command not found → 導入場所を確認

  1. ターミナルを完全に閉じ、開き直します。
  2. opencode --versionを再実行します。
  3. Homebrewを使ったならbrew list | grep opencodeで導入済みか確認します。
  4. 導入方法を混ぜた場合は、どの方法を残すか決めてから整理します。

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-flashopencode 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の推奨修正を意味を読まずにすべて適用しません。

予定外の大量変更 → その場で止める

  1. Control + Cで実行を止めます。
  2. git statusgit diff --statで規模を見ます。
  3. まだ保存・公開・削除をしません。
  4. 対象ファイルを特定し、必要な変更と不要な変更を分けます。
  5. 戻す前に、未保存の自分の作業がないか確認します。

APIキーを誤って表示した → 直ちに無効化

画面を閉じるだけでは足りません。OpenRouterで該当キーを無効化し、新しいキーを作ります。Gitへ入れた場合は、公開状況と履歴を確認します。秘密を履歴から消す作業は複雑なので、公開済みならセキュリティに詳しい人へ相談してください。

相談するときの情報セット Macの種類とmacOS版、OpenCode版、使ったモデルID、実行した命令、エラー全文、最後に成功した操作、期待した結果、実際の結果をそろえます。APIキーや個人情報は必ず伏せます。
CHAPTER 22

30日で「AIに作らせる人」から「AI開発を管理できる人」へ進みます

毎日長時間は不要です。週ごとに、観察→小変更→作品→レビューと負荷を上げます。できなかった日は飛ばして構いません。

第1週:Macの現在地と変更を読めるようにする

課題できた証拠
1pwdlsを使う現在地を言葉で説明
2専用フォルダを3つ作る作品ごとに部屋を分けた
3OpenCodeを読み取り専用で起動ファイル数だけ答えた
4Planで計画だけを作る変更が0件のまま
51行だけ変更する変更前後を説明できる
6git statusgit diff予定外変更がない
7料金Activityを確認1週間のSpendを記録

第2週:小さなWeb作品で確認ループを回す

第12章の自己紹介ページを作り、色変更、ボタン文言、入力欄追加を1日1変更で行います。毎回、計画、差分、ブラウザ確認、コミットの順に進めます。2つ以上の機能を同日にまとめないでください。

第3週:Chrome拡張機能を育てる

第14章のコピー拡張機能を完成させます。権限一覧を自分の言葉で説明し、通常ページ、長いタイトル、日本語URL、コピー失敗の場面を試します。機能追加より、エラーを再現して説明する練習に時間を使います。

第4週:Macアプリとレビュー担当へ進む

休憩タイマーを作り、二重開始、0秒、リセット、再起動を確認します。Gitの保存地点を作り、読み取り専用レビューを1回だけ呼びます。指摘をそのまま採用せず、完成条件と実物に照らして仕分けます。

卒業制作の条件

卒業とは、何も見ずにコードを書けることではありません 分からないことを安全に調べ、小さく試し、証拠を見て、戻せる状態を保てること。それがAI時代の開発力です。コードの知識は、作品を作るたびに後から付いてきます。
ここで通読は完了です。今日の20分で行う3手 1. 第8章を見ながらpwdlsを1回ずつ実行する。2. 第7章の専用フォルダを作る。3. 第11章の読み取り専用確認まで進む。作品づくりは別の日で構いません。

APPENDIX 必要なときに引く資料

GLOSSARY

用語集は、分からない言葉へ戻るための索引です

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。提供者が入力を保持しない方針。利用可能な提供者が減る場合がある。
PROMPT LIBRARY

困ったときは、完成済みの依頼文から始められます

1. 変更前の安全確認

このプロジェクトを読み取り専用で調べてください。
まだファイル変更、コマンド実行、インストール、通信はしないでください。
目的に関係するファイル、現在の動作、想定される変更範囲、危険な点を説明してください。

2. 計画だけを作る

次の目的を達成する最小の計画を作ってください。
まだ実装しないでください。

【目的】
ここに書く

【完成条件】
- ここに書く

計画には、変更ファイル、変更理由、確認方法、戻し方、未確定事項を含めてください。

3. 最小実装

確認済みの計画に沿って、最小の変更だけを実装してください。
指定外ファイル、依存ライブラリ、設定、外部通信は変更しないでください。
変更後にテストを行い、変更ファイル、結果、未確認事項を報告してください。

4. エラーの原因調査

次のエラーを調査してください。まだ修正しないでください。
原因候補を最大3つに絞り、根拠と確認方法を示してください。
秘密情報が含まれている場合は表示せず、存在だけ知らせてください。

【期待した結果】
ここに書く

【実際の結果】
ここに書く

【エラー全文】
ここに貼る

5. 修正後の再確認

修正した問題だけでなく、影響を受ける既存機能も再確認してください。
実行したテスト、成功した結果、失敗した結果、実行できなかった確認を分けて報告してください。
「問題ありません」だけで終わらず、証拠を示してください。

6. 読み取り専用レビュー

現在の差分を読み取り専用でレビューしてください。
ファイルは変更しないでください。
完成条件、明確なバグ、セキュリティ、プライバシー、権限、テスト不足を確認し、
各指摘へ対象ファイル、根拠、再現手順、重大度を付けてください。

7. 作業終了時の引き継ぎ

ここで作業を終了します。追加変更はしないでください。
次回のために、目的、完了したこと、変更ファイル、テスト結果、未解決、次の安全な一手を整理してください。
APIキーや秘密情報は書かないでください。

8. 料金が増えたとき

これ以上の実装を止め、料金を抑える観点で現在の作業を整理してください。
重複して読んでいる可能性のあるファイル、不要な長い履歴、繰り返している失敗、
安価なモデルで続けられる部分、上位モデルが必要な部分を分けてください。
SOURCES

変わりやすい情報は、公式一次情報へ戻って確認できます

本書は2026年8月27日に以下の公式資料を確認して作成しました。価格、モデル提供、画面、設定形式は変わります。利用時点の公式ページを最終判断にしてください。

  1. OpenCode公式ドキュメント — 導入、基本概念、設定。
  2. OpenCode Providers — OpenRouterの/connect/models、追加モデル設定。
  3. OpenCode Agents — Primary/Subagent、権限、Markdown担当、opencode agent create
  4. OpenCode Troubleshooting — モデルID形式、ProviderModelNotFoundError。
  5. OpenCode RulesAGENTS.mdとプロジェクト指示。
  6. OpenRouter公式 OpenCode Integration — ターミナル版・デスクトップ版の接続手順。
  7. OpenRouter GLM-5.3-Flashモデルページ — 正式ID、料金、コンテキスト、提供者、機能。
  8. Z.ai公式 GLM-5.3-Flash発表 — 設計、評価、公開情報。
  9. OpenRouter FAQ — クレジット、購入手数料、料金、認証、ログ。
  10. OpenRouter Data Collection — 入力・出力保存、任意設定、メタデータ。
  11. OpenRouter Provider Logging — 提供者ごとのデータ方針。
  12. OpenRouter Zero Data Retention — ZDRの意味と制限。
  13. OpenRouter Activity Export — Spend、Tokens、Requestsの確認。
  14. Chrome for Developers: Manifest file format — Manifest V3の基本。
  15. Chrome for Developers: Declare permissions — 権限と任意権限。
  16. Chrome for Developers: Protect user privacy — 最小権限と利用者データ。
  17. Apple Developer: Welcome to SwiftUI — Xcode、Swift、SwiftUIの公式入門。
  18. Apple Developer: Develop apps for Apple platforms — Apple公式の体系的な学習コース。
  19. fujikawa.com: iTerm2 — iTerm2のインストールと設定。
このガイドで解決しない疑問の持ち込み先 OpenCodeの不具合はGitHub Issuesで既存事例を検索し、OpenRouterの請求はsupport@openrouter.aiへ相談します。Chrome拡張機能はChrome for Developers、MacアプリはApple Developer Documentationへ確認します。新しく相談する前に検索し、第21章の情報セットを添えます。APIキーは必ず伏せてください。

本文中の料金計算はコードで検算済みです。ベンチマーク値はZ.aiの公表値であり、本書が独自に再測定した結果ではありません。実習の画面名は製品更新や言語設定により変わる場合があります。

30日コースと今日の3手へ戻る ページの先頭へ戻る

著者: 藤川忠彦(ふじかわ ただひろ) — 企業向けAI導入アドバイザー、神奈川県茅ヶ崎市。

頭脳と中継所と手足をつなぐ三点の線でMacのAI開発室の仕組みを表した表紙画像
FUJIKAWA LAB SPECIMEN 41 / 41