소스 코드 학습 경로

이것은 OpenCode 소스 코드의 가이드 코스입니다. 아래 8 개 모듈은 보텀업 순서로 정렬되어 있습니다: 기초(설정, 프로바이더, 권한)로 시작해 통합층(MCP, LSP), 코어 엔진(Agent), 마지막으로 사용자 대상 인터페이스(Command, CLI)로 끝납니다.

각 장은 하나의 모듈 아키텍처, 타입, 코어 흐름, 설계 트레이드오프 심층 분석(3000-4000 자)입니다. 순서대로 읽으면 완전한 멘탈 모델을 얻을 수 있고, 필요한 모듈만 건너뛰어 읽을 수도 있습니다.

필수 스킬

소스 코드를 읽기 전, 다음에 익숙한지 확인하세요:

스킬	중요도	이유
TypeScript	필수	코드베이스가 완전히 타입화되어 있으며, 타입이 주요 문서입니다
Promises / async-await	필수	거의 모든 것이 비동기입니다(LLM 스트림, 파일 I/O, 도구 실행)
Node.js streams	중요	LLM 응답과 세션 이벤트는 스트림입니다
Git / 터미널	도움됨	저장소를 클론하고 로컬에서 디버그합니다
React / Vue	불필요	TUI 는 웹 프레임워크가 아닙니다. 프론트엔드 스킬이 필요 없습니다

소요 시간

목표	시간	학습 후 할 수 있는 것
1 모듈 이해	~30 분	1 장을 읽고 그 모듈이 무엇을 하는지 설명
전체 요청 추적	~1 주	prompt 가 CLI → Session → Agent → Provider → Tool → 응답으로 흐르는 과정 추적
기능 변경	~1 개월	어떤 동작(예: 새 권한 규칙)을 변경하고 작동하게 함
확장 작성	1-3 개월	플러그인, 커스텀 도구, 코어 기여

8 개 챕터 (순서대로)

기초 — 토대

Config · 초급 · ~25 분 설정 로딩: 6 계층 우선순위, Zod 스키마, JSONC 파싱, 핫 리로드. 여기서 시작하세요. 다른 모든 모듈이 설정에 의존합니다.
Provider · 초급 · ~20 분 모델 추상화 계층: OpenCode 가 Vercel AI SDK 로 75 개 이상 LLM 에 프로바이더별 HTTP 클라이언트 없이 통신하는 방법.
Permission · 중급 · ~25 분 안전 게이트: 3 단계 결정(허용/거부/확인), 와일드카드 매칭, 연쇄 거부, 일괄 승인.

통합 — 외부 프로토콜

MCP · 중급 · ~25 분 외부 도구 채널: 3 종 전송, OAuth 2.0 + PKCE, MCP 도구가 AI SDK 동적 도구가 되는 방법.
LSP · 중급 · ~25 분 IDE 급 코드 이해: Effect Service 아키텍처, 30 개 이상 언어 서버 정의, 진단.

코어 — 엔진

Agent · 고급 · ~30 분 설정과 실행의 분리: Agent 는 설정 정의, Session 이 루프 구동. 동시성 제어, 에러 처리, 상태 관리.

인터페이스 — 사용자가 접하는 입구

Command · 고급 · ~20 분 명령은 함수가 아닌 설정: 4 개 소스(내장, Config, MCP 프롬프트, Skills), 템플릿 기반 실행.
CLI · 고급 · ~25 분 진입점: Yargs 명령 트리, 듀얼 모드 설계(TUI worker vs 비대화형 run), SSE 이벤트 브릿지.

어디서 시작할까

코드베이스가 처음이라면: Config 부터 시작.

prompt 가 코드 편집이 되는 과정을 이해하고 싶다면: Agent 로 이동해 콜 체인을 역추적하세요.

새 도구로 OpenCode 를 확장하고 싶다면: MCP 와 Command 를 읽으세요.