HEARTBEAT.md는 AI가 하트비트 때마다 읽는 작업 지시서 입니다.
이 파일 하나로 AI의 능동적 행동을 완전히 제어할 수 있습니다.
기본 구조 # HEARTBEAT.md ## 체크 항목 (돌아가며 하루 2-4회) - [ ] 이메일 - 긴급한 안 읽은 메시지? - [ ] 캘린더 - 24-48시간 내 이벤트? - [ ] 날씨 - 급변 예보? ## 조용한 시간 - 23:00-08:00: 긴급 아니면 알림 금지 ## 연락할 때 - 중요 이메일 도착 - 캘린더 이벤트 2시간 전 - 8시간 이상 무소식 ## 조용히 있을 때 (HEARTBEAT_OK) - 새로운 거 없을 때 - 30분 전에 방금 체크했을 때
섹션별 설계 체크 항목 AI가 라운드 로빈으로 순회할 항목들입니다:
## 체크 항목 - [ ] 이메일 - 새 메일 중 긴급한 것 - [ ] 캘린더 - 다가오는 일정 - [ ] GitHub - 새 PR/이슈/멘션 - [ ] 서버 상태 - 이상 징후 - [ ] 프로젝트 진행 - 마감 임박 태스크
항목이 많을수록 토큰 소모가 늘어납니다.
5개 이하로 유지하고, heartbeat-state.json으로 라운드 로빈 하세요.
판단 기준 AI가 언제 알려야 하는지 명확하게 지정합니다:
## 알림 기준 ### 즉시 알림 🔴 - 상사/고객 이메일 - 1시간 내 회의 - 서버 다운 ### 다음 대화 때 🟡 - 일반 업무 메일 - 내일 일정 변경 ### 무시 ⚪ - 뉴스레터, 프로모션 - 이미 알고 있는 것
조용한 시간 ## 조용한 시간 - 평일: 23:00-07:00 - 주말: 00:00-09:00 - 예외: 서버 다운, 긴급 이메일
조용한 시간을 설정하지 않으면 새벽 3시에도 알림이 올 수 있습니다.
반드시 설정하세요.
자율 작업 알림 없이 AI가 스스로 할 수 있는 작업:
## 자율 작업 (알림 불필요) - memory/ 파일 정리 및 MEMORY.md 업데이트 - git status 확인, 자기 변경사항 커밋 - 문서 오타 수정 - heartbeat-state.json 업데이트
고급: 임시 태스크 추가 HEARTBEAT.md에 임시 항목을 추가해서 단기 모니터링에 활용:
## 임시 태스크 (완료 후 삭제) - [ ] 택배 배송 추적 - 배송완료되면 알려줘 (2/15까지) - [ ] PR #123 리뷰 상태 - 승인되면 알려줘
AI에게 직접 요청할 수도 있습니다:
사용자: "내일까지 택배 추적해줘. 도착하면 알려줘" → AI가 HEARTBEAT.md에 임시 항목 추가 → 하트비트마다 체크 → 도착 확인 시 알림 + 항목 삭제
실전 HEARTBEAT.md 템플릿 # HEARTBEAT.md ## 순회 체크 (돌아가며) - [ ] 이메일 (gmail 스킬) - [ ] 캘린더 (24h 이내 일정) - [ ] GitHub 멘션/PR ## 알림 규칙 - 🔴 즉시: 긴급 메일, 1h 내 일정, 서버 이상 - 🟡 나중: 일반 업무, 내일 일정 - ⚪ 무시: 스팸, 이미 확인한 것 ## 조용한 시간 - 23:00-07:00 (긴급 외 알림 금지) - 주말은 10:00 이후부터 ## 자율 작업 - 메모리 파일 정리 - heartbeat-state.json 업데이트 - 자기 변경사항 git commit/push ## 임시 (없음)
heartbeat-state.json 연동 { "lastChecks" : { "email" : 1707620400 , "calendar" : 1707616800 , "github" : null }, "lastNotification" : 1707620400 , "tempTasks" : { "택배추적" : { "deadline" : "2026-02-15" , "status" : "tracking" } } }
AI는 이 JSON을 읽어서 가장 오래된 체크 항목을 우선 확인합니다.
매번 모든 걸 확인하지 않으므로 하트비트당 토큰 소모가 적습니다.
FAQ
AI가 HEARTBEAT.md를 직접 수정해도 되나요? 네! AI에게 “HEARTBEAT.md에 이거 추가해”라고 말하면 됩니다.
자율 작업 중 완료된 임시 태스크 삭제도 AI가 합니다.
하트비트 간격은 어떻게 바꾸나요? config.yaml의 heartbeat.intervalMinutes를 수정하세요.
30분이 비용과 반응성의 좋은 균형점입니다.