# OpenCode 用ワークスペーススターター

デスクトップアプリでこの文書、または下のブラウザー版ガイドをエージェントに渡し、共通の作業場所と最初のプロジェクトの初期設定を依頼してください。利用者がコマンドを入力する必要はありません。エージェントに既存ファイルを調べてもらい、変更内容と確認結果を受け取ります。

[ブラウザー版ガイド](https://zov.la/ja/setup)

共通ルートに README.md と AGENTS.md、その下に projects/、memory/、documents/、skills/ を並列で配置します。projects/my-project/ には専用の AGENTS.md と STATUS.md を作ります。Claude Code 版は共通ルートとプロジェクトに CLAUDE.md を加えます。記憶と資料の索引には記録方法を用意し、実際の知識は空の状態から育てます。

## エージェント向け実行手順

### 変更前に

変更前に、既存の導入記録があれば読み、今回の対象と現在の状態を照合してください。変更する既存の指示ファイルだけを、公開・Git追跡・クラウド同期されないローカルの保存先へ退避し、元のパスと内容の照合値を記録してください。認証情報やアプリ設定全体は収集しません。保存できない場合は、その既存ファイルの変更を保留してください。新規ファイルは新規と記録し、過去の退避を上書きしないでください。

利用目的が未指定なら最初に会話で確認する。依頼文に用途があれば再質問せず、その用途で必要になる能力を調べる。

1. [setup.mjs](./setup.mjs)、[files.json](./files.json)、[manifest.json](./manifest.json) を確認する。公開 manifest の SHA-256 はダウンロードファイルの照合に使える。実際の保存先と既存ファイルを確認する。
2. 新しい共通ルートを作る場合、Node.js 20 以上があれば、ダウンロードした setup.mjs の場所で実行する。保存先は先に選んだ場所の絶対パスを `--dest` に渡し、`--check` にも同じパスを渡す。次はエージェント向けの OS 別の例であり、実際のパスに置き換える。

Windows の例:

```sh
node ./setup.mjs --dest "C:/Users/you/ai-workspace"
node ./setup.mjs --check --dest "C:/Users/you/ai-workspace"
```

macOS の例:

```sh
node ./setup.mjs --dest "/Users/you/ai-workspace"
node ./setup.mjs --check --dest "/Users/you/ai-workspace"
```

Linux の例:

```sh
node ./setup.mjs --dest "/home/you/ai-workspace"
node ./setup.mjs --check --dest "/home/you/ai-workspace"
```

3. Node.js がなければ、[files.json](./files.json) の `files[].path` と `files[].content` を新しい保存先へ正確に作成する。可能なら各 `sha256` と照合する。
4. 既存フォルダにはインストーラーを実行しない。既存リポジトリを配置のためだけに移動せず、プロジェクトの入口から共通ルートへの実際のパスを案内する。既存の `AGENTS.md`、README、進捗記録、知識ベースを読み、役割ごとに使える内容だけを差分として統合する。既存の NOTES.md や tracker が現在地を管理していれば STATUS.md を重複作成せず、資料や記憶も既存の正本を活かす。入口と索引の参照先を実際の配置へ揃える。既存の内容を消さず、古い記録を現物と照合する。Claude Code 版では既存 `CLAUDE.md` を確認し、必要なら `@AGENTS.md` を追加する。
5. projects/my-project/ は空のひな形なので実際の仕事の名前へ変えるか、最初の仕事を決めるまでそのまま残す。基本は共通ルートをアプリで開き、対象プロジェクトを指定する。プロジェクトだけを開く場合も含め、新しい会話で共通の指示、対象の STATUS.md、関連する記憶が読めるか確認する。親フォルダが読めなければ共通ルートを開くか、アプリで必要な読み取り範囲を指定する。新規作成なら STATUS.md と索引に架空の進捗や記憶がないことを確認する。既存プロジェクトなら、既存の継続記録が保たれ、現物と照合されたことを確認する。実際のモデルで未確認なら、その旨を結果に書く。

6. 利用者の依頼に個人設定の導入が含まれる場合だけ、[PERSONALIZATION.md](./PERSONALIZATION.md) を読む。対象は選択されたアプリのユーザー単位の指示ファイルだけとし、実際の設定先と既存内容を確認する。Codex は通常 ~/.codex/AGENTS.md（CODEX_HOME が設定されていればその場所）だが、AGENTS.override.md があればそちらが優先されるため、実際に有効なファイルを確認する。Claude Code は ~/.claude/CLAUDE.md、OpenCode は通常 ~/.config/opencode/AGENTS.md。OpenCode は AGENTS.md を新設すると既存の ~/.claude/CLAUDE.md のフォールバックが適用されなくなる場合があるため、継承されていた指示も確認する。別アプリの指示全文をコピーして二重管理しない。既存の適用範囲を保てない場合は既存設定を維持し、統合できない内容と具体的な選択肢を報告する。Codex の override が一時設定なら、恒久的な個人設定の保存先と分けて扱い、既存の優先関係を勝手に変えない。既存の内容を丸ごと置換せず、同義の指示は追加しない。初回は追加内容を範囲の分かる見出し「ZOVLA personal preferences」の下へ統合し、再実行時はその節だけを差分更新する。衝突する好みは利用者に確認する。実際の変更前後を比較し、新しい会話で有効な指示を確認する。設定画面への貼り直しは不要。書き込み権限がなければアプリの案内に従い、制限を迂回しない。

インストーラーは親ディレクトリが存在する未作成の保存先だけを受け付けます。既存の空ディレクトリ、リンクを経由するパス、不足した親は拒否します。失敗時は不完全な保存先を残して報告し、自動で削除・上書きしません。`--check` は非破壊で照合します。通信、外部コマンド、グローバル設定変更、Git 初期化、プラグイン・hook・定期実行の登録は行いません。

## 用途に合うSkillsの選定と導入

利用目的が分からなければ「何を作る・調べる・整理するために使いたいか」を聞き、必要な出力形式や繰り返す作業だけを追加で確認してください。まず利用中アプリの既存機能・導入済みSkillsで足りるか調べ、不足する能力に合うSkillsを公式配布元やアプリのカタログから探してください。候補の本文・補助コード・提供元・利用条件・依存ツール・権限を確認し、用途との対応、追加が必要な理由、導入先と影響範囲を少数に絞って説明してください。利用者が候補を選んだら、そのアプリで使える形式と実際の読み込み場所を公式資料と現物で確かめ、選ばれたものを導入してください。Skillsを含むプラグインに別の接続やhookが付属する場合は影響を分けて説明し、追加の承認やログインが必要な操作はアプリの手順で案内してください。権限変更や課金をこの依頼だけで行わないでください。同名・同等のものを重複導入せず、既存ファイルを変更する前に退避してください。導入後は使い捨ての例で読み込みと実行結果を確認し、skills/INDEX.mdに用途、出典・版、実際の登録先、更新・無効化方法、確認結果を記録してください。共有skills/にコピーしただけで登録済みとは扱いません。追加不要なら理由を、候補が見つからない・検証できない場合は不足と次の手順を記録し、架空のSkillsや成功を作らないでください。

## 導入結果と戻し方

作成・変更した指示とSkillsは導入直後の内容も同じ非公開の退避先へ保存し、変更前・導入直後・現在の3つを比較できるようにしてください。導入結果を共通ルートのSETUP.mdへ記録してください。既存の同名文書が別用途なら上書きせず、別名を選びREADMEから案内してください。利用目的、選択アプリ・OS、実施日、作成・変更・保留した項目、変更理由、実際の保存先、退避先、変更前後の保存先と照合値（導入記録自身の照合値は不要）、Skillsの選定結果、確認済みと未確認、次に開くフォルダを残してください。設定内容の全文や秘密情報は記録へ転記しません。既存の記録は履歴を残して更新し、未実施を完了と書かないでください。各変更の戻し方を記し、復元時は現在の内容と導入直後の内容を比較して、後から加わった仕事や設定を保護してください。一致しないものを退避ファイルで丸ごと上書きせず、追加分だけを差分で戻します。新規の作業フォルダも一括削除しません。Skillsはアプリの無効化・削除手順と対象を示してください。記録と退避の場所を利用者に伝え、READMEから導入記録へリンクしてください。

SETUP.md は空の記録用ひな形です。インストーラーが書いたことを、エージェントによる導入全体の完了と扱わないでください。--check は配布時のひな形との一致を調べます。名前変更や記録更新を始める前に実行し、その後の差分は導入記録と現物で確認してください。差分を消すためにひな形へ戻さないでください。

OpenCode はプロジェクトの `AGENTS.md` を読みます。

## 公式資料

- [OpenCode の指示ファイル仕様](https://opencode.ai/docs/rules/)

- [OpenCode のSkills仕様](https://opencode.ai/docs/skills/)

## 利用許可

このオリジナルのスターター文書は、目的を問わずコピー・変更・共有できます。無保証です。