Claude Code로 디스코드 FAQ 봇 1시간 만에 만들기
서버에서 같은 질문이 반복될 때
디스코드 서버를 운영하다 보면 비슷한 질문이 계속 올라옵니다. 입장 링크는 어디 있는지, 결제는 언제 열리는지, 오류가 나면 뭘 먼저 눌러야 하는지 같은 내용이죠. 운영진이 그때그때 답해도 되지만, 사람이 바뀌면 말투가 달라지고 공지 문장도 조금씩 어긋납니다. 그래서 이번 글에서는 디스코드 FAQ 봇 첫 버전을 만드는 흐름을 잡아보겠습니다. 처음부터 복잡한 관리자 화면을 붙이기보다, 자주 받는 질문을 먼저 정리하고 그 데이터를 브라우저 미리보기와 디스코드 응답이 함께 읽게 만드는 방식입니다.
이 방식이 좋은 이유는 출발점이 분명하기 때문입니다. 첫 5분 안에는 브라우저에서 답변 카드가 뜨는지 확인하고, 남은 시간에 슬래시 명령을 붙여 1시간 안에 기본형을 마무리하는 순서로 가면 됩니다. 이렇게 나누면 데이터가 문제인지, 디스코드 권한이나 명령 등록이 문제인지 구분하기 쉬워집니다. 처음 만드는 사람 입장에서는 이 차이가 꽤 큽니다.
Claude Code 하나로 흐름을 끊지 않기
이번 편에서 중심이 되는 도구는 Claude Code입니다. 대화형 세션으로 프로젝트 규칙을 먼저 깔고, claude -p로 자주 묻는 질문을 정리하고, --json-schema로 JSON 형태를 고정한 다음, 마지막에 /review로 초보가 자주 놓치는 부분만 좁게 확인하는 흐름입니다. 도구가 많아질수록 처음 시작하는 사람은 어디서 꼬였는지 찾기 어려워집니다. 반대로 지금 방식은 규칙 만들기, 데이터 만들기, 화면 보기, 디스코드 연결하기로 단계가 또렷해서 따라가기가 편합니다.
여기서 먼저 챙길 포인트는 답변 문장을 한 파일에 모으는 일입니다. 브라우저에서 보이는 문장과 채팅창에 나가는 문장이 따로 놀면 수정이 두 배로 늘어납니다. 공지를 고쳤는데 미리보기만 바뀌고 봇 답변은 예전 문장으로 남아 있으면 운영이 금방 지저분해집니다. 그래서 faq.json을 중심에 두고 나머지가 그 파일을 읽게 만드는 게 깔끔합니다.
보이는 결과부터 만드는 순서
이 프롬프트를 먼저 넣는 이유는 답변 길이와 태도를 초반에 묶어두기 위해서입니다. 제한이 없으면 한 줄이면 끝날 문장이 길어지고, 모르는 질문에도 그럴듯한 말이 붙기 쉽습니다. CLAUDE.md에 2문장 제한과 운영진 문의 규칙을 적어두면 나중에 FAQ 항목이 늘어나도 톤이 크게 흔들리지 않습니다. 이 파일은 거창한 설계 문서라기보다 작은 룰북에 가깝습니다.
이 단계에서 얻는 이점도 분명합니다. 새 질문이 들어왔을 때 누가 문장을 추가하더라도 답변 길이, 말투, 예외 처리 방향이 한쪽으로 맞춰집니다. 특히 서버 공지형 봇은 친절함보다 일관성이 더 중요할 때가 많습니다. 짧게 답하고, 다음 행동을 붙이고, 애매하면 운영진으로 돌리는 원칙만 지켜도 답변 품질이 꽤 안정됩니다.
claude -p --json-schema schema.json 'faq-source.txt를 읽고 Discord FAQ 챗봇용 faq.json을 만들어줘. 필드는 category, question, keywords, answer만 써. keywords는 질문을 찾기 쉬운 짧은 단어 3개씩만 넣고, answer는 복붙해도 어색하지 않게 2문장 이하로 써.'이 단계에서는 질문 원문을 코드 안에 바로 박지 않는 게 중요합니다. faq-source.txt를 먼저 faq.json으로 정리하면 질문 묶음을 데이터처럼 다룰 수 있고, 검색 로직을 바꿔도 본문 문장을 다시 손볼 일이 줄어듭니다. --json-schema를 함께 쓰면 필드가 흔들릴 가능성도 낮아집니다. 처음 만들 때는 category, question, keywords, answer 네 칸만 있어도 충분합니다.
예를 들어 결제 일정 질문이라면 keywords에는 결제, 일정, 오픈처럼 짧은 단어 3개만 넣고, answer는 운영진 공지 문장을 그대로 붙여도 어색하지 않은 길이로 정리하면 됩니다. 이 구조가 단정하면 뒤에서 카드 검색을 붙일 때도 편하고, 디스코드 응답을 만들 때도 같은 데이터를 그대로 재사용할 수 있습니다. 글을 여러 군데 복사하는 습관보다 이런 데이터 분리가 나중에 훨씬 덜 피곤합니다.
faq.json을 읽는 preview.html 하나만 먼저 만들어줘. 검색창에 질문 일부를 치면 가장 가까운 답 1개가 카드로 뜨게 해줘. 파일은 하나로 끝내고, 모바일에서도 보기 쉽게 해줘.처음부터 봇 초대 링크와 권한 설정으로 들어가면 어디서 막혔는지 감이 흐려집니다. 반대로 preview.html을 먼저 띄우면 FAQ 문장이 사람 눈에 읽히는지, 질문 일부만 쳐도 원하는 답이 나오는지 바로 확인할 수 있습니다. 이 화면이 5분 안에 뜨면 데이터 구조와 검색 기준은 이미 절반 이상 잡힌 셈입니다.
검색창에 입장, 결제, 오류 같은 단어를 넣었을 때 카드가 한 장으로 또렷하게 보이면 좋습니다. 질문 여러 개가 한꺼번에 튀어나오는 방식보다 가장 가까운 답 1개가 먼저 뜨는 쪽이 초보 운영자에게 더 다루기 쉽습니다. 이 화면을 보면 공지 링크를 더 붙일지, 다음 행동 문장을 더 짧게 줄일지, 키워드가 너무 넓지는 않은지 같은 판단도 빨라집니다.
discord.js로 index.js를 만들어줘. /ask 슬래시 명령으로 질문을 받으면 faq.json의 keywords를 보고 가장 가까운 답을 보내줘. 못 찾으면 운영진 문의 문구를 보내고, 토큰은 .env에서 읽게 해줘. 설치 명령과 실행 명령도 README에 짧게 적어줘.여기서는 욕심을 줄이는 편이 낫습니다. 질문 받기, faq.json 읽기, 가장 가까운 답 보내기까지만 붙이면 기본형으로는 충분합니다. 버튼 UI나 관리자 대시보드까지 한 번에 넣으려 하면 디스코드 권한 문제와 검색 품질 문제를 구분하기 어려워집니다. 첫 버전은 길게 만드는 것보다 어디서 수정할지 보이게 만드는 쪽이 중요합니다.
/ask 결제는 언제 열려? 같은 문장을 넣었을 때 짧은 답과 다음 행동이 같이 나오면 흐름은 완성입니다. 질문을 못 찾았을 때도 억지로 비슷한 답을 꾸며내기보다 운영진 문의 문구로 돌리는 쪽이 서버 공지를 덜 꼬이게 합니다. 사람이 다시 이어받기 쉬운 형태로 끝나는 봇이 실제 운영에서는 더 편합니다.
/review 이 Discord FAQ 챗봇에서 초보가 바로 밟을 버그만 봐줘. 특히 slash command 등록 누락, .env 이름 오타, 질문이 애매할 때 엉뚱한 답을 고르는 부분만 체크해줘.마지막 검토는 범위를 좁혀야 빨리 끝납니다. 지금 필요한 건 코드 스타일 감상이 아니라 실제로 안 움직일 가능성이 높은 지점 세 군데입니다. slash command 등록이 빠졌는지, .env 변수 이름이 코드와 다른지, 키워드가 너무 넓어서 엉뚱한 답을 고르지 않는지만 보면 됩니다. 이 정도만 체크해도 첫 배포에서 막히는 문제를 꽤 줄일 수 있습니다.
기능을 더 붙이기 전에 확인할 건 단순합니다. 명령이 서버에서 보이는지, 찾은 답이 faq.json에 적어둔 문장과 어긋나지 않는지, 못 찾는 질문에는 안전하게 운영진 문의로 빠지는지입니다. 이 세 가지만 맞아도 디스코드 FAQ 봇 첫 버전으로는 충분히 출발할 수 있습니다.
처음 막히는 지점 세 군데
/ask가 안 보일 때: 봇은 켜졌는데 명령이 안 뜨면 slash command 등록이 빠졌거나 초대 링크에 applications.commands 범위가 없는 경우가 많습니다. 이때는 명령 등록용 파일을 따로 만들게 하고, 초대 링크를 다시 만든 뒤 서버에 재초대하는 쪽이 빠릅니다. 재등록 뒤 1~2분 정도 반영 시간을 두면 상태를 보기 좋습니다.
비슷한 질문에 딴 답이 나올 때: keywords가 너무 넓거나 faq-source.txt 한 항목 안에 주제가 두 개 섞여 있으면 이런 일이 생깁니다. 실제로 들어올 만한 질문 문장 5개를 따로 적어 두고, 그 문장에 맞춰 키워드를 다시 뽑게 하면 검색 정확도가 더 또렷해집니다. 결제 일정과 환불 문의를 한 항목에 같이 넣지 않는 것도 도움이 됩니다.
미리보기는 되는데 봇 로그인에서 멈출 때: 대개 .env에 토큰 앞뒤 공백이 들어갔거나 변수 이름이 코드와 다릅니다. 그래서 .env.example를 함께 만들고, TOKEN 이름을 코드와 예시 파일에서 똑같이 맞추는 편이 안전합니다. 실행 명령을 README에 한 줄로 적어두면 나중에 다시 열어봐도 덜 헷갈립니다.
다음 단계는 질문 누적 파일 붙이기
기본형이 돌아가기 시작하면 답을 못 찾은 질문만 unknown-questions.json에 쌓이게 붙여보세요. 그러면 단순 응답 봇에서 끝나지 않고, 운영진이 어떤 공지를 아직 FAQ로 옮기지 못했는지 보이는 기록이 생깁니다. 서버가 커질수록 새 기능 하나 더 넣는 일보다 이런 누락 기록이 더 실용적으로 남습니다. 나중에 공지가 길어졌을 때도 어디를 먼저 손봐야 할지 금방 드러납니다.
이런 글도 있어요
관련 검색어
- 🔍 Claude Code 사용법
- 🔍 Claude Code 비교
- 🔍 디스코드 FAQ 봇 사용법
- 🔍 디스코드 FAQ 봇 비교
- 🔍 Discord 봇 사용법
- 🔍 Discord 봇 비교
