trycompai/crm 딥다이브
— "에이전트가 제품이고, 데이터베이스는 그 에이전트가 메모를 적는 곳이다"

1한 줄 정체

trycompai/crm은 "영업 담당자가 연락처·회사·거래 정보를 손으로 채우는 대신, 스스로 도는 리서치 에이전트가 이메일 스레드·회의·서명란·웹을 뒤져 '이 사람이 누구인지'를 알아내고 증거와 함께 기록하는, 에이전트 우선(agentic-first)의 오픈소스 CRM"이다. 핵심 뒤집기 한 줄로 요약하면 — 에이전트는 CRM의 기능이 아니라, CRM이 에이전트의 메모장이다.

연락처 하나가 새로 생겼을 때 시스템 안에서 벌어지는 일을 압축하면 이렇다. 왼쪽(전통 CRM)과 오른쪽(이 레포)의 대비가 핵심이다:

오른쪽 흐름의 각 마디 — 큐, lease, 조사 세션, 증거 원장 — 가 이 레포에서 배울 만한 설계의 전부다. 4장에서 하나씩 뜯어본다.

2왜 주목받는가 — "폼을 채우지 말고, 에이전트가 알아내게 하라"

이 레포가 뜬 이유는 기능이 많아서가 아니다. 별(star)은 이 글을 쓰는 시점에 아직 두 자릿수인 신생 저장소다(TrendShift의 굵은 숫자는 별 수가 아니라 모멘텀 점수다). 뜨는 이유는 "AI를 CRM에 어떻게 붙일 것인가"에 대한 지금까지의 답을 정면으로 반박하기 때문이다.

README의 표현을 빌리면: "대부분의 CRM은 앞에 폼을 세운 데이터베이스다. AI CRM은 그 폼 옆에 챗박스를 볼트로 조여 붙인다. 둘 다 진짜 일 — 무엇이 사실인지 알아내고 그것을 적어 두는 일 — 은 더 나은 할 일이 있는 사람에게 떠넘긴다." 이 레포는 그 "진짜 일"을 제품의 중심에 놓았다.

주목 포인트 ① — API에는 지능을 절대 두지 않는다

백엔드(NestJS API)는 일부러 아무 판단도 하지 않는다. 스레드가 하나 수집됐다, 회사가 생성됐다, 참석자가 누군지 모른다 — 이런 "무슨 일이 일어났다"를 큐에 한 행 적을 뿐이다. 그 행이 무슨 의미인지는 에이전트가 lease해서 결정한다. Nest 서비스가 직접 enrichment API를 호출하면 그것은 버그로 취급된다. 왜 이런 규칙이 생겼는지는 docs/api.md에 "그 규칙을 만들게 한 장애(outage)" 일화로 남아 있다.

주목 포인트 ② — 확신도를 입력받지 않는 "증거 원장"

이 레포에서 가장 배울 만한 설계다. 어떤 도구도 confidence: 0.9 같은 값을 받지 않는다. 이유가 날카롭다:

주목 포인트 ③ — 유출 불가능한 모양의 샌드박스

에이전트에게 셸(bash·grep·glob)과 /workspace를 주되, 샌드박스는 deny-all 이그레스(egress) — 바깥으로 나가는 네트워크가 완전히 차단된다. 게다가 샌드박스에는 DATABASE_URL을 절대 넘기지 않는다. 크레덴셜과 송신 경로를 둘 다 가진 셸은 "유출 모양(exfiltration-shaped)"이지만, 둘 다 없는 셸은 그냥 텍스트 처리기다. 고객 이메일 본문이 셸 명령으로 빠져나갈 유일한 경로를 구조적으로 없앤 것이다.

주목 포인트 ④ — 단일 테넌트, 그리고 그것을 자랑으로 여김

이 CRM은 의도적으로 단일 테넌트(single-tenant)·내부 전용이다. 로그인은 Google 하나, 접근 허용 목록은 환경변수 딱 하나(ALLOWED_SIGN_IN), 들어온 사람은 전부 다 본다. "항상 같은 값인 organizationId는 컬럼 하나, 인덱스 하나, 권한 체크 하나를 늘리면서 아무것도 사주지 못한다"는 이유로 조직(organization) 개념 자체를 뺐다. 스타트업 하나가 자기 영업에 쓰려고 만든 물건이라는 정직함이, 역설적으로 설계를 날카롭게 만든다.

3기술 스택 전체 지도

한마디로 "Vercel 생태계로 끝까지 밀어붙인 TypeScript 모노레포"다. 런타임은 Node가 아니라 Bun, 빌드 오케스트레이션은 Turborepo, 세 개의 앱과 다섯 개의 공유 패키지가 하나의 저장소에 산다.

스택 한눈에 (README stack 표 + 실제 버전)

왜 이 조합인가 — "관리할 키가 없다"

눈에 띄는 선택은 Vercel AI Gateway다. OpenAI/Anthropic SDK를 직접 붙이지 않고 게이트웨이를 거치면, Vercel 위에서는 OIDC로 인증되어 API 키를 코드나 환경변수에 둘 필요가 없다. 모델 선택은 DB 설정(AppSetting)에서 읽어 세션 시작 때 동적으로 바뀐다(lib/model.ts의 selectedModel()). 무거운 GPU도, 모델 프로바이더 계정도 이 앱이 직접 들고 있지 않다.

4아키텍처 심화 — 일 큐, 증거 원장, deny-all 샌드박스

시스템 구조도 — 세 개의 배포판과 한 개의 Postgres

앱(Next.js)·API(NestJS)·에이전트(eve)는 서로 독립된 세 배포판이고, 이들이 반드시 합의해야 하는 건 DATABASE_URL과 BETTER_AUTH_SECRET 둘뿐이다. 모든 소통은 Postgres를 통해 간접적으로 일어난다.

패턴 ① — 자기 자신을 돌리는 일 큐 (Postgres FOR UPDATE SKIP LOCKED)

에이전트는 크론 표현식으로 "매 N분마다 오래된 연락처 10명" 같은 걸 하지 않는다. 그런 건 전부 각 작업의 dueAt(마감 시각)에 들어간다. 스케줄러(dispatch.ts)는 매분 깨어나 지금 마감된 일만 lease한다.

// lib/tasks.ts — 마감된 일을 원자적으로 lease (핵심만)
export async function claimDue(limit) {
  return db.$queryRaw<LeasedTask[]>`
    UPDATE "agentTask" AS t
    SET "leasedUntil" = ${until},                 -- 10분 임대
        "attempts"    = t."attempts" + 1
    FROM (
      SELECT id FROM "agentTask"
      WHERE "finishedAt" IS NULL
        AND "dueAt" <= ${now}                      -- 지금 마감된 것만
        AND ("leasedUntil" IS NULL OR "leasedUntil" < ${now})
        AND "attempts" < 3                         -- 3번 실패하면 포기
      ORDER BY "priority" DESC, "dueAt" ASC
      LIMIT ${limit}
      FOR UPDATE SKIP LOCKED                     -- 겹치지 않게 나눠 집기
    ) AS due
    WHERE t.id = due.id
    RETURNING t.id, t."contactId", t.kind, t.reason, t.budget;`;
}

에이전트가 나중에 이 사람을 또 보고 싶으면 schedule_recheck를 호출하며 이유를 적는다 — 그리고 그 이유가 담당자에게 그대로 보인다. "14일 뒤에 다시 볼게요"라고만 하고 이유를 못 대는 에이전트는 이유가 있는 게 아니라 그냥 기본값을 쓰는 것이기 때문이다.

패턴 ② — 확신도를 안 받는 증거 원장 (evidence.ts)

2장에서 예고한 그 원장이다. 증거는 종류(kind)별로 무게가 코드에 박혀 있고, 여러 증거는 확률적으로 결합된다. 핵심은 "독립된 소스 하나당 증거 한 개" — 같은 페이지에서 이름과 회사가 둘 다 맞는 건 증거 두 개가 아니라 한 개다(안 그러면 한 페이지를 이중으로 세어 거짓 확신이 된다).

// evidence.ts — 증거 무게(일부)와 결합
WEIGHTS = {
  "profile.email-match":        { weight: 0.95, primary: true },  // 프로필에 그 이메일
  "linkedin.employer-and-name": { weight: 0.85, primary: true },  // 이름+회사 동시 일치
  "crm.signature-block":        { weight: 0.80, primary: true },  // 본인 서명란
  "github.account-identity":    { weight: 0.80, primary: true },
  "web.cited-claim":            { weight: 0.40, primary: false }, // 보조: 혼자선 부족
  "employer-only":              { weight: 0.20, primary: false }, // 회사만 맞음(거의 무의미)
  "contradiction":              { weight: 0.00 },                // 모순: 통째로 hold
};

// 결합: 1 - ∏(1 - wᵢ)  → 증거가 쌓일수록 1에 수렴, 상한 0.99
score = 1 - evidence.reduce((rem, e) => rem * (1 - WEIGHTS[e.kind].weight), 1);
// primary 증거 없이 높은 점수만으로는 VERIFIED가 안 됨
band  = score >= 0.85 && hasPrimary ? VERIFIED
      : score >= 0.55 ? PROBABLE
      : score >= 0.30 ? POSSIBLE : null;

패턴 ③ — 유출 불가능한 모양의 샌드박스 (sandbox.ts)

단 8줄이지만 보안 사고방식이 압축돼 있다. 세 실행 백엔드(Vercel/Docker/microsandbox) 전부에 나가는 네트워크 전면 차단을 건다.

// sandbox/sandbox.ts — 전부
export default defineSandbox({
  backend: defaultBackend({
    vercel:       { networkPolicy: "deny-all" },
    docker:       { networkPolicy: "deny-all" },
    microsandbox: { networkPolicy: "deny-all" },
  }),
});

차단이 공짜인 이유가 영리하다. web_fetch는 앱 런타임에서, web_search는 모델 공급자 쪽에서 돈다 — 즉 바깥과 통신하는 도구들은 애초에 샌드박스 밖에 있다. 그래서 샌드박스에서 네트워크를 없애도 기능은 그대로고, 사라지는 건 딱 하나 — 고객 이메일 본문이 셸 명령으로 빠져나갈 경로다. 여기에 "샌드박스에는 DATABASE_URL을 절대 주지 않는다"가 더해지면, 셸은 크레덴셜도 송신 경로도 없는 순수 텍스트 처리기가 된다.

패턴 ④ — API에는 지능이 없다 (이벤트만 기록)

NestJS API의 agent/ 모듈은 agent-queue.service와 agent-trigger.service뿐이다. 하는 일은 "연락처가 생겼다 → agentTask 한 행 넣기". 판단(누구인지, 무엇을 조사할지)은 전부 에이전트 몫이다. 이 경계가 흐려지면 무슨 일이 생기는지 docs/api.md가 증언한다: "신원 매처가 두 벌로 복제됐다가 서로 갈라져, 결국 한쪽이 지구상 모든 고용주를 일치로 판정했다." 지능을 한 곳(에이전트)에만 두는 이유다.

5디렉토리 구조 해부

에이전트 도구 19개 — 몇 개만 골라 보면

6학습 포인트 — 기술별 배울 것

이 저장소는 "CRM 만드는 법"보다 "에이전트를 신뢰할 수 있게 만드는 법"의 교재에 가깝다. 층별로 배울 것을 정리한다.

7시스템 / 배포 요구사항

로컬 구동에 필요한 것

• Bun(1.3.12)과 Docker — 그게 전부의 시작점.
• Postgres는 docker compose up -d로 즉시(포트 5432, postgres 17-alpine).
• Node ≥22(engines에 명시).
• 무거운 GPU·로컬 모델 불필요 — 추론은 Vercel AI Gateway 뒤에서 일어난다.

딱 4개의 필수 환경변수

DATABASE_URL은 docker compose Postgres에 이미 맞춰져 있어 손댈 필요가 없다. Google 로그인이 유일한 문이므로, 이 값들이 없으면 API가 아예 뜨지 않는다(안전한 방향).

선택 능력(capabilities) — 없어도 돌아간다

핵심 설계 철학: 외부 소스는 전부 선택이며, 하나도 없어도 작동한다. 에이전트는 세션 시작 때 "이 설치본에 무엇이 켜져 있나"를 통보받아, 없는 걸 뒤늦게 하나씩 실패로 발견하지 않고 미리 계획한다.

// 시작 로그 예시 — 켜진 능력과 꺼진 능력
[agent] on   LinkedIn (RAPIDAPI_KEY)
[agent] off  Web research (PERPLEXITY_API_KEY)
[agent] off  Company brand data (CONTEXT_DEV_API_KEY)

키가 하나도 없어도 read_crm_history가 우리 자신의 스레드·회의·서명란을 읽는다 — 공짜이고, "상대 본인 주소에서 온 답장"만큼 좋은 증거는 어떤 데이터 업체도 팔 수 없다.

실제 배포

세 배포판(app·api·agent) + Postgres 하나. 셋이 반드시 합의해야 하는 건 DATABASE_URL과 BETTER_AUTH_SECRET뿐 — 어긋나면 에러가 아니라 리다이렉트 루프로 드러난다. Gmail/Calendar 동기화를 유지하려면 CRON_SECRET을 세우고 스케줄러가 POST /internal/sync/google를 치게 한다.

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 로드맵 (주차별)

10핵심 키워드 사전

11참고 링크

• GitHub 저장소: github.com/trycompai/crm
• 만든 곳: Comp AI — 보안·컴플라이언스 자동화 스타트업
• 1차 소스: README.md(철학·스택) · docs/agent.md(에이전트 전체 서술) · docs/api.md("API에 지능 없음" 규칙) · docs/design.md · adrs/comp-palette.md
• 핵심 코드: apps/agent/agent/lib/tasks.ts(일 큐) · lib/evidence.ts(증거 원장) · schedules/dispatch.ts(디스패처) · sandbox/sandbox.ts(deny-all)
• 에이전트 프레임워크: eve(Vercel, durable agents) · 문서는 node_modules/eve/docs/에 동봉
• 인프라 문서: Vercel AI Gateway · Vercel Sandbox · Vercel Blob
• 스택 도구: nestjs-trpc · nuqs · Better Auth · Prisma · Turborepo · Bun
• 참고 개념: 지속형 에이전트, 작업 큐 & SKIP LOCKED, 증거 기반 확신(anti-hallucination), 최소권한 샌드박스, 엔드투엔드 타입 안전, 단일 테넌트 인증