cron-management

cron.md 구조

전체 구성

# Cron: {자신의_이름}

## 태스크명 1
schedule: 0 9 * * *
type: llm
태스크 설명...

## 태스크명 2
schedule: */5 * * * *
type: command
command: /path/to/script.sh

반드시 지켜야 할 규칙

1. 각 태스크는 ## 태스크명으로 시작 (H2 헤더. H3이나 H1은 사용하지 않음)
2. schedule: 행은 필수 (schedule: 키워드로 시작. ### 헤더가 아님)
3. 스케줄은 표준 5필드 cron 표현식만 가능 (09:00이나 매주 금요일 17:00은 불가)
4. type: 행은 필수 (llm 또는 command)
5. 태스크 사이에 빈 줄을 삽입 (가독성을 위해)

잘못된 형식

❌ ### */5 * * * *           ← H3 헤더에 cron 표현식을 쓰면 안 됨
❌ ### 09:00                 ← 자연어 시간 표기는 불가
❌ ### 매주 금요일 17:00      ← 한국어 스케줄 표기는 불가
❌ cron: 0 9 * * *           ← 키 이름은 "schedule:"이어야 함 ("cron:"이 아님)
❌ interval: 5m              ← interval 형식은 불가
❌ schedule: 0 9 * * * *     ← 6필드는 불가 (5필드만 가능)

올바른 형식

✅ schedule: 0 9 * * *       ← "schedule:" + 스페이스 + 5필드 cron 표현식
✅ schedule: */5 * * * *
✅ schedule: 30 21 * * *
✅ schedule: 0 17 * * 5

5필드 cron 표현식 레퍼런스

필드 구성

schedule: 분 시 일 월 요일

주의: 요일은 0=월요일, 6=일요일 (APScheduler 사양. 일반적인 cron의 0=일요일과 다름)

특수 문자

자주 사용하는 스케줄 예시

매일

간격

요일

월별

태스크 유형 상세

type: llm — LLM 판단 태스크

사고와 판단이 필요한 태스크. schedule:과 type: llm 뒤에 자유롭게 태스크 내용을 작성합니다.

## 매일 아침 업무 계획
schedule: 0 9 * * *
type: llm
장기 기억에서 어제의 진행 상황을 확인하고 오늘의 태스크를 계획합니다.
비전과 목표에 비추어 우선순위를 판단합니다.
결과를 state/current_state.md에 기록합니다.

• 설명 텍스트가 그대로 LLM 프롬프트로 전달됩니다
• 구체적인 출력(무엇을 기록할지)을 명시하면 효과적입니다
• 여러 줄 가능

type: command — 커맨드 실행 태스크

결정적으로 실행할 bash 커맨드나 도구 호출입니다.

패턴 A: bash 커맨드

## 백업 실행
schedule: 0 2 * * *
type: command
command: /usr/local/bin/backup.sh

• command:에 실행할 커맨드를 한 줄로 작성합니다
• 셸 리디렉션 (>, >>, |)을 사용할 수 있습니다
• 여러 줄 커맨드는 비권장 (한 줄로 통합하거나 스크립트 파일을 사용하세요)

패턴 B: 도구 호출

## Slack 아침 인사
schedule: 0 9 * * 0-4
type: command
tool: slack_send
args:
  channel: "#general"
  message: "좋은 아침입니다!"

• tool:에 도구명 (get_tool_schemas()의 스키마명)을 작성합니다
• args: 이하는 YAML 블록 형식으로 2스페이스 인덴트
• dispatch(tool_name, args)를 통해 실행됩니다

옵션: skip_pattern

커맨드의 표준 출력이 특정 패턴에 매칭될 때 LLM 분석 세션을 건너뜁니다.

## Chatwork 미회신 확인
schedule: */5 * * * *
type: command
command: chatwork_cli.py unreplied --json
skip_pattern: ^\[\]$

• skip_pattern:에는 정규 표현식을 작성합니다
• 위 예시에서는 미회신이 0건([])인 경우 건너뜁니다

옵션: trigger_heartbeat

커맨드 출력 시 LLM 분석 세션을 트리거할지를 태스크 단위로 제어합니다.

## Chatwork 미회신 확인
schedule: */15 * * * *
type: command
command: animaworks-tool chatwork unreplied
skip_pattern: ^\[\]$
trigger_heartbeat: false

• trigger_heartbeat: false — 커맨드 출력이 있어도 LLM 분석 세션을 건너뜀
• trigger_heartbeat: true (기본값) — 커맨드 출력이 있으면 cron LLM 세션에서 분석 및 대응
• false, no, 0을 지정하면 LLM 분석 억제. 그 외는 true 처리
• skip_pattern과 병용 가능. trigger_heartbeat: false는 skip_pattern보다 먼저 평가됨
• LLM 분석 세션은 heartbeat 동등의 컨텍스트(기억, Knowledge, 조직 정보)를 가짐

유형 선택 판단 기준

type: command를 사용할 경우

• 실행할 커맨드가 완전히 확정된 경우
• 파라미터가 고정 (리전, 클러스터명, 프로파일 등)
• 결과 판단은 cron LLM 세션에 맡김

type: llm을 사용할 경우

• 상황에 따라 실행 내용을 바꿔야 하는 경우
• 여러 도구를 조합한 조사가 필요한 경우
• 인간적인 판단 및 분석이 실행 단계에서 필요한 경우

금지 패턴

• type: llm에 확정 커맨드를 포함 → 해당 커맨드는 type: command로 해야 함
• "이대로 실행하라"고 작성해 놓고 type: llm 사용 → LLM은 커맨드를 정확히 재현할 수 없음. type: command를 사용하세요

Anima는 "커맨드를 외우는 사람"이 아닙니다

type: command는 사람이 스크립트를 저장하는 것과 같습니다. Anima의 가치는 결과를 보고 판단하는 능력에 있습니다. 확정적인 실행은 프레임워크에 맡기고, Anima에게는 판단, 분석, 보고에 집중시키세요.

cron.md 조작 절차

새 태스크 추가

1. 자신의 cron.md를 읽어들입니다
2. 파일 끝에 새 섹션을 추가합니다
3. 작성 전에 형식을 확인합니다 (아래 체크리스트 참조)
4. 파일을 저장합니다

## 새 태스크명
schedule: <5필드 cron 표현식>
type: llm|command
<설명 또는 command/tool 행>

기존 태스크 변경

1. cron.md를 읽어들입니다
2. 해당 섹션 (## 태스크명에서 다음 ## 직전까지)을 찾습니다
3. 변경할 행 (schedule:, type:, 설명 등)을 편집합니다
4. 파일을 저장합니다

태스크 삭제

1. cron.md를 읽어들입니다
2. 해당 섹션 전체 (## 태스크명에서 다음 ## 직전까지)를 삭제합니다
3. 파일을 저장합니다

태스크 일시 비활성화

HTML 주석으로 감싸면 파서가 건너뜁니다:

<!--
## 일시 정지 중인 태스크
schedule: 0 9 * * *
type: llm
이 태스크는 일시적으로 정지 중입니다.
-->

작성 전 체크리스트

cron.md를 업데이트하기 전에 다음을 반드시 확인하세요:

• 각 태스크가 ## 태스크명으로 시작하는가 (###이나 #이 아닌지)
• schedule: 행이 있는가 (### 헤더나 자연어가 아닌지)
• 스케줄이 5필드 cron 표현식인가 (분 시 일 월 요일)
• 각 필드 값이 유효 범위 내인가 (분: 0-59, 시: 0-23, 일: 1-31, 월: 1-12, 요일: 0-6)
• type: 행이 있는가 (llm 또는 command)
• command 유형의 경우 command: 또는 tool:이 있는가
• tool 유형의 경우 args: 인덴트가 올바른가 (2스페이스)
• 태스크 사이에 빈 줄이 있는가

검증 방법

작성 후 다음 커맨드로 올바르게 파싱되는지 확인할 수 있습니다:

python -c "
from core.schedule_parser import parse_cron_md, parse_schedule
import pathlib

content = pathlib.Path('$ANIMAWORKS_ANIMA_DIR/cron.md').read_text()
tasks = parse_cron_md(content)
for t in tasks:
    trigger = parse_schedule(t.schedule)
    status = '✅' if trigger else '❌ 파싱 실패'
    print(f'{status} {t.name}: schedule=\"{t.schedule}\" type={t.type}')
"

모든 태스크에 ✅가 표시되면 정상입니다. ❌가 나오면 스케줄 표현식을 수정하세요.

전체 기술 예시

# Cron: example_anima

## 매일 아침 업무 계획
schedule: 0 9 * * *
type: llm
장기 기억에서 어제의 진행 상황을 확인하고 오늘의 태스크를 계획합니다.
비전과 목표에 비추어 우선순위를 판단합니다.
결과를 state/current_state.md에 기록합니다.

## Chatwork 미회신 확인
schedule: */5 9-18 * * 0-4
type: command
command: chatwork-cli unreplied --json > $ANIMAWORKS_ANIMA_DIR/state/chatwork_unreplied.json
skip_pattern: ^\[\]$
trigger_heartbeat: false

## Slack 아침 인사
schedule: 0 9 * * 0-4
type: command
tool: slack_send
args:
  channel: "#general"
  message: "좋은 아침입니다! 오늘도 잘 부탁드립니다."

## 주간 회고
schedule: 0 17 * * 4
type: llm
이번 주의 episodes/를 다시 읽고 패턴을 추출하여 knowledge/에 통합합니다.
개선점이 있으면 procedures/에 절차를 추가합니다.

## 월간 리포트
schedule: 0 10 1 * *
type: llm
지난달의 episodes/와 knowledge/를 분석하여 월간 요약 리포트를 작성합니다.
리포트는 knowledge/monthly_report_YYYY-MM.md로 저장합니다.

자주 하는 실수와 수정

주의사항

• cron.md 변경은 서버 재시작 또는 다음 Heartbeat에서 반영됩니다 (즉시 적용되지 않음)
• 타임존은 config.json의 system.timezone으로 설정 가능. 미설정 시 시스템 타임존 자동 감지
• 동시각에 여러 태스크가 겹치면 병렬 실행됩니다
• command 유형 태스크 실패 시에도 서버는 중지되지 않습니다 (로그에 기록됨)
• LLM 유형 태스크 실행에는 현재 모델 설정(status.json)이 사용됩니다
• 다른 Anima의 tools/ 디렉토리에 접근할 때는 사전에 권한을 확인하세요