Cq: AI 코딩 에이전트를 위한 Stack Overflow

AI 코딩 에이전트가 좋아진다고 해서, 갑자기 덜 헤매는 건 아닙니다.

오히려 더 자주 같은 실수를 반복합니다.
문서에 안 적힌 API 동작, 버전 충돌, CI 설정 함정, 빌드 툴의 미묘한 차이 같은 것들을 세션마다 다시 발견하죠. 인간 개발자가 예전엔 검색으로 해결했다면, 이제는 에이전트가 매번 토큰과 시간을 태우며 같은 벽에 부딪히고 있습니다.

Mozilla.ai의 Cq는 바로 이 지점을 찌릅니다. 이 프로젝트는 “AI가 코드를 더 잘 생성하게 하는 도구”라기보다, 에이전트가 이미 누군가 겪은 실패를 다시 겪지 않게 만드는 지식 공용층에 가깝습니다. 저장소의 공식 설명도 Cq를 “shared agent knowledge commons”이자 “shared agent learning을 위한 open standard”로 정의하고 있고, 현재 상태는 실험적 탐색 단계의 PoC로 공개되어 있습니다. (GitHub)

 

GitHub - mozilla-ai/cq: An open standard for shared agent learning. Agents persist, share, and query collective knowledge so the

 

---

프로젝트 소개

Cq는 AI 에이전트가 작업 전에 관련 지식을 조회하고, 작업 중 새롭게 알게 된 사실을 제안하고, 그 지식이 실제로 맞았는지 확인하거나 잘못됐는지 플래그하는 흐름을 제공하는 시스템입니다. 핵심은 단순 메모리가 아니라 구조화된 지식 단위를 에이전트 사이에서 재사용 가능하게 만든다는 점입니다. README 기준으로 Cq는 Claude Code 플러그인과 OpenCode용 MCP 서버로 설치할 수 있고, 로컬 전용 모드에서는 SQLite에 저장되며, 팀 단위 공유가 필요하면 별도 Team API에 동기화할 수 있습니다. 저장소는 Python 중심이며, MCP 서버는 mcp 기반, 팀 API는 FastAPI 기반으로 구성되어 있습니다. (GitHub)

여기서 중요한 건 Cq가 “모델 하나를 더 똑똑하게 만드는 프롬프트 모음”이 아니라는 점입니다.
Mozilla.ai가 제안하는 방향은 더 큽니다.

• 에이전트가 지식을 질문(query) 한다
• 새로 발견한 것을 제안(propose) 한다
• 검증된 지식을 확인(confirm) 한다
• 틀리거나 오래된 지식을 표시(flag) 한다
• 세션이 끝나면 회고(reflect) 로 공유 가능한 인사이트를 추출한다

즉, Cq는 AI 에이전트를 위한 검색창이 아니라, 학습 프로토콜에 가깝습니다. 실제 skill 문서도 “낯선 API, 라이브러리, 프레임워크, CI/CD, 인프라 작업 전에 먼저 query 하라”는 운영 규칙을 강하게 박아두고 있습니다. (GitHub)

---

왜 이 프로젝트가 등장했을까

이 프로젝트의 문제 정의는 꽤 명확합니다.

오늘날의 AI 에이전트는 대부분 고립된 세션 단위로 움직입니다. 어떤 에이전트가 Stripe의 이상한 응답 형태를 발견해도, 다른 에이전트는 다음 세션에서 그걸 또 처음부터 다시 겪습니다. Mozilla.ai의 제안 문서는 이걸 단순 생산성 문제가 아니라, 중복 추론이 전기·냉각·시간을 계속 소모시키는 구조적 비효율로 봅니다. 동시에 벤더별 메모리 시스템이 폐쇄적으로 쌓이면서, 공유 학습이 있어도 각 플랫폼 안에 갇혀 버린다는 점도 문제로 짚습니다. (GitHub)

개발자 관점에서 번역하면 이렇습니다.

예전에는 시니어 한 명이 팀 위키나 Slack에 남긴 “이거 이렇게 해야 됨”이 조직의 생산성을 지켰습니다.
AI 시대에는 그 역할을 사람이 아니라 지식 레이어가 해야 합니다.

즉, 앞으로의 경쟁력은 “누가 더 좋은 모델을 쓰느냐”보다도
누가 에이전트가 실패를 재사용하지 않게 만드는가에 가까워질 수 있습니다.

이 점에서 Cq는 Stack Overflow와 닮았지만, 사실 더 근본적으로는 다음과 같은 차이가 있습니다.

• 사람을 위한 Q&A 사이트가 아니라
• 에이전트가 바로 소비 가능한 구조화 지식 저장소
• 그리고 단순 검색이 아니라
• 검증, 승격, 신뢰, 안전장치까지 포함한 체계

그래서 “AI용 Stack Overflow”라는 비유는 훅으로는 좋지만, 아키텍처적으로는 에이전트용 지식 운영체제의 일부라고 보는 편이 더 정확합니다. (GitHub)

---

핵심 기능

1. 작업 전에 먼저 조회하는 query

Cq의 첫 번째 철학은 “문제를 풀기 전에 먼저 물어봐라”입니다.
skill 문서에는 낯선 API 연동, 새로운 프레임워크, 에러 상황, CI/CD, 인프라 설정 전에는 query를 호출하라고 적혀 있습니다. 서버 구현도 로컬 SQLite를 먼저 조회한 뒤, 팀 API가 설정돼 있으면 원격 저장소 결과를 합쳐 재정렬합니다. 점수는 도메인 태그 겹침이 가장 크고, 언어와 프레임워크 일치 여부를 보조 신호로 사용합니다. (GitHub)

예를 들어 Stripe 결제를 붙이는 상황이라면 이런 흐름이 됩니다.

# 개념 예시
result = query(
    domain=["api", "payments", "stripe"],
    language="python",
    limit=5,
)

for ku in result["results"]:
    print(ku["insight"]["summary"])
    print(ku["insight"]["action"])

이 구조가 좋은 이유는 단순합니다.
에이전트가 “이걸 해본 적이 없는데 일단 시도해볼게요”가 아니라
“이 영역에 이미 알려진 함정이 있는지 먼저 확인할게요”로 행동 패턴이 바뀌기 때문입니다.

---

2. 새로 배운 사실을 축적하는 propose

작업 중 새롭게 알게 된 비직관적 사실은 propose로 저장할 수 있습니다.
skill 문서는 좋은 제안의 조건을 아주 구체적으로 정의합니다.

• 조직 내부 세부정보는 제거할 것
• 6개월 뒤에도 의미가 남는 원칙 중심으로 쓸 것
• summary, detail, action을 모두 채울 것
• 가능하면 언제 검증했는지와 어떤 근거였는지 포함할 것

이게 중요한 이유는, “에러를 고쳤다”와 “다른 에이전트가 재사용 가능한 지식을 만들었다”는 완전히 다른 일이기 때문입니다. Cq는 후자를 강제합니다. (GitHub)

예시는 이런 식으로 생각하면 됩니다.

propose(
    summary="webpack 5 removes built-in Node.js polyfills",
    detail=(
        "webpack 5 no longer includes Node.js core module polyfills. "
        "Imports like 'stream' fail unless explicit fallbacks are configured."
    ),
    action=(
        "Add resolve.fallback entries for required Node.js modules "
        "such as stream-browserify or buffer."
    ),
    domain=["bundler", "webpack", "nodejs-polyfills"],
    language="typescript",
    framework="react",
    pattern="build-tooling",
)

이건 그냥 로그가 아닙니다.
다음 에이전트의 시행착오를 없애는 압축 지식입니다.

---

3. 지식의 품질을 키우는 confirm / flag

지식 저장소가 쓸모 있으려면 쌓는 것보다 걸러내는 것이 중요합니다.
Cq는 지식 단위를 확인하거나 플래그하는 루프를 넣어 신뢰도를 관리합니다. 서버 코드 기준으로 confirm은 confidence를 0.1씩 올리고, flag는 0.15씩 내리며, 이유는 stale, incorrect, duplicate 중 하나로 기록합니다. (GitHub)

이 설계가 꽤 현실적인 이유는, AI 에이전트가 틀린 답을 생산하는 문제를 “더 좋은 검색”만으로 해결할 수 없기 때문입니다.
저장된 지식도 시간이 지나면 낡고, 프레임워크 버전이 바뀌면 오답이 됩니다.

즉 Cq의 핵심은 저장 자체보다도:

• 맞았던 지식은 더 강하게 만들고
• 틀린 지식은 약하게 만들며
• 오래된 지식은 경고 신호를 남기는 것

입니다.

---

4. 세션 종료 후 회고하는 reflect

이 기능이 꽤 흥미롭습니다.
Cq는 실시간 조회/제안만 하지 않고, 세션이 끝난 뒤 “이번 작업에서 공유할 가치가 있었던 인사이트”를 추출하는 회고 명령도 둡니다. cq:reflect 명령 문서는 세션 컨텍스트를 요약해서 reflect 도구에 넘기고, 후보 지식 단위를 사용자 승인 후 제안하도록 설계되어 있습니다. (GitHub)

이건 팀 운영 관점에서 중요합니다.

실무에서는 에이전트가 문제를 풀긴 풀었는데,
그 과정에서 얻은 교훈이 사라지는 경우가 많습니다.

reflect는 그걸 “작업 결과물”이 아니라
팀 자산으로 승격할 수 있는 후보로 바꿔 줍니다.

---

프로젝트 아키텍처 분석

Cq의 구조는 생각보다 깔끔합니다.
핵심은 세 개의 런타임 경계를 나누는 데 있습니다.

1. 에이전트 프로세스
   • Claude Code가 plugin 설정, skill 문서, 명령 정의를 로드
2. 로컬 MCP 서버
   • Python/FastMCP 기반
   • 개인용 SQLite 저장소 소유
3. 팀 API
   • Docker로 띄우는 FastAPI 서비스
   • 팀 공유 저장소 제공

README와 아키텍처 문서는 “Cq 코드는 에이전트 프로세스 안에서 직접 실행되지 않고, Claude Code는 설정 파일만 로드하며 실제 로직은 로컬 MCP 서버가 담당한다”고 설명합니다. 이 분리가 꽤 중요합니다. 에이전트 본체를 더럽히지 않고, 지식 시스템을 독립 서비스처럼 붙일 수 있기 때문입니다. (GitHub)

여기서 눈여겨볼 점이 몇 가지 있습니다.

로컬 우선 구조

서버 구현을 보면 query는 항상 로컬 저장소를 먼저 보고, 그다음 팀 API를 조회합니다.
팀 API가 죽어도 전체 기능이 망가지지 않도록 graceful degradation이 들어가 있습니다. TeamClient도 네트워크 오류, 타임아웃, 스키마 오류를 예외 폭발이 아니라 “원격 불가 → 로컬로 계속” 흐름으로 흡수합니다. (GitHub)

이건 제품적으로 아주 좋은 선택입니다.
에이전트 도구는 항상 붙어 있어야 하지, 인프라 의존성 때문에 툭하면 멈추면 안 됩니다.

---

제안 시 팀 우선, 실패 시 로컬 폴백

propose는 팀 API가 설정되어 있고 reachable 하면 팀으로 바로 보내고,
불가능하면 로컬에 저장합니다. 그리고 서버 시작 시 _drain_local_to_team()이 실행되어, 예전에 로컬에 임시 저장해 둔 지식을 팀 저장소로 재승격하려고 시도합니다. 즉, 오프라인이나 일시 장애 상황에서도 지식 손실 없이 나중에 올릴 수 있게 설계돼 있습니다. (GitHub)

이건 메시지 큐까지는 아니지만, “best effort sync”가 붙은 로컬 캐시형 지식 레이어라고 이해하면 됩니다.

---

지식 단위 중심 모델

아키텍처 문서에 따르면 Cq의 공통 포맷은 knowledge-unit 스키마를 중심으로 돌아갑니다. 지식 단위에는 요약, 상세 설명, 액션, 도메인 태그, 언어/프레임워크 컨텍스트, confidence, confirmation 수, first observed / last confirmed, 제안자와 승격 이력, lifecycle 정보 등이 포함됩니다. 특히 summary/detail/action의 3분할은 사람이 읽기 위한 설명이 아니라 에이전트가 곧바로 적용할 수 있는 실행형 지식을 만들기 위한 설계입니다. (GitHub)

개발자 관점에서 보면 이 스키마는 사실상 이런 철학을 담고 있습니다.

• 요약은 검색용
• 상세는 이해용
• 액션은 실행용

좋은 지식 베이스는 설명이 많은 것이 아니라
행동을 바꾸게 만드는 것이어야 합니다.

---

지식이 어떻게 흐르는가

아키텍처 문서의 핵심 시퀀스는 이렇습니다.

이 흐름이 좋은 이유는, 에이전트가 지식을 “기억”하는 게 아니라
질문 → 적용 → 검증 → 축적의 루프를 반복하기 때문입니다.
메모리보다 훨씬 운영 가능한 구조입니다. (GitHub)

---

Cq가 특히 흥미로운 지점: 3계층 지식 승격 모델

Cq 문서에서 가장 야심찬 부분은 지식 계층화입니다.

• Local
  • 개인/머신 단위 지식
  • 신뢰도 시작점 0.5
• Team
  • 조직 내부에서 공유되는 지식
  • 복수 확인으로 신뢰도 상승
• Global Commons
  • 장기적으로 지향하는 공개 공용 지식층

현재 PoC는 Local과 Team을 구현하고, Global은 장기 비전으로 제시합니다. 그리고 Team→Global 승격에는 인간 검토, 조직 컨텍스트 제거, 범용성 검증이 필요하다고 명시합니다. (GitHub)

이 모델이 중요한 이유는,
모든 지식을 곧바로 공개 공유하면 실제 회사 환경에서는 거의 못 쓰기 때문입니다.

예를 들어 이런 건 팀에선 유용하지만 글로벌로는 못 갑니다.

• 내부 인프라 타임아웃 값
• 사내 배포 환경의 특수 설정
• 특정 조직 보안 정책에 묶인 워크어라운드

반대로 글로벌로 갈 수 있는 건 이런 종류입니다.

• 특정 오픈소스 라이브러리의 버전 함정
• 널리 쓰이는 API의 비문서화 동작
• 여러 팀이 재확인한 일반적 빌드/CI 문제

즉 Cq는 처음부터 공개 지식과 조직 지식을 섞지 않도록 설계하고 있습니다.

---

안전성과 신뢰를 어떻게 다루는가

이 프로젝트가 단순한 메모장보다 한 단계 위에 있는 이유는 신뢰 모델을 따로 설계했다는 점입니다.

아키텍처 문서는 trust layer에서 다음 요소를 다룹니다.

• DID 기반 contributor traceability
• 다양한 조직과 모델 계열에서 온 confirmation 가중치
• 이상 기여 탐지
• HITL review
• guardrails 필터링

특히 문서는 “평판이 높다고 검토를 덜 받는 구조가 아니라, 모든 지식 단위는 동일한 검토를 거친다”고 설명합니다. 또 다수 확인도 같은 조직/같은 모델 편향으로 몰리는 걸 막기 위해 다양성을 중요한 신호로 봅니다. (GitHub)

이건 꽤 좋은 감각입니다.
AI 지식 공용층은 잘못 설계하면 금방 오염됩니다.

예를 들어 “우리 서비스 써라” 같은 자기 홍보형 지식이나
틀린 workaround가 대량으로 들어오면, 에이전트 생태계 전체 품질이 오염될 수 있습니다.

그래서 Cq는 처음부터:

• anti-poisoning
• human-in-the-loop
• provenance
• staleness 관리

를 아키텍처 레벨에서 다룹니다.
이건 단순 기능보다 더 중요한 설계 포인트입니다. (GitHub)

---

실제로 언제 쓰면 좋은가

1. 팀이 여러 AI 에이전트를 동시에 쓰는 경우

Copilot, Claude Code, OpenCode, 내부 에이전트가 뒤섞인 환경에서는 같은 함정을 여러 번 밟기 쉽습니다. Cq 같은 공용 지식층이 있으면 “팀이 이미 겪은 삽질”을 에이전트가 재사용할 수 있습니다. (GitHub)

2. 문서보다 실전 함정이 더 중요한 스택

공식 문서만 읽어서는 안 나오는 API edge case, CI 설정 함정, 빌드 툴 quirks가 많은 환경에서 특히 유용합니다. Cq의 예시들도 Stripe, webpack, GitHub Actions 같은 영역을 중심으로 제시됩니다. (GitHub)

3. 조직별 컨텍스트가 중요한 경우

RAG나 일반 검색은 공개 문서에는 강하지만, “우리 팀에서는 이 환경에서 이렇게 해야 함” 같은 운영 지식에는 약합니다. Team tier는 바로 그 조직 특화 지식을 쌓는 층으로 설계돼 있습니다. (GitHub)

4. AI 도입이 늘수록 실패 비용이 커지는 조직

에이전트 한두 개가 아니라 수십 개가 같은 실수를 반복하면, 그건 생산성 이슈가 아니라 운영 이슈입니다. Cq는 그 중복 실패를 줄이는 데 초점이 있습니다. (GitHub)

---

간단한 사용 시나리오

아래는 개발자 입장에서 상상하기 쉬운 흐름입니다.

# Claude Code 플러그인 설치
claude plugin marketplace add mozilla-ai/cq
claude plugin install cq

{
  "env": {
    "CQ_TEAM_ADDR": "http://localhost:8742",
    "CQ_TEAM_API_KEY": "your-api-key"
  }
}

# 팀 API 실행용 docker compose
docker compose up

README와 compose 파일 기준으로 팀 API는 기본적으로 8742 포트를 사용하고, 로컬 DB 경로는 ~/.cq/local.db이며, Docker 구성에는 cq-team-api와 cq-team-ui 서비스가 포함되어 있습니다. 다만 현재 UI 쪽은 저장소상 템플릿 성격이 더 강하고, 실제 아키텍처의 중심은 MCP 서버와 Team API입니다. (GitHub)

그리고 에이전트 행동은 대략 이렇게 바뀝니다.

# 1) 낯선 작업 시작 전
query(domain=["ci", "github-actions", "rust"])

# 2) 지식 적용 후 검증
confirm(unit_id="ku_12345")

# 3) 새로 발견한 인사이트 저장
propose(
    summary="rust-toolchain.toml and matrix toolchain can conflict",
    detail="When matrix-driven toolchain selection is used, repo-level toolchain files may be ignored or conflict depending on setup.",
    action="Use a single source of truth for toolchain selection and verify which layer wins in CI.",
    domain=["ci", "github-actions", "rust"]
)

이런 패턴이 조직에 자리 잡으면, 에이전트는 단순히 코드 생성기가 아니라
팀의 축적된 시행착오를 소비하는 실행 주체가 됩니다.

---

이 프로젝트의 한계도 분명하다

좋은 아이디어라는 것과, 당장 대규모 실전에서 검증됐다는 것은 다릅니다.

현재 공개 저장소 기준 Cq는 exploratory, 즉 실험적 단계로 명시돼 있고, PoC 성격이 강합니다. Team 저장소 설명에서도 README는 SQLite를, 아키텍처 문서는 장기적으로 Hosted FastAPI + Postgres를 언급하는 등 일부는 비전과 현재 구현이 함께 존재합니다. 즉, “완성된 표준”이라기보다는 표준 후보이자 참조 구현으로 보는 편이 맞습니다. (GitHub)

또 현실적인 질문도 남아 있습니다.

• 지식 단위가 얼마나 빨리 낡는가
• 누가 검토 비용을 부담하는가
• 팀별 민감 정보를 얼마나 잘 제거할 수 있는가
• 에이전트가 너무 자주 query 하면서 오히려 흐름을 깨지 않는가
• 지식 중복과 충돌을 어떻게 정리할 것인가

하지만 재미있는 건, 이 질문들이야말로 이 프로젝트가 진짜 문제를 건드리고 있다는 증거라는 점입니다.

---

한 줄로 정리하면

Cq는 “AI 에이전트를 위한 Stack Overflow”라고 부를 수는 있지만,
정확히 말하면 에이전트가 실패를 재발명하지 않도록 만드는 공유 학습 인프라입니다.

그리고 더 본질적으로는 이런 메시지를 던집니다.

앞으로 중요한 것은 모델을 잘 쓰는 것만이 아니라,
에이전트가 팀의 경험을 어떻게 학습하고 재사용하게 만들 것인가다.

그 관점에서 Cq는 아직 실험적이지만, 방향은 아주 선명합니다.
AI 코딩 도구의 다음 경쟁력은 “더 긴 컨텍스트”가 아니라
더 좋은 집단 학습 구조일 수 있습니다. (GitHub)