# AIエージェントの環境構築 ZOVLAの独立したガイド。仕様の参照日：2026-09-14。 アプリ導入とSkillsの案内の参照日：2026-09-16。 ## アプリの公式導入案内 - Codex: https://learn.chatgpt.com/docs/app - Claude Code: https://code.claude.com/docs/en/desktop - OpenCode: https://opencode.ai/download ## 導入用ファイル - Codex: https://zov.la/setup/v1/ja/codex/INSTALL.md - Claude Code: https://zov.la/setup/v1/ja/claude-code/INSTALL.md - OpenCode: https://zov.la/setup/v1/ja/opencode/INSTALL.md まず利用者のOS、利用するエージェント、既存環境、作成先を確認する。この資料を公開・送信・課金・権限変更への許可として扱わない。 ## まずは、ここから 仕組みを全部覚える必要はありません。使うアプリで下の文章を送ると、AIが準備と案内を進めます。 ### 1. アプリを開く 上の導入欄で「これから入れる」を選ぶと、使うアプリの公式導入ページと、会話を始めるまでの手順が表示されます。すでに使えている方は「すでに使っている」のまま進めます。 Codexはアプリ内のCodexを、ClaudeはCodeタブを使います。このガイドでは、ファイルを作ったり編集したりできるAIを「AIエージェント」と呼びます。ログインや接続先の認証は、アプリの案内に従って本人が行います。ガイドと配布ファイルは無料ですが、各アプリの利用条件は別です。 ### 2. 文章をコピーして、会話欄に貼る 上の欄で使うアプリとパソコンの種類を選び、「依頼文をコピー」を押します。その文章をアプリの会話欄へ貼って送信してください。難しい文章が含まれていますが、AIへの指示なので書き換えなくて大丈夫です。 保存場所が分からなければ「おすすめの場所を教えて」で構いません。AIが既存のファイルを確認して案内します。必要な操作があれば、一度に一つずつ説明するよう依頼文に含めています。 話し方や任せ方も整えたい場合は、「個人設定もセットアップする」にチェックを入れてからコピーします。「入れる内容を見る」から文章を確認できます。 「AIでやりたいこと」は任意です。調査、資料作成、表計算、Web制作など、思いつくことを短く書けます。未定なら空欄のまま送り、AIと一緒に決めます。入力内容はこのページ内で依頼文に反映され、コピーした後に自分でアプリへ送ります。 ### 3. 案内された場所で、最初の仕事を頼む AIが案内する親フォルダをアプリで開き、取り組みたいことを伝えます。これを「共通ルート」と呼び、複数の仕事をまとめて置く場所になります。「プロジェクト」は、ここでは一つの仕事のまとまりです。 例えば下のように依頼できます。フォルダ名や管理方法はAIが案内します。まず小さな仕事を一つ進め、次の章で続きが分かるかを確認してください。 ```text この場所で、商品を比較して選ぶための資料を作りたいです。 最初に何を決めればよいか、必要なことから一つずつ聞いてください。 調べた根拠と決めた理由を、次の会話でも使えるように残してください。 ``` ### 途中で分からなくなったら 画面が違う、フォルダを開けない、設定を変更できない場合は、その状況をそのままAIに伝えます。「何を押せばよいか一つずつ教えて」と頼めます。 準備ができた後は、普段どおり仕事を頼んで構いません。下のフォルダ構成やスキルの説明は、仕組みを知りたくなった時に読めます。 ## 新しい会話で確かめる ファイルができただけでは完了にしません。導入した場所で新しい会話を開き、指示と記録が使われるか確認します。 ### 記録が実際に読まれることを確認する 下の依頼を新しい会話へ貼り、実際に読んだファイルと、そこから分かったことを確認します。導入直後は、進捗と知識が未記入と返るのが正しい状態です。 一つ仕事を進めた後にも試します。索引にある関連項目から本文を開き、根拠の資料まで必要に応じてたどれるかを見ます。全資料の要約を求める必要はありません。 ```text この作業場所の指示、対象プロジェクトのSTATUS.md、memory/INDEX.mdを読んでください。 今の仕事に関係する記憶の本文と、必要な根拠資料も開いてください。 実際に読んだファイル、目的、次の作業、未確認点を示してください。 空欄は空欄として扱い、この確認ではファイルを変更しないでください。 ``` ### 一つの仕事で試す 小さな作業を頼み、目的に沿う成果、実際に行った確認、残件が区別されているかを見ます。次の会話で続けられる記録も確認します。 うまく読めない時は、開いているフォルダ、ファイル名、アクセス権、アプリの読み込み仕様をエージェントに調べてもらいます。指示を増やす前に、入口が届いているかを確かめます。 ### このスターターで確認している範囲 配布ファイルからの新規作成、内容の照合、既存の保存先を上書きしないことを検証します。アプリやモデルの全組み合わせでの動作や、性能向上を保証するものではありません。 利用中の環境での読み込みは、上の手順で確認してください。基本構成は追加のサービス契約やグローバル設定変更を行いません。 ## 個人設定も、導入時に整える 話し方・判断の仕方・任せ方は、アプリのユーザー指示へ。共通の作業手順や仕事の進捗と分けて管理します。 ### 設定画面への貼り直しは不要 導入欄の「個人設定もセットアップする」を選ぶと、エージェントが選択したアプリの既存設定を読み、下の文を統合します。既存の内容を丸ごと置換せず、同じ指示を重複追加しません。好みが衝突する場合だけ確認します。 対象はユーザー単位のカスタム指示です。テーマ、モデル、権限、アプリ独自の記憶などを一括変更するものではありません。通常の保存先だけでなく、上書き用ファイルや他アプリからのフォールバックも調べ、実際に有効な指示へ統合します。変更後の差分と、新しい会話で適用される指示を確認します。 ### 共通の個人設定文 自然な対話、必要な場面での反論、実行と確認、事実と推測の区別を基準にしています。特定の職業、名前、フォルダの絶対パスは含めません。利用者の好みに合わせ、説明量や任せる範囲を調整できます。 ```text 利用者が使う言語で、自然で分かりやすく話してください。結論や結果を先に伝え、判断に必要な理由と具体例を添えてください。説明の詳しさは依頼に合わせ、不要な称賛や同じ内容の繰り返しを避けてください。 利用者の現在の目的を起点に考えてください。同意することを優先せず、問題やよりよい方法があれば理由とともに伝えてください。通常の細かな判断は自分で行い、結果を大きく変える不足情報に絞って質問してください。 実行を頼まれた時は、利用できる道具と与えられた権限の範囲で、成果物と確認まで進めてください。既存の作業を保護し、既に伝えられた内容や許可を繰り返し確認しないでください。実行できない部分は具体的に説明してください。 事実、資料に基づく情報、推測、未確認を区別してください。変わり得る情報は必要に応じて現物や一次情報を確認し、確認していないことを確認済みとしないでください。 作業場所に指示や記録がある場合は、その入口と適用範囲を確認して使ってください。過去のメモは現物と照合し、現在の依頼より優先しないでください。記録の更新は、その場所の方針に従ってください。 結果は、できたこと、確かめた方法、残っていることが分かる形で伝えてください。 ``` ### アプリごとの保存先 Codexのカスタム指示は通常~/.codex/AGENTS.mdです。CODEX_HOMEを変更している場合は実際の保存先を確認します。パーソナライズ全体がこの一つのファイルに保存される、という意味ではありません。 Claude Codeのユーザー指示は~/.claude/CLAUDE.md、OpenCodeは通常~/.config/opencode/AGENTS.mdです。通常チャットの好みがコード作業にも自動適用されるとは仮定せず、使っている機能の設定先を確認します。 既存ファイルに「ZOVLA personal preferences」の節を使って追加分を管理し、再導入時はその範囲だけを更新します。ファイルを編集できない環境ではアプリの案内に従います。 ## 仕事と知識を支える基本構成 複数の仕事を置く共通ルートの下に、仕事・知識・根拠資料・手順を並べます。分類の基準は、情報をどう使い、誰と共有するかです。 ```text ai-workspace/ ├── README.md ├── SETUP.md ├── AGENTS.md ├── projects/ │ ├── README.md │ └── my-project/ │ ├── AGENTS.md │ └── STATUS.md ├── memory/ │ └── INDEX.md ├── documents/ │ └── INDEX.md └── skills/ └── INDEX.md ``` ### 入口：AGENTS.mdとREADME.md ルートのAGENTS.mdは共通の進め方と読み込み順を示します。README.mdは利用者向けの案内です。個人の好みはアプリのユーザー指示へ、仕事固有の条件は各プロジェクトへ置きます。 Claude Code版には、共通ルートとプロジェクトにAGENTS.mdを取り込むCLAUDE.mdを加えます。取り込み用のファイルに方針本文を重複させません。 SETUP.mdは導入の記録です。何を変更したか、どのSkillsを選んだか、どう戻すかを導入したAIが記入します。日々の仕事の進捗は各プロジェクトのSTATUS.mdに残します。 ### projects/：成果物と現在地 仕事ごとにフォルダを分けます。それぞれに固有の指示を置くAGENTS.mdと、目的・完了条件・進行中の作業・確認結果・次の一手を記すSTATUS.mdを持たせます。 ソースコードや成果物、その仕事だけの判断と資料もここで管理します。現在地は仕事ごとに更新し、ルートの一つの進捗ファイルに全案件を詰め込みません。既存の課題管理があれば、その正本を使えます。 ### memory/：仕事をまたいで使える知識 再利用する判断、制約、教訓を一題ずつ短く残します。INDEX.mdには読む条件、要点、本文へのリンクを記します。利用者が決めたこととエージェントの提案を区別し、適用範囲・根拠・確認日を残します。 特定の相手や案件だけの事情は、そのプロジェクトに残します。共通記憶へ移すのは、別の仕事で使える理由を説明できる内容です。 ### documents/：共通知識の詳しい根拠 共通で使う調査、設計、比較、参考資料を置きます。memory/には結論とこの資料へのリンクを残し、長文を重複させません。INDEX.mdは用途と対象を案内します。 資料には目的、出典と確認日、結論、適用範囲、未確認点を記します。プロジェクト固有の仕様書をここへ移す必要はなく、既存の正本へのリンクで足ります。 ### skills/：繰り返し使う手順 入力、使う条件、手順、確認方法が決まった仕事をまとめます。補助スクリプトはその手順の中へ置きます。調べた内容を読むdocuments/に対し、skills/は実行する時に使う手順の置き場所です。 配布直後は索引と運用案内だけです。セットアップを進めるAIが用途と既存機能を調べ、必要なSkillsの候補を示します。選んだものだけを利用中アプリへ登録し、結果を索引に残します。この共有フォルダ自体は各アプリの自動検出先ではありません。 ### 配置より、役割と参照を揃える この構成は、空の箱を増やすためのものではありません。既存の資料や進捗管理があれば活かし、読む入口と更新先を一本に揃えます。 inbox/は取り込み待ち資料が増えた時、archive/は保存期間や参照頻度を分ける必要が生じた時に追加できます。バックアップやアクセス制御は、名前の付いたフォルダを作るだけでは成立しません。 ## 同じ説明を繰り返さない いつも必要な約束と、記録の読み方を短い入口へまとめます。今の依頼を、大量の規則や資料で見失わないための案内です。 ### 実際の困りごとを指示にする 「品質を高く」より、「変更後に何を確かめるか」を具体的に書きます。実行方法は現物で確認し、使っていない道具のコマンドをテンプレートから持ち込まないようにします。 現在の依頼、既存の作業の保護、根拠と推測の区別、結果の確認。この基本から始め、同じ説明が繰り返し必要になった時に追記します。 ```text # この仕事の進め方 - 今の依頼と、既にあるファイルを確認してから作業する。 - 対象プロジェクトのSTATUS.mdとmemory/INDEX.mdを読み、関係する本文を現物と照合する。 - 詳しい根拠が必要ならdocuments/INDEX.mdから探す。 - 結果を大きく変える不明点だけ質問する。 - 作業を実行・確認し、進捗と再利用する知識をそれぞれ更新する。 ``` ### 同じ本文をアプリごとに複製しない 複数のアプリで同じ仕事をする場合も、作業方針はAGENTS.mdで管理できます。Claude Code向けのCLAUDE.mdは、下の取り込みだけにできます。既存の指示がある場合は、内容を読んでから統合します。 指示ファイルはエージェントへ渡す文脈です。そこに禁止事項を書いただけで、すべての操作を機械的に防げるわけではありません。アクセス権や外部操作の許可は、アプリの設定でも管理します。 ```text # CLAUDE.md @AGENTS.md ``` ### 資料は、必要な時に読む 作業に関係する資料の場所と、どんな時に読むかを書きます。リンクを置いただけで本文まで自動的に読み込まれるとは限らないので、「この変更の前に読む」と明記します。 短い入口から必要な資料へ進めるようにすると、会話が始まるたびに全資料を読み込ませずに済みます。 ## 記録を、次に使える知識へ 作業の現在地、再利用する要点、詳しい根拠をつなぎます。保存・発見・読み込み・更新が一巡して、記録が次の仕事に役立ちます。 ### 開始時：索引から必要な本文を読む AGENTS.mdには、作業開始時に対象プロジェクトのSTATUS.mdと共通のmemory/INDEX.mdを読むように記載します。エージェントは今の依頼に関係する項目を選び、本文を読んで現物と照合します。 詳細な資料が必要ならdocuments/INDEX.mdか記憶のリンクから探します。索引は短く保ち、全ファイルを毎回読み込ませません。索引に載っていることと、本文を実際に読んだことは別です。 ### 作業中：結論と根拠をつなぐ たとえば資料を比較して方針を選んだ場合、詳しい比較は対象プロジェクトの資料へ、実装の残件はそのSTATUS.mdへ残します。他の仕事にも使える知見は共通memory/へ、長い共通の根拠はdocuments/へ整理します。同じ長文を3か所にコピーする必要はありません。 memory/の本文は、結論、適用条件、根拠、確認日、確定か提案かを含めます。長さのために重要な条件を削るのではなく、詳しい説明へのリンクで分けます。 ```text 作業の記録先 今の目的・進捗・次の作業 → 対象プロジェクトのSTATUS.md 再利用する判断・制約・教訓 → memory/トピック名.md 詳しい調査・設計・手順 → documents/資料名.md 何があり、いつ読むか → 各フォルダのINDEX.md ``` ### 区切り：引き継ぎと索引を更新する スターターのAGENTS.mdには、作業の区切りで対象プロジェクトのSTATUS.mdを更新し、再利用する知見と詳しい根拠を分けて残す指示を入れています。新しいファイルを作ったら、索引から見つかるようにします。 利用者は下のように依頼できます。一回限りの経過や会話全文をすべて記憶へ移すのではなく、次の判断に必要な内容を選びます。 ```text 次の会話で続きを進められるように記録を整理してください。 対象プロジェクトのSTATUS.mdを現在の状態に更新し、再利用する判断や教訓はmemory/へ、 詳しい根拠はdocuments/へ残してください。 索引と参照先を更新し、提案・決定・未確認を区別してください。 ``` ### 訂正時：古い記憶を確定事項にしない 利用者が決めたこととエージェントの提案を分けます。「検討した」が次の会話で「承認された」にならないようにします。古い記録が今の依頼より優先されることもありません。 誤りや条件の変化を見つけたら、根拠と訂正理由を残して更新します。置き換えた記憶はその状態と新しい参照先を示し、索引も直します。使われないという理由だけで、根拠資料を自動削除しません。 ### ファイルの記憶と、アプリの記憶 memory/という名前だけで、自動検索や想起の仕組みが動くわけではありません。この構成ではAGENTS.mdの指示に従い、エージェントが索引と本文を読み書きします。実際に読めているかは新しい会話で確認します。 アプリ独自の自動記憶も利用できます。保存先と適用範囲を確認し、同じ内容の食い違いを避けます。検索や自動抽出を追加するなら、保存成功だけでなく、必要な場面で正しい本文が届くかまで確認します。 ## 困りごとに合わせて広げる 追加する仕組みは、何を解決するかで選びます。最初から大量のフォルダや連携を用意する必要はありません。 ### 用途に合うSkillsを選んで使う Skillsは、AIが特定の仕事を進めるための手順です。例えば表計算なら計算や出力の確認、調査なら出典の確認など、作りたい成果物から必要な能力を考えます。職業名だけで同じ一式を入れることはしません。 導入用の依頼文には、用途を聞く→既存機能と導入済みSkillsを調べる→不足に合う候補を説明する→選ばれたものを導入する、という流れが含まれています。利用者はSkillsの名前を知っている必要はありません。追加が不要な場合も、その理由を受け取れます。 候補は提供元、内容、必要な道具や権限を確認してから提示します。導入後は小さな例で読み込みと出力を試し、結果を記録します。接続やログインが必要なら本人の操作を案内します。試せなかった項目は、導入済みと動作確認済みを分けて報告します。 登録場所はアプリの仕様に合わせます。代表的なプロジェクト内の場所はCodexの.agents/skills、Claude Codeの.claude/skills、OpenCodeの.opencode/skillsです。既存の機能や別アプリから読み込まれるSkillsとの重複も確認します。出典と版、登録先、更新・無効化方法をskills/INDEX.mdへ残します。 ```text 今の仕事に必要なSkillsを見直してください。 作りたい成果物と、いま困っている点を確認し、既存機能で足りる部分と不足を分けてください。 候補の提供元、必要な理由、依存ツールや権限、導入先を説明してください。 私が選んだものを導入して小さな例で試し、結果と無効化方法をskills/INDEX.mdと導入記録へ残してください。 ``` ### 外部の情報が必要なら、連携 外部サービスの資料や操作が必要になった時に、アプリのコネクタやMCPを検討します。まず、既に使える道具で目的を満たせるか確かめます。 提供元、渡る情報、権限を確認してから接続します。読み取りで足りる仕事に、書き込み権限まで追加する必要はありません。認証や承認が必要な部分はアプリから案内してもらいます。 ### 決まった検査を自動化するなら、フック 同じ検査を繰り返し忘れるなど、明確な問題がある時に自動化を考えます。エージェントに利用中のアプリの仕組みを調べてもらい、正常な作業を妨げず、対象の操作で発火することを確認します。 フックやプラグインの設定形式はアプリごとに異なります。定期実行も含め、他のアプリの設定をそのまま流用せず、必要な処理、費用、結果の確認先、停止方法を決めます。 ### 複数の仕事で知識を共有したくなったら 共通memory/に残した知見も、すべての仕事に適用できるとは限りません。本文の読む条件と適用範囲を確認して使います。アプリの個人設定へプロジェクトの詳細や共通資料の全文をコピーしません。 機密性や共有相手が異なる仕事は、別の共通ルートやアクセス範囲で運用できます。複数の知識ベースを一つの巨大な索引へ統合する前に、誰が何を読む必要があるかを決めます。 ## 変更を確認し、元に戻す 何を入れたか分からなくならないよう、導入したAIが変更内容と戻し方を記録します。 ### 変更前の状態を残す 既存の指示ファイルを変える前に、AIが元の状態を保存します。保存先は公開・Git追跡・クラウド同期の対象外とし、場所を導入記録に残します。保存できない既存ファイルは変更を保留します。アプリ設定全体や認証情報を集める手順ではありません。 ### 導入結果を一か所で確認する 共通ルートのSETUP.mdに、用途、アプリ、変更したファイル、退避先、Skillsの選定結果、確認結果、残件、次に開く場所がまとまります。配布時は未記入のひな形なので、AIが実際の結果を記入して初めて導入記録になります。既存の同名文書があれば別名にし、READMEから案内します。 「導入された」「小さな例で動作を確認した」「まだ試せていない」を分けて読みます。新しい版を取り込む場合も、元の記録と自分の変更を残して差分を取り込みます。 ### 必要な部分だけを戻す 戻す時は、導入記録と現在のファイルをAIに比較してもらいます。導入後に加えた設定や成果物があれば保護し、元のファイルで丸ごと上書きしません。使わないSkillsは記録されたアプリの手順で無効化できます。作業フォルダ全体を消す必要はありません。 ```text READMEから導入記録を探し、今回戻したい設定を私に確認してください。 記録、退避、現在の内容を比較し、導入後に追加した仕事や設定を守れる戻し方を説明してください。 まだ変更せず、戻す対象と影響を示してください。 ``` ## 役立ったものを残す 環境は、仕事を進めるための道具です。設定を増やすこと自体を目的にしません。 ### 失敗を何でも恒久ルールにしない 問題が起きたら、指示の不足、古い資料、ツールの失敗、今回だけの事情を切り分けます。一度の失敗を、すべての作業へ適用する規則に広げないようにします。 追加した指示が役立ったかは、似た仕事での誤り、手戻り、確認の負担を見て判断します。使われない手順や矛盾は整理します。 ### 更新は、今の仕事に合わせて取り込む 新しいスターターを取り込む場合は、別の場所へ作って差分を比較します。自分用に育てた指示や記録を、配布版で丸ごと置き換えません。 ファイルを分けるのは、長くなって探しにくい、仕事ごとに権限が違う、共有する相手が違う、といった理由ができてからで十分です。 ### 共有する範囲を分ける プロジェクトの記録は、同じ仕事をする人に渡す範囲を基本にします。他の仕事でも使う知識は、個別の事情を除いて適用範囲を見直してから共有します。 memory/やdocuments/という名前はアクセス制御ではありません。クラウド同期や公開リポジトリへ含める前に内容を確認します。秘密情報や個人情報は、エージェントが書ける記録へ一律に集約しません。 ### 変更を見直し、戻せるようにする 指示や記憶も間違って更新されることがあります。エージェントに差分を示してもらい、特に判断理由や許可の記録が変わっていないか確認します。 必要なら既存のGitやバックアップに含め、復元できるか小さなファイルで試します。共有先と記録内容を確認してから設定し、バックアップが公開を意味する状態を避けます。 ## 公式資料 - [Codex · AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md) - [Codex · Skills](https://learn.chatgpt.com/docs/build-skills) - [Claude Code · Memory & CLAUDE.md](https://code.claude.com/docs/en/memory) - [Claude Code · Skills](https://code.claude.com/docs/en/skills) - [Claude Code · Hooks](https://code.claude.com/docs/en/hooks) - [OpenCode · Rules](https://opencode.ai/docs/rules/) - [OpenCode · Skills](https://opencode.ai/docs/skills/) - [OpenCode · Permissions](https://opencode.ai/docs/permissions/) - [Codex · Personalization](https://learn.chatgpt.com/docs/personalize)