봇 운영 실전 가이드 — 나만의 AI 봇 팀, 0에서 운영까지

표지

나만의 AI 봇 팀, 0에서 운영까지

사람 1명과 봇 여러 대가 지식창고(책장)·메신저와 연결된 시스템 전체 지도 일러스트 — 전체 그림 — 사람 1명 + 봇 팀 + 지식창고 + 메신저, 그리고 바닥의 규칙들

누구를 위한 가이드인가: "AI 봇을 만들어서 매일 나 대신 일하게 하고 싶다"는 분. 코딩 경험은 없어도 됩니다 — 터미널(검은 화면)에 명령어를 복사해 붙여넣는 것까지는 함께 갑니다.

이 가이드의 약속: 모든 단계 끝에 "이 화면이 나오면 정상" 체크포인트가 있습니다. 그 화면이 안 나오면 넘어가지 말고 "막혔을 때" 박스를 보세요. 실제로 봇 5대를 매일 굴리며 겪은 실패로 만든 가이드라, 여러분이 만날 함정은 대부분 우리가 먼저 밟았습니다.

🤖 메타 한 줄

이 가이드 자체가 그 증거입니다 — 본문 작성·일러스트·검증을 전부 그 봇 팀(조율봇·이미지봇·검증봇)이 분담해 만들었습니다.

짝꿍 문서: 봇들이 쓰는 "지식창고 검색"의 내부가 궁금하면 LLM wiki + GraphRAG 가이드북을 보세요.

0단계

읽는 법 + 준비물

전체 그림 (3층 구조) — 이 시스템은 세 층으로 되어 있습니다:

층	무엇	역할
지식 층	Obsidian vault (연결된 노트 창고)	봇들이 읽고 쓰는 공동 서재
실행 층	봇들 (Claude Code 세션)	조사·글쓰기·일정·조율 — 각자 역할
규칙 층	운영 규칙	어떻게 말하고, 검증하고, 언제 사람에게 묻나

준비물 3가지:

① Claude Code — Anthropic의 AI 비서 도구. 유료 구독(Pro 이상)이 필요합니다.
② Discord 계정 — 봇과 대화할 메신저(무료). 카톡이 아니라 Discord인 이유: 봇 계정을 공식 지원하고, 주제별 대화방(스레드)이 있어서입니다.
③ Obsidian — 노트 앱(무료). 선택이지만 강력 권장 — 없으면 봇이 "기억"을 쌓을 곳이 없습니다.

도구 설치는 이미 정리된 문서가 있습니다. 플러그인·검색 기능·Obsidian 연결은 ThisCode 초심자 가이드가 5단계·약 30분으로 안내합니다. 제일 쉬운 방법은 AI에게 설치를 시키는 것 — Claude Code를 열고 이렇게 붙여넣으세요:

https://github.com/treylom/ThisCode 의 설치 문서를 따라 단계별로 설치해줘.
README.md부터 시작하고, 비밀번호나 시스템 변경 전엔 꼭 나한테 물어봐.
끝나면 문서에 있는 검증 명령어로 확인까지 해줘.

✅ 체크포인트 — ThisCode의 healthcheck.sh가 통과(녹색 표시)하면 0단계 완료.

1단계

첫 봇 하나 세우기 (약 30분)

개념부터: "봇"이란 = Claude Code 세션 하나 + Discord 연결 + 페르소나 메모(soul.md). 이 셋이 합쳐지면 "Discord에서 부르면 대답하고, 자기 역할을 기억하는 AI 직원"이 됩니다.

비유: 신입사원 입사 절차 — ① 사원증 발급(봇 계정·토큰) ② 자리 배정(봇 폴더) ③ 직무기술서(soul.md) ④ 출근(세션 켜기).

1-1. 사원증 — Discord 봇 계정 만들기

① Discord 개발자 포털 접속 → New Application → 이름 입력(예: "조사봇").
② 왼쪽 메뉴 Bot → Reset Token → 나오는 긴 문자열이 토큰(봇의 비밀번호)입니다.
③ Installation 메뉴에서 서버 초대 링크를 만들어 여러분의 서버에 봇을 초대합니다.

⚠️ 토큰 보안 — 토큰은 절대 채팅·문서·코드에 붙여넣지 마세요. 노출되면 누구나 여러분의 봇인 척할 수 있습니다. 토큰의 유일한 자리는 다음 단계의 .env 파일입니다.

1-2. 자리 배정 + 직무기술서 — 봇 폴더와 soul.md

봇마다 폴더 하나를 만듭니다. 우리 시스템의 실제 폴더입니다:

실제 봇 채널 폴더 내부 — .env, soul.md, inbox 폴더가 보이는 터미널 화면 — 실제 운영 중인 조사봇의 폴더 — .env(토큰) · soul.md(직무기술서) · inbox(받은 파일)

soul.md에 꼭 들어가야 할 4가지 (ThisCode soul 템플릿 5종에서 골라 시작하세요):

① 정체성 1줄 — "나는 자료조사 전문 봇 OOO이다"
② 역할 경계 — 무엇을 하고(조사·출처 추적), 무엇을 안 하나(글 발행은 글쓰기 봇에게)
③ 말투 — 응답 끝 서명, 어조
④ 철칙 — 예: "모든 주장에 출처를 단다", "사용자 응답은 반드시 Discord로 보낸다"

왜 봇마다 폴더와 soul이 따로인가: 한 AI에게 모든 역할을 시키면 관점이 섞이고 책임이 흐려집니다. "조사 따로, 검증 따로"가 멀티봇의 출발점입니다.

1-3. 출근 — 세션 켜기

터미널에서 tmux(세션을 계속 살려두는 도구)로 봇을 켭니다. ThisCode 설치를 마쳤다면 기동 명령이 준비되어 있습니다. 우리 실제 운영 화면 — 세션 하나가 봇 하나이고, 컴퓨터를 끄지 않는 한 계속 "출근" 상태입니다:

tmux ls 실행 결과 — 8개 봇 세션이 attached 상태로 나열된 실제 터미널 — 실제 화면 — 봇 세션 8개가 동시에 살아있는 모습 (tmux ls)

1-4. 첫 인사

Discord에서 봇을 불러봅니다: @조사봇 안녕, 자기소개 해줘

Discord에서 봇이 soul.md의 정체성과 서명으로 첫 응답하는 실제 화면 — 봇이 soul.md에 적은 정체성·말투·서명으로 대답하면 성공

✅ 체크포인트 — 봇이 soul.md의 정체성과 말투로 대답하면 1단계 완료.

🔧 막혔을 때 (점검 순서) — ① tmux 세션이 살아있나(tmux ls) → ② .env 토큰이 정확한가(따옴표·공백) → ③ 봇이 서버에 초대돼 있고 채널 볼 권한이 있나 → ④ 그래도 안 되면 세션 재시작.

2단계

봇에게 일 시키기 — 위임의 기술 (5패턴)

봇이 응답하기 시작하면 다음 벽은 "일을 시켰는데 이상하게 한다"입니다. 봇끼리는, 그리고 사람과 봇 사이에는 '대충 알아듣기'가 없습니다. 우리가 수십 번의 실패로 만든 통신 규칙 5개:

로봇 둘이 무전기로 명확한 호출-응답을 주고받는 일러스트, 옆에는 잡음 혼선과의 대비 — 무전기 교신 — "수신자 호출 → 본문 → 송신 종료" 규약이 없으면 명령은 그냥 사라진다

#	패턴	막는 실패
①	Reply 게이트 — 봇 응답은 반드시 메시지 발송 도구로	봇이 자기 터미널에만 답 출력 — "내 화면에 썼다 ≠ 상대가 받았다"
②	멘션 규약 — 봇 부를 땐 시작과 끝에 `@봇이름`	멘션 없는 호출은 조용히 증발(silent drop)
③	분할 retag — 긴 메시지가 쪼개지면 모든 조각에 멘션 재삽입	2부·3부가 미발신과 동일해짐
④	위임은 HOW까지 — 첫 메시지에 방법·도구·금지 경로까지	목표만 주면 봇이 자기 방식으로 표류 → 교정 핑퐁 N회
⑤	입력 주입 금지 — 봇끼리 신호는 공식 채널로만	봇A가 봇B 터미널에 직접 타이핑 = 발신자 불명의 지시로 둔갑

좋은 위임 vs 나쁜 위임 (실제 사례)

❌ 나쁜 위임: "이미지 만들어줘" — 봇이 유료 API를 멋대로 쓰거나 엉뚱한 도구로 7번 표류했습니다(실화).

✅ 좋은 위임 — 우리가 실제로 보낸 메시지입니다:

실제 위임 메시지 — 실행 방법, 도구, 금지 경로, 산출 위치가 번호로 완전 명시된 Discord 메시지 — 좋은 위임의 4요소 — 무엇을 + 어떻게(도구) + 하지 말 것 + 어디에(산출·보고)

보내기 전 자가진단 한 문장: "봇이 이 메시지 하나만 보고 내가 원하는 정확한 방법으로 실행할 수 있는가?"

검증 문화 — 봇의 말을 그대로 믿지 않기

• "알겠습니다"(접수) ≠ 작업 시작. 시킨 뒤 1~3분 안에 실제로 움직이는지 확인합니다(세션 화면을 읽기만).
• "완료했습니다" ≠ 완료. 산출 파일을 직접 열어 대조한 뒤에만 받아들입니다. "보고는 통과인데 실물이 없는" 사고를 여러 번 겪고 만든 철칙입니다.

✅ 체크포인트 — 위임 메시지 하나로 봇이 교정 없이 일을 끝내면 2단계 졸업.

3단계

지식창고 연결 — 봇에게 기억을 주기

봇이 일을 하긴 하는데 매번 백지에서 시작한다면, 지식창고가 없기 때문입니다.

사서 로봇이 새 책을 분류 데스크에서 서가로, 목록 카드로 연결하는 도서관 입고 일러스트 — 도서관 신간 입고 — 분류하고, 서가에 꽂고, 목록 카드와 연결해야 사서가 찾아준다

파이프라인: 원본 파일(hwp·pdf·xlsx·카톡 내보내기) → 마크다운 변환(AI가 읽는 형식) → 기존 노트와 대조(중복·연결점) → 쪼개고 연결(3층 구조 + 링크 3개+) → 그래프(지식 별자리).

따라하기 (10분)

① 아무 폴더(예: inbox/)에 정리 안 된 문서 3~4개를 넣습니다 — PDF, 엑셀, 메모 뭐든.
② 봇에게: @봇 inbox 폴더 문서들을 vault에 정리해줘. 기존 노트와 연결까지.
③ 끝나면 Obsidian 그래프 뷰를 엽니다.

정리 전 inbox 원본 파일과 정리 후 생성된 마크다운 노트 폴더를 비교한 화면 — 정리 전(원본 파일) → 정리 후(연결된 노트)

Obsidian 그래프 뷰 — 새로 만든 노트들이 기존 노트 별자리에 선으로 연결된 모습 — 새 노트가 기존 별자리에 연결된 모습 — 이게 보이면 성공

핵심 원칙 3개:
• 3층 구조가 기본 — 큰 지도(MOC) → 카테고리 → 낱개 노트. 거대한 노트 1개는 검색은 돼도 연결이 안 됩니다.
• 고립 노트 금지 — 새 노트는 기존 노트와 링크 3개 이상. 고립 노트 = "저장됐지만 다시는 안 읽히는" 노트.
• 한국 문서도 OK — HWP·복잡한 표는 변환기(kordoc)를 거치면 됩니다.

✅ 체크포인트 — 그래프 뷰에서 새 노트가 기존 노트들과 선으로 이어져 있으면 성공. 외딴섬으로 떠 있으면 "연결까지"를 다시 시키세요.

검색이 어떻게 정답 노트를 찾아내는지(임베딩·그래프·하이브리드)는 LLM wiki 가이드북 Part 2가 다룹니다.

4단계

봇 둘 이상 — 회의실 운영

봇이 2개가 되는 순간 새 문제가 생깁니다: "지금 누가 뭘 하고 있지?" 채팅은 흘러가고, 봇은 세션이 리셋되면 기억을 잃습니다. 해답은 파일로 남는 회의실입니다.

비유: 회의실 화이트보드 — 참석자가 바뀌어도 보드만 보면 30초 만에 따라잡는 것. 채팅 ≠ 정본, 회의 문서 = 정본.

4-1. 회의실 = 폴더 하나 + 파일 4개

실제 회의 폴더 — 00-context, 01-spec, 02-progress 파일과 산출 문서, images 폴더가 보이는 목록 — 실제 회의 폴더 — 바로 이 가이드를 만든 회의실이다

파일	무엇
`00-context.md`	목표·참석자·완료 조건 (회의 중 안 바꿈)
`01-spec.md`	상세 작업 명세
`02-progress.md`	진행 로그 — 모두가 추가, 회의의 심장
`03-outcome.md`	결정·후속 작업 (끝날 때)

4-2. 02-progress 규약 — 회의의 심장

모든 봇은 행동 직전에 읽고, 직후에 한 줄 추가합니다:

[19:08 KST] 조사봇 | 착수 | 공식 문서 3건 수집 시작
[19:15 KST] 조사봇 | 완료 | 10-조사결과.md 박제 — 검증 대기

왜: "내가 아는 최신"과 "실제 최신"이 어긋나는 게 멀티봇 사고의 단골 원인입니다. 한 줄 로그가 그 어긋남을 끊습니다.

실제 회의 Discord 스레드 — 개시 발화와 봇들의 착수·완료 보고가 오가는 화면 — 실제 회의 스레드 — 위임, 착수 보고, 완료 보고가 한 방에서 흐른다

4-3. 운영 장치 4개 (요약)

장치	한 줄
생존 점검	진행 중 회의는 몇 분 간격으로 각 봇 상태를 직접 물음 — 침묵이 "일하는 중"인지 "멈춤"인지 구분
대기 표시	사람 결정을 기다리는 중이면 장부에 표시 — 정당한 대기를 "멈춤"으로 오판해 깨우지 않게
현황 한 장	긴 회의는 "지금 상태 10줄"(LATEST.md) 별도 유지 — 새 봇이 로그 전체를 안 읽게
시간 통일	모든 시각은 한국시간(KST) 하나로 — 시간대가 섞이면 사건 순서가 역전돼 보임

✅ 체크포인트 — 봇 2개에게 한 주제를 시키고, 02-progress만 보고 전체 흐름을 재구성할 수 있으면 4단계 졸업.

5단계

믿을 수 있게 만들기 — 신뢰 장치 4종

멀티봇의 진짜 난제는 속도가 아니라 신뢰입니다. "봇이 한 말을 어디까지 믿을 것인가"에 대한 우리의 답 4가지:

1. 출처 의무 — 모든 주장에 출처(파일 위치·링크·명령 결과). 특히 "없다/비어있다" 단정은 두 번 검색한 뒤에만. 한 번 검색해서 안 나오면 "없는 것"이 아니라 "못 찾은 것"일 확률이 높습니다.

2. 검증 사다리 — "확인했다"에도 급이 있습니다:

4단 계단 일러스트 — 자동 점검 기계, 재현 실험, 검사관 로봇, 맨 위에 사람의 최종 확인 — 검증 사다리 — 1단 자동 검사 → 2단 시나리오 재현 → 3단 다른 봇 교차 검증 → 4단 사람 검토

봇이 "검증 끝"이라고 말할 땐 몇 단까지 했는지를 같이 말하게 하세요. "1단만 통과"와 "3단 교차 검증"은 전혀 다른 보증입니다.

3. 완료 게이트 — 봇이 "완료"라고 선언하기 직전, 보고 전용 스레드에 산출물 경로와 함께 선보고:

완료 보고 전용 스레드 — [작업명] 완료, 산출: 경로 형식의 보고가 쌓여 있는 실제 화면 — 실제 완료 보고 스레드 — 모든 완료가 산출 경로와 함께 한 곳에 쌓인다

왜: "완료 선언만 있고 산출물 추적이 안 되는" 상황을 구조적으로 차단합니다 — 나중에 되짚어보기(감사)도 됩니다.

4. 자율성 가격표 — 봇이 사람에게 언제 물어야 하나:

행동	규칙
읽기 · 탐색 · 초안	자유 — 묻지 말고 진행, 결과로 보고
파일 수정 · 커밋	스스로 판단 — 되돌릴 수 있으면 진행
배포 · 공개 · 삭제	반드시 사람 승인

왜 3단계인가: 매사 허락을 구하면 봇을 쓰는 의미가 없고, 다 맡기면 위험합니다. "되돌릴 수 있는가"가 경계선입니다.

✅ 체크포인트 — 봇 보고에서 ①출처 ②검증 급 ③산출 경로 3가지가 자동으로 나오면 5단계 완성.

6단계

스스로 자라는 시스템 — 규칙은 사고에서 태어난다

마지막 단계는 도구가 아니라 운영 철학입니다. 우리 규칙 17장은 한 번에 설계된 게 아니라 이 루프로 자랐습니다:

실패 발생 → 원인 분석 → 규칙 1줄 추가 → 그래도 재발하면 → 자동 장치(훅)로 강제

• 지식 ≠ 강제: 규칙을 문서에 적어도 봇은(사람도) 까먹습니다. 반복 위반되는 규칙은 시스템이 자동으로 잡게 만드세요 — 예: 산출물을 만들면 자동으로 노트 창고에 복사, 응답 없이 끝내려 하면 차단.
• 규칙 전부를 외우게 하지 않기: 규칙이 많아지면 통째로 주입할수록 오히려 기억이 떨어집니다. 목차 1장만 항상 들고, 상황에 걸리는 규칙만 그때 펴 봅니다 (사규 전권 암기 대신 "이럴 땐 몇 장" 색인).
• 측정으로 다이어트: 어떤 규칙이 실제로 읽히는지 기록해서, 안 읽히는 규칙은 통합·삭제합니다.

스타터 세트 — 처음엔 이 5개만

#	규칙	이유
1	Reply 게이트 — 봇 응답은 반드시 메시지 도구로	가장 흔한 첫 실패
2	회의 = 폴더 + 파일 4개	봇 2개부터는 채팅이 아니라 회의실
3	멘션 + 분할 retag	부른 봇이 조용하면 멘션부터 의심
4	출처 의무	봇 주장엔 파일·링크. "없다" 단정은 두 번 검색 후
5	완료 게이트	완료는 산출 경로와 함께, 막히면 10분 내 먼저 보고

흔한 함정 5

① 목표만 주고 방법을 안 줘서 표류 ② 봇 보고를 검증 없이 수용 ③ 규칙을 문서에만 적고 강제 장치 없음 ④ 채팅을 정본으로 착각(파일 정본 부재) ⑤ 한 봇에게 조사+작성+검증을 몰아주기

✅ 체크포인트 — 한 달 운영 후 "우리 집 규칙"이 3개 이상 생겼다면, 시스템이 자라고 있는 겁니다.

확장

Codex 봇 연결 — 다른 엔진의 팀원 들이기 (ThisCodex)

왜 다른 엔진인가: 지금까지 만든 봇들은 전부 Claude Code(Anthropic) 엔진입니다. 여기에 OpenAI Codex 엔진 봇을 한 명 들이면, 같은 질문을 다른 두뇌로 교차 확인할 수 있게 됩니다 — 우리 팀의 "검증 담당(외부 엔진)" 봇이 정확히 이 방식입니다. 한 엔진의 버릇(같은 실수를 같은 방향으로 반복하는 것)은 같은 엔진끼리는 못 잡고, 다른 엔진이 잡아냅니다.

비유: 같은 회사 출신으로만 팀을 꾸리면 다들 비슷한 데서 틀립니다. 다른 회사 출신 경력직 한 명이 들어오면, 모두가 당연하다고 넘기던 걸 "이거 왜 이렇게 해요?"라고 물어봐 줍니다.

ThisCodex가 그 연결법의 정리본입니다 — Codex CLI 봇을 Claude Code 봇들과 같은 Discord 사무실 · 같은 지식창고 · 같은 회의실 규약으로 합류시키는 공개 레포(github.com/treylom/ThisCodex)입니다. 0단계에서 쓴 ThisCode(Claude Code 쪽)의 짝꿍 문서이고, 두 봇이 한 팀으로 협업하는 규약(서로 부르기·회의 스레드·완료 보고)까지 들어 있습니다.

	ThisCode	ThisCodex
엔진	Claude Code (Anthropic)	Codex CLI (OpenAI)
맡기면 좋은 일	일상 운영 · 조사 · 글쓰기 · 조율	교차 검증 · 코드 리뷰 · 이미지 생성
공통	같은 Discord 사무실 · 같은 지식창고(vault) · 같은 회의실 규약(파일 4개)

설치도 0단계와 같은 방식 — AI에게 시키는 게 제일 쉽습니다. Claude Code나 Codex를 열고 이렇게 붙여넣으세요:

https://github.com/treylom/ThisCodex 의 설치 문서를 따라 단계별로 설치해줘.
README.md부터 시작해서 npx github:treylom/ThisCodex init (대화형 설정)을 돌리고,
비밀번호나 시스템 변경 전엔 꼭 나한테 물어봐.
끝나면 npx github:treylom/ThisCodex doctor 로 검증까지 해줘.

✅ 체크포인트 — doctor 점검이 통과하고, Discord에서 Codex 봇을 멘션해 첫 답장을 받으면 합류 완료. 막히면 /thiscodex:help 로 하위 명령 목록부터 확인하세요.

마무리

다음 단계

• 도구 설치부터 다시: ThisCode (Claude Code용) · ThisCodex (Codex용)
• 검색의 원리가 궁금하면: LLM wiki + GraphRAG 가이드북 — 봇들이 쓰는 "지식창고 검색"의 내부
• 체계적으로 배우고 싶으면: 패스트캠퍼스 강의 "LLM wiki로 10배 똑똑한 AI Agent 팀빌딩" — 이 가이드의 모든 단계를 손잡고 같이 갑니다.

🤖 다시, 메타 한 줄

이 가이드는 실제로 봇 5대(+검증봇 2대)가 매일 운영되는 시스템에서 나왔고, 이 문서의 재작업 역시 그 봇들(조율봇 작성 · 이미지봇 일러스트 · 검증봇 톤 검사)이 회의실 규약대로 수행했습니다. 여러분도 한 달이면 여기까지 옵니다.