텐센트, 팀 단위 AI 에이전트 미들웨어 TeamAI-CLI 오픈소스

서문

"AI Agent의 능력은 각자 자신의 대화 기록 속에 갇혀 있어서는 안 되며, 팀의 공동 자산이 되어야 한다."

이것은 "하루에 하나씩 오픈소스 프로젝트" 시리즈의 第 223 篇입니다. 오늘의 프로젝트는 TeamAI-CLI입니다.

팀의 모든 구성원이 Claude Code, Cursor, Codex로 코드를 작성할 때, 숨겨진 문제가 발생하고 있습니다. 바로 모두가 각자 독립적으로 자신의 AI를 "학습"시키고 있다는 점입니다. 장싼(张三)은 반나절을 들여 Claude Code가 프로젝트 아키텍처를 올바르게 이해하도록 만드는 Prompt 기술을 터득했지만, 리쓰(李四)는 같은 함정을 만나고도 전혀 알지 못한 채 다시 한 번 밟아야 합니다. 팀 곳곳에 흩어진 Skills, Rules, CLAUDE.md 설정은 각자 따로 싸우고 있으며, 통일된 배포와 동기화 메커니즘이 없습니다.

TeamAI-CLI가 바로 이 문제를 해결하려 합니다. 이것은 또 하나의 AI 프로그래밍 보조 도구가 아닙니다. 프로젝트 문서는 Claude Code, Codex, Cursor 같은 도구들을 경쟁 상대가 아니라 명확히 자신의 "호환 대상"으로 규정하고 있습니다. 이것은 여러분이 이미 사용 중인 AI 도구 위에 얹히는 한 층의 메타 관리 시스템 으로서, 기술과 규칙, 지식 베이스를 팀 구성원 사이에 동기화·배포하고, 개인이 AI를 사용하는 과정에서 축적한 경험을 팀 공유 자산으로 만드는 역할을 담당합니다.

4.8k Stars, MIT 라이선스, TypeScript 개발.

배우게 될 내용

- TeamAI-CLI의 3계층 제품 아키텍처: Team Execution / Team Context / Team Improvement

- push → MR → 검토 병합 → SessionStart hook 자동 동기화의 배포 흐름

- "마찰 신호"(friction) 기반으로 경험을 자동 축적하는 메커니즘

- 코드베이스 지식 그래프(tree-sitter AST + 정규식 휴리스틱)의 구축 방식

- Claude Code, Codex 등 도구와의 관계: 대체가 아니라 "팀 계층"

사전 지식

- Claude Code, Cursor 또는 Codex 같은 AI 코딩 도구를 사용해 본 경험

- Git 워크플로(branch, Merge Request)에 대한 이해

- 선택 사항: MCP(Model Context Protocol)의 기본 개념에 대한 이해

프로젝트 배경

프로젝트 소개

TeamAI의 공식 포지셔닝은 "팀이 어떻게 AI를 사용하고, AI를 학습하며, 지속적으로 AI를 활용해 자신을 개선해 나가는지에 대한 공유 기반"(the shared foundation for how your team works, learns, and improves with AI)입니다. 핵심 이념을 한 문장으로 요약하면 다음과 같습니다. 개인의 AI 활용 능력을 팀 공유 능력으로 전환하고, Agent 간·머신 간·팀 구성원 간에 이를 관통시킨다 .

팀 및 프로젝트 정보

- 소속 조직 : Tencent(텐센트)

- 라이선스 : MIT License

- 주요 언어 : TypeScript

- 배포 방식 : npm 전역 설치( teamai-cli )

프로젝트 데이터

- ⭐ GitHub Stars: 4,800+

- 🍴 Forks: 340+

- 👀 Watchers: 17

- 📄 라이선스: MIT

- 🔧 Open Issues: 33, Open PR: 14(활발히 유지보수 중)

주요 기능

어떤 문제를 해결하는가

TeamAI가 없는 팀의 현실: 장싼의 Claude Code에는 완벽한 프로젝트 규칙 한 세트가 설정되어 있음 ← 장싼의 로컬에만 존재 리쓰는 사흘 동안 함정을 파헤치고 나서야 AI가 코드 아키텍처를 올바르게 이해하게 하는 방법을 알아냄 ← 경험이 전달되지 않음 왕우(王五)의 CLAUDE .md와 팀 규범은 이미 오래전에 낡아버림 ← 아무도 동기화해 갱신하지 않음 ↑ 각자의 AI 능력은 서로 고립되어 있고, 팀 전체의 능력에는 복리가 없음 TeamAI의 방식: 통일된 팀 리소스 저장소(Skills/Rules/Docs/Agents/Hooks/MCP) ↓ teamai push(공유) → MR 검토 → 병합 ↓ SessionStart hook이 자동으로 teamai pull(동기화)을 트리거 모든 팀 구성원의 로컬 AI 도구가 최신 팀 규범을 자동으로 받아감 ↑ 개인 경험 → 팀 자산, AI 능력을 코드처럼 버전 관리·검토·배포 가능

사용 시나리오

기술 리드가 팀 AI 도구 규범을 통일

- 프로젝트 특화 코딩 규범, 아키텍처 제약을 Skills/Rules로 작성하면 한 번 설정으로 팀 전체가 동기화

신규 구성원이 기존 AI 협업 체계에 빠르게 적응

- 팀 저장소에 합류하면 로컬 AI 도구가 최신 기술 라이브러리와 컨텍스트를 자동으로 가져와, 처음부터 헤맬 필요가 없음

팀 구성원이 개인이 정리한 경험을 공유

- teamai contribute 로 AI 디버깅 중 겪은 함정 경험 하나를 클릭 한 번에 팀 전체에 공유

코드베이스 지식을 축적해 AI가 검색하도록 제공

- 지식 그래프 기능을 통해 AI가 코딩 작업을 처리하기 전에 관련 코드 배경과 과거 의사결정을 자동으로 검색할 수 있음

팀 AI 사용 현황 시각화

- dashboard와 digest 명령으로 팀 전체의 AI 사용 트렌드와 활성도를 파악

빠른 시작

방식 1: 대화형 설치(AI가 설치하도록 하기)

이 문장을 그대로 Claude Code 또는 Skills를 지원하는 다른 Agent에 붙여넣으면 됩니다.

Install the teamai skill: https://github.com/Tencent/teamai-cli/tree/main/skills/teamai , load the teamai skill, then set up TeamAI for my team from scratch.

방식 2: 명령줄 수동 설치

관리자: 팀 공유 저장소 생성 npm install -g teamai-cli teamai init https://github.com/yourorg/yourrepo # 팀 구성원: 기존 팀에 합류 cd /path/to/my-project teamai init https://github.com/yourorg/yourrepo # 또는 사용자 레벨 설치(프로젝트를 넘어 적용) teamai init https://github.com/yourorg/yourrepo --scope user

핵심 특징

1. 3계층 제품 아키텍처

계층 포지셔닝 핵심 역량 Team Execution "모든 Agent가 팀 방식으로 일하게 한다" Skills/Rules/Agents/Hooks/MCP/Env의 init/pull/push 동기화 Team Context (beta) "모든 Agent가 팀을 이해하게 한다" 지식 회상 recall, 경험 학습 learnings, 코드베이스 지식 그래프, 팀 Wiki Team Improvement (beta) "매 실행이 팀에 환류되게 한다" 마찰 신호 기반 경험 공유, 세션 기록, 주간 리포트 요약, 사용 대시보드

2. Git화된 배포 흐름

teamai push → branch + MR 생성 → reviewer 검토 병합 ↓ SessionStart hook이 자동으로 teamai pull 트리거 → 로컬 AI 도구로 동기화

GitHub, GitLab, GitCode, CNB, TGit 및 사설 Git 서비스를 지원하며, 본질적으로는 AI 협업 규범을 정상적인 Code Review 흐름에 편입시키는 것입니다.

3. 자주 쓰는 명령 한눈에 보기

명령 기능 teamai init 초기화: OAuth 로그인, 저장소 연결, 구성원 등록, hook 주입 teamai pull / push 팀 리소스 가져오기/올리기 teamai status 로컬과 팀 저장소의 차이 표시 teamai contribute 세션 경험을 팀 저장소에 공유 teamai recall <query> 팀 지식 베이스 검색(BM25 + 지식 그래프 강화) teamai codebase --extract/--deep-enrich/--reconcile 코드베이스 지식 그래프 작업 teamai digest / dashboard 팀 사용 데이터 통계 및 시각화 teamai doctor 설정 문제 진단

4. 폭넓은 Agent 호환 매트릭스

TeamAI-CLI는 Claude Code, Codex, Cursor, GitHub Copilot CLI, CodeBuddy, OpenCode, Kiro 등 십여 종의 AI 코딩 도구와의 호환을 명확히 선언하고 있으며, 각 도구가 지원하는 능력 항목(skills/rules/docs/env/hooks/mcp)은 문서에 상세한 호환 표로 정리되어 있습니다.

심층 분석

"마찰 신호"가 이끄는 경험 축적 메커니즘

TeamAI-CLI의 가장 흥미로운 설계는 Team Improvement 계층의 트리거 로직입니다. 사용자가 능동적으로 경험을 기록하도록 요구하지 않고, 세션 내의 마찰 신호를 모니터링 하여 "여기에 기록할 만한 일이 발생했다"고 판단합니다.

마찰 신호의 예: "사용자가 AI를 두 번 중단시켰다" "AI가 실패한 동일한 도구 호출을 연속 8회 재시도했다" ↓ 시스템이 비정상적 마찰을 인식 ↓ 사용자에게 안내: "이번 디버깅 과정에 공유할 만한 경험이 있는 것 같습니다. 팀에 기여하시겠습니까?"

이 설계는 "직원에게 정기적으로 주간 보고서를 작성해 경험을 정리하라고 요구"하는 것보다 훨씬 영리합니다. 대부분의 가치 있는 함정 경험은 문제를 해결하는 과정에서 발생하는데, 사후에 회상하면 대개 세부 사항을 잃어버리기 때문입니다. 상호작용 마찰을 신호로 삼아 포착을 트리거하면, 경험이 가장 신선한 순간에 축적을 완료할 수 있습니다.

코드베이스 지식 그래프: 이중 트랙 추출 전략

Team Context 계층의 코드베이스 지식 그래프 구축에는 이중 트랙 전략이 사용되었습니다.

AST Track(정확하지만 비용이 큼) tree-sitter WASM 파서로 코드를 파싱 ↓ 함수, 클래스, 의존 관계를 정확히 추출 ↓ 핵심 모듈의 심층 파싱에 적합 Heuristic Track(빠르지만 입자가 굵음) 정규식 휴리스틱으로 코드를 스캔 ↓ 대범위 파일을 빠르게 커버 ↓ 주변부 코드의 빠른 인덱싱에 적합 두 트랙의 결과 → teamwiki/ 디렉터리에 기록 → recall 명령의 BM25 검색 강화에 제공

이 이중 트랙 설계의 취사선택은 매우 현실적입니다. 거대한 전체 코드베이스에 tree-sitter 수준의 정확한 AST 파싱을 하는 것은 비용이 매우 크고, 순수 정규식 매칭은 시맨틱 관계를 잃어버립니다. 둘을 결합해 핵심 모듈은 정확히 파싱하고 주변부 코드는 빠르게 커버하는 것은 실용적인 절충안입니다.

Claude Code, Codex와는 어떤 관계인가

이것은 TeamAI-CLI를 이해할 때 가장 혼동하기 쉬운 점으로, 명확히 해명할 필요가 있습니다.

잘못된 이해: TeamAI-CLI는 Claude Code의 경쟁 상대이며, 새로운 AI 프로그래밍 CLI 도구다 올바른 이해: TeamAI-CLI는 Claude Code/Codex/Cursor 위에 얹히며, 팀 레벨의 리소스 배포 및 지식 관리 계층 이다 유추: Claude Code / Codex / Cursor ≈ 각자 컴퓨터의 IDE TeamAI-CLI ≈ 팀의 Git 저장소 + Code Review 흐름 (단, 대상은 Skills/Rules/지식이고 코드가 아니다)

이것은 이미 설치된 AI 도구에 hook(예: SessionStart hook)과 공유 설정 파일(CLAUDE.md, Skills 디렉터리 등)을 주입하는 방식으로 작동하며, 그 자체로는 추론 능력을 제공하지 않고 "누가 어떤 규칙을 써야 하고, 언제 동기화할 것인가"라는 일을 조율합니다.

유사 팀 협업 도구와의 비교

차원 수동 유지보수 CLAUDE.md Cursor Rules(로컬) TeamAI-CLI Agent 간 호환 각 도구가 자체 구현에 의존 Cursor 전용 ✅ 십여 종 도구 팀 동기화 메커니즘 수동 복사·붙여넣기/구두 전달 ❌ 없음 ✅ Git push/pull + MR 검토 경험 자동 축적 ❌ ❌ ✅ 마찰 신호 기반 코드 지식 그래프 ❌ ❌ ✅ AST + 휴리스틱 이중 트랙 사용 데이터 시각화 ❌ ❌ ✅ dashboard/digest 버전 관리 및 검토 수동 로컬 파일, 검토 없음 ✅ 표준 Git 흐름 준수

TeamAI-CLI의 차별점은 "AI 협업 규범"을 일등 시민으로서 소프트웨어 공학의 표준 흐름(버전 관리, Code Review)에 편입시키는 데 있으며, 각자가 자기 로컬 설정 파일을 스스로 유지보수하게 두지 않는 것입니다.

프로젝트 주소 및 리소스

공식 리소스

- 🌟 GitHub : github.com/Tencent/tea…

- 📦 npm 패키지 : teamai-cli

- 🐛 Issues : GitHub Issues

관련 리소스

- tree-sitter — TeamAI-CLI 코드 지식 그래프 AST Track에서 사용하는 파서 프레임워크

- Model Context Protocol — TeamAI-CLI 호환 매트릭스에 포함된 MCP 리소스 배포 표준

- Claude Code — TeamAI-CLI가 주로 적응(어댑팅)한 AI 코딩 Agent 중 하나

총괄 및 전망

핵심 요점 되돌아보기

- AI 프로그래밍 어시스턴트가 아니라 팀级 미들 레이어다: Claude Code/Codex/Cursor 등의 도구 위에 얹혀 있으며, 코드 생성이 아니라 규범 동기화를 담당한다

- 3계층 아키텍처가 단계적으로 심화된다: Team Execution은 배포를, Team Context는 이해를, Team Improvement는 진화를 관리한다

- Git화된 배포 프로세스: push → MR 검토 → 병합 → hook 자동 동기화로, AI 협업 규범이 표준 소프트웨어 공학 프로세스를 따른다

- 마찰 신호 기반 경험 포착: 수동 정리에 의존하지 않고, 상호작용 이상(異常)을 통해 경험 축적을 자동으로 촉발한다

- 10여 종의 Agent 호환: 단일 AI 도구 생태계에 묶이지 않고 Claude Code, Codex, Cursor 등 주류 선택지를 포괄한다

누구에게 적합한가

- 기술 팀 리더: 팀의 AI 협업 규범을 통일하고 싶지만, 각자가 알아서 시행착오를 겪게 하고 싶지 않은 사람

- 중대형 엔지니어링 팀: 여러 구성원이 서로 다른 AI 도구를 사용해, 중립적인 규범 동기화 계층이 필요한 경우

- 지식 관리를 중시하는 팀: 시행착오 경험과 코드 지식을 체계적으로 축적해, 인력 이동에 따라 유실되지 않게 하고 싶은 팀

- 이미 Claude Code/Cursor 등의 도구를 쓰고 있는 팀: 도구를 바꾸고 싶지 않고, 기존 도구를 더 똑똑하고 더 일관되게 쓰고 싶을 뿐인 팀

한마디 평가

TeamAI-CLI가 해결하려는 것은 "AI가 어떻게 코드를 작성하는가"가 아니라 "팀 안에서 각자의 AI 경험이 어떻게 모두의 경험이 되는가"이다 — 이것은 단순히 더 강력한 모델을 쌓아 올리는 것보다 주목할 가치가 있는 방향일 수 있다.

PrimeSkills를 방문해 보시기 바랍니다 — 실제 엔터프라이즈급 워크플로로 검증된, 세심하게 큐레이션된 AI Agent 및 스킬 마켓입니다. 과장은 없고, 정말로 효과가 있는 것만 있습니다.

더 많은 실용 지식과 흥미로운 제품은 제 개인 홈페이지를 방문해 주시기 바랍니다.

冬奇Lab

소프트웨어 아키텍처

513

글

326k

조회

755

팔로워