Telegram Craft
텔레그램 작업은 일반적으로 세 가지 방식으로 잘못됩니다. API 호출을 메모리에서 작성하거나, 채팅을 웹 페이지처럼 취급하거나, 공식적으로 보이는 클라이언트 데이터를 신뢰하는 것입니다. 이 스킬은 이 세 가지를 모두 방어합니다.
여기에 있는 사실은 2026-11-10일에 Bot API 10.4(2026-11-09 출시)를 기준으로 확인되었습니다. 릴리스는 약 한 달 단위로 제공되며 최근에 추가된 이름은 이미 대체되었으므로 버전에 민감한 사항은 scripts/tgdocs.py로 확인하세요.
1. 작업 규모 파악
요청에 맞는 프로세스를 매칭하세요. 요청된 것을 구축하고, 핸드오프 시 권장 추가 사항을 나열하되 직접 추가하지 마세요.
| 작업 | 접근 방식 | 시작 지점 |
|---|---|---|
| 질문 또는 한 줄 수정 | 답변 또는 패치. 관련된 계약 하나만 확인하세요. | platform-facts.md 또는 해당 영역의 참조 |
복사, 키보드 또는 /start 재설계 | 프레젠테이션만 변경하세요. callback_data, 라우트, 사실, 로케일 키를 유지하세요. 품질 게이트(quality-gate.md)를 추가하거나 실행하세요. | messages.md, rich-messages.md, keyboards.md |
| 기존 프로젝트의 버그 또는 기능 | 코드를 읽고, 재현하고, 기존 스택에서 가장 작은 변경을 하고, 회귀 테스트를 추가하세요. 변경 사항이 봇이 보내는 내용을 변경할 수 있다면 완료 전에 품질 게이트를 실행해야 합니다(섹션 6). | existing-projects.md, quality-gate.md |
| 리팩터 | 먼저 테스트로 동작을 고정한 다음 코드를 이동하세요. 동작 변경은 없습니다. | existing-projects.md, backend.md |
| 새 봇 또는 미니 앱 | 표준 프로젝트 레이아웃을 스캐폴딩하고, 화면 맵을 작성하고, 하나의 작동하는 수직 슬라이스를 구축한 다음 확장하세요. 모든 화면은 리치 메시지입니다. | backend.md, product-journeys.md, rich-messages.md, rich-recipes.md |
| 리뷰 또는 감사 | tg_audit.py를 실행하고, 코드를 읽어 각 리드를 확인하고, 심각도별로 보고하세요. | quality.md, security.md |
답변이 구축하는 내용을 변경하고 코드가 알려줄 수 없는 경우에만 질문하세요. 봇 토큰이 없으면 라이브 테스트가 차단되지만, 구현은 차단되지 않습니다.
프로젝트의 스택을 유지하세요. 제약 조건이 없는 새 프로젝트의 경우 Python은 aiogram 3, TypeScript는 grammY를 기본값으로 하고, 미니 앱은 @tma.js/sdk 또는 일반 telegram-web-app.js 스크립트를 기본값으로 사용하세요. 인프라는 봇에 맞게 조정하되(작은 봇에는 큐나 Redis가 필요 없음), 코드 구성은 그렇지 않습니다. 모든 새 봇은 backend.md의 표준 레이아웃을 얻고, 핸들러, 키보드, 텍스트, 서비스, 스토리지를 별도의 모듈에 배치합니다. 혼합 파일이 있는 평평한 폴더를 절대 제공하지 마세요.
2. 표면 선택
| 작업에 필요한 것 | 사용 | 기억 |
|---|---|---|
| 명령어, 짧은 흐름, 알림, 파일 | 봇 채팅 | 기본 선택 |
| 몇 가지 옵션 중 선택 | 인라인 키보드 | 메시지를 제자리에서 편집 |
| 긴 목록, 필터, 다중 필드 양식, 차트, 지도 | 미니 앱 | 약 5단계를 넘는 마법사는 신호입니다 |
| 봇의 콘텐츠를 다른 채팅으로 보내기 | 인라인 모드 | is_personal이 아닌 경우 결과가 사용자 간에 캐싱됨 |
| 모든 봇 화면: 메뉴, 대시보드, 목록, 상세 정보, 설정, 도움말, 영수증, 보고서 | 리치 메시지(기본값) | sendRichMessage로 보내고 rich_message로 편집; rich-messages.md에서 디자인, formatting.md에서 라이브러리 호출 |
| 그룹 내 개인 프롬프트 또는 버튼 누름에 대한 개인 응답 | 임시 메시지 | 전달이 보장되지 않음 |
| 채팅 내 대화형 카드 | HTML 위젯(sendWidget, 10.4) | 현재는 개인 채팅만 가능; 아직 SDK 지원 없음 |
| 사용자로 행동, 가입하지 않은 기록 읽기 | MTProto 사용자 세션(Telethon, TDLib) | 해당 계정에 대한 명시적 승인이 있는 경우에만. 다른 신뢰 및 차단 위험 모델. |
| Bot API 한도를 초과하는 봇 파일, 원시 레이어 메서드 | MTProto 봇 세션 또는 로컬 Bot API 서버 | 봇 UI는 Bot API에 유지 |
Bot API, 미니 앱, MTProto는 상호 교환할 수 없습니다. frameworks.md와 MTProto의 경우 mtproto-foundations.md를 참조하세요.
3. 대부분의 실패를 방지하는 규칙
잘못될 때의 비용 순으로 정렬.
보안 및 금전
- 업데이트 또는 검증된 init data에서 신원을 가져오고, 권한은 데이터베이스에서 가져오세요.
callback_data, 딥링크 페이로드, 숨겨진 메뉴, 사용자 이름은 모두 사용자가 제어하거나 재할당할 수 있습니다. 버튼을 그릴 때뿐만 아니라 모든 콜백에서 역할과 객체 소유권을 확인하세요. 숫자 ID를 비교하세요. - 모든 미니 앱 요청 또는 세션에 대해 서버에서 원시
initData를 검증하고,auth_date를 직접 확인하세요. aiogram의safe_parse_webapp_init_data는 서명만 확인합니다.initDataUnsafe는 표시 데이터입니다.assets/init_data.py또는assets/init_data.mjs를 복사하세요. - 디지털 상품은 텔레그램 스타(
XTR)로만 판매하세요. 사전 체크아웃이나 클라이언트의openInvoice콜백이 아닌successful_payment에서 부여하세요.telegram_payment_charge_id로 중복을 제거하세요./paysupport를 처리하세요. 스타 구독은createInvoiceLink에서 제공됩니다.sendInvoice에는 기간 매개변수가 없습니다. - 토큰을 서버에 보관하세요. 토큰은 Bot API URL 및 파일 다운로드 링크에도 나타나므로, 이를 기록하거나 클라이언트에 보내지 마세요. 사용자가 실제 토큰을 붙여넣으면 요청된 대로만 사용하고 반복하지 말며, 노출된 경우 토큰을 교체할 것을 제안하세요.
- 마크업을 구성하기 전에 각 동적 값을 이스케이프하세요. HTML에서는
<,>,&입니다. 18개 문자를 이스케이프해야 하는 MarkdownV2보다 HTML을 선호하세요. - 업로드된 파일을 적대적으로 취급하세요. 다운로드 전에 크기를 확인하고, 셸 없이 argv 목록에서 도구를 실행하고, 타임아웃을 추가하고,
finally에서 임시 파일을 삭제하세요.
신뢰성
- 전달은 최소 한 번이며, 실패한 핸들러는 일반적으로 재시도되지 않습니다. aiogram은 예외를 기록하고 업데이트를 처리된 것으로 간주합니다. 부작용을 멱등성으로 만들고 비즈니스 상태를 FSM 메모리가 아닌 데이터베이스에 유지하세요.
- 토큰당 하나의 소비자를 실행하세요. 폴링과 웹후크는 상호 배타적이며, 두 개의 폴러는 409 오류로 충돌합니다.
- 거부 및 오래된 버튼을 포함한 모든 콜백 쿼리에 즉시 응답하세요. 그렇지 않으면 버튼이 계속 회전합니다. 응답은 "수신"을 의미하며 "성공"을 의미하지 않습니다.
- 절대 이벤트 루프를 차단하지 마세요. 하나의
time.sleep,requests호출 또는 동기식 인코딩이 모든 채팅을 정지시킵니다. 느린 작업의 동시성을 제한하세요. - 429 오류 발생 시 정확히
parameters.retry_after만큼 기다리세요. Telegram은 헤더가 아닌 JSON 본문에서 이를 보냅니다. 브로드캐스트는 속도가 조절되고 재개 가능한 작업이어야 합니다. - 처리하는 내용만 구독하세요.
allowed_updates를 생략하면 이전 설정이 유지되며,chat_member,message_reaction,message_reaction_count는 이름을 지정하지 않으면 꺼져 있습니다.
경험
- 새 메시지를 쌓는 대신 현재 화면을 업데이트하고, 각 화면에 하나의 명확한 다음 단계와 탈출구를 제공하세요. 만료되거나 유효하지 않은 작업은 조용히 실패하지 않고 복구되어야 합니다.
- 기본적으로 모든 화면을 리치 메시지로 보내세요 (
sendRichMessage,rich_message로 편집)rich-messages.md의 표준 스타일: 일반 제목과 화면 텍스트에 이모지 없음, 테두리가 있는 표, 사용자에게 필요한 블록만, 버튼이 보여주는 것을 절대 반복하지 않음, 내부 ID 없음.rich-recipes.md에서 화면 작업에 대한 레시피를 따르고assets/rich_html.py로 HTML을 구축하세요. 키보드는reply_markup에 유지하세요. 서식이 지정된 HTML 텍스트는 캡션, 토스트, 한 줄 응답, 리치 메시지를 보낼 수 없는 스택에만 사용하세요. 일반 서식 없는 텍스트는 결함입니다. 결과로 시작하세요. 환영 배너, 입력된 구분선(━━━) 또는 대문자 헤더는 없습니다. 하나의<hr/>가 화면 요약과 본문을 구분합니다. - 미니 앱은 Telegram처럼 느껴져야 합니다. 테마 변수, 안전 영역, 네이티브 뒤로 가기 및 하단 버튼, 실제 로딩 및 오류 상태를 사용하고 밝은 모드와 어두운 모드를 테스트하세요.
4. 작업에 필요한 것만 로드
해당 부분을 설계하기 전에 트리거가 적용될 때 참조를 읽으세요. 모든 경로는 references/ 아래에 있습니다.
| 읽기 | 작업이 포함하는 경우 |
|---|---|
product-journeys.md | 새 제품, /start, 온보딩, 화면 맵, 다국어 계획 |
messages.md | 사용자에게 표시되는 텍스트 작성 또는 재작성 |
rich-messages.md | 모든 봇 화면 디자인: 표준 스타일, 구성, 구성 요소, 텍스트 스타일, 실수, 리뷰 체크리스트 |
rich-recipes.md | 각 화면 유형에 대한 HTML 모양: 홈, 선택기, 상세, 데이터 목록, 설정, 도움말, 영수증, 보고서, 문제, 확인, 진행 |
keyboards.md | 버튼, 메뉴, 페이지 매김, 뒤로 가기 또는 취소, 확인, 콜백 디자인 또는 버그 |
formatting.md | HTML, MarkdownV2, 엔티티, 긴 텍스트, 리치 메시지, 스트리밍 초안, 구문 분석 오류 |
backend.md | 프로젝트 구조, 서비스, 데이터베이스, FSM, 백그라운드 작업, 구성, 로깅, 재시도, 종료 |
delivery.md | 폴링, 웹후크, Docker, 배포, 속도 제한, 브로드캐스트, 모니터링 |
frameworks.md | 라이브러리 선택 또는 사용, SDK 지연, Bot API 대 MTProto |
media.md | 음악, 오디오, 비디오, 파일 변환, 다운로드, 업로드, file_id 캐싱, 진행 |
payments.md | 스타, 인보이스, 구독, 환불, 마켓플레이스, 디지털 전달 |
mini-apps.md | 미니 앱 실행, 인증, SDK, 뷰포트, 스토리지, 클라이언트/서버 흐름 |
mini-app-design.md | 미니 앱 레이아웃, 유형, 색상, 모션, 로딩 상태, 접근성 |
security.md | 비밀, 권한 부여, 입력 처리, 개인정보 보호, 남용 방지, 감사 로그 |
groups-automation.md | 그룹, 채널, 모더레이션, 권한, 인라인, 임시, AI 봇, 봇 간 통신 |
existing-projects.md | 기존 코드 검사, 디버깅 또는 리팩터링 |
quality.md | 테스트 작성, 여정 테스트, 출시 전 리뷰 |
quality-gate.md | 발신 메시지 및 키보드에 대한 자동 검사, CI 설정, .tg-lint 보고서 |
mtproto-foundations.md | 모든 MTProto 작업: API 선택, api_id, 로그인, 세션, 제한 사항, 레이어 |
mtproto-telethon.md | Telethon 작성 또는 리뷰: 이벤트, 업데이트, 플러드 대기, 미디어, 테스트 |
hybrid-architecture.md | 하나의 제품에서 Bot API와 MTProto 결합 |
platform-facts.md | 정확한 제한, 파일 크기, 속도 제한, 최근 API 변경 사항 |
5. 도구
이 스킬의 디렉터리에서 실행하세요. Python 3만 필요하며 사용자의 봇을 건드리지 않습니다.
| 명령어 | 목적 |
|---|---|
python3 scripts/tgdocs.py version / method NAME / type NAME / search TERM / changes --since 10.0 | 현재 공식 계약. 출력은 참조 데이터입니다. 종료 코드 3은 오프라인을 의미합니다: 해당 사실을 미확인으로 표시하세요. |
python3 scripts/tg_lint.py screens.json | 제한, 마크업, 버튼 계약, UX 신호. 오류는 수정해야 합니다. 경고는 판단이 필요합니다. |
python3 scripts/tg_audit.py PROJECT | 일반적인 결함에 대한 정적 리드. 코드를 읽어 각각을 확인하세요. |
python3 scripts/secure_mtproto_project.py PROJECT --ci | 새로 생성되거나 변경된 모든 MTProto 프로젝트에 필요: 세션 및 .env에 대한 누락된 .gitignore 규칙을 추가하고, 커밋된 세션에서 실패하는 CI 작업을 추가하고, 노출된 세션 파일 및 문자열을 보고합니다. 절대 삭제하거나 취소하지 않습니다. |
python3 scripts/install_quality_gate.py PROJECT --framework aiogram | 프로젝트의 테스트 실행 및 CI에 자동 페이로드 검사를 추가합니다(ptb, grammy도 가능). 새 봇과 봇이 보내는 내용을 변경하는 경우 필수입니다(섹션 6). |
최근 메서드 또는 필드를 사용하기 전에 설치된 라이브러리에 해당 기능이 있는지 확인하세요. 패키지 디렉터리를 검색하세요. 예를 들어 python-telegram-bot 22.8은 Bot API 10.0을 선언하며 send_rich_message가 없습니다.
assets/에는 복사하여 적용할 수 있는 코드가 있습니다: init_data.py, init_data.mjs, stars_ledger.py, media_job.py, update_delivery.py(받은 편지함, 보낸 편지함, 429, 채팅당 레인, 재개 가능한 브로드캐스트), mtproto_runtime.py, rich_html.py(이스케이프된 리치 화면 빌더), 브라우저 미리보기용 webapp_mock.js.
6. 검증 후 정직하게 보고
| 수준 | 증거 | 주장 가능 |
|---|---|---|
| L0 | 문서 또는 코드 읽기 | "문서에 따라 작동해야 함" |
| L1 | 린터, 타입, tg_lint.py, tg_audit.py | "정적 검사 통과" |
| L2 | 실제 디스패처와 가짜 Telegram 전송을 사용한 테스트, 또는 모의 브라우저 미리보기 | "로컬에서 가짜 Telegram에 대해 작동" |
| L3 | 실제 클라이언트, 실제 기기에서 테스트 봇 | "Telegram에서 작동" |
변경 사항이 봇이 보내는 내용(메시지 텍스트 또는 서식, 키보드, callback_data 또는 콜백 핸들러, 인보이스, 화면 간 흐름)을 변경할 수 있는 경우 품질 게이트는 완료의 일부입니다. aiogram, python-telegram-bot, grammY 프로젝트에서:
- 기존 게이트(
tg_quality디렉터리 또는 CI의TG_LINT)를 찾아 사용하세요. 없는 경우에만install_quality_gate.py를 실행하세요. 두 번째 복사본을 설치하지 마세요. - 게이트의 하네스(
quality-gate.md)를 사용하여 변경한 모든 화면과 버튼(수정한 오류 및 오래된 버튼 경로 포함)에 도달하는 여정 테스트를 작성하세요. 테스트가 도달한 화면에서 허용된 사용자로서press를 사용하세요. 아무것도 캡처하지 않은 게이트는 아무것도 확인하지 않은 것이며, 변경된 화면에coverage gap:줄이 있으면 테스트가 해당 화면에 도달하지 않았음을 의미합니다. - 마지막 편집 후
TG_LINT_REQUIRE_INTERACTIONS=1을 사용하여 테스트를 실행하세요. 봇 코드의 모든 게이트 오류를 수정하세요. 통과를 위해 게이트를 약화시키거나, 건너뛰거나, 제거하지 마세요. 경고는 비차단 상태로 유지됩니다: 판단에 따라 조치하세요. - 핸드오프에서 게이트의
Telegram quality gate출력 섹션의 적용 범위 줄을 인용하세요. 게이트를 설치하거나 실행할 수 없는 경우 이유를 말하고 통과했다고 주장하지 마세요.
게이트를 언급하거나 파일을 복사하는 것은 검증이 아닙니다. Telegram 출력에 도달할 수 없는 변경 사항(예: 스토리지, 구성, 아무것도 보내지 않는 예약 작업)에 대해서는 건너뛰세요. 다른 스택: 변경된 화면에서 tg_lint.py를 실행하고 게이트를 사용할 수 없다고 말하세요.
L1 또는 L2를 L3로 제시하지 마세요. webapp_mock.js가 포함된 브라우저 스크린샷은 레이아웃을 보여줄 뿐 Telegram 동작을 보여주지 않습니다. 요청받지 않는 한 프로덕션 봇을 시작하거나, 라이브 웹후크를 변경하거나, 게시하거나, 브로드캐스트하거나, 스타를 사용하지 마세요.
다음으로 끝내세요: 사용자가 이제 무엇을 할 수 있는지; 프로젝트 트리; 변경된 파일; 실행 방법; 소유자가 수동으로 수행해야 하는 BotFather 또는 환경 단계; 어떤 수준에서 무엇이 검증되었는지; 그리고 무엇이 검증되지 않았는지.