OpenCode로 30분 만에 Full-Stack Bookmark Manager 만들기 (단계별 가이드)

우리가 만들 것

기능 목록은 잊어버리세요. 도구를 배우는 가장 좋은 방법은 그것으로 무언가를 직접 만들어보는 것입니다.

이 튜토리얼에서는 120,000개 이상의 GitHub 스타를 보유한 오픈 소스 AI 코딩 에이전트인 OpenCode를 사용하여 처음부터 완벽한 북마크 관리자를 구축해 보겠습니다. 이 앱은 다음과 같은 기능을 갖추게 됩니다:

• Express.js 및 TypeScript를 사용한 REST API
• 전체 텍스트 검색 기능이 포함된 SQLite 데이터베이스
• 북마크 정리를 위한 태그 시스템
• 심플하지만 기능적인 프런트엔드
• 단위 테스트

모든 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에서 모델을 선택하라는 메시지가 표시됩니다. 세 가지 경로가 있습니다:

무료 (Zen 모델): /models를 입력하고 무료 Zen 모델 중 하나를 선택하세요. 이 튜토리얼에서는 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가 시작될 때 읽는 project configuration file을 생성합니다. 이를 통해 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를 사용하는 방식입니다. 먼저 계획을 세우고, 접근 방식을 검토한 다음 구축합니다. 계획 파일은 .opencode/plans/에 저장되며 나중에 참조할 수 있습니다. 이를 통해 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의 custom agents 기능이 등장합니다. 테스트를 위해 일반적인 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) 서버를 통해 외부 도구를 연결할 수 있습니다.

예시: 링크 프리뷰 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 mode가 있어 자동화에 적합합니다. 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