OpenCode v2 활용법: 인터뷰 메모를 검색하는 나만의 앱 만들기

고객 인터뷰 메모가 열 개만 넘어가도 “그때 누가 이 말을 했지?”를 찾는 데 시간이 듭니다. 문서를 더 잘 정리하는 방법도 있지만, 메모를 검색하고 태그로 모으며 원문까지 열 수 있는 작은 앱을 만들 수도 있습니다. OpenCode는 이런 작업을 내 컴퓨터의 폴더에서 진행하는 코딩 에이전트입니다. 모델을 연결하면 파일을 읽고 코드를 만들고 실행 명령을 사용할 수 있습니다.

이번 작업은 인터뷰 보관함입니다. 목록과 검색, 태그 필터, 원문 상세 화면, 새 메모 입력을 만들고 새로고침해도 추가한 메모가 남도록 요청했습니다. 2026년 10월 5일 OpenCode v2에서 실제로 파일을 생성한 뒤, 브라우저에서 검색과 저장을 눌러봤습니다. 입력은 가상의 인터뷰 두 건입니다.

OpenCode로 만든 인터뷰 보관함부터 열어보세요

처음에는 강사 A·B의 메모 두 건이 보였습니다. 검색창에 ‘파일’을 입력하니 A의 메모 한 건이 남았고, 그 상태에서 ‘일정’ 태그를 누르자 두 조건을 동시에 만족하는 메모가 없어 결과 없음 안내가 나왔습니다. 검색과 태그 초기화 버튼을 누르면 다시 두 건으로 돌아왔습니다.

새 메모에는 강사 C라는 가명과 “지난 수업의 자료를 찾느라 같은 폴더를 두 번 열었어요”라는 가상 발언을 넣었습니다. 저장 직후 목록은 세 건이 됐고, 새로고침 후에도 C의 메모가 남았습니다. JSON 내보내기로 내려받은 파일을 열어 세 객체가 들어 있는 것까지 확인했습니다. 팀 계정이나 서버 저장소는 아직 없는 개인용 페이지입니다.

OpenCode를 고를 이유가 있는 작업

OpenCode v2는 터미널, 데스크톱 앱, 웹 앱으로 작업할 수 있고 여러 모델 공급자를 연결합니다. 이미 익숙한 편집기가 있고 결과를 내 폴더에 남기고 싶다면 살펴볼 만합니다. 모델을 바꿔도 프로젝트 파일과 작업 규칙을 같은 곳에서 관리할 수 있다는 점이 이 글의 선택 이유입니다. 터미널에서 시작한 뒤 opencode pair가 안내하는 접속 주소로 웹 화면을 연결할 수도 있습니다.

개발 환경을 전혀 만지고 싶지 않고 브라우저에서 바로 공개 주소까지 받고 싶다면, 설치와 배포를 함께 제공하는 제작 서비스가 시작하기 편할 수 있습니다. 반대로 내 자료를 바탕으로 작은 기능을 고치거나, 이미 만든 프로젝트에 검색 기능을 더하거나, 같은 작업을 특정 규칙으로 반복하려면 폴더 기반 에이전트가 편합니다. 여기서는 서버 운영까지 넓히지 않고 개인용 프로토타입 하나를 끝냅니다.

앱이 어떻게 보여야 하는지부터 적습니다

첫 요청에 “인터뷰 관리 SaaS를 만들어줘”만 넣으면 로그인, 팀 관리, 구독 결제처럼 당장 쓰지 않을 화면까지 붙을 수 있습니다. 일단 한 사람이 자기 브라우저에서 쓰는 앱으로 정합니다. 수십 개의 메모를 보면서 태그를 고르고 특정 문장으로 검색하는 상황을 설명하세요. 버튼 색보다 검색했을 때 무엇이 남고 무엇이 사라져야 하는지 먼저 정해야 합니다.

저장은 브라우저 안의 로컬 데이터로 시작합니다. 이 선택 덕분에 처음부터 회원 계정이나 데이터베이스를 준비하지 않아도 됩니다. 대신 다른 기기와 자동으로 동기화되지 않고, 브라우저 데이터를 지우면 사라질 수 있습니다. 그래서 내보내기 기능을 같은 첫 버전에 넣습니다. 이 제한이 괜찮은지 판단하는 것도 제품 기획의 일부입니다.

[
  {
    "id": "i-001",
    "person": "강사 A",
    "date": "2026-10-01",
    "tags": ["과제 전달", "파일 찾기"],
    "quote": "이름이 비슷해서 열어봐야 어떤 학생 파일인지 알아요.",
    "note": "메신저 검색으로 최근 과제를 찾는 장면을 관찰했다."
  },
  {
    "id": "i-002",
    "person": "강사 B",
    "date": "2026-10-02",
    "tags": ["일정", "학부모 연락"],
    "quote": "변경된 수업 시간을 여러 사람에게 다시 알려줘요.",
    "note": "같은 내용을 각각의 대화방에 보냈다."
  }
]

프로젝트 폴더에서 모델을 연결합니다

macOS나 Linux에서 Node.js와 npm을 쓴다면 아래 명령으로 v2를 설치할 수 있습니다. 이 글은 확인한 2.0.22를 명시합니다. 공식 문서에는 Homebrew와 직접 다운로드 방법도 있습니다. Windows는 v2 문서에서 Windows용 파일을 골라 설치하세요. 확인일 기준 Windows의 패키지 매니저 설치는 아직 지원하지 않는다고 안내돼 있습니다. v1이 이미 설치돼 있다면 두 버전이 같은 opencode 명령을 쓰므로 공식 이전 안내부터 읽습니다.

npm install -g @opencode/cli@2.0.22
mkdir interview-shelf
cd interview-shelf
opencode

/connect
/models

/connect에서는 사용할 공급자를 선택하고 그 공급자의 인증 절차를 따릅니다. API 키는 OpenCode가 요구하는 인증 입력란에 넣습니다. 앱에 넣을 sample-interviews.json이나 AGENTS.md에 키를 적지 않습니다. /models로 연결된 모델을 고른 뒤 짧은 질문에 응답하는지 확인하면, 뒤에서 생긴 오류가 인증 문제인지 코드 문제인지 나누기 쉽습니다.

AGENTS.md에 이번 프로젝트의 규칙을 남깁니다

프로젝트 폴더에 AGENTS.md를 만들고 이번 앱의 범위와 데이터 규칙을 적습니다. 편집기로 직접 저장하거나 OpenCode에 아래 내용으로 파일을 만들어 달라고 요청할 수 있습니다. v2는 AGENTS.md를 프로젝트 지침으로 읽습니다. 인터뷰 데이터를 정리하는 규칙과 앱을 만드는 규칙을 남겨두면 다음 대화에서 기능을 추가할 때 같은 설명을 반복할 일이 줄어듭니다. CLAUDE.md만 있는 프로젝트라면 v2에서는 AGENTS.md도 준비해야 합니다.

# Interview Shelf

## 목적
혼자 인터뷰 메모를 찾고 분류하는 브라우저 앱.
화면과 오류 안내는 한국어로 작성한다.

## 이번 버전
목록, 검색, 태그 필터, 상세 화면, 메모 추가, JSON 내보내기를 만든다.
새로고침해도 추가한 메모가 같은 브라우저에 남아야 한다.
입력 샘플은 sample-interviews.json을 사용한다.

## 데이터
quote는 실제 발언 칸, note는 작성자 메모 칸이다. 두 값을 합치지 않는다.
실명·전화번호가 없는 가상 데이터로 화면을 만든다.
현재 폴더 밖의 파일은 작업 대상으로 삼지 않는다.

## 완성 기준
검색과 태그를 함께 적용해도 동작한다.
검색 결과가 없거나 메모가 비어 있을 때도 화면이 있다.
오류가 나면 재현한 입력과 수정한 파일을 기록한다.

기획을 맡는 에이전트와 구현 요청을 연결합니다

OpenCode에는 기본 Build와 Plan 에이전트가 있고, 역할을 직접 정의할 수도 있습니다. 이번에는 product-planner라는 작은 보조 에이전트를 만듭니다. 할 일은 입력 데이터에서 빠진 항목과 화면 상태를 찾아 주는 것입니다. 코드 작성은 주 대화의 Build가 이어받습니다. 사람마다 역할 이름을 멋지게 늘리기보다, 서로 다른 결과가 필요한 작업만 나누면 대화가 덜 복잡해집니다.

---
description: 작은 개인용 앱의 입력 데이터와 화면 상태를 구체화한다. 인터뷰 보관함 기능을 정할 때 사용한다.
mode: subagent
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: shell
    resource: "*"
    effect: deny
---

AGENTS.md와 sample-interviews.json을 읽는다.
사용자가 메모 하나를 찾는 과정을 기준으로 화면 상태를 제안한다.
첫 버전에서 꼭 필요한 기능과 다음 버전으로 미룰 기능을 구분한다.
결과는 데이터 항목, 화면 상태, 빠진 질문으로 작성한다.
이 에이전트는 파일을 만들거나 실행 명령을 사용하지 않는다.

product-planner 하위 에이전트를 사용해서 인터뷰 보관함의 첫 버전 범위를 정리해줘. 검색어와 태그를 같이 썼을 때, 메모가 없을 때, 새 메모 저장이 실패했을 때의 화면도 포함해줘.

보조 에이전트가 제안한 내용을 그대로 전부 구현할 필요는 없습니다. 예를 들어 팀 초대가 추가됐다면 “개인용이므로 빼고 JSON 내보내기는 유지”처럼 범위를 고칩니다. Build에 넘기는 요청에는 실제로 고른 범위를 붙입니다. 분업의 효과는 에이전트 숫자보다 입력과 다음 작업이 얼마나 정확하게 이어지는지에 달려 있습니다.

AGENTS.md와 sample-interviews.json을 바탕으로 인터뷰 보관함을 구현해줘.

목록 카드, 검색과 태그 필터, 원문 상세, 새 메모 입력, JSON 내보내기를 만든다.
브라우저 로컬 저장을 사용하고, 불러오기·검색 결과 없음·입력 오류 상태도 구현한다.
quote와 note는 상세 화면에서 시각적으로 구분해줘.

필요한 파일과 실행 스크립트를 만들고 실제로 실행 가능한지 확인해줘.
완료하면 접속 주소, 실행한 확인 명령, 아직 연결하지 않은 기능을 알려줘.
화면을 직접 열어볼 수 없으면 그 사실을 밝히고 확인한 범위만 적어줘.

파일이 만들어진 실제 OpenCode 세션

실행에는 파일 읽기와 편집만 허용했습니다. 기록에는 AGENTS.md·샘플 JSON을 읽은 도구 호출과 index.html·open-app.sh·README.md를 추가한 patch 완료가 남았습니다. product-planner 하위 에이전트도 준비했지만 이 실행에서는 호출하지 않았습니다. 설정 파일을 만들었다는 사실만으로 분업이 실제 이루어졌다고 설명하면 안 됩니다.

처음 시도한 무료 모델은 짧은 응답에는 성공했지만 실제 앱 생성 요청에서 403 오류를 반환했습니다. 그래서 OpenCode가 제공하는 공식 OAuth 연결을 이용해 모델을 바꿨습니다. 앱 파일 생성은 끝났지만, 최종 설명을 기다리는 도중 설정해 둔 240초 실행 제한에 도달해 세션이 종료됐습니다. 완료 문장 대신 실제 저장된 파일과 patch 기록을 확인하고, 앱 동작은 별도 브라우저에서 시험했습니다. 무료 모델이나 연결 상태가 항상 같다고 가정하지 말고 자신에게 실제 표시되는 모델을 선택하세요.

명령 실행과 화면 확인은 실제 연결된 도구에 달려 있습니다

앱 파일을 만들 수 있다는 것과 브라우저 화면을 직접 볼 수 있다는 것은 다른 기능입니다. 에이전트가 개발 서버를 실행했다면 안내한 로컬 주소를 브라우저에서 엽니다. 화면을 다룰 브라우저 MCP가 연결돼 있다면 실제 클릭과 스크린샷까지 요청할 수 있지만, MCP 서버를 이름만 적었다고 연결되는 것은 아닙니다. 이 예제의 첫 실행은 독자가 직접 브라우저를 열어보는 것으로도 충분합니다.

검색어에 “파일”을 입력했을 때 첫 번째 샘플만 남는지, “일정” 태그를 함께 고르면 결과 없음 화면이 나오는지 확인합니다. 새 메모를 추가한 다음 새로고침하고, 내보낸 JSON에 새 항목이 들어 있는지도 봅니다. “버튼이 안 돼요”보다 “메모를 추가하면 목록에는 나오지만 새로고침 뒤 사라져요”라고 전달하면 저장 경로를 고치는 작업으로 바로 이어집니다.

명령 실행 범위는 프로젝트의 opencode.json에서 정합니다. 아래 예제는 파일 편집을 허용하고 셸 명령은 확인하는 구성입니다. v2의 기본 형식은 permissions 배열이며 실행 명령의 action은 shell입니다. shell을 전부 막으면 패키지 설치나 개발 서버 실행도 막힙니다. AGENTS.md에 적은 작업 규칙과 실제 도구 권한은 서로 다르므로, 필요한 동작에 맞춰 둘 다 설정합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "edit", "resource": "*", "effect": "allow" },
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "external_directory", "resource": "*", "effect": "deny" }
  ]
}

이번 결과에서 직접 확인한 것은 검색, 검색과 태그의 교차 조건, 메모 추가, 새로고침 뒤 저장 유지, JSON 다운로드입니다. 모바일 배치와 저장소 용량 초과 상태는 따로 시험하지 않았습니다. 아래의 인터뷰 가져오기 스킬과 MCP 연결은 다음 단계의 설정 예제이며, 이번 생성 세션에서 작동시킨 기능은 아닙니다.

두 번째 인터뷰부터는 가져오기 규칙을 스킬로 묶습니다

첫 버전이 뜨면 다음 문제는 메모 형식입니다. 사람마다 날짜를 다르게 쓰고 태그를 쉼표나 줄바꿈으로 구분합니다. 매번 그 차이를 설명하는 대신 interview-import라는 스킬에 앱이 받는 JSON 형식을 적어둘 수 있습니다. OpenCode에서는 .opencode/skills/interview-import/SKILL.md로 시작하면 됩니다. 이 스킬은 앱 코드를 바꾸는 용도가 아니라 새로운 메모를 같은 입력 형식으로 정리하는 용도입니다.

---
name: interview-import
description: 인터뷰 메모를 Interview Shelf에서 가져올 JSON으로 정리한다. 새 인터뷰 파일을 앱에 추가할 때 사용한다.
---

앱의 데이터 형식과 사용자가 지정한 메모를 읽는다.
id, person, date, tags, quote, note 항목으로 JSON 배열을 만든다.
quote는 원문 발언을 보존하고 작성자의 해석은 note에 넣는다.
날짜나 화자를 알 수 없으면 임의로 만들지 말고 부족한 항목을 알려준다.
출력은 imports/ 아래 새 JSON 파일에 저장한다.

스킬로 만든 JSON을 앱에서 읽으려면 앱에도 JSON 가져오기 기능이 있어야 합니다. 에이전트가 파일을 만들었다는 이유만으로 화면에 자동 반영되지는 않습니다. 첫 버전의 내보내기 기능과 같은 형식을 사용하도록 가져오기 화면을 추가해 달라고 요청하면, 메모 정리와 제품 기능을 같은 데이터 구조로 연결할 수 있습니다. 스킬과 앱을 따로 설계할 때 자주 빠지는 부분입니다.

무료 도구와 모델 사용료를 나눠 계산합니다

OpenCode 소프트웨어 설치와 모델 호출의 비용은 구분해야 합니다. API 키를 연결했다면 선택한 공급자의 요금이 적용됩니다. OpenCode Console의 종량제 공급자를 쓰는 경우에는 공식 표의 모델별 입력·출력·캐시 단가를 봅니다. 포함된 사용량이 있는 OpenCode Go 구독도 별도로 제공됩니다. 무료로 표시되는 모델도 기간과 조건이 달라질 수 있으므로, 모든 작업이 계속 무료라고 계산하지 않습니다.

예산을 잡을 때는 “앱 하나에 얼마”보다 실제 호출량을 봅니다. 입력 100만 토큰 단가가 I, 출력 단가가 O인 모델에서 입력 20만·출력 4만 토큰을 썼다고 가정하면, 캐시나 다른 비용을 제외한 모델 비용은 0.2×I + 0.04×O입니다. 이 수치는 설명을 위한 가정이며 이번 앱의 측정 사용량이 아닙니다. 큰 자료를 매번 붙이거나 여러 에이전트가 같은 자료를 반복해서 읽으면 호출량도 늘어납니다.

개인용 앱을 다른 사람에게 배포하고 싶어지면 저장 방식을 다시 결정할 차례입니다. 지금 브라우저에 남은 메모를 서버로 옮길지, 계정을 어떻게 만들지, 다른 사람의 메모가 섞이지 않게 할지 정해야 합니다. 먼저 지금 만든 검색·태그·상세 흐름을 한 명이 실제로 사용해 보고, 계속 쓰게 된 기능을 기준으로 다음 버전을 요청하세요. 그때도 같은 프로젝트 폴더와 AGENTS.md에서 이어갈 수 있습니다.