이제 팀에서 AI 코딩 에이전트의 규칙을 정하다 - Tencent TeamAI
AI 코딩 도구를 팀에서 사용하기 시작하면 금방 새로운 문제가 생긴다.
누군가는 Claude Code를 사용하고, 다른 개발자는 Codex나 Cursor를 사용한다. 개발자마다 사용하는 SKILL.md, 코딩 규칙, MCP 서버, 프롬프트, 개발 지식도 달라진다.
결국 AI를 사용하면서 쌓인 경험이 개인의 로컬 환경에만 남는 문제가 발생한다.
Tencent가 공개한 TeamAI CLI는 이 문제를 해결하기 위한 오픈소스 프로젝트다.
단순한 Skill 동기화 도구라기보다는,
팀의 AI 개발 환경을 하나의 Git 저장소를 기준으로 관리하는 AI Agent Harness
에 가깝다.
현재 TeamAI는 Claude Code, Codex, Cursor, CodeBuddy, WorkBuddy, OpenCode, Qoder 등 여러 AI 개발 도구를 대상으로 Skills, Rules, Docs, Hooks, MCP, Knowledge 등을 관리하도록 설계되어 있다.
1. TeamAI가 해결하려는 문제
예를 들어 개발팀에서 Claude Code를 사용하면서 이런 Skill을 만들었다고 해보자.
skills/
├─ code-review/
├─ database-migration/
├─ deploy-production/
└─ api-design/
그리고 프로젝트 규칙도 있다.
rules/
├─ backend-style.md
├─ security-guide.md
└─ testing-guide.md
일반적으로 이런 파일들은 각 개발자의
~/.claude/
~/.codex/
~/.cursor/
같은 디렉터리에 흩어진다.
TeamAI는 이것을 중앙 Git 저장소에서 관리한다.
TeamAI Repository
│
┌─────────────┼─────────────┐
│ │ │
Skills Rules Docs
│ │ │
└─────────────┼─────────────┘
│
teamai pull
│
┌────────────────┼────────────────┐
▼ ▼ ▼
Claude Code Codex Cursor
공식 문서에서 설명하는 기본 철학 역시 One Team, One Harness, Every Agent다.
2. 설치
npm 패키지로 배포된다.
npm install -g teamai-cli
그리고 팀에서 사용할 Git 저장소를 만든다.
예를 들어:
github.com/mycompany/team-ai
이후 프로젝트에서 실행한다.
cd my-project
teamai init https://github.com/mycompany/team-ai
현재 기본 동작은 Project Scope다.
특정 프로젝트가 아니라 개발자의 모든 프로젝트에 적용하고 싶다면:
teamai init https://github.com/mycompany/team-ai --scope user
를 사용할 수 있다. Project Scope는 프로젝트 디렉터리에 리소스를 설치하고, User Scope는 ~/ 아래 AI 도구 환경에 설치하는 방식이다.
3. 핵심은 Git 기반 Push → Review → Pull
TeamAI에서 상당히 중요한 부분이다.
Skill을 중앙 저장소에 바로 덮어쓰는 구조가 아니다.
기본 흐름은 다음과 같다.
개발자
│
▼
Skill / Rule 수정
│
▼
teamai push
│
▼
Git Branch 생성
│
▼
Pull Request / Merge Request
│
▼
팀 리뷰
│
▼
Merge
│
▼
teamai pull
│
▼
팀원 AI 환경 동기화
공식 문서에서도 teamai push가 브랜치와 MR/PR을 생성하고, 리뷰 후 merge된 내용을 teamai pull로 가져오는 구조를 설명한다. 또한 AI 세션 시작 시 SessionStart Hook이 최신 리소스를 자동으로 pull할 수 있다.
따라서 Git의
Versioning
Review
History
Rollback
Access Control
을 AI 프롬프트와 Skill 관리에도 활용할 수 있다.
4. Skill만 공유하는 프로젝트가 아니다
TeamAI가 흥미로운 이유는 관리 대상이 꽤 넓기 때문이다.
공식 문서는 TeamAI 구조를 크게 세 영역으로 구분한다.
Team Execution
Team Context
Team Improvement
Team Execution
AI가 우리 팀 방식으로 일하도록 만드는 영역이다.
관리 대상은 다음과 같다.
Skills
Rules
Docs
Env
Agents
Hooks
MCP
예를 들어 모든 개발자의 AI에 동일한 보안 Hook을 배포할 수도 있다.
hooks:
- id: block-secret
description: Scan for secrets before commit
event: PreToolUse
matcher: Bash
command: ...
Hook 정의를 중앙에서 배포하고 teamai pull을 통해 각 지원 도구에 주입하는 구조다.
5. MCP도 팀 단위로 관리한다
요즘 AI 개발환경에서 상당히 유용한 부분이다.
예를 들어 회사에서 다음 MCP를 사용한다고 하자.
GitHub MCP
Database MCP
Linear MCP
Internal API MCP
GPU MCP
TeamAI에서는 mcp/mcp.yaml로 정의할 수 있다.
servers:
- name: gpu-analysis
transport: http
url: https://example.com/api/mcp
headers:
Authorization: Bearer ${GPU_ANALYSIS_TOKEN}
그리고
teamai mcp inject
등으로 지원 AI 도구들의 네이티브 설정에 반영할 수 있다.
Claude, Cursor, CodeBuddy, Codex, Qoder, OpenCode 등에 따라 실제 설정 파일 위치와 형식을 변환해서 적용한다.
6. 상당히 흥미로운 기능: Team Knowledge Recall
TeamAI는 단순 동기화를 넘어서 팀 지식 검색 기능도 제공한다.
예를 들어 팀원이 예전에
Docker 환경에서 8080 포트 충돌 해결
경험을 문서화했다고 하자.
다른 개발자가 몇 달 후 비슷한 문제를 만나면 AI가 TeamAI Knowledge Base에서 관련 정보를 검색할 수 있다.
teamai recall "port conflict"
공식 문서의 예시는 검색 결과에 작성자, 점수, 태그 등이 포함되는 형태다.
Recall 기능은 기본적으로 꺼져 있으며 명시적으로 활성화해야 한다.
teamai recall enable
활성화하면 TeamAI가 지원되는 AI 도구에 teamai-recall 서브에이전트를 배포하는 구조다.
7. 소스코드를 Knowledge Graph로 만든다
개인적으로 이 프로젝트에서 기술적으로 가장 흥미로운 부분 중 하나다.
TeamAI에는 다음 명령이 있다.
teamai import --from-repo https://github.com/company/backend
teamai import --from-org company
teamai codebase --lint
소스 저장소를 분석해서
Component
Interface
Config
Import
Dependency
Reference
Implementation
관계를 Knowledge Graph 형태로 만든다.
구조는 대략 다음처럼 볼 수 있다.
UserService
│
├── DEPENDS_ON ── UserRepository
│
├── REFERENCES ── AuthService
│
└── IMPLEMENTS ── IUserService
공식 README에 따르면 TypeScript/JavaScript, Python, Go 등에 대해서는 WASM 기반 tree-sitter AST 분석을 사용하고, 지원 범위를 보완하기 위해 heuristic 기반 분석도 병행한다. AST 분석 결과가 존재하면 해당 결과가 우선된다.
TeamAI의 현재 소스 트리에도
wiki-engine/
codebase-extract.ts
code-knowledge-recall.ts
graph-aggregate.ts
deep-enrich.ts
enrich-with-ai.ts
rebuild-wiki-index.ts
등 관련 모듈들이 존재한다.
즉 구조적으로는
Source Code
↓
AST / Heuristic Parsing
↓
Knowledge Graph
↓
Index
↓
Recall
↓
AI Agent
방향을 지향하고 있다.
8. AI와 싸운 경험도 팀 지식으로 만든다
또 하나 특이한 기능이 있다.
TeamAI는 AI 세션에서 사용자가 AI를 반복해서 수정하거나, Tool 호출을 거부하거나, AI가 실패한 Tool을 여러 번 재시도하는 등의 friction signal을 감지할 수 있다.
문제가 많이 발생한 세션이면 TeamAI가 해당 경험을 정리해 팀과 공유하도록 제안한다.
개념적으로 보면:
AI 작업
↓
문제 발생
↓
사용자가 AI 수정
↓
문제 해결
↓
Learning 생성
↓
Team Repository
↓
다른 AI Agent가 Recall
이라는 피드백 루프가 된다.
[Inference] 이 구조의 핵심 가치는 한 개발자가 AI와 시행착오를 겪으며 알아낸 해결 방법을 다른 팀원이 다시 동일하게 시행착오하지 않도록 만드는 것에 있다.
9. Role과 Tag 기반 배포도 가능하다
모든 Skill을 모든 사람에게 배포할 필요는 없다.
예를 들어:
Backend
Frontend
DevOps
Designer
PM
마다 필요한 Skill이 다르다.
TeamAI에서는 Role과 Tag 기반 필터링을 지원한다.
teamai roles
teamai tags
그리고 외부 Skill Repository도 추가할 수 있다.
teamai source add \
https://github.com/other-team/teamai-public.git \
--name other-team
따라서 조직 규모가 커지면
Company AI Repo
│
┌──────┼─────────┐
│ │ │
Backend Frontend DevOps
│ │ │
Skills Skills Skills
형태로 구성하는 것도 가능하다.
10. Single Repo Mode도 지원한다
별도의 TeamAI 저장소를 만들지 않고 기존 프로젝트 자체를 TeamAI 저장소로 사용하는 방식도 있다.
cd my-project
teamai init .
특정 AI만 지정할 수도 있다.
teamai init . --agent claude,codex
이 경우 프로젝트의 .teamai/에 Knowledge와 설정이 들어가며, reports와 machine-local 데이터는 서로 다른 방식으로 관리된다. 공식 문서는 지식 리소스와 teamai.yaml은 main branch에 두고, reports는 별도 orphan branch, 로컬 설정과 token 등은 gitignored machine-local 영역으로 구분한다고 설명한다.
작은 팀이나 개인 프로젝트에서는 이 방식이 꽤 단순하다.
11. 지원하는 AI 도구
현재 README에는 주요 기능을 폭넓게 지원하는 도구로 다음이 표시돼 있다.
Claude Code
Codex
Cursor
CodeBuddy
Qoder
그 외에도
WorkBuddy
OpenCode
OpenClaw
Hermes
DeepSeek Harness
등이 포함돼 있으며, 도구마다 지원되는 Agents·Hooks·MCP·Dashboard 등의 범위에는 차이가 있다.
따라서 TeamAI의 장점 중 하나는
Claude 전용 Skill 관리 시스템
이 아니라
AI Agent Independent Harness Layer
를 지향한다는 점이다.
12. 내부 구현
프로젝트는 TypeScript 기반 CLI다.
현재 package.json 기준 주요 기술 스택은:
TypeScript
Node.js
Commander
simple-git
Zod
YAML
TOML
Vitest
tsup
이며 ESM 형태로 빌드된다.
소스도 기능별로 상당히 명확하게 분리돼 있다.
src/
├─ providers/
├─ resources/
├─ wiki-engine/
├─ ci/
├─ maintenance/
│
├─ init.ts
├─ pull.ts
├─ push.ts
├─ contribute.ts
├─ codebase-extract.ts
├─ code-knowledge-recall.ts
├─ dashboard.ts
├─ digest.ts
├─ hooks.ts
├─ mcp-reconcile.ts
└─ doctor.ts
즉 크게 보면
CLI
│
├── Git Provider Layer
│
├── Resource Sync Engine
│
├── Agent Adapter Layer
│
├── Hook / MCP Reconciler
│
├── Knowledge Engine
│
└── Dashboard / Analytics
형태로 이해할 수 있다.
13. 보안 측면에서 반드시 알아야 할 부분
MCP Secret 처리 부분은 특히 주의해야 한다.
TeamAI는 ${VAR} 형태로 Secret을 지정할 수 있지만, 실제 AI 도구의 설정 파일을 생성할 때 환경변수를 해석해서 실제 값을 설정 파일에 기록한다.
공식 문서에서도 프로젝트 스코프의 MCP 설정 파일에는 결과적으로 literal secret이 들어갈 수 있기 때문에 .gitignore에 추가하고 절대로 커밋하지 말라고 경고한다.
즉:
mcp.yaml
Authorization: Bearer ${TOKEN}
이라고 작성하더라도 최종 생성 파일에서는
Authorization: Bearer 실제토큰
이 될 수 있다는 의미다.
회사 프로젝트에 도입한다면 이 부분은 반드시 Secret 관리 정책과 같이 검토해야 한다.
최근 릴리스에서는 TGit CLI 인자와 env.sh 값에 shell quoting을 적용하는 보안 강화 작업도 포함됐다.
14. 사용량 통계와 Dashboard
TeamAI에는 AI 사용 현황을 확인하기 위한 기능도 있다.
teamai digest
teamai dashboard
teamai session save
공식 README에서는 Weekly Digest, Session 정보, Dashboard, Knowledge Base Health 등을 제공한다고 설명한다.
사용 가이드에 따르면 기본 세션 통계에서는 prompt 본문이나 transcript를 저장하지 않고 대화 횟수와 token 수 등의 집계값을 기록한다. session save --push도 기본적으로 count와 tool name 위주이며 첫 요청 내용 포함은 별도 옵션이다.
15. 이 프로젝트를 한 문장으로 정리하면
[Inference]
TeamAI CLI는 쉽게 말하면
“GitHub를 기반으로 팀 전체의 Claude Code / Codex / Cursor용 AGENTS.md, SKILL.md, Rules, MCP, Hooks와 개발 노하우를 중앙 관리하는 AI DevOps 도구”
라고 이해하면 가장 쉽다.
기존의 개발팀이
Git
CI/CD
Docker
Terraform
Package Manager
등을 이용해 개발 환경을 표준화했다면,
TeamAI는 여기에
AI Skills
AI Rules
Agent Config
MCP
AI Knowledge
AI Experience
까지 포함시키려는 접근이다.
특히 주목할 부분
[Inference] 개인적으로 단순 Skill Sync보다 다음 구조가 TeamAI의 핵심이라고 본다.
Team AI Repository
│
┌───────────────┼────────────────┐
│ │ │
Execution Context Improvement
│ │ │
Skills/Rules Knowledge Sessions
Hooks/MCP Graph Friction
│ │ │
└───────────────┼────────────────┘
↓
Claude / Codex / Cursor
↓
개발 작업 수행
↓
새로운 경험 축적
↓
Team Repository
즉 AI에게 지시하는 시스템에서 끝나는 것이 아니라,
AI 사용 경험 → 팀 지식 → 다시 AI Context
라는 순환 구조를 만들려는 프로젝트다.
그래서 여러 개발자가 Claude Code, Codex, Cursor를 동시에 사용하는 팀이라면 상당히 흥미롭게 살펴볼 만한 오픈소스다.
현재 GitHub 저장소는 약 2.3k stars를 표시하고 있으며 MIT 라이선스로 공개되어 있다.
프로젝트
Tencent / teamai-cli
GitHub - Tencent/teamai-cli: Make Every Team AI Native
Make Every Team AI Native. Contribute to Tencent/teamai-cli development by creating an account on GitHub.
github.com