蓝皮书(블루북)WorkBuddyGuide는 "텐센트의 직장용 AI 에이전트 WorkBuddy를 어떻게 실무에 써먹는지"를 사례 중심으로 정리한 커뮤니티 실전 매뉴얼이다. 저자들 표현으로는 蓝皮书(블루북 = 실무 백서). 설치·로그인부터 시작해 Office 자동화, 데스크톱 파일 정리, 회의록, 투자 분석, AI 영상 제작까지 4부 27개 챕터로 이어지고, 각 챕터는 "이 상황에서 WorkBuddy에게 뭐라고 시키면 어떤 결과가 나오는지"를 실제 프롬프트·스크린샷과 함께 보여준다.
여기서 반드시 구분할 것 두 가지. 첫째, WorkBuddy(제품)는 텐센트가 만든 것이고, 이 가이드(문서)는 텐센트가 아닌 커뮤니티 저자 5인이 만든 3자 자료다(리포지토리 면책 문구에 "community-maintained" 명시). 둘째, 이 저장소에는 WorkBuddy의 소스 코드가 없다 — 들어있는 "코드"는 이 가이드를 웹사이트로 굽는 VitePress 문서 사이트 장치(Vue 컴포넌트 5개 + 콘텐츠 수집 파이썬 1개)뿐이다.
WorkBuddy가 말귀 알아듣고 컴퓨터를 대신 조작해주는 신입 비서라면, WorkBuddyGuide는 그 비서를 먼저 써본 선배들이 "이럴 땐 이렇게 시켜라"를 시나리오별로 적어 돌려보는 공동 노트다.
게임으로 치면 게임사(텐센트)가 만든 건 게임(WorkBuddy)이고, 이건 유저들이 만든 공식이 아닌 완벽 공략집. 공략집을 읽으면 게임뿐 아니라 "RPG를 공략하는 일반 원리"까지 배우듯, 이 가이드도 WorkBuddy 너머의 에이전트 다루는 법(Skills·MCP·멀티에이전트)을 가르친다.
workbuddy.homes에서 읽을 수 있다.이 저장소는 오래된 클래식이 아니라 2026년에 새로 생긴 "New 2026" 자료다. 그런데도 이번 주 Weekly 3위(모멘텀 점수 249)로 치고 올라온 데는 뚜렷한 이유가 있다. (TrendShift의 굵은 숫자는 별 수가 아니라 사회적 언급 모멘텀이다.)
WorkBuddy는 텐센트가 2026년 초 내놓은 "직원처럼 일하는 AI 에이전트"로, Forbes·TechNode·Product Hunt가 다룰 만큼 주목받았다. "OpenClaw(오픈클로우)류 워크플레이스 에이전트"로 불리며 글로벌 확장까지 거론된다. 제품이 화제이니 "그래서 이걸 실제로 어떻게 쓰냐"에 대한 수요가 폭발했고, 그 빈자리를 이 커뮤니티 가이드가 채웠다.
제품 공식 매뉴얼은 보통 기능 나열에 그친다. 이 가이드는 반대로 "뉴스 20개를 매일 아침 요약 리포트로", "회의 녹취를 할 일까지 자동 추적", "한 문장으로 홍보 영상 팀 소환"처럼 결과물이 명확한 실무 사례를 27장에 걸쳐 재현한다. 가장 큰 18장(투자 분석)은 홀로 529줄에 달한다. "따라 하면 되는" 구체성이 실사용자를 끌어들였다.
백미는 3부(고급편)다. Skills를 직접 만드는 법(22장)·멀티에이전트 시스템 설계(24장)·자동화 워크플로우의 신뢰성(25장)을 다루는데, 여기서 설명하는 SKILL.md 구조·MCP·역할 계약(role contract)은 WorkBuddy 전용이 아니라 Claude Code·Codex 등 오늘날 모든 에이전트에 공통인 개념이다. "제품 공략집"인 척하지만 실제로는 에이전트 리터러시 교재인 셈.
내용뿐 아니라 만드는 방식도 눈길을 끈다. 저자들은 Feishu(飞书/Lark) 위키에 글을 쓰고, download_feishu_wiki.py로 마크다운을 뽑아내 VitePress로 픽셀아트 테마의 사이트를 짓고 Cloudflare Pages로 자동 배포한다. "협업으로 쓴 원고 → 정적 문서 사이트" 파이프라인 자체가 문서 자동화를 배우려는 개발자에게 좋은 레퍼런스다.
이 저장소를 이해하려면 스택을 두 겹으로 봐야 한다. 하나는 이 문서 저장소가 실제로 돌리는 코드(VitePress 문서 사이트), 다른 하나는 문서가 설명하는 대상(WorkBuddy 제품의 아키텍처)이다. 저장소에 코드로 존재하는 건 (A)뿐이고, (B)는 문서 속 지식이다.
저장소의 본체는 코드가 아니라 글이다. 마크다운 57개(약 7,221줄) 중 핵심 블루북이 27개 챕터 · 4,991줄, 나머지는 부(部) 소개·부록·커뮤니티 사례. 여기에 앱 화면 스크린샷 260장(png/jpg/gif)이 붙어 전체 347개 파일 중 대부분을 차지한다. 언어는 간체 중국어가 주력이고 영어는 README·기여 가이드 정도의 얇은 껍데기다.
| 도구 | 역할 |
|---|---|
| VitePress 1.6.4 | Vite 기반 정적 사이트 생성기(SSG). 마크다운을 검색 가능한 문서 사이트로 빌드. lang: "zh-CN", config.mts가 진입점. |
| Vue 컴포넌트 5개 | 커스텀 홈(HomePage.vue), 다이어그램(MermaidDiagram.vue), 픽셀 아이콘(PixelIcon.vue·PixelIconSprite.vue), QR 메뉴(GroupQrMenu.vue). |
| Mermaid 11.16.0 | 마크다운 안의 워크플로우 다이어그램을 사이트에서 렌더(mermaid-markdown.ts가 코드펜스를 가로챈다). |
| @fontsource/silkscreen | 픽셀 폰트. 테마색 #d8f238(형광 연두)로 "픽셀-그린" 레트로 UI를 낸다. |
| sidebar.ts · seo.ts | 사이드바 목차 생성, SEO 메타/JSON-LD 주입 로직. |
| 도구 | 역할 |
|---|---|
| download_feishu_wiki.py | 저자들의 콘텐츠 수집 파이프라인. Feishu(Lark) 위키를 lark-cli로 훑어 오프라인 마크다운으로 내려받는다. "협업 원고 → 저장소 소스"의 다리. |
| Cloudflare Pages | main에 푸시하면 자동 빌드·배포. 온라인판 workbuddy.homes가 여기서 서빙된다(DEPLOYMENT.md). |
| SEO 자산 | canonical·OG/Twitter 태그, JSON-LD(WebSite/Organization/Article/BreadcrumbList), sitemap, robots.txt, Baidu·Google 웹마스터 인증 파일. 문서 사이트 표준 세팅. |
| Node ≥20 <25 | package.json type: module, 스크립트 dev/docs:build/docs:preview. 라이선스 MIT. |
| 구성요소 | 가이드 설명 |
|---|---|
| 멀티 모델 스위칭 | 混元(Hunyuan)·DeepSeek·GLM·Kimi·MiniMax를 상황에 맞게 교체. 특정 모델 종속을 피한다. |
| Skills | Anthropic의 Agent Skills와 같은 SKILL.md 방식. 반복 작업을 "기술 팩"으로 캡슐화(§4·§6). |
| MCP Server | 외부 도구·데이터를 표준 프로토콜로 연결. 커스텀 커넥터를 MCP로 붙인다. |
| 내장 커넥터 | QQ 메일·텐센트 문서(腾讯文档)·러샹(乐享)·텐센트 회의(腾讯会议)·TAPD — 텐센트 생태계 정황. |
| 안전장치 | 고위험 명령 가로채기 + 권한 제어. 컴퓨터를 대신 조작하는 에이전트의 필수 가드레일. |
| 실행 형태 | 로컬 파일에 접근하는 데스크톱 에이전트 + 사내 채팅으로 부리는 IM 봇 두 얼굴. |
(B)의 모델 목록·커넥터 목록·기능 설명은 이 커뮤니티 가이드(1·7장)의 서술이다. 텐센트 소유·멀티에이전트·MCP·20+ 스킬팩 같은 큰 줄기는 Forbes·TechNode·Product Hunt 등 외부 보도로도 확인되지만, 세부 수치·버전은 공식 채널로 재확인하는 게 안전하다. 가이드 자신도 가격·최신 기능은 "공식 WorkBuddy 소스를 보라"고 반복해 안내한다.
저자 5인은 코드가 아니라 글을 협업으로 쓴다. 그 흐름은 다음과 같다. 사람이 만지는 건 왼쪽 끝(Feishu 위키)뿐이고, 오른쪽 산출물은 자동화된다.
가이드가 처음부터 끝까지 강조하는 WorkBuddy의 작동 모델은 "한 명의 오케스트레이터가 목표를 잘게 쪼개, 여러 전문 하위 에이전트(전문가·전문가팀)에게 나눠 시키고, 각자는 Skills·MCP·커넥터라는 도구를 써서 실제 컴퓨터를 조작한다"이다.
가이드 5장은 WorkBuddy의 Skills가 Anthropic Agent Skills와 같은 방식임을 정확히 짚는다(Anthropic이 2025년 10월 발표, 12월 개방형 표준화). 핵심은 폴더 하나에 규칙·스크립트·참고자료를 담고, 진입점 SKILL.md의 YAML 머리말로 "언제 이 기술을 꺼내 쓸지"를 적어두는 것이다.
# SKILL.md — YAML 머리말(frontmatter)로 트리거를 선언
---
name: tech-article-writing
description: 기술 아티클을 쓸 때 사용. 구조 잡기·초안·다듬기 규칙을 담음.
---
# 이하 본문: 에이전트가 따를 절차·좋은 예/나쁜 예·검증법# 스킬 폴더 구조 — 진입점 + 필요할 때만 여는 곁가지
skill-folder/
├── SKILL.md # 진입점(머리말 + 절차) — 항상 읽음
├── scripts/ # 실행 스크립트
├── references/ # 참고 문서 — 필요할 때만 로드
└── assets/ # 템플릿·이미지 등name·description만 훑어 "쓸지 말지" 판단 → ② 쓰기로 하면 SKILL.md 본문 로드 → ③ 정말 필요할 때만 references/·scripts/를 연다. 가이드는 "OpenAI Codex도 유사 메커니즘"이라고 정확히 덧붙인다. 맥락(context) 낭비를 줄이는 핵심 설계다.7장은 MCP(Model Context Protocol)를 "Anthropic이 2024년 말 공개·오픈소스화한 표준 프로토콜"로 정확히 소개하고, 명쾌한 비유를 든다: MCP는 AI 세계의 USB-C 단자. 도구마다 제각각 연결 코드를 짜면 N×M 조합이 폭발하지만, 표준 단자 하나로 통일하면 N+M으로 줄어든다.
| MCP 3대 프리미티브 | 뜻 |
|---|---|
| Tools (도구) | 에이전트가 호출해 행동하는 함수 (회의 생성, 파일 검색 등). |
| Resources (리소스) | 에이전트가 읽어오는 데이터 (문서, DB 레코드 등). |
| Prompts (프롬프트) | 재사용 가능한 프롬프트 템플릿. |
구조는 Host / Client / Server 3자다. 에이전트 앱(Host)이 Client를 통해 여러 MCP Server(도구 제공자)에 붙는다. 로컬 우선(stdio·로컬 HTTP) 설계라 보안상 유리하다. 가이드는 곧바로 실전 예를 보여준다 — 텐센트 회의 커넥터를 붙인 뒤 "내일 오후 3시 '프로젝트 논의' 회의 1시간짜리 잡아줘"라고 말하면 실제로 생성되는 흐름.
24장은 단일 에이전트 vs 멀티에이전트를 맥락·분업·도구·품질·비용·리스크 6축 표로 비교하고, "쪼갤 가치가 있는가?"의 판단 기준을 준다. 백미는 실제로 굴린 홍보 영상 "전문가팀" 사례 — HeyGen이 오픈소스로 낸 에이전트 친화 HTML 영상 렌더러 HyperFrames(약 1.77만 스타) 위에 팀을 짠다.
포인트는 각 하위 에이전트에게 "무엇을 받고, 무엇을 내놓고, 무엇을 하지 말지"를 계약처럼 못박는 것이다. 이 "금지사항"이 멀티에이전트가 서로 남의 작업을 망치지 않게 하는 가드레일이다 — 사람 팀의 R&R(역할과 책임)을 에이전트에 옮긴 셈.
25장은 "에이전트를 자동으로 돌리면 언젠가 틀린다"는 현실을 정면으로 다룬다. 매일 자동 실행되는 워크플로우(10장의 예약 작업)가 도중에 실패하거나 엉뚱한 결과를 낼 때 어떻게 검증·복구·재시도할지를 논한다. 화려한 데모가 아니라 운영(production) 관점의 신뢰성을 챕터 하나로 떼어 다룬 점이 이 가이드의 성숙도를 보여준다.
눈여겨볼 점: 실행 코드는 .vitepress/의 사이트 장치와 파이썬 1개가 전부이고, 나머지는 콘텐츠(마크다운 57개)와 스크린샷(260장)이다. 파일 347개 중 260개가 이미지라 저장소가 무거워 git clone이 느리다(§7). 이 구조가 프로젝트의 정체성을 요약한다 — "소프트웨어"가 아니라 "잘 조판된 책 + 그 책을 웹으로 굽는 얇은 도구".
이 저장소의 진짜 교육 가치는 특정 제품 조작법이 아니다. 아래 개념들은 WorkBuddy를 안 써도, Claude Code·Codex·Cursor 등 어떤 에이전트에도 그대로 옮겨지는 지식이다.
SKILL.md의 머리말(트리거)·본문(절차)·곁가지(scripts/references) 3층 구조와 점진적 공개는, 에이전트에게 "언제·어떻게 이 능력을 꺼내 쓸지"를 문서로 못박는 법이다. 자기 업무의 반복 패턴을 스킬로 캡슐화하는 감각을 여기서 얻는다. (이 프로젝트가 이미 다룬 obsidian-skills·emilkowalski/skills·hallmark와 곧장 연결된다.)
"USB-C 단자" 비유로 N×M→N+M 문제를 이해하고, Tools/Resources/Prompts와 Host/Client/Server 3자 구조를 잡으면, 앞으로 어떤 에이전트에 외부 도구를 붙일 때든 지도가 생긴다. 로컬 우선(stdio) 설계의 보안 이점도 함께.
"언제 쪼갤 가치가 있나"의 판단 기준과, 하위 에이전트마다 입력·출력·금지사항을 계약처럼 정의하는 법. 단일 에이전트로 될 일을 굳이 쪼개면 비용·리스크만 는다는 균형 감각까지. 사람 팀 관리 원리를 에이전트에 적용하는 훈련이다.
예약 실행되는 워크플로우가 실패했을 때의 검증·복구·재시도(25장). "한 번 성공"과 "매일 안전하게 반복"은 전혀 다른 문제라는 것 — 운영 엔지니어링의 첫 감각.
마크다운을 VitePress로 굽고 Mermaid로 다이어그램을 렌더하며, config.mts·sidebar.ts·커스텀 Vue 테마로 사이트를 조립하는 실물 예제. 나만의 문서 사이트를 만들 때 그대로 베낄 수 있는 골격이다.
download_feishu_wiki.py로 "협업 원고 → 저장소 소스"를 잇는 발상, 그리고 CASE_TEMPLATE.md·이슈/PR 템플릿으로 커뮤니티 사례 기여를 질서 있게 받는 구조. 다수가 함께 쓰는 지식 베이스를 어떻게 운영하는가의 사례.
중국어라 진입장벽이 있지만, 3부(22~25장)만큼은 브라우저 번역으로라도 읽을 값어치가 있다. 거기 나오는 Skills·MCP·멀티에이전트·자동화 신뢰성은 제품 이름만 빼면 Claude Code에 100% 통하는 개념이다. "WorkBuddy에게 시킨다"를 "내 에이전트에게 시킨다"로 바꿔 읽으면, 이 가이드는 훌륭한 에이전트 실전 교본이 된다.
| 목적 | 필요한 것 |
|---|---|
| 가이드 읽기 | 브라우저만. 온라인판 workbuddy.homes 또는 GitHub의 마크다운. |
| 가이드 사이트 로컬 빌드 | Node.js ≥20 <25 + npm install → npm run dev(미리보기) / npm run docs:build. GPU·대용량 메모리 불필요. |
| 저장소 클론 | git. 단 이미지 260장 때문에 저장소가 무거워 클론이 느리다 — 텍스트만 필요하면 --filter=blob:none 부분 체크아웃 권장. |
| 콘텐츠 파이프라인 실행 | Python + lark-cli + Feishu(Lark) 위키 접근 권한(저자 전용 — 일반 학습엔 불필요). |
| WorkBuddy(제품) 실제 사용 | 가이드가 대상으로 하는 WorkBuddy 데스크톱 앱(별도 설치·로그인). 컴퓨터를 대신 조작하므로 권한 부여가 전제. — 제품 요구사양은 공식 채널 확인. |
정리하면 이 저장소를 "공부"하는 데는 Node와 브라우저면 충분하다. 무거운 건 소프트웨어가 아니라 스크린샷 용량뿐이다. "제품을 돌리는 것"과 "가이드를 읽/빌드하는 것"은 완전히 다른 요구사항임을 헷갈리지 말 것.
저장소를 부분 체크아웃(--filter=blob:none)으로 가볍게 받아 npm install → npm run dev로 VitePress 문서 사이트를 로컬 실행해보자. config.mts·sidebar.ts를 열어 목차가 어떻게 생성되는지, 커스텀 픽셀 테마가 어디서 오는지 추적하면 "문서 사이트의 뼈대"가 보인다.
가이드 5·22장을 참고해, 내가 자주 하는 반복 작업(예: 회의록 정리) 하나를 골라 SKILL.md로 캡슐화하자. YAML 머리말에 name·description을 쓰고, 본문에 절차·좋은 예/나쁜 예를 넣는다. Claude Code나 Codex에 붙여 "트리거가 실제로 작동하는지" 확인해보면 점진적 공개가 체감된다.
7장의 "USB-C" 개념을 실물로. 공개 MCP Server(파일시스템·검색 등) 하나를 골라 자신의 에이전트에 연결하고, Tools/Resources가 실제로 어떻게 노출되는지 관찰하자. 가이드의 "회의 잡기" 예처럼, 자연어 한 줄이 도구 호출로 바뀌는 순간을 직접 만들어본다.
24장을 본떠, 작은 작업(예: 블로그 글 1편)을 기획→작성→검수 3역할로 쪼개고 각 역할의 입력·출력·금지사항을 표로 못박아보자. 그다음 "굳이 안 쪼개고 한 번에 시켰을 때"와 결과·비용을 비교. "언제 쪼갤 값어치가 있나"를 몸으로 배운다.
25장의 신뢰성 개념을 적용해, 매일 돌아가는 자동 작업(뉴스 요약 등)을 만들되 중간 실패 시 검증·재시도·알림을 넣어보자. 성공 케이스만 있는 데모에서 벗어나, "틀릴 수 있다는 전제"로 설계하는 운영 엔지니어링을 연습한다. 예약 실행(cron)까지 붙이면 10장 재현 완성.
| 주차 | 주제 | 핵심 질문 · 자료 |
|---|---|---|
| 1주차 | Skills 설계 | SKILL.md 머리말/본문/곁가지 3층과 점진적 공개. → 가이드 5·22장 + 이 프로젝트의 obsidian-skills·emilkowalski/skills 딥다이브. |
| 2주차 | MCP 프로토콜 | Tools/Resources/Prompts, Host/Client/Server, stdio 로컬 우선. → 가이드 7장 + MCP 공식 사양. |
| 3주차 | 멀티에이전트 오케스트레이션 | "쪼갤 가치" 판단, 역할 계약(입력/출력/금지), HyperFrames 같은 에이전트 친화 도구. → 가이드 24장. |
| 4주차 | 문서 엔지니어링 & 자동화 신뢰성 | VitePress 사이트 조립·Mermaid·SEO, 그리고 자동 워크플로우 검증·복구. → .vitepress/ 소스 + 가이드 10·25장. |
먼저 Skills와 MCP(1·2주차)로 "에이전트에 능력·도구를 어떻게 붙이나"를 잡아라. 그게 나머지 전부의 벽돌이다. 그다음 그 벽돌로 여러 에이전트를 어떻게 협업시키나(3주차), 마지막으로 그 협업을 매일 안전하게 굴리는 법(4주차)이다. 제품 이름(WorkBuddy)은 잊고 개념만 챙기면, 이 로드맵은 어떤 에이전트 스택에도 통한다.
같은 "에이전트/스킬" 물결 속에서 결이 다르다. anthropics/claude-cookbooks는 1차(공식) 레시피 모음, WorkBuddyGuide는 3자(커뮤니티)의 특정 제품 공략집이다. Shubhamsaboo/awesome-llm-apps가 "실행되는 앱 100선"이라면 이건 "실행되는 워크플로우 27장"에 가깝다. Skills 개념은 obsidian-skills·emilkowalski/skills·Nutlope/hallmark와, 문서-데이터화는 jaywcjlove/awesome-mac과 나란히 놓고 보면 "지식을 어떻게 유통 가능한 형태로 굳히는가"의 여러 답이 보인다.
| 구분 | 링크 / 위치 |
|---|---|
| GitHub 저장소 | github.com/AlephAITech/WorkBuddyGuide |
| TrendShift | trendshift.io/repositories/81050 |
| 온라인 블루북 | workbuddy.homes (VitePress + Cloudflare Pages) |
| 핵심 콘텐츠 | docs/bluebook/ (4부 27章) — 특히 5장(Skills)·7장(MCP)·24장(멀티에이전트)·25장(신뢰성) |
| 핵심 파일 | scripts/download_feishu_wiki.py (콘텐츠 수집 파이프라인) |
| 핵심 파일 | docs/.vitepress/config.mts · sidebar.ts · seo.ts (사이트 조립) |
| 제품(공식) | WorkBuddy — 텐센트 공식 채널(가격·최신 기능은 여기서 확인) |
| 이웃 프로젝트 | anthropics/claude-cookbooks · Shubhamsaboo/awesome-llm-apps · obsidian-skills · emilkowalski/skills |
| 연관 개념 | Agent Skills(SKILL.md) · MCP · 멀티에이전트 · VitePress · Progressive Disclosure |