OpenCode + oh-my-opencodeベストプラクティスガイド
AIプログラミング・アシスタントの使用経験がある開発者を対象とし、実世界に焦点を当て、最新の公式ドキュメント（2026-04）に基づいている。
I. オープンコードとは
OpenCodeはターミナルで動作するオープンソースのAIプログラミング・エージェントで、Claude、GPT、Geminiなど75以上のモデルをサポートし、3種類のTUI/IDEプラグイン/デスクトップ・アプリケーションを提供する。
クロード・コードとの最大の違い：モデルロックがなく、完全にオープンソースで、エージェントシステムは深く拡張可能です。
インストールと設定
# 方式一：官方安装脚本（推荐）
curl -fsSL <https://opencode.ai/install> | bash
# 方式二：Homebrew（最新版本）
brew install anomalyco/tap/opencode
# 方式三：Node.js
npm install -g opencode-aiAPIキーを設定します：
export ANTHROPIC_API_KEY="sk-ant-..."
# 或在 TUI 里运行 /connect，按提示授权OpenCodeのコアコンセプト：エージェントシステム
これが、クロード・コードのシングル・エージェント・モデルとは対照的に、オープンコードを理解する鍵である。
3.1 2種類のエージェント
OpenCodeには2種類のエージェントがあります：
主代理店あなたが直接話している相手。 Tab キーで切り替える。
サブエージェントマスターエージェントは自動的にスケジュールします。 @mention 通話専門のアシスタント。
oh-my-opencodeをインストールすると、メイン・エージェントとサブ・エージェントの両方が大幅に拡張される。
3.2 @ の2つの用途がある。
@ はTUIで最も重要な入力記号で、2つのまったく異なる用途がある：
参考文献(あいまい検索)
这段鉴权逻辑有没有问题？@src/middleware/auth.tsファジーファイル検索のトリガーとなり、選択されるとファイルの内容が自動的にコンテキストに挿入される。
サブエージェント(直通電話)
@explore 找出所有调用了 sendEmail 的地方
@general 帮我并行处理这三个模块的文档生成マスターエージェントは、実行中に特殊なタスクを実行するサブエージェントを自動的に指名することもできる。
どちらも同じメッセージに混ぜることができる：
@explore 分析 @src/api/ 目录下所有接口的结构3.3 Tab キー：メインエージェントの切り替え
Tab すべてのキー主代理店 間のローテーション。Shift+Tab リバース・スイッチング。
Tab # 切换主 Agent（Build → Plan → 自定义 Agent → ...）
Shift+Tab # 反向切换⚠️ よくある誤解：タブは「プラン/ビルドモードの切り替え」ではなく、2つの別々のマスターエージェントの切り替えです。
プラン・エージェントは基本的に、「ファイル書き込みとbashコマンドにはデフォルトで手動確認を要求する」制限付きエージェントである。
典型的な使用法：
# 先切到 Plan Agent 规划，只提方案不改代码
Tab → 描述需求，拿到方案后审查
# 方案确认后切回 Build Agent 执行
Tab → 好，按计划执行。3.4 ショートカットキー
リーダーキーのデフォルトは
Ctrl+X以下はその例である。tui.jsonで修正した。
IV. TUI共通オペレーション
4.1 プロジェクトの初期化
cd /path/to/project
opencodeTUI内部で実行される：
/initプロジェクトの構造を分析し、ルート・ディレクトリに生成する。 AGENTS.md——必ずGitにコミットしてください。これがエージェントのプロジェクトメモリーだ。
4.2 シェルコマンドの実行
メッセージは次のような形で伝えられた。 ! はシェルコマンドで始まり、それが直接実行され、出力はツールの結果としてコンテキストに注入される：
!git log --oneline -20
!npm test -- --coverage
!cat package.json4.3 元に戻す／やり直す
/undo # 撤销最近一次修改（含文件变更），可多次执行
/redo # 重新应用已撤销的修改ファイルの変更を管理するためにGitに頼る。プロジェクトはGitリポジトリでなければならない。
4.4 コンテキスト管理
/compact # 压缩当前会话，保留关键上下文，释放 token（alias: /summarize）
/new # 开启新会话（alias: /clear）
/sessions # 查看并切换历史会话（alias: /resume）4.5 その他の共通コマンド
/share # 生成会话分享链接（复制到剪贴板）
/unshare # 取消分享
/export # 导出会话为 Markdown，用外部编辑器打开
/thinking # 切换是否显示 Extended Thinking 内容
/models # 列出可用模型
/themes # 切换主题V. AGENTS.mdとカスタム拡張機能
5.1 3つの入団ポジション
オープンコードは、クロードコードの CLAUDE.md フォーマット（マイグレーションにそのまま使用可能）。
5.2 AGENTS.mdに書くべきこと
# 项目名称
## 技术栈
- 后端：Java 21 + Spring Boot 3.x
- 数据库：PostgreSQL（ORM 用 jOOQ，禁止使用 Hibernate）
- API 风格：RESTful，响应统一用 Result<T> 包装
## 构建与测试
- 构建：`mvn clean package`
- 单元测试：`mvn test`
- 集成测试：`mvn verify -P integration`
## 代码规范
- 所有 public 方法必须有 Javadoc
- 禁止在循环内执行数据库查询
- 异常统一通过 GlobalExceptionHandler 处理
## 架构说明
- 请求链路：Controller → Service → Repository → DB
- 跨模块只能通过 service 层调用，不能跨层调用 repository5.3 エージェントのカスタマイズ
在 .opencode/agents/ 或 ~/.config/opencode/agents/ 確立 .md ドキュメンテーション
---
description: 安全审计，检查代码安全漏洞
mode: subagent
model: anthropic/claude-opus-4-6
temperature: 0.1
tools:
write: false
edit: false
bash: false
---
你是一名安全专家，专注以下方面的代码审计：
- SQL 注入、XSS、CSRF 漏洞
- 不安全的反序列化
- 硬编码的密钥或密码
- 权限校验缺失
只提供分析报告，不直接修改代码。ファイル名はエージェント名（例えば security-auditor.md → @security-auditor），mode: subagent が使用できるプロパティを表す。 @mention 電話だ。
5.4 カスタムコマンド
在 .opencode/commands/ 或 ~/.config/opencode/commands/ コマンドファイルを作成する：
---
description: Code Review，重点关注安全和性能
agent: build
---
请对以下代码进行 Code Review，重点关注：
1. 安全漏洞（注入、权限、加密）
2. 性能问题（N+1 查询、内存泄漏）
3. 边界条件和异常处理
4. 命名和可读性
文件：$ARGUMENTS使用する：/code-review src/api/OrderController.java
コマンドサポート $ARGUMENTS(全パラメータ）または $1、$2(位置パラメーター）で、フロントマターで指定できる。 agent、model。
VI. oh-my-opencode：オープンコードを開発チームに変える
oh-my-opencode（現在は改名されている。 oh-my-openagentnpm パッケージ名はまだ oh-my-opencode)は最強のOpenCodeプラグインだ。
コア能力：11の専門エージェント＋パラレル・サブエージェント＋α ulw ワンクリック完全自動化＋LSP/AST-Grepツール＋自動コンテキスト管理。
6.1 インストール
bunx oh-my-opencode installインストールを確認する：
cat ~/.config/opencode/opencode.json
# plugins 数组中应包含 "oh-my-opencode"6.2 ulw：最も重要な言葉のひとつ
ulw(ウルトラワークの略)は、オー・マイ・オペコードの核となるキーワードである。
キュー・ワードには ulw 或 ultraworkプラグインは自動的に「最強モード」をトリガーする：
-
- コードベースの自己探索と実装パターンの研究 -
- 複数のスペシャリスト・エージェントのスケジューリング 並行する仕事 -
- 確認を待つために停止することなく、完了するまで継続的に実行される。 -
- 自動診断の検証結果
使用量は最小限だ：
ulw 给 /api/orders 接口增加分页功能，参考 /api/products 的实现方式ulw 找出所有 N+1 查询问题并修复ulw 将整个项目的错误处理统一改为 Result 模式ulw 重构 src/payment/ 为策略模式，现有支付方式三种，对外接口不变フォーミュラ大きな仕事に直面し、何から手をつけたらいいのかわからないときは、まずこのページにアクセスしよう。
ulwシステムに判断を委ねる。
その他のキーワード・トリガーのモード：
6.3 11 プロフェッショナル・エージェント
インストール後Tab キーを押して、これらのマスターエージェントを（優先順位によって）切り替えます：
メインエージェント（タブスイッチ）：
サブ・エージェント（＠指名コール）：
ほとんどのシナリオでは、手動でエージェントを選択する必要はありません。ulw 自動的にスケジュールされる。
6.4 /start-work: 大規模機能開発ワークフロー
モジュール横断的で、アーキテクチャー上の決定事項がある大規模な機能の場合。そのプロセスは以下の通りである：
ステップ1：プロメテウスにタブでアクセスし、要件を説明する
プロメテウスは本物のエンジニアのように詳細を尋ね返す。答えの後
好，生成计划。プランファイルは .sisyphus/plans/*.md以下は、このソフトウェアの助けを借りて行うことができるタイプの仕事の例である。
ステップ2：プランの確認と実行
/start-workアトラス・テイクオーバー、スケジュールによる自動実行、切断されても自動再開（ステータスあり） boulder.json）。
⚠️ プロメテウスとアトラスはペアでなければならない。アトラス実行に直接切り替えないでください。
いつulwを使い、いつ/start-workを使うのか？
VII.実際の典型的なシナリオ
シナリオ1：見慣れないコードベースを素早く理解する
@explore 找出所有 API 入口点，列出路由和对应的 Handlerulw 分析这个项目的整体架构，重点是请求的完整链路，
输出一份给新人的 onboarding 文档シナリオ2：新機能開発
小さな機能（1～2ファイル）：ダイレクトビルドエージェント
在 @src/user/UserService.java 增加手机号登录方法，
参考邮箱登录 @src/user/EmailLoginStrategy.java中機能（複数ファイル連携）：プラン→ビルド
Tab（切换到 Plan Agent）
给删除订单功能加软删除：deleted_at 标记删除时间，
新增回收站页面支持恢复和彻底删除
（审查方案）
Tab（切回 Build Agent）
好，按计划执行。大規模な関数（モジュールをまたがる）： ulw または /start-work
ulw 实现完整的优惠券系统：
固定金额/百分比两种折扣，限制使用次数和有效期，与购物车集成シナリオ3：コードレビュー（コード変更なし）
@explore 全量扫描 src/api/ 目录，找出所有没有做权限校验的接口@oracle 对 @src/payment/PaymentService.java 做架构审查，
重点：并发安全、幂等性、异常边界シナリオ4：複雑なバグのデバッグ
ulw 追踪这个 NPE 的根本原因，从堆栈顶部到数据来源全链路分析，
找到根因后给出修复方案。堆栈：
java.lang.NullPointerException
at com.example.OrderService.process(OrderService.java:142)
...シナリオ5：大規模な再構成
ulw 将 src/payment/ 模块重构为策略模式，
现有支付方式：支付宝、微信、信用卡，
要求：对外接口不变，所有现有测试继续通过シナリオ6：UIの復元（デザイン案）
スクリーンショットをターミナルにドラッグ＆ドロップした後：
@multimodal-looker 分析这张设计稿的布局和样式
按照图中的设计实现 @src/components/Dashboard.tsxシナリオ7：ドキュメントの作成
ulw 为 src/api/ 下所有公开接口生成 OpenAPI 3.0 规范，
输出到 docs/openapi.yaml，参考 @docs/openapi-sample.yaml 的格式設定クイックリファレンス
8.1 opencode.json
{
"$schema": "<https://opencode.ai/config.json>",
"model": "anthropic/claude-opus-4-6",
"autoshare": false,
"plugins": ["oh-my-opencode"]
}8.2 oh-my-opencode エージェントの設定
~/.config/opencode/oh-my-opencode.json：
{
"agents": {
"sisyphus": {
"model": "anthropic/claude-opus-4-6"
},
"oracle": {
"thinking": {
"type": "enabled",
"budgetTokens": 200000
}
},
"explore": {
"textVerbosity": "low"
}
}
}8.3 内蔵スキル（オーマイオペコード）
スキルパスのカスタマイズ
.opencode/skills/my-skill/SKILL.md
~/.config/opencode/skills/my-skill/SKILL.mdIX.よくある質問
Q:@ 文書の引用 @mention エージェントはどのように差別化されるのか？
両者共通 @ シンボル、差別化されたロジック：入力 @ マッチがファイルへのパスの場合、ファイルの内容が注入される。入力が登録されたエージェント名（例えば @explore)、子エージェントの呼び出しがトリガされる。
Q:Tab エージェントと Ctrl+T モデルチェンジの違いは何ですか？
Tab モードまたはデータストリームを切り替える主な代理店(役割の切り替え、エージェントの専用モデルとツールの権限の切り替え)；Ctrl+T 現在のエージェントのモデルバリエーション(例えば、同じモデルの標準思考バージョンと拡張思考バージョン）。
Q: ulwと要求事項の直接記述の違いは何ですか？
直接的に説明すると、シジフォスはシングルスレッドで実行され、不確実性に遭遇すると停止して質問することがある。追加 ulw ポストトリガー完全自動化並列モード：複数のサブエージェントが同時に作業し、コードベースを独自に探索し、プロセスの途中で確認を待つことなく、完全に終了するまで検証を続ける。
Q: /start-workが中断された場合、どうすればいいですか？
再実行 /start-workシステム boulder.json 進捗状況を再開し、未完了のタスクを続行する。
Q: コンテキストがほぼ満杯の場合はどうなりますか？
うごきだす /compact 現在のセッションを圧縮することで、重要なコンテキストは保持されます。大きなタスクは /start-work ワークフロー、サブエージェントがコンテクストプレッシャーを分散させる。
書誌
-
- OpenCode公式ドキュメント -
- OpenCodeエージェントのドキュメント -
- OpenCodeキーバインド・ドキュメンテーション -
- oh-my-opencode GitHub -
- awesome-opencodeプラグイン集
この投稿はWeChat: Xuanentropy Intelligenceによるものです。
