HeiGeAi/opc-team

“고정된 역할표”를 가진 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 도구의 아키텍처 사상을 채택했습니다.