MVP Apache-2.0 · 운영 검증 전 · 기능 현황 보기 →

버그 리포트가 쌓이면,
Clio가 묶고 원인을 찾습니다.

Clio는 버그 리포트를 수집하고, 같은 원인의 오류를 이슈로 묶어, 프로젝트 문서와 소스코드에 근거한 분석을 제공하는 오픈소스 서비스입니다. 반복적인 분류와 조사는 Clio가 맡고, 근거가 부족하거나 충돌하면 사람에게 넘깁니다. 

$ curl -fsSL https://raw.githubusercontent.com/team-clio/clio-platform/main/compose.release.yaml -o compose.yaml
$ echo "OPENAI_API_KEY=sk-..." > .env
$ docker compose up -d
로컬에서 띄우기 작동 방식 보기
무엇을 하나요

버그 수집부터 원인 분석까지, 한 흐름으로

여러 경로로 들어오는 오류는 같은 문제라도 표현이 다르고, 비슷한 메시지라도 원인이 다를 수 있습니다. Clio는 수집부터 분석까지 연결하고, 각 판단의 근거와 불확실성을 남깁니다.

  • 리포트 정규화

    오류 제목, 메시지, stack trace, 발생 시각 같은 원문을 보존하고 증상, 환경, 재현 정보, 오류 신호로 구조화합니다. 원문에 없는 내용은 채우지 않고 missing_fields로 표시합니다. 같은 오류가 다시 나도 새 Bug로 남깁니다.

  • 중복 이슈 연결

    정확한 오류 신호, trigram 문자열 유사도, 벡터 의미 검색을 함께 써서 비슷한 Bug를 찾고, 연결된 Issue별로 묶어 후보를 만듭니다. 검색 유사도와 최종 연결 판단은 분리되어 있습니다.

  • 코드 근거 원인 분석

    분석 시작 시 문서 revision과 저장소 commit을 고정하고 코드·문서·과거 이력을 병렬로 탐색합니다. 인용이 스냅샷과 일치하는지 확인하고, 결과는 완료 / 근거 부족 / 검토 필요로 나눠 저장합니다.

  • 사람이 끼어드는 지점이 분명함

    확신도가 애매하거나 후보끼리 경합하면 자동 연결하지 않고 검토 대기로 보냅니다. 기준값은 환경변수로 바꿀 수 있습니다.

  • 프로젝트 문서 기억 (PCM)

    Markdown과 텍스트 PDF를 올리면 heading 단위 지식으로 정리해 출처, 개정 이력과 함께 보관합니다. 관리 화면에서 분석에 쓰인 지식과 스냅샷을 그대로 볼 수 있습니다.

  • 완전한 셀프호스팅

    임베딩은 로컬 Ollama의 qwen3-embedding:0.6b로 만듭니다. 코드 저장소는 서버 안의 bare mirror로만 다루고, 에이전트에는 원격 주소나 토큰을 넘기지 않습니다.

  • 원하는 LLM 사용

    모든 에이전트가 CLIO_MODEL=provider:model 하나를 공유하고, 인증 정보는 각 provider의 표준 환경변수를 씁니다.

  • 재분석해도 이력이 남음

    분석 결과는 실행마다 스냅샷으로 저장됩니다. 재분석이 이전 결과를 덮어쓰지 않아 판단이 어떻게 바뀌었는지 비교할 수 있습니다.

누구를 위한가

조사는 줄이고, 고칠 문제에 집중하도록

  • 개발자

    관련 코드와 문서 근거가 붙은 이슈를 받아 원인 조사와 수정에 바로 들어갑니다.

  • 유지보수 담당자

    기존 이슈 연결과 신규 생성 판단을 확인하고, 검토가 필요한 결과만 골라 봅니다.

  • 프로젝트 관리자

    이슈 상태, P0~P4 우선순위, 발생 현황을 한 화면에서 봅니다.

작동 방식

리포트 하나가 거치는 네 단계

각 단계는 LangGraph 노드로 구현되어 있습니다. 노드 이름 그대로 로그와 트레이스에서 확인할 수 있습니다.

1 · NORMALIZE

정규화

민감한 키를 가리고 32 KiB 이내로 잘라 모델에 넘깁니다. 결과는 원문에 근거한 표준 사실입니다.

load_and_normalize_report
2 · MATCH

후보 비교

기존 이슈 후보를 찾아 오류 유형, 오류 코드, 스택 프레임이 겹치는지 비교합니다.

search_issue_candidatesmatch_report
3 · DECIDE

연결 · 검토 · 신규

확실하면 기존 이슈에 연결하고, 애매하면 사람에게 넘기고, 처음 보는 문제면 새 이슈를 만듭니다.

apply_match_decision→ needs_review
4 · ANALYZE

원인 분석

문서·코드·이력을 병렬로 찾고, 해결 계획을 세운 뒤 품질 게이트를 통과해야 저장됩니다.

search_documents · search_code · search_historyplan_resolutionquality_gate
자동으로 처리사람이 확인하는 지점
판단 정책

언제 자동으로 연결하고, 언제 묻나요

Report Matcher의 분기 규칙을 그대로 옮겼습니다. 값을 움직여 Clio가 어떤 결정을 내리는지 확인해 보세요.

사람 검토 REVIEW
  • 0.70 이상이지만 자동 연결 조건을 만족하지 않습니다.

기본값은 CLIO_RM_AUTO_LINK_THRESHOLD=0.95, CLIO_RM_REVIEW_THRESHOLD=0.70, CLIO_RM_CANDIDATE_MARGIN=0.10입니다. 자동 연결의 운영 임계값은 아직 평가 데이터로 보정 중이므로 팀에 맞게 조정하세요.

분석 결과의 구조

확인한 사실과 추측을 섞지 않습니다

Issue Analyzer의 결과는 세 층으로 나뉩니다. 위 층은 반드시 아래 층의 ID를 참조하므로, 어떤 가설이 어떤 코드에서 나왔는지 끝까지 따라갈 수 있습니다.

EVIDENCE · E1 · 예시

실제로 본 코드

분석에 사용한 커밋의 코드 스냅샷을 1~10줄로 그대로 보존합니다. 경로나 라인 번호는 설명용 메타데이터일 뿐입니다.

// PaymentService.java @ 0123abc
if (res.status() == TIMEOUT) {
  order.markPending();
  return;  // 이벤트 미발행
}
source: snapshot
FINDING · F1

근거에서 얻은 해석

PG 응답이 타임아웃이면 주문은 PENDING으로 남고 완료 이벤트가 발행되지 않습니다.

refs: E1
HYPOTHESIS · H1

가능한 원인

결제는 PG 쪽에서 승인됐지만 타임아웃으로 처리돼, 주문 목록 조회 조건에서 빠졌을 가능성이 있습니다.

refs: F1
평가

변경할 때마다 같은 조건으로 잽니다

clio-benchmark는 합성 결함이 있는 테스트 저장소에 리포트를 넣고, 분석 결과와 인용 무결성, 처리 시간을 기록하는 CLI입니다. 아래는 지금까지의 비교 실험 한 번의 결과입니다.

구성평균 점수70점 이상평균 분석 시간
full-clio92.68 / 10028 / 3032.8초
one-shot (코드 검색만)80.56 / 10024 / 3027.5초

합성 결함 10개 × 보고 문구 3종 = 30건, 저장소 하나에서 한 번 실행한 자동 채점 결과입니다. 문서·이력 검색과 quality gate가 함께 달라진 비교라 요소별 효과는 분리되지 않으며, 실제 수정 성공률이나 다른 코드베이스의 품질을 보장하지 않습니다. 시간에는 저장소 동기화가 빠져 있고 토큰 비용은 수집하지 않았습니다.

cd clio-benchmark
uv sync --extra dev
cp benchmark.example.yaml benchmark.local.yaml
uv run clio-benchmark setup
uv run clio-benchmark run      # 서버와 에이전트를 먼저 띄운 뒤
uv run clio-benchmark report --format html
아키텍처

API 서버와 에이전트 그래프, 하나의 데이터베이스

사용자와 외부 서비스는 Java API 서버만 봅니다. Python 에이전트 그래프는 비동기로 요청을 받아 처리하고, 업무 데이터는 서버의 internal API로만 바꿉니다.

외부 서비스와 관리자 UI가 API 서버로 요청을 보내고, API 서버는 에이전트 그래프에 비동기로 전달하며, 둘 다 PostgreSQL을 사용하고 에이전트는 Ollama로 임베딩을 만든다. 외부 서비스 QA · 에러 수집기 · CS clio-admin React · 검토 · 설정 JAVA 21 · SPRING · :8080 clio-server 버그 수집 · 이슈 · 권한 internal-api PYTHON 3.11 · LANGGRAPH · :2024 clio-agent-graph Normalizer · Matcher Issue Analyzer · RAG PCM Inspect :2025 · Git mirror PostgreSQL + pgvector clio · clio_pcm · :5432 Ollama 임베딩 · :11434 async 요청 internal-api

데이터 소유권이 나뉨

Bug·Issue·실행 상태·분석 결과는 서버가, 정규화 리포트·검색 색인·PCM·Git mirror는 에이전트 그래프가 소유합니다. 에이전트는 업무 테이블을 직접 고치지 않고 좁은 internal API로 요청합니다.

코드는 커밋 단위로 읽음

검색·목록·읽기 모두 고정된 커밋을 씁니다. 경로 탈출은 막고 secret 파일은 읽지 않으며 값은 가립니다.

중복 실행에 안전함

워크플로는 PENDING → RUNNING → COMPLETED / FAILED로 추적하고 request_id와 요청 hash로 중복 적용을 막습니다. 검토 필요는 실패가 아니라 정상 결과입니다.

시작하기

명령 세 줄로 띄우기

서버, 에이전트, 관리 화면, PostgreSQL, 임베딩 서버가 컨테이너 다섯 개로 함께 올라옵니다. 처음 실행할 때 임베딩 모델 약 639MB를 내려받아 몇 분 걸립니다.

DockerOpenAI API 키

  1. 실행하기

    구성 파일 하나를 받고 API 키를 넣은 뒤 실행합니다.

    curl -fsSL https://raw.githubusercontent.com/team-clio/clio-platform/main/compose.release.yaml -o compose.yaml
echo "OPENAI_API_KEY=sk-..." > .env
docker compose up -d

  2. 프로젝트 연결하기

    http://localhost:3000에서 프로젝트를 만들고 Git 저장소(HTTPS)를 연결합니다. 저장소 동기화가 끝나면 버그 처리가 시작됩니다. 기획·설계 문서(Markdown, 텍스트 PDF)를 올리면 분석에 함께 쓰입니다.

  3. 버그 보내기

    에러 수집기나 QA 도구에서 아래 API로 버그를 보냅니다.

    curl -X POST http://localhost:3000/external-api/v1/projects/1/bugs \
  -H 'content-type: application/json' \
  -d '{"source": "API", "title": "결제 실패",
       "error_type": "PaymentException",
       "stack_trace": ["PaymentService.approve"],
       "occurred_at": "2026-10-04T05:00:00Z"}'

모델을 바꾸려면 .env에 CLIO_MODEL=provider:model을, OpenAI 호환 서버를 쓰려면 CLIO_MODEL_BASE_URL을 넣습니다. 소스에서 직접 실행하는 방법은 각 저장소의 README에 있습니다.

현재 상태

지금 쓸 수 있는 기능

핵심 흐름은 구현되어 있지만 운영 환경에서의 품질 검증은 아직 진행 중입니다.

영역내용
리포트 처리정규화, 하이브리드 후보 검색, 매칭, 연결 / 검토 / 신규 분기
이슈 분석 · 재분석병렬 탐색, Evidence·Finding·Hypothesis, quality gate, 실행별 스냅샷
프로젝트 · 이슈 관리관리 API와 화면, 이슈 통계, 상태·담당자·P0~P4 우선순위
문서 · PCMMarkdown·텍스트 PDF 업로드, 중복 거절, 동기화 상태, PCM 조회. 스캔 PDF OCR은 범위 밖
저장소 연동HTTPS 저장소 등록·수정·삭제, commit 단위 스냅샷
FAQ

자주 묻는 질문

Clio는 무엇인가요?

버그 리포트를 수집하고, 같은 원인의 오류를 이슈로 묶어, 프로젝트 문서와 소스코드에 근거한 분석을 제공하는 서비스입니다. Java API 서버, Python LangGraph 에이전트 그래프, React 관리 화면으로 이루어져 있습니다.

Bug와 Issue는 어떻게 다른가요?

Bug는 수집된 오류 한 건이고, 같은 오류가 다시 나도 새 Bug로 남깁니다. Issue는 같은 원인으로 판단한 여러 Bug를 묶은 작업 단위입니다. Bug 하나는 최대 하나의 Issue에만 연결됩니다.

Clio가 코드를 직접 고치거나 PR을 만드나요?

아니요. Clio는 원인과 해결 방향을 근거와 함께 정리하는 데까지 합니다. LLM에는 읽기 도구만 주고, 업무 데이터 변경도 서버가 검증한 뒤 수행합니다.

라이선스는 무엇인가요?

Apache License 2.0입니다. 상업적 용도를 포함해 자유롭게 사용, 수정, 배포할 수 있습니다. 배포할 때는 라이선스 사본과 저작권 고지를 함께 포함하고, 수정한 파일에는 변경 사실을 표시해야 합니다.

제 코드가 외부로 나가나요?

저장소는 서버 안의 bare Git mirror로 관리되고, 임베딩은 로컬 Ollama에서 만듭니다. 외부로 나가는 것은 설정한 LLM Provider로 보내는 프롬프트뿐입니다. 그 안에 들어가는 코드는 분석에 필요한 짧은 구간이며, secret 파일은 읽지 않고 값은 가립니다. 로컬 LLM을 쓰면 전부 내부에서 처리됩니다.

어떤 LLM을 쓸 수 있나요?

CLIO_MODEL=provider:model 형식으로 지정한 모델을 모든 에이전트가 함께 씁니다. 인증은 각 provider의 표준 환경변수를 사용합니다. 관리 화면에서 모델을 바꾸는 기능은 아직 준비 중입니다.

잘못 연결하면 어떻게 하나요?

자동 연결은 confidence 0.95 이상이고, 강한 오류 신호가 있으며, 모순과 후보 경합이 없을 때만 일어납니다. 그 밖의 애매한 경우는 검토 대기로 가서 사람이 결정합니다. 기준값은 환경변수로 더 보수적으로 바꿀 수 있습니다.

GPU가 필요한가요?

아니요. 기본 임베딩 모델은 0.6B로 CPU에서 돌아갑니다. macOS의 Docker는 Metal 가속을 쓰지 못해 네이티브 Ollama보다 느릴 수 있습니다.

어떻게 기여하나요?

GitHub에서 이슈를 열거나 TODO로 표시된 영역부터 시작해 보세요. 서버는 ./gradlew test, 에이전트는 uv run pytest와 uv run ruff check ., 관리 화면은 npm run typecheck와 npm run lint로 확인합니다. 분석 품질에 영향을 주는 변경은 clio-benchmark로 전후를 비교해 주세요.

버그는 자동으로 묶고,
판단은 사람이.

GitHub에서 보기 시작하기