OpenSpec 소개
OpenSpec은 AI 에이전트(Agent)의 행동, 도구 사용, 환경 설정 등을 정의하기 위한 오픈 표준 명세(Specification)입니다. 현재 AI 산업은 에이전트(Agentic AI) 시대로 빠르게 전환되고 있지만, 각 프레임워크(LangChain, Semantic Kernel 등)나 모델 제공자(OpenAI Assistants API, Anthropic 등)마다 에이전트를 정의하는 방식이 제각각입니다. 이로 인해 개발자들은 특정 벤더나 프레임워크에 종속(Lock-in)되는 문제가 발생하며, 한 번 작성한 에이전트 로직을 다른 환경으로 이식하기가 매우 어렵습니다.
OpenSpec은 이러한 파편화 문제를 해결하기 위해 등장했습니다. 이는 마치 REST API를 정의할 때 사용하는 OpenAPI(Swagger) 명세나, 인프라를 정의하는 Terraform 설정과 유사한 역할을 AI 에이전트 분야에서 수행합니다. 개발자는 OpenSpec을 사용하여 에이전트가 무엇을 해야 하는지(What)를 선언적으로 정의할 수 있으며, 구체적으로 어떻게 실행되는지(How)는 실행 런타임(Runtime)에 맡길 수 있습니다. 이를 통해 에이전트의 정의와 실행 환경을 분리하여 이식성과 재사용성을 극대화하는 것이 핵심 목표입니다.
Traditional (phase-locked):
PLANNING ────────► IMPLEMENTING ────────► DONE
│ │
│ "Can't go back" │
└────────────────────┘
OPSX (fluid actions):
proposal ──► specs ──► design ──► tasks ──► implement
OpenSpec 프로젝트는 Fission AI 주도로 개발되고 있으며, 단순한 프롬프트 템플릿을 넘어 에이전트의 복잡한 추론 루프, 도구 호출(Function Calling), 메모리 관리, 제약 조건 등을 JSON 또는 YAML 기반의 표준화된 스키마로 표현합니다. 이를 통해 개발자들은 특정 LLM이나 프레임워크에 얽매이지 않고, 표준화된 방식으로 에이전트를 설계, 공유, 평가할 수 있는 생태계를 구축할 수 있습니다.
OpenSpec vs. 기존 방식 (Vendor-Specific SDKs & Frameworks)
기존에 AI 에이전트를 개발할 때는 특정 플랫폼의 SDK나 프레임워크에 강하게 결합된 코드를 작성해야 했습니다:
- OpenAI Assistants API: OpenAI의 특정 API 엔드포인트와 데이터 구조에 맞춰 에이전트를 생성해야 하며, 이를 다른 모델(예: Claude, Llama 3)로 옮기려면 전체 코드를 다시 작성해야 합니다.
- LangChain / LangGraph: 파이썬이나 자바스크립트 코드 레벨에서 에이전트의 로직(Chain)이 정의되므로, 언어 간 이식이나 비개발자(기획자 등)와의 협업이 어렵고 프레임워크 버전 변경에 민감합니다.
이에 비해, OpenSpec은 에이전트를 코드가 아닌 **데이터(선언적 명세)**로 정의합니다:
- 이식성(Portability): 한 번 작성된 OpenSpec 파일은 OpenSpec을 지원하는 모든 런타임에서 실행될 수 있습니다. 즉, 동일한 정의 파일을 사용하여 OpenAI 모델로 실행하거나, 로컬에서 호스팅 된 Llama 모델로 실행하는 것이 가능합니다.
- 상호 운용성(Interoperability): 서로 다른 도구와 에이전트 간의 통신 규약을 표준화하여, 다양한 에이전트가 서로 협력(Multi-agent system)하거나 도구를 공유하기 쉽습니다.
OpenSpec의 주요 구성 및 기능
You: /opsx:new add-dark-mode
AI: Created openspec/changes/add-dark-mode/
Ready to create: proposal
You: /opsx:ff # "fast-forward" - generate all planning docs
AI: ✓ proposal.md — why we're doing this, what's changing
✓ specs/ — requirements and scenarios
✓ design.md — technical approach
✓ tasks.md — implementation checklist
Ready for implementation!
You: /opsx:apply
AI: Implementing tasks...
✓ 1.1 Add theme context provider
✓ 1.2 Create toggle component
✓ 2.1 Add CSS variables
✓ 2.2 Wire up localStorage
All tasks complete!
You: /opsx:archive
AI: Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
Specs updated. Ready for the next feature.
OpenSpec은 에이전트 개발의 복잡성을 줄이고 표준화를 위해 다음과 같은 핵심 구성 요소를 제공합니다.
선언적 에이전트 정의 (Declarative Agent Definition)
OpenSpec의 가장 큰 특징은 에이전트의 페르소나, 목표, 사용 가능한 도구, 제약 조건 등을 JSON 기반의 스키마로 명확하게 정의한다는 점입니다. 이는 쿠버네티스(Kubernetes)의 Manifest 파일처럼 에이전트의 '의도'를 기술합니다.
- Identity & Persona: 에이전트의 이름, 역할, 말투 등 페르소나를 설정합니다.
- Instruction: 에이전트가 따라야 할 핵심 지침과 작업 흐름을 자연어로 기술합니다.
- Constraints: 에이전트가 하지 말아야 할 행동이나 보안 가드레일을 명시합니다.
표준화된 도구 인터페이스 (Universal Tool Interface)
AI 에이전트의 핵심 능력은 외부 도구(API, 데이터베이스, 검색 등)를 사용하는 것입니다. OpenSpec은 에이전트가 사용할 도구(Tools)의 입력과 출력을 표준화된 방식으로 정의합니다. 이는 OpenAI의 Function Calling 규격과 유사하지만, 특정 모델에 종속되지 않는 범용적인 구조를 가집니다. 이를 통해 개발자는 '검색 도구'나 '계산기 도구'를 한 번만 정의해 두면, 여러 에이전트에서 재사용할 수 있습니다.
컴포저블 아키텍처 (Composable Architecture)
OpenSpec은 모듈화를 지향합니다. 복잡한 작업을 수행하는 하나의 거대 에이전트(Monolithic Agent)를 만드는 대신, 작은 단위의 전문화된 에이전트들을 정의하고 이들을 조합하여 복잡한 워크플로우를 구성할 수 있습니다. 예를 들어 '조사 에이전트'와 '작문 에이전트'를 각각 OpenSpec으로 정의한 뒤, 이를 묶어 '블로그 포스트 작성 팀'으로 운용할 수 있습니다.
런타임 독립성 (Runtime Agnostic)
OpenSpec으로 정의된 에이전트는 '컴파일러'나 '인터프리터' 역할을 하는 런타임을 통해 실행됩니다. 현재 OpenSpec 생태계는 이 명세를 해석하여 실제 LLM 호출로 변환해 주는 구현체들을 포함하고 있습니다.
즉, 개발자는 로직에 집중하고, 런타임이 LLM API 호출, 컨텍스트 윈도우 관리, 재시도 로직 등 하위 수준의 복잡성을 처리합니다.
OpenSpec 스키마 예시
실제 OpenSpec이 어떻게 구성되는지 보여주는 간단한 개념적 예시입니다. 실제 문법은 버전 업데이트에 따라 달라질 수 있으므로, 주의해야 합니다:
{
"specVersion": "1.0.0",
"kind": "Agent",
"metadata": {
"name": "tech-blogger",
"description": "기술 블로그 작성을 돕는 AI 어시스턴트"
},
"spec": {
"model": "gpt-4-turbo",
"instructions": "당신은 전문적인 기술 블로거입니다. 명확하고 간결한 문체를 사용하세요.",
"tools": [
{
"name": "web_search",
"description": "최신 기술 정보를 인터넷에서 검색합니다.",
"parameters": {
"type": "object",
"properties": {
"query": { "type": "string" }
}
}
}
]
}
}
라이선스
OpenSpec 프로젝트는 MIT License으로 공개 및 배포되고 있어, 상업적 이용 및 수정 배포가 자유롭습니다.
OpenSpec 공식 홈페이지
OpenSpec 프로젝트 GitHub 저장소
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 