OpenCodeを使用して30分でフルスタックのBookmark Managerを構築する（ステップ・バイ・ステップ）

私たちが構築するもの

機能リストのことは忘れてください。ツールを学ぶ最良の方法は、それを使って何かを構築することです。

このチュートリアルでは、120K以上のGitHubスターを持つオープンソースのAIコーディングエージェントであるOpenCodeを使用して、ゼロから完全なブックマークマネージャーを構築します。このアプリには以下が含まれます：

• Express.jsとTypeScriptによるREST API
• full-text searchを備えたSQLiteデータベース
• ブックマークを整理するためのタグシステム
• シンプルだが機能的なフロントエンド
• Unit tests

OpenCodeの各機能は、抽象的な機能セクションではなく、必要になった瞬間に導入されます。最終的には、OpenCodeのインストール方法、モデルの設定、BuildおよびPlanモードの使用方法、MCPサーバーのセットアップ、カスタムエージェントの作成方法を、実際のプロジェクト構築を通じて習得できます。

時間： ~30分 前提条件： Node.js 18+ がインストールされていること、ターミナル（macOS、Linux、またはWindows上のWSL） 費用： 無料（OpenCode Zenモデルを使用）

フェーズ 1：OpenCodeのインストールとプロジェクトのセットアップ（5分）

OpenCodeのインストール

ターミナルを開き、以下のいずれかのコマンドを実行してください：

# オプション 1: npm (推奨)
npm i -g opencode-ai@latest

# オプション 2: Homebrew (macOS/Linux)
brew install sst/tap/opencode

# オプション 3: ワンラインインストーラー
curl -fsSL https://opencode.ai/install.sh | bash

インストールを確認します：

opencode --version

バージョン番号が表示されるはずです。2026年3月現在、最新の安定リリースはOpenCode GitHub repositoryで入手可能です。

プロジェクトディレクトリの作成

mkdir bookmark-manager && cd bookmark-manager
git init
npm init -y

OpenCodeを初めて起動する

opencode

これにより、Bubble Teaで構築されたフルスクリーン対話型インターフェースであるOpenCodeのTUI（Terminal User Interface）が開きます。下部にチャット入力、メインエリアに会話ペインが表示されます。

モデルの選択

初回起動時に、OpenCodeはモデルの選択を求めます。3つのパスがあります：

無料（Zenモデル）： /modelsと入力し、無料のZenモデルの1つを選択します。このチュートリアルでは、Grok Code Fast 1 または GLM 4.7 が適しています。これらは無料で、APIキーは不要です。

ローカル（Ollama）： Ollamaがインストールされている場合、OpenCodeは自動的にそれを検出します。Ollamaの推奨モデルは glm-4.7:cloud です。

有料（自前のキーを持参）： /connectと入力して、Anthropic、OpenAI、またはGoogleのAPIキーを連携させます。キーはローカルの ~/.local/share/opencode/auth.json に保存されます。

このチュートリアルでは、どのモデルでも動作します。より高度な能力を持つモデル（Claude Sonnet 4.6、GPT-5.4）は複雑なタスクでより良い結果を出しますが、無料のZenモデルでもここで構築するすべてを処理できます。

フェーズ 2：Buildモードによるプロジェクトの雛形作成（4分）

OpenCodeはデフォルトでBuildモードで起動します。Buildモードでは、AIエージェントがファイルの作成、コードの編集、コマンドの実行に対するフルアクセス権を持ちます。これは雛形作成に最適です。

最初のプロンプト

OpenCodeのチャットに以下を入力してください：

Set up a TypeScript Node.js project with Express for a bookmark manager REST API.
Use SQLite via better-sqlite3 for the database. Add TypeScript, ts-node, and
nodemon as dev dependencies. Create a src/ directory with an index.ts entry point
that starts an Express server on port 3000.

OpenCodeは以下を行います：

1. tsconfig.json の作成
2. npm install による依存関係のインストール
3. Expressサーバーのセットアップを含む src/index.ts の作成
4. 起動スクリプトを含む package.json の更新

TUIに注目してください。エージェントがターミナルコマンドを実行し、ファイルを作成し、各ステップで行っていることを説明するのがわかります。これは孤立したコード生成ではありません。OpenCodeはファイルシステムとターミナルへのフルアクセスを持っています。

動作確認

OpenCodeが完了したら、次のように伝えます：

Run the server and verify it starts correctly on port 3000.

OpenCodeは npx nodemon src/index.ts を実行し、サーバーがリッスンしていることを確認します。Server running on http://localhost:3000 のような出力が表示されるはずです。

何が起きたのか（機能：Buildモード）

BuildモードはOpenCodeのデフォルトエージェントです。ファイル読み書き、ターミナル実行、コード編集といったすべてのツールにアクセスできます。OpenCode documentationによると、開発環境にフルアクセスできるAIペアプログラマーと考えることができます。

フェーズ 3：データモデルとデータベースの作成（4分）

スキーマの設計

次のプロンプトを入力します：

Create a database module at src/db.ts that:
1. Initializes a SQLite database at ./data/bookmarks.db
2. Creates a bookmarks table with: id (auto-increment), url (text, unique),
   title (text), description (text, nullable), created_at (datetime),
   updated_at (datetime)
3. Creates a tags table with: id (auto-increment), name (text, unique)
4. Creates a bookmark_tags junction table for many-to-many relationships
5. Enables WAL mode for concurrent read performance
6. Creates an FTS5 virtual table for full-text search on title and description
Export a function to get the database instance.

OpenCodeは完全なデータベースモジュールを生成します。FTS5（Full-Text Search 5）のセットアップをどのように処理するかに注目してください。これは、後ほど検索機能を実現するためのSQLiteの機能です。

サーバー起動時のデータベース初期化

Import the database module in index.ts and initialize it when the server starts.
Log a confirmation message.

opencode.json設定の作成

ここでプロジェクト設定を導入しましょう。OpenCodeに伝えてファイルを作成します：

Create an opencode.json file in the project root with the project name
"bookmark-manager" and a rule that says "This is a TypeScript Express API
using better-sqlite3. Follow RESTful conventions. Use async/await. Return
JSON responses with consistent error formatting."

これにより、OpenCodeが起動時に読み込むプロジェクト設定ファイルが作成されます。これにより、AIにプロジェクトの永続的なコンテキスト（コーディング標準、アーキテクチャの決定、制約など）を与えることができ、プロンプトごとに繰り返す必要がなくなります。

フェーズ 4：REST APIエンドポイントの構築（5分）

ルートの生成

Create a routes module at src/routes/bookmarks.ts with these endpoints:
- POST /api/bookmarks — create a bookmark (validate url and title are present)
- GET /api/bookmarks — list all bookmarks with pagination (page, limit params)
- GET /api/bookmarks/:id — get a single bookmark with its tags
- PUT /api/bookmarks/:id — update a bookmark
- DELETE /api/bookmarks/:id — delete a bookmark and its tag associations
Use proper HTTP status codes. Return JSON with a consistent shape:
{ success: boolean, data: any, error?: string }

ルートの登録

Import the bookmark routes in index.ts and register them. Also add
express.json() middleware and a global error handler.

curlによるテスト

Start the server, then create a test bookmark using curl:
curl -X POST http://localhost:3000/api/bookmarks \
  -H "Content-Type: application/json" \
  -d '{"url": "https://opencode.ai", "title": "OpenCode - AI Coding Agent"}'
Then fetch all bookmarks to verify it was saved.

OpenCodeはターミナルでこれらのコマンドを実行し、レスポンスを表示します。ここでツールの真価が発揮されます。ターミナルを離れることなく、AIが自身の作業を検証します。

フェーズ 5：FTS5による検索機能の追加（4分）

Planモードの導入

検索機能を構築する前に、Planモードを使用して実装を検討しましょう。モードを切り替えます：

/plan

これでPlanモードになりました。AIはコードを読み取って分析できますが、ファイルを変更することはできません。これは変更を加える前の計画作成に役立ちます。

Analyze my current database schema and FTS5 table. Plan how to implement a
search endpoint that queries the FTS5 table and returns bookmarks ranked by
relevance. Consider edge cases: empty queries, special characters, partial
matches.

OpenCodeはコードを調査し、計画を .opencode/plans/ に書き出し、ファイルに触れることなくそのアプローチを説明します。計画を読み、必要に応じて調整してから、元に戻ります：

/build

検索の実装

Based on the plan, implement a GET /api/bookmarks/search?q=query endpoint
that uses the FTS5 virtual table for full-text search. Include snippet
highlighting and relevance ranking. Handle edge cases from the plan.

検索のテスト

Create three more test bookmarks with different titles and descriptions,
then test the search endpoint with a query that should match two of them.

何が起きたのか（機能：Planモード）

Plan/Buildワークフローは、経験豊富な開発者が複雑なタスクでOpenCodeを使用する方法です。まず計画（Plan）し、アプローチを確認してから、構築（Build）します。計画ファイルは .opencode/plans/ に保存され、後で参照可能なため、Buildエージェントが使用できます。これにより、AIがその場で大きな構造的決定を下すのを防ぎます。

フェーズ 6：タグシステムの実装（4分）

タグエンドポイントの作成

Create a routes module at src/routes/tags.ts with:
- POST /api/tags — create a new tag
- GET /api/tags — list all tags with bookmark counts
- POST /api/bookmarks/:id/tags — add a tag to a bookmark
- DELETE /api/bookmarks/:id/tags/:tagId — remove a tag from a bookmark
- GET /api/bookmarks?tag=tagname — filter bookmarks by tag (update existing
  list endpoint to support this query parameter)
Register the tag routes in index.ts.

タグフローのテスト

Create two tags: "dev-tools" and "tutorials". Add the "dev-tools" tag to
the OpenCode bookmark. Then fetch bookmarks filtered by the "dev-tools" tag.

フェーズ 7：シンプルなフロントエンドの構築（5分）

フロントエンドの生成

Create a public/ directory with a single-page frontend:
- index.html with a clean, minimal design (no framework, just HTML/CSS/JS)
- A form to add bookmarks (url, title, description)
- A search bar that queries the search endpoint with debounced input
- A list of bookmarks showing title, url, tags, and a delete button
- A tag filter sidebar that shows all tags with counts
- Use fetch() for API calls. Mobile responsive. No build step needed.
Serve the public/ directory as static files from Express.

OpenCodeは、HTML構造、CSSスタイリング、APIインタラクション用のJavaScriptを含む完全なフロントエンドを一括で生成します。ターミナルでAIエージェントを使用して構築する利点は、フロントエンドがAPIに接続されているかどうかを即座にテストできることです。

フルスタックのテスト

Start the server, open http://localhost:3000 in a description, and verify
that adding a bookmark from the form, searching, and filtering by tag all
work correctly.

フェーズ 8：テストの追加とカスタムエージェント（5分）

カスタムテストエージェントの作成

ここでOpenCodeのカスタムエージェント機能の出番です。テストに汎用的なBuildエージェントを使用する代わりに、特化したエージェントを作成します。

opencode.json に以下を追加します：

{
  "agents": {
    "test": {
      "name": "Test Writer",
      "instructions": "You are a testing specialist. Write comprehensive tests using Vitest. Focus on edge cases and error paths. Never modify source code — only create and edit test files.",
      "tools": ["read", "write", "terminal"]
    }
  }
}

では、テストエージェントに切り替えます：

/agent test

テストの生成

Write comprehensive tests for the bookmark API using Vitest and supertest.
Cover:
- Creating a bookmark with valid data
- Creating a bookmark with missing required fields
- Fetching all bookmarks with pagination
- Searching with FTS5 (matching and non-matching queries)
- Adding and removing tags
- Deleting a bookmark removes its tag associations
Use an in-memory SQLite database for test isolation.

テストの実行

Install vitest and supertest as dev dependencies, add a test script to
package.json, then run the test suite.

何が起きたのか（機能：カスタムエージェント）

カスタムエージェントを使用すると、特定の指示とツールアクセス権を持つ特化したペルソナを作成できます。作成したテストエージェントは、ファイルの読み取り、テストファイルの書き込み、ターミナルコマンドの実行のみが可能で、ソースコードの変更はできません。この制約により、テストが失敗したときにAIがテストを修正するのではなく、ソースコードを修正してしまうというよくある問題を防ぐことができます。

コードレビュー、ドキュメント作成、データベースマイグレーション、DevOpsスクリプトなど、あらゆる専門ワークフロー向けのエージェントを作成できます。OpenCode agents documentationにはさらなる例があります。

ボーナス：機能拡張のためのMCPサーバーの接続

ブックマークマネージャーを拡張したい場合は、MCP (Model Context Protocol)サーバーを介して外部ツールを接続できます。

例：Link Preview MCPサーバーの追加

ブックマーク作成時に、OpenCodeが自動的にURLからメタデータ（タイトル、説明、ファビコン）を取得するようにしたいとします。HTTP取得を行うMCPサーバーを接続できます：

opencode.json に以下を追加します：

{
  "mcp": {
    "link-preview": {
      "type": "local",
      "command": ["npx", "link-preview-mcp-server"]
    }
  }
}

これでOpenCodeに新しいツールが追加されました。ワークフローの一部としてURLのメタデータを取得できるようになります。「https://example.com のブックマークを追加し、タイトルと説明を自動入力して」と頼むと、MCPサーバーを使用してそのデータを取得します。

リモートMCPサーバー

クラウドサービスの場合は、自動OAuth処理を備えたリモートMCPサーバーを使用します：

{
  "mcp": {
    "cloud-storage": {
      "type": "remote",
      "url": "https://mcp.example.com/storage",
      "headers": {
        "Authorization": "Bearer ${STORAGE_TOKEN}"
      }
    }
  }
}

OpenCodeは401レスポンスを検出し、サーバーがDynamic Client Registrationをサポートしている場合は自動的にOAuthフローを開始します。

ボーナス：CI/CDでのOpenCodeの使用

OpenCodeにはTUIなしで動作するCLIモードがあり、自動化に最適です。GitHub Actionsや任意のCIパイプラインで使用できます：

# 単一のプロンプトを実行して終了
opencode -p "Review the changes in the last commit for security issues" --no-tui

# 特定のモデルを使用
opencode -m "claude-sonnet-4-6" -p "Generate a changelog entry for this release" --no-tui

ブックマークマネージャーの場合、PRを自動的にレビューするためにOpenCodeを実行するCIステップを追加できます。OpenCode GitHub integrationは、このワークフローのより合理化されたバージョンを提供します。

完全なプロジェクト構成

このチュートリアルに従うと、プロジェクトは次のようになります：

bookmark-manager/
  opencode.json          # OpenCode プロジェクト設定 + カスタムエージェント + MCP
  package.json
  tsconfig.json
  src/
    index.ts             # Express サーバーエントリーポイント
    db.ts                # FTS5 を含む SQLite データベースモジュール
    routes/
      bookmarks.ts       # CRUD + 検索エンドポイント
      tags.ts            # タグ管理エンドポイント
  public/
    index.html           # シングルページフロントエンド
  tests/
    bookmarks.test.ts    # API テストスイート
  data/
    bookmarks.db         # SQLite データベース (gitignored)
  .opencode/
    plans/               # Plan モードセッションからの計画

学んだこと

実際のプロジェクトを構築することで、以下のOpenCode機能を実践しました：

OpenCodeと他のAIコーディングツールの主な違いは、完全にオープンソースであり、ターミナルで動作し、コードやコンテキストデータを保存しないことです。モデルを制御し、データはローカルに留まり、800人以上のコントリビューターからなるコミュニティが急速な進化を支えています。

複数のAIツールを使用しているチームにとって、OpenCodeはIDEアシスタントを補完するターミナルベースのツールとして適しています。ZBuildでは、開発ワークフローの異なる部分でエディタベースのツールと併用することがよくあります。

次のステップ

機能するブックマークマネージャーが完成し、OpenCodeをしっかりと理解できたところで、さらに探索すべき方向性をいくつか紹介します：

1. 認証の追加 — Buildエージェントを使用して、ユーザーアカウントによるJWTベースの認証を追加する
2. 本番環境へのデプロイ — OpenCodeにDockerfileの生成を依頼し、Fly.ioやRailwayにデプロイする
3. ブラウザ拡張機能の構築 — API経由でブックマークを追加するChrome拡張機能を作成する
4. より多くのZenモデルの探索 — Big Pickle, MiniMax M2.1を試すか、Ollamaを通じてローカルモデルを実行する
5. さらなるカスタムエージェントの作成 — 「リファクタリング」エージェント、「ドキュメント」エージェント、または「セキュリティ監査」エージェント

OpenCode documentationやawesome-opencode repositoryには、さらに多くのプラグイン、テーマ、コミュニティ設定が用意されています。

情報源

• OpenCode — Official Documentation
• OpenCode — GitHub Repository
• OpenCode — Zen Models
• OpenCode — Agents Documentation
• OpenCode — MCP Servers
• OpenCode — CLI Mode
• OpenCode — Configuration
• OpenCode — GitHub Integration
• Ollama — OpenCode Integration
• awesome-opencode — Community Resources
• Composio — MCP with OpenCode
• Computing for Geeks — Setup OpenCode AI