Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
OPC Team은 단순한 프롬프트 기반 에이전트를 넘어 상태 머신, 결정 이력, 리스크 정량화 등을 통해 제어 가능한 AI 에이전트 협업 프레임워크를 제공합니다. 작업 강도에 따라 에이전트 팀을 자동으로 확장/축소하는 탄력적 그룹화 기능을 갖추고 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Claude Ecosystem의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기“고정된 역할표”를 가진 AI Agent를 “작업 강도에 따라 자동으로 확장 및 축소(Auto-scaling)할 수 있는” 실행 시스템으로 업그레이드합니다.
English: README_EN.md · Examples: examples/ · Roadmap: ROADMAP.md
OPC Team은 크로스 플랫폼 Agent 협업 프레임워크입니다. 목표는 단순히 역할극(Role-playing) 프롬프트를 다시 만드는 것이 아니라, AI 실행 과정에 명확한 엔지니어링 제약 조건을 추가하는 것입니다: 작업 상태 머신(State Machine), 결정 이력(Decision Log), 리스크 정량화(Risk Quantification), 3단계 메모리(Three-level Memory), 그리고 감사 가능한(Auditable) CLI 도구 세트입니다. 이 프레임워크는 Claude Code / OpenClaw / Cursor / Windsurf / 범용 CLI / API 워크플로우에서 실행하기에 적합하며, Agent의 실행 과정을 “할 수 있을 것처럼 보이는” 단계에서 “진정으로 제어 가능하고, 재생 가능하며, 관리 가능한” 단계로 격상시킵니다. 현재 기본 오케스트레이션(Orchestration) 전략은 3 / 8 / 20으로 업그레이드되었습니다.
세 단계의 탄력적 그룹화(Elastic Grouping)를 통해, 일상적인 작업에는 상주 소규모 팀을 유지하고, 중요한 작업에는 핵심 큐(Core Queue)로 자동 확장하며, 복잡한 작업에는 모든 역할을 최대한 투입하여 협업합니다.
Quick Start · Platform Matrix · Deployment Guide · Agent Catalog · Skill Manual · API Schema
단순한 프롬프트(Prompt) 템플릿이 아닙니다: 핵심 능력은 tools/*.py에 있는 상태 머신, 결정, 리스크, 메모리 및 구성 시스템이며, 단순히 “COO 역할을 설정하는 것”이 아닙니다. 플랫폼 종속적인 플러그인이 아닙니다: 동일한 프레임워크가 Claude Code, OpenClaw, Cursor, Windsurf, 범용 CLI 및 API 시나리오를 동시에 커버합니다. 블랙박스 실행이 아닙니다: 매 작업 생성, 상태 전환, 리스크 평가, 결정 업데이트, 메모리 동기화가 모두 기록, 추적 및 감사될 수 있습니다. 세션 종료 시 망각하지 않습니다: L0/L1/L2 3단계 메모리를 통해 작업 요약, 장기적 선호도 및 방법론을 축적할 수 있습니다.
| 프롬프트에만 의존하는 Agent 팀 설정 | OPC Team이 하는 일 |
|---|---|
| 상태를 컨텍스트(Context)로 “추측”함 | 상태 머신(State Machine)을 사용하여 작업 흐름을 강력하게 제약함 |
| ... | ... |
Task Flow: 작업 생성, 등급 지정, 상태 전환, 진행 상황 보고, SLA 체크. Decision Log: 방안, 선택, 이유, 가설을 기록하며 추후 검증 및 피드백을 지원합니다. Risk Score: 리스크를 “약간 위험해 보인다”는 느낌에서 정량화 가능한 등급과 대응 계획으로 변환합니다. Memory Sync: 즉시 메모리, 단기 요약, 장기 경험을 통합 저장소로 동기화합니다. Config + Storage: 플랫폼 적응, 경로 설정, 파일 저장 및 SQLite 저장소를 지원합니다. Agent Catalog: 내장된 역할을 agents/*.md 또는 agents/<pack>/*.md에 정의하며, 통합 스키마(Schema)와 린트(Lint)를 사용하여 역할 계층을 관리합니다. 20-Role Bench: 기본 팩(Default pack)에 전략, 연구, 제품, 경험, 성장, 기술, 운영, 데이터, 재무, 법무, 고객 성공 등 워크플로우를 아우르는 20개의 오케스트레이션 가능한 역할이 내장되어 있습니다. Role Packs: 기본 역할 세트를 새로운 팩으로 복사하고 실행 시점에 서로 다른 역할 팩을 전환할 수 있습니다. Main/Sub Orchestration: CEO 주 Agent -> sub-agent 구조의 주-종 오케스트레이션을 내장하여, 주 Agent가 하위 작업을 할당할 수 있도록 지원합니다. Agent Board: 로컬에서 확인 및 스케줄링할 수 있는 패널로, 주 Agent, sub-agent, 현재 그룹화 단계, 모델 라우팅(Model Routing) 및 최근 상태 변화를 볼 수 있으며, 패널에서 작업을 할당하고 상태와 모델 라우팅을 조정할 수도 있습니다. Model Routing: 주 Agent와 각기 다른 sub-agent가 서로 다른 API 제공업체(Provider) / 모델(Model)을 지정할 수 있도록 허용합니다. 설정되지 않은 경우 기본적으로 호스트 플랫폼의 모델을 상속받습니다. Adaptive Orchestration: daily / important / full 세 단계의 그룹화를 지원하며, 기본적으로 각각 3 / 8 / 20개 역할의 협업 규모에 대응합니다. Workflow Runbooks: OPC-Micro / Sprint / Control 세 가지 실행 모드와 handoff/runbook 템플릿을 제공합니다.
tools/agent_ops.py는 주 Agent / sub-agent 레지스트리, 작업 상태, 작업 할당 및 모델 구성을 관리합니다. tools/agent_catalog.py는 역할 디렉토리를 검증하고, 매니페스트(Manifest)를 출력하며, role pack을 발견/복사하고, 역할 계층과 오케스트레이션 계층을 분리하는 역할을 합니다. tools/agent_convert.py는 역할 디렉토리를 OpenClaw / Claude Code / Cursor / Windsurf / API 통합 파일로 내보내는 역할을 합니다. tools/dashboard.py serve
통합 대시보드(Integrated Dashboard)를 실행하여 브라우저에서 현재의 그룹화 단계(Grouping Tier), 역할 상태(Role Status) 및 모델 전환 엔트리를 직접 확인할 수 있습니다.
agent 모델 설정은 세 가지 소스를 지원합니다:
default: 글로벌 기본 라우팅인 platform_default를 상속합니다.
platform_default: 호스트 플랫폼 모델을 강제로 사용합니다.
custom_api: 독립적인 provider / model / api_base / api_key_env를 지정합니다.
기본 글로벌 라우팅은 platform_default이며, 즉 "기본적으로 모델 자체의 모델을 사용"합니다.
기본 토폴로지(Topology)에서 ceo는 메인 agent이며, default pack에는 현재 20개의 역할이 내장되어 있어 프로젝트, 연구, 제품, 경험, 성장부터 기술, 운영, QA, 데이터, 구매, HR, 법무까지 직접 편성(Orchestration)할 수 있습니다.
그룹화는 기본적으로 세 단계로 나뉩니다:
daily: 3개의 sub-agent가 상주합니다.
important: 8개의 핵심 sub-agent를 호출합니다.
full: 20개의 역할을 모두 활성화합니다 (CEO + 19개의 sub-agent).
이는 OPC의 중점이 "20개의 역할을 모두 상주시켜 두는 것"이 아니라, CEO 메인 agent가 작업 강도에 따라 언제 소규모 팀만 움직일지, 언제 핵심 인력을 소집할지, 언제 전체 인원을 투입하여 전투를 시작할지를 결정하는 데 있음을 의미합니다.
아래는 정적인 프롬프트(Prompt) 예시가 아니라, OPC Team의 로컬 상태 머신(State Machine)을 통해 실행된 3가지 L3 전략 작업 형태입니다. 각 작업은 작업 상태, 리스크 기록, 결정 이력 및 메모리 요약을 생성합니다.
| 실제 작업 | OPC Team이 내린 주요 결정 | 리스크 제어 |
|---|---|---|
| 직장인의 부업 발전 방법 | 먼저 수직적 기술 서비스를 제공하고, 그 다음 콘텐츠화하며, 마지막으로 제품화한다 | 매주 투입되는 리듬을 제어합니다; 먼저 인터뷰와 저가형 MVP를 진행하여 초기 과도한 투입을 방지합니다 |
| ... |
이러한 출력물은 data/tasks/, data/decisions/, data/risks/, data/agents/, data/assignments/ 및 data/MEMORY.md에 축적되어, 프로세스 재생, 가설 복기, 메인-서브 agent 간의 분업 및 후속 실행 추적에 사용됩니다.
agents/*.md에 위치하며, 추가 역할 팩(Role Pack)은 agents/<pack>/*.md에 둘 수 있습니다. tools/agent_ops.py 실행 시 Python 상수에 역할을 고정하는 대신 현재 팩으로부터 메인-서브 토폴로지를 로드합니다. tools/agent_catalog.py lint를 통해 스키마(Schema), 섹션 완전성 및 부모-자식 관계를 검증할 수 있습니다. tools/agent_catalog.py scaffold-pack을 사용하면 기본 역할로부터 새로운 팩을 복사하여 산업군이나 기업 시나리오에 맞게 커스텀할 수 있습니다. tools/agent_ops.py switch-pack으로 현재 실행 중인 팩을 직접 전환할 수 있습니다. - 이를 통해 향후 역할을 확장하거나, 산업별 팩을 만들거나, 플랫폼 적응을 할 때 편성 코드를 직접 수정할 필요가 없습니다.strategy/QUICKSTART.md는 OPC-Micro / OPC-Sprint / OPC-Control 세 가지 실행 모드를 제공합니다. strategy/coordination/handoff-templates.md는 메인-서브 인수인계, QA 통과/실패, 에스컬레이션(Escalation) 보고서 템플릿을 제공합니다. strategy/runbooks/에는 startup-mvp / enterprise-feature / incident-response 세 가지 유형의 시나리오 런북(Runbook)이 제공됩니다. - 이로써 OPC는 단순히 "역할을 할당하는 것"을 넘어, 다양한 시나리오의 실행 방식을 고정할 수 있습니다.
daily: 일상적으로 3개의 sub-agent가 상주하며, 기본값은 coo / project / strategist입니다.
important: 중요 작업 시 8개의 핵심 sub-agent를 소집하며, 기본값은 coo / project / strategist / research / product / tech / data / qa입니다.
full: 사용자가 지정하거나 복잡도가 높은 작업의 경우 20개의 역할을 모두 활성화하여 CEO + 19개의 sub-agent가 전체 협업을 수행합니다.
tools/task_flow.py assess --agent-profile ...를 통해 단계를 명시적으로 지정할 수 있습니다. tools/agent_ops.py recommend를 통해 작업 등급, 제목 또는 키워드에 따른 현재 권장 그룹을 출력할 수 있습니다.
git clone https://github.com/HeiGeAi/opc-team.git
cd opc-team
./install.sh -p generic --skip-env -t
...
pip install -e .
pip >= 21.3 (PEP 660 editable install)가 필요합니다. 이전 버전의 pip는 먼저 pip install -U pip를 실행해 주세요.
v4.5부터 python3 tools/<name>.py ... 방식의 모든 작성법에는 더 짧은 등가 명령인 opc <name> ...이 존재합니다.
아래에 대조하기 쉽도록 두 가지 작성법을 모두 제공합니다.
# 1. 태스크 생성
opc task create --title "지식 유료화 타당성 평가" --ceo-input "지식 유료화 사업을 하고 싶습니다"
# 등가: python3 tools/task_flow.py create --title ... --ceo-input ...
...
더 완전한 예시 실행 결과(태스크/의사결정/리스크 JSON)는 examples/를 참조하세요.
Claude Code / OpenClaw / Cursor / Windsurf: 설치 후 즉시 자연어 명령을 내려 Agent가 SKILL.md에 따라 CLI를 호출하도록 합니다. 범용 CLI (General CLI): SKILL.md를 시스템 프롬프트 (System Prompt)로 사용하여 python3 tools/*.py 실행을 허용합니다. API 워크플로우 (API Workflow): adapters/api.json을 함수 호출 (Function Calling) 또는 도구 계층 (Tool Layer)에 연결합니다.
opc-team/
├── SKILL.md # 범용 AI 실행 매뉴얼
├── README.md # 본 파일
...
| 플랫폼 | 상태 | 설치 방식 | 사용 방식 |
|---|---|---|---|
| Claude Code | ✅ | ./install.sh -p claude_code | 자연어 명령 |
| OpenClaw | ✅ | ./install.sh -p openclaw | 직접 명령 하달 |
| Cursor | ✅ | ./install.sh -p cursor | Composer에서 사용 |
| Windsurf | ✅ | ./install.sh -p windsurf | 직접 명령 하달 |
| 범용 CLI | ✅ | ./install.sh -p generic | 시스템 프롬프트 |
| API 호출 | ✅ | ./install.sh -p api | 함수 호출 (Function Calling) |
상세 배포 설명은 DEPLOYMENT.md를 확인하세요.
# 태스크 생성
python3 tools/task_flow.py create --title "태스크 제목" --ceo-input "CEO 입력"
# 등급 지정
...
# 사용 가능한 역할 팩 (Role Pack) 확인
python3 tools/agent_catalog.py list-packs
# 역할 스키마 (Schema) 및 섹션 검증
...
현재 default 팩의 20개 역할은 워크플로우 (Link)에 따라 몇 가지 그룹으로 나뉩니다:
제어 및 스케줄링 (Control & Scheduling):
ceo、coo、project
전략 및 연구 (Strategy & Research):
strategist、research
제품 및 경험 (Product & Experience):
product、ux
성장 및 상업화 (Growth & Monetization):
marketing、growth、sales、brand
기술 및 인도 (Tech & Delivery):
tech、devops、qa、data
경영 및 보장 (Management & Assurance):
finance、procurement、customer_success、hr、legal
# 지원하는 플랫폼 확인
python3 tools/agent_convert.py list-tools
# 지원하는 내보내기(Export) 가능 역할 팩 확인
...
설치 스크립트는 claude_code / openclaw / cursor / windsurf / generic / api 모드에서 모두 해당 플랫폼의 통합 파일 (Integration Files)을 자동으로 생성합니다. 기본 팩은 대상 번들 (Bundle)의 integrations/<tool>/ 또는 저장소 루트 아래의 output/integrations/<tool>/로 출력되며, 커스텀 팩은 각각 integrations/<pack>/<tool>/ 또는 output/integrations/<pack>/<tool>/로 출력됩니다.
# 의사결정 생성
python3 tools/decision_log.py create \
--task-id T001 \
...
# 리스크 평가
python3 tools/risk_score.py assess \--task-id T001 \...
# L0(즉시 기억)에 쓰기
python3 tools/memory_sync.py write --level L0 --task-id T001 --content "내용"
# L1(단기 기억)으로 압축
...
# 기본 마스터-슬레이브 에이전트(agent) 레지스트리 초기화
python3 tools/agent_ops.py init
# 사용 가능한 역할 팩(pack) 확인
...
# 요약 JSON 출력
python3 tools/dashboard.py summary --pretty
# 요약 파일 내보내기
...
# 세 가지 표준 실행 모드 확인
sed -n '1,220p' strategy/QUICKSTART.md
# 표준 인수인계(handoff) 템플릿 열기
...
| 레벨 | 특징 | 처리 방식 | 예상 시간 |
|---|---|---|---|
| L1 | 단순 질의/실행 | daily : 3개의 상주 sub-agent | < 5분 |
| L2 | 제한적 판단 | daily : 3개의 상주 sub-agent | 5-30분 |
| L3 | 다중 방안+리스크 | important : 8개의 핵심 sub-agent | 30분-2시간 |
| L4 | 전략적 수준 | full : 20개 역할 풀 편성 협업 | 2시간 이상 |
| 등급 | 설명 | 처리 방식 |
|---|---|---|
| 1 | 무시 가능 | 병행 처리 |
| ... | ||
| 계산 공식: 확률(1-5) × 영향(1-5) → 리스크 등급(1-5) |
storage.backend
선택 사항: file / sqlite
예시는 유효한 JSON이며, 바로 복사하여 사용할 수 있습니다:
{
"version": "4.7.0",
"platform": "generic",
...
}
export OPC_HOME="/path/to/opc-team"
export OPC_CONFIG="/custom/path/config.json"
# macOS
brew install python3
# Ubuntu/Debian
...
pip install filelock
chmod -R 755 data/
더 자세한 질문은 DEPLOYMENT.md의 트러블슈팅(troubleshooting) 섹션을 참조하세요.
# 1. 작업 생성
python3 tools/task_flow.py create \--title "지식 유료화 타당성 평가" \...
v4.7.0(2026-06-10): 데이터 무결성 및 인터페이스 강화 — decision-id 화이트리스트 검증, 중복 생성 차단(--force 사용 시 제외), 작업 간 의사결정 조회 모호성 해소(--task-id 제한), escalated 상태에 아웃 에지(out-edge) 추가(실행 재개 / cancelled), L4 완료 시에도 의사결정 이력 요구, check-sla 전체 경로 구조화 출력, completed 흐름 단일 JSON 계약, MEMORY.md 작업별 멱등성(idempotent) 동기화 및 SQLite 백엔드 동작 일관성 확보, config 읽기 경로 부작용(side-effect) 제거, readonly_mode 두 가지 작성 방식 호환. 테스트 수 58 → 90. 자세한 내용은 CHANGELOG.md 참조.
v4.6.0(2026-05-26): 강도 테스트를 통해 발견된 3개의 P0 버그 수정 — agent catalog에 mtime 기반 캐시 추가(쓰기 경로 5배 속도 향상), sync 훅(hook)에서 SystemExit 대응, SQLite 백엔드 db_path 수정 및 namespace 격리 추가. 테스트 수 45 → 58. 자세한 내용은 CHANGELOG.md 참조.
v4.5.0(2026-05-26): 엔지니어링 품질 기반 마련 — pytest 스위트(45개 케이스) + GitHub Actions CI + opc 커맨드라인(pip install) + 영문 README + examples/ 실제 실행 결과물 + ROADMAP/CHANGELOG. 자세한 내용은 CHANGELOG.md 참조.
v4.4.0(2026-04-17): 기본 역할을 20개로 확장, strategy/ 워크플로우 계층, handoff 템플릿 및 시나리오 runbook 보충, 팩(pack) 기반 오케스트레이션 설명 강화
v4.3.0(2026-04-13): 신규 CEO 마스터 Agent -> sub-agent
Master-Slave 오케스트레이션 (Orchestration), 작업 할당 기록, Multi-agent 독립 모델 라우팅 (Routing), 쓰기 가능한 통합 칸반 (Kanban) 및 대시보드 (Dashboard) API
v4.2.3(2026-04-10): completed 상태가 진행률 100%로 자동 수렴되지 않는 문제 및 동일 작업의 동시 쓰기 시 진행률이 덮어씌워질 수 있는 문제 수정, 런타임 시맨틱 (Runtime Semantics) 및 버전 동기화 유지
v4.2.2(2026-04-09): CLI 실패 반환 코드, Windows 런타임 잠금 (Lock), 파라미터 검증, 플랫폼 파라미터 초기화 수정
v4.2.1(2026-04-09): readonly_mode 쓰기 관통 (Write-through) 문제, 플랫폼 설치 후 설정 미적용 문제, 버전 번호 관리 수정
v4.2.0(2026-04-09): 사용자 피드백 최적화 버전 - 동시 ID 충돌, -p 파라미터 덮어쓰기, 읽기 전용 모드 (Read-only mode), auto_sync_memory, 문서 노이즈 제거 수정
v4.1.0(2026-04-08): 설치 링크, 경로 설정, storage 버그, SKILL.md 인자 (args) 수정
v4.0.0(2026-04-08): 크로스 플랫폼 (Cross-platform) 범용 버전, 멀티 플랫폼 지원, 설정 시스템, 스토리지 추상화 계층 (Storage Abstraction Layer) 지원
v3.0.0(2026-04-08): 문서 버전, 모든 히스토리 버전 통합 (폐기됨)
v2.5.0: 메모리 시스템 (Memory System) 통합
v2.1.0: 3단계 메모리 + 토론 메커니즘 (Debate Mechanism)
v2.0.0: MBTI + 고문 (Classical Chinese) + 사고 프레임워크 (Thinking Framework)
v1.2.0: 조정 모드 (廷议模式) + 상류 전달 (Upstream Passing)
v1.1.0: 기초 버전
MIT
Issue 및 Pull Request 제출을 환영합니다.
문제가 있을 경우 다음으로 연락해 주세요:
저자: Blake徐
WeChat: 488137
GitHub: @HeiGeAi
본 프로젝트는 edict에서 영감을 받았으며, 상태 머신 (State Machine) + CLI 도구의 아키텍처 사상을 채택했습니다.