Opencode Docs로 배우는 AI 에이전트 설계의 7가지 빌딩 블록

Opencode가 Claude Code 다음으로 개발자들 사이에서 주목받고 있습니다. Oh-my-opencode 덕분에 한국에서도 빠르게 퍼지고 있고요.

그런데 이 도구의 진짜 가치는 코딩 지원만이 아닙니다. 오픈 소스라서 에이전트가 어떻게 설계되는지 직접 뜯어볼 수 있거든요. 오픈 소스는 다양한 개발자 분들이 참여하여 가장 최신의 내용을 반영할 수 있는 시스템이기도 합니다.

Opencode docs의 Configure 섹션 문서들이 에이전트 아키텍처 입문 교재로 딱입니다. 7가지 핵심 빌딩 블록과 각각이 중요한 이유를 정리합니다.

Tools: 에이전트가 세상과 상호작용하는 방식

에이전트가 할 수 있는 일을 정의하는 영역입니다. 각 도구는 파일 읽기, 파일 쓰기, 터미널 명령 실행, 웹 검색 같은 개별 기능이며, 호출 가능한 함수로 등록됩니다.

• 어떤 도구를 제공하느냐에 따라 에이전트의 능력 범위가 결정됩니다
• 도구는 언어 모델과 외부 환경 사이의 인터페이스입니다
• 직접 사용해 보니, 도구를 너무 많이 주면 오히려 역효과가 납니다. 어떤 도구를 쓸지 고르느라 실행보다 결정에 시간을 더 쓰게 됩니다

설계 원칙은 단순합니다. 도구 없는 에이전트는 그냥 챗봇입니다. 적절한 도구를 갖춘 에이전트가 자율적 작업자가 됩니다.

Rules (AGENTS.md): 에이전트의 행동 원칙

AGENTS.md는 프로젝트별 맥락과 제약 조건을 에이전트에게 전달하는 파일 형식입니다. 사람이 아닌 AI를 위해 작성된 README라고 보면 됩니다.

• “테스트 없이 코드 수정 금지”, “이 폴더 구조를 따를 것” 같은 지침을 담습니다
• AGENTS.md 표준은 이미 6만 개 이상의 오픈소스 프로젝트에서 채택하고 있습니다
• 규칙은 기본 모델을 바꾸지 않으면서 에이전트의 의사결정을 형성합니다

규칙이 없으면 에이전트가 범용 학습 내용을 여러분의 프로젝트에 그대로 적용합니다. 규칙이 있으면 프로젝트의 관례, 제약, 선호도를 반영합니다. 차이가 상당합니다.

Agents (서브에이전트): 나눠서 정복하기

복잡한 작업은 하나의 범용 에이전트가 아니라 여러 전문 에이전트로 분할하는 것이 효과적입니다.

• Build, Plan, Review, Debug 등 역할별 에이전트를 정의할 수 있습니다
• 메인 에이전트가 계획을 세우고, 서브에이전트가 개별 단계를 실행합니다
• 각 서브에이전트는 집중된 컨텍스트로 작동하여, 긴 단일 세션에서 생기는 노이즈와 드리프트를 줄입니다

마이크로서비스의 원리를 AI 워크플로우에 적용한 것과 같습니다. 전문화가 품질을 높이고, 격리가 컨텍스트 오염을 방지합니다.

MCP (Model Context Protocol): 외부 연결의 표준

Model Context Protocol은 Anthropic이 만든 오픈 프로토콜로, 에이전트가 외부 데이터 소스 및 서비스에 연결하는 방식을 표준화합니다.

• 데이터베이스, 파일 시스템, API 및 기타 통합을 위한 일관된 인터페이스를 제공합니다
• 각 서비스마다 커스텀 어댑터를 작성하는 대신, MCP가 에이전트에게 통합된 외부 접근 방식을 제공합니다
• MCP 레이어 위에 다양한 서비스 애플리케이션 생태계가 성장할 것으로 예상됩니다

MCP는 실질적인 상호운용성 문제를 해결합니다. 이전에는 모든 에이전트 프레임워크가 외부 도구에 연결하는 고유한 방식을 개발했습니다. MCP는 이러한 연결을 이식 가능하고 조합 가능하게 만듭니다.

LSP (Language Server Protocol): 코드 이해의 기반

Language Server Protocol은 원래 IDE용으로 설계되었지만, 코드베이스를 탐색해야 하는 AI 에이전트에게도 동일하게 가치 있는 것으로 드러났습니다.

• LSP는 정의로 이동, 참조 찾기, 자동완성, 진단 기능을 제공합니다
• Opencode에서 LSP 통합은 아직 실험 기능이지만, 코드 탐색 정확도가 크게 향상됩니다
• 순수 텍스트 검색에 의존하는 대신, 에이전트가 LSP를 사용해 코드 구조를 의미적으로 이해할 수 있습니다

함수 호출을 정의까지 추적하고, 모든 참조를 찾고, 타입 계층을 이해하는 에이전트는 문자열 패턴 매칭만 하는 에이전트와 근본적으로 다른 수준에서 작동합니다.

A2A와 ACP: 에이전트 간 통신 표준

서로 다른 프레임워크로 만든 에이전트들이 협업하려면 공통 프로토콜이 필요합니다. 이 격차를 메우기 위해 두 가지 표준이 부상하고 있습니다.

• A2A (Agent-to-Agent): Google이 만들고 Linux Foundation에 기부했습니다. 에이전트가 서로를 발견하고, 역량을 협상하고, 메시지를 교환하는 방식을 정의합니다
• ACP (Agent Communication Protocol): BeeAI 팀이 구축했으며, 최근 A2A 노력에 합류했습니다

둘 다 초기 단계이지만, 서로 다른 벤더와 프레임워크의 에이전트가 원활하게 협업하는 멀티 에이전트 시스템의 기반을 대표합니다. 비유하자면 웹의 HTTP - 모든 것을 상호운용 가능하게 만드는 공유 전송 레이어입니다.

Skills: 재사용 가능한 능력 패키지

Agent Skills는 도구, 규칙, 프롬프트를 하나의 설치 가능한 단위로 묶습니다. Anthropic이 처음 도입한 이 형식은 이제 표준화되었습니다.

• 에이전트는 코드 리뷰, TDD 워크플로우, 보안 분석 같은 특정 역량이 필요할 때 스킬을 로드합니다
• 스킬은 프로젝트와 팀 간에 공유 가능하여 재사용 가능한 에이전트 행동 생태계를 만듭니다
• 이는 문서를 소비하는 것에서 스킬을 소비하는 것으로의 전환을 의미합니다. 방법을 읽는 대신 능력을 설치하는 시대입니다

스킬은 에이전트에게 패키지가 애플리케이션에게인 것과 같습니다. 전문성을 모듈화하고 배포 가능하게 만듭니다.

핵심 정리

효과적인 AI 에이전트를 만드는 것은 사용 가능한 모든 도구를 아는 것이 아닙니다. 아키텍처를 이해하는 것입니다. 에이전트가 어떻게 생각하고, 외부 세계와 어떻게 연결되고, 서로 어떻게 협업하는지 구조를 이해하는 것입니다.

이 7가지 빌딩 블록 - Tools, Rules, 서브에이전트, MCP, LSP, A2A/ACP, Skills - 이 에이전트 설계의 구조적 어휘를 형성합니다. 각각이 고유한 관심사를 다루며, 함께 잘 설계된 에이전트 시스템의 모습을 정의합니다.

Opencode는 오픈 소스이기 때문에 문서가 개발자 커뮤니티의 기여와 함께 진화합니다. 에이전트 아키텍처를 제대로 이해하고 싶다면, Opencode docs를 읽어볼 가치가 있습니다.