BRYZE 위키

회사와 브랜드의 기준, 함께 쌓는 지식

사용자 도구

사이트 도구

현재 위치: BRYZE 내부 위키 홈 » ai » 크론잡
ai:assistant_ops_cron

차이

문서의 선택한 두 판 사이의 차이를 보여줍니다.

차이 보기로 링크

양쪽 이전 판이전 판
다음 판		이전 판
ai:assistant_ops_cron [2026-04-09 14:06] – 복잡한 크론잡 단계 분리 원칙과 예시 추가 [기존 위키에서 이전] 172.19.176.1ai:assistant_ops_cron [2026-10-30 14:55] (현재) – 바깥 편집 127.0.0.1
줄 1: 줄 1:
 ====== 크론잡 ====== ====== 크론잡 ======
  
-이 문서는 멀티 에이전트 환경에서 크론잡을 설계·운영하는 사람이 반드시 확인해야 할 주의사항을 정리한 가이드입니다. +멀티에이전트 환경에서 크론잡 등록 시에는 목적지에 대한 정보를 반드시 포함해야 한다.
-핵심 목적은 ''자동 실행은 되었지만 결과가 잘못된 대상에게 전달되는 사고''를 줄이는 것입니다.+
  
-특히 여러 에이전트가 함께 동작하는 환경에서는, +메뉴얼.md 문서는 작업자가 그대로 따라도 오차가 없도록 자세히 작성해야 한다.
-단순히 작업이 성공했는지만 볼 것이 아니라 +
-''어느 에이전트가 실행했는지'', ''어느 계정으로 동작했는지'', ''누구에게 결과가 전달되는지''를 사람이 명확하게 통제해야 합니다.+
  
-===== 1. 왜 이 문서가 필요한가 ===== +복잡한 작업을 수행하는 크론잡은 업무 단계를 나누어 설계해야 한다.
-크론잡은 한 번 설정해두면 반복 실행됩니다. +
-따라서 설정이 잘못된 상태로 배포되면 같은 문제가 계속 반복될 수 있습니다.+
  
-멀티 에이전트 환경에서는 특히 아래와 같은 사고가 발생할 수 있습니다. +구글드라이브 스프레드시트를 참조할 때에는 웹버전 페이지 주소를 함께 기재해야 한다.
-  * A 사용자를 위한 결과가 B 사용자에게 전달됨 +
-  * 테스트용 메시지가 실제 운영 채널로 발송됨 +
-  * 다른 에이전트의 계정/설정을 참조해 잘못 동작함 +
-  * 대상 정보가 비어 있는데도 기본값으로 발송됨+
  
-이 문서는 이런 종류의 운영 실수를 예방하기 위한 사람 중심 체크리스트입니다.+결과 보고 및 진척 상황 확인을 위해 외부 스프레드시트에 기록하도록 설계해야 한다.
  
-===== 2. 가장 중요한 원칙 ===== +메뉴얼은 크론잡 등록 전 수 번 테스트하면서 시행착오를 직접 업데이트하라고 지시한다.
-크론잡은 ''누가 실행하느냐''보다, +
-''결과가 정확히 어디로 가느냐''를 더 엄격하게 관리해야 합니다. +
- +
-운영자가 반드시 지켜야 할 기본 원칙은 아래와 같습니다. +
- +
-  * 목적지 정보가 불명확하면 보내지 않는다. +
-  * 기본값에 기대지 않는다. +
-  * 최근 대화나 마지막 세션 정보를 재사용하지 않는다. +
-  * 이름이 아니라 식별자 기준으로 목적지를 관리한다. +
-  * 테스트와 운영 목적지를 절대 섞지 않는다. +
- +
-즉, +
-''애매하면 발송하지 않는 것''이 +
-''일단 보내고 나중에 수정하는 것''보다 훨씬 안전합니다. +
- +
-===== 3. 가장 흔한 사고 유형 ===== +
-==== 3-1. 목적지 누락 ==== +
-가장 위험한 경우는 결과를 보낼 대상 정보가 빠져 있는데, +
-시스템이 임의의 기본값이나 이전 컨텍스트를 사용해 메시지를 보내는 경우입니다. +
- +
-예시: +
-  * chat_id 없이 발송 +
-  * accountId 없이 발송 +
-  * 대상 세션 정보 없이 마지막 세션에 의존 +
- +
-이 경우 운영자는 ''왜 저 사람에게 갔는지'' 원인을 추적하기 어렵고, +
-수신자는 예상하지 못한 메시지를 받게 됩니다. +
- +
-==== 3-2. 테스트/운영 혼동 ==== +
-처음에는 테스트 채널로 보내던 크론잡이, +
-설정 변경 후 운영 채널로 그대로 나가는 경우가 있습니다. +
- +
-예시: +
-  * 테스트용 목적지를 운영 목적지로 덮어씀 +
-  * 검증용 계정으로 만들었는데 실제 계정으로 전송됨 +
- +
-==== 3-3. 다른 에이전트 컨텍스트 참조 ==== +
-멀티 에이전트 환경에서는 비슷한 이름의 세션이나 설정이 존재할 수 있습니다. +
-이때 ''마지막 값 재사용'' 방식은 매우 위험합니다. +
- +
-예시: +
-  * 다른 에이전트의 accountId 사용 +
-  * 다른 세션의 delivery context 재사용 +
-  * 동일 이름 사용자 간 혼동 +
- +
-===== 4. 반드시 명시해야 하는 항목 ===== +
-크론잡을 설계하거나 검토할 때 아래 정보는 필수 항목으로 봐야 합니다. +
- +
-  * 실행 에이전트 ID +
-  * 채널 종류 (예: googlechat, discord, telegram) +
-  * accountId +
-  * 정확한 목적지 식별자 (chat_id 또는 sessionKey 등) +
-  * 개인 대상인지 그룹 대상인지 +
-  * 목적지 누락 시 어떻게 처리할지 +
-  * 실패 시 재시도 여부 +
-  * 중복 발송 방지 기준 +
- +
-이 항목 중 하나라도 비어 있다면, +
-운영 관점에서는 ''완성되지 않은 크론''으로 보는 것이 안전합니다. +
- +
-===== 5. 사람이 운영할 때 꼭 지켜야 하는 기준 ===== +
-==== 5-1. 이름보다 식별자를 사용한다 ==== +
-사람 이름, 채널 이름, 별칭은 바뀌거나 중복될 수 있습니다. +
-가능하면 아래처럼 식별자를 직접 관리하는 편이 안전합니다. +
- +
-  * 이름보다 chat_id +
-  * 별칭보다 sessionKey +
-  * 감으로 아는 계정보다 accountId +
- +
-==== 5-2. 목적지 없으면 멈추게 한다 ==== +
-목적지가 비어 있거나 애매한데도 발송되게 두면 사고 가능성이 큽니다. +
-운영자는 ''전송 실패''를 두려워하기보다 ''오발송''을 더 위험하게 봐야 합니다. +
- +
-즉, +
-  * 목적지 없음 → 발송 금지 +
-  * accountId 없음 → 발송 금지 +
-  * 채널 불명확 → 발송 금지 +
- +
-이런 규칙이 기본이어야 합니다. +
- +
-==== 5-3. 테스트와 운영을 분리한다 ==== +
-테스트 중인 크론잡은 반드시 별도 목적지에서 검증해야 합니다. +
- +
-권장 방식: +
-  * 테스트용 채널 별도 운영 +
-  * 테스트용 accountId 별도 확인 +
-  * 실제 대상과 동일한 이름을 가진 테스트 대상을 만들지 않기 +
- +
-==== 5-4. 조회 단계와 발송 단계를 분리한다 ==== +
-가능하면 크론잡을 아래처럼 나눠 생각하는 것이 좋습니다. +
- +
-  * 1단계: 정보 조회 / 분석 / 정리 +
-  * 2단계: 목적지 검증 / 발송 +
- +
-이렇게 하면 조회는 성공했더라도, +
-목적지 검증에 실패하면 발송만 중단할 수 있습니다. +
- +
-===== 6. 배포 전에 사람이 확인해야 할 체크리스트 ===== +
-아래 항목은 실제 배포 전에 반드시 사람이 확인해야 합니다. +
- +
-  * 이 크론은 어떤 에이전트가 실행하는가? +
-  * 어떤 계정으로 메시지를 보내는가? +
-  * 목적지 식별자가 정확히 입력되어 있는가? +
-  * 목적지가 개인인지 그룹인지 명확한가? +
-  * 목적지 정보가 없을 때 발송이 막히는가? +
-  * 테스트 채널에서 먼저 검증했는가? +
-  * 동일 메시지 중복 전송 방지 기준이 있는가? +
-  * 문제가 생기면 즉시 중단할 수 있는가? +
- +
-이 체크리스트를 통과하지 못하면 운영 배포를 보류하는 것이 안전합니다. +
- +
-===== 7. 운영자가 피해야 할 패턴 ===== +
-아래 방식은 편해 보여도 멀티 에이전트 환경에서는 사고 가능성이 높습니다. +
- +
-  * 최근 대화 상대를 목적지로 간주하는 방식 +
-  * 마지막 활성 세션을 재사용하는 방식 +
-  * 사람 이름만 보고 목적지를 고르는 방식 +
-  * 기본 계정에 의존하는 방식 +
-  * 테스트와 운영을 같은 채널에서 진행하는 방식 +
-  * 실패 원인 기록 없이 자동 재시도만 반복하는 방식 +
- +
-===== 8. 권장 문서화 방식 ===== +
-크론잡을 만들 때는 최소한 아래 수준으로 문서화하는 것이 좋습니다. +
- +
-  * 실행 에이전트: sungyong +
-  * 채널: googlechat +
-  * accountId: acc_sungyong +
-  * 목적지 chat_id: googlechat:spaces/XXXXX +
-  * 대상 유형: 개인 DM / 그룹 채널 +
-  * 목적지 누락 시 동작: 발송 금지 및 로그 기록 +
-  * 중복 방지 기준: 동일 키 1회만 전송 +
-  * 테스트 목적지: 별도 검증 채널 사용 +
- +
-이 문서화가 되어 있어야, +
-나중에 문제가 생겼을 때 운영자가 원인을 빠르게 추적할 수 있습니다. +
- +
-===== 9. 요약 ===== +
-멀티 에이전트 환경에서 크론잡 운영의 핵심은 +
-''자동 실행'' 자체가 아니라, +
-''정확한 계정과 정확한 목적지로만 안전하게 보내는 것''입니다. +
- +
-특히 목적지 정보가 불명확한 상태에서는 보내지 않는 것이 기본 원칙이며, +
-이 원칙이 오발송과 운영 사고를 줄이는 가장 중요한 안전장치입니다. +
- +
-===== 10. 장기 실행 환경에서의 또 다른 위험: 컨텍스트 손실 ===== +
-OpenClaw 기반 크론잡은 세션이 길어지거나, 대화 이력이 누적되거나, 세션이 초기화되는 상황을 완전히 피할 수 없습니다. +
-이 경우 사람이 보기에는 분명했던 맥락이 실행 시점에는 충분히 남아 있지 않을 수 있습니다. +
- +
-특히 아래와 같은 상황에서 문제가 커집니다. +
-  * 세션이 재시작되어 이전 대화 맥락이 약해진 경우 +
-  * 대화가 너무 길어져 과거 지시가 뒤로 밀린 경우 +
-  * 크론 설명이 짧고 추상적으로만 적혀 있는 경우 +
-  * “전에 하던 방식대로” 같은 암묵적 지시에 의존하는 경우 +
- +
-이런 환경에서는 두루뭉술하게 작성된 크론잡일수록 실행 실패 확률이 높아집니다. +
-또는 실행은 되더라도 사람이 기대한 방식과 조금씩 다른 결과가 나올 수 있습니다. +
- +
-===== 11. 권장 대응: 매뉴얼 문서를 별도로 상세하게 유지 ===== +
-이 문제를 줄이기 위한 가장 현실적인 방법은, +
-크론잡 자체를 짧게만 적어두는 것이 아니라 +
-''작업 기준을 매우 자세히 적은 매뉴얼 문서(MD)를 별도로 유지하고, +
-크론 실행 시 그 문서를 먼저 읽도록 지침에 포함하는 것''입니다. +
- +
-이 방식의 장점은 아래와 같습니다. +
-  * 세션 상태와 관계없이 항상 동일한 기준을 다시 불러올 수 있음 +
-  * 과거 대화 기억에 덜 의존하게 됨 +
-  * 담당자가 바뀌어도 운영 기준이 유지됨 +
-  * 결과 품질 편차를 줄이고 균일성을 높일 수 있음 +
-  * 크론 설명문은 짧게 유지하면서도 실제 판단 기준은 상세하게 관리 가능함 +
- +
-즉, +
-크론 자체에는 ''무엇을 언제 실행할지''를 적고, +
-별도 매뉴얼 문서에는 ''어떻게 판단하고 어떤 형식으로 결과를 만들지''를 상세히 적는 구조가 바람직합니다. +
- +
-===== 12. 매뉴얼 문서에 반드시 들어가야 할 내용 ===== +
-크론잡이 참조할 매뉴얼 문서에는 최소한 아래 항목을 상세하게 적는 것이 좋습니다. +
- +
-  * 작업 목적 +
-  * 입력 데이터의 위치와 형식 +
-  * 반드시 확인해야 하는 전제 조건 +
-  * 예외 상황 처리 방식 +
-  * 결과 정리 형식 +
-  * 금지해야 할 행동 +
-  * 전송 대상과 전송 조건 +
-  * 실패 시 대응 방식 +
-  * 예시 입력 / 예시 출력 +
-  * 사람이 기대하는 문체 또는 보고 형식 +
- +
-가능하면 애매한 표현보다, +
-실행자가 그대로 따를 수 있는 수준으로 구체적으로 적는 것이 좋습니다. +
- +
-좋지 않은 예: +
-  * 최근 내용 보고 적절히 정리해서 보내기 +
- +
-좋은 예: +
-  * 지정 문서 A를 먼저 읽고, +
-  * 시트 B의 특정 범위를 확인한 뒤, +
-  * 누락 행이 있으면 제외 사유를 기록하고, +
-  * 결과는 3줄 요약 + 상세 항목 형식으로, +
-  * 지정된 chat_id에만 전송하기 +
- +
-===== 13. 크론 지침에 넣어야 할 문구 방향 ===== +
-크론 설정 또는 지침에는, +
-실행 전에 특정 매뉴얼 문서를 반드시 읽도록 명시하는 것이 좋습니다. +
- +
-예시 방향: +
-  * 실행 전 지정된 MANUAL.md 문서를 먼저 읽을 것 +
-  * 과거 대화 맥락에 의존하지 말고 문서 기준으로 판단할 것 +
-  * 문서에 없는 사항은 추정하지 말고 보수적으로 처리할 것 +
-  * 목적지 정보가 누락되면 전송하지 말 것 +
- +
-핵심은, +
-크론이 ''기억''에 기대지 않고 ''문서화된 기준''에 기대도록 설계하는 것입니다. +
- +
-===== 14. 운영 관점에서 기대할 수 있는 효과 ===== +
-이 방식을 적용하면 아래와 같은 효과를 기대할 수 있습니다. +
- +
-  * 세션 길이에 따른 품질 흔들림 감소 +
-  * 재시작 이후에도 동일한 기준 유지 +
-  * 운영자 의도와 결과물 간 편차 축소 +
-  * 신규 담당자 인수인계 용이 +
-  * 크론 실행 실패 및 오해석 가능성 감소 +
- +
-특히 정기 실행 작업은 ''한 번 잘 되는 것''보다 +
-''매번 비슷한 품질로 안정적으로 동작하는 것''이 중요하므로, +
-문서 기반 실행 방식이 장기적으로 더 안전합니다. +
- +
-===== 15. 복잡한 크론잡은 작업 단계를 나누어 설계하는 것이 안전함 ===== +
-복잡한 작업을 한 번의 크론 실행 안에서 모두 처리하려고 하면, +
-중간 판단이 많아지고 예외 상황이 늘어나면서 실패 확률이 높아집니다. +
- +
-특히 아래와 같은 작업은 단일 단계로 처리할수록 불안정해질 가능성이 큽니다. +
-  * 여러 데이터 소스를 동시에 읽어야 하는 작업 +
-  * 조회 → 정리 → 판단 → 전송이 모두 포함된 작업 +
-  * 표 분리, 문서 읽기, 예외 처리, 보고 형식 결정이 함께 필요한 작업 +
-  * 사람마다 다른 목적지나 다른 기준을 적용해야 하는 작업 +
- +
-이런 유형은 가능한 한 ''업무 단계를 나누어 쪼개서'' 설계하는 것이 좋습니다. +
- +
-===== 16. 왜 단계 분리가 필요한가 ===== +
-복잡한 작업을 단계별로 나누면 아래와 같은 장점이 있습니다. +
- +
-  * 각 단계의 역할이 명확해집니다. +
-  * 어느 단계에서 실패했는지 원인 추적이 쉬워집니다. +
-  * 중간 결과를 검증할 수 있습니다. +
-  * 발송 단계 전에 검토/차단이 가능합니다. +
-  * 세션 컨텍스트가 짧아져도 각 단계의 목적이 덜 흔들립니다. +
-  * 동일한 로직을 다른 크론에서도 재사용하기 쉬워집니다. +
- +
-즉, +
-''한 번에 다 하게 하는 방식''보다 +
-''잘게 나눈 뒤 순서대로 처리하는 방식''이 안정성과 재현성 측면에서 유리합니다. +
- +
-===== 17. 권장 분리 방식 ===== +
-복잡한 크론잡은 보통 아래처럼 나누어 생각하는 것이 좋습니다. +
- +
-  * 1단계: 데이터 조회 +
-  * 2단계: 데이터 정리 / 전처리 +
-  * 3단계: 해석 / 판단 +
-  * 4단계: 결과 포맷팅 +
-  * 5단계: 목적지 검증 후 발송 +
- +
-모든 작업이 반드시 5단계일 필요는 없지만, +
-최소한 ''조회''와 ''발송''은 분리하는 것이 안전합니다. +
- +
-===== 18. 권장 예시 1: 스프레드시트 요약 보고 ===== +
-예를 들어, 여러 표가 섞여 있는 Google 스프레드시트를 읽고 요약 보고를 보내는 크론이 있다고 가정합니다. +
- +
-좋지 않은 방식: +
-  * 스프레드시트를 읽는다 +
-  * 여러 표를 한 번에 해석한다 +
-  * 바로 요약을 만든다 +
-  * 곧바로 메시지를 발송한다 +
- +
-이 방식은 중간 검증이 어렵고, +
-표 구조를 잘못 읽었을 때 오해석된 결과가 그대로 발송될 가능성이 있습니다. +
- +
-권장 방식: +
-  * 1단계: 시트를 읽고 ''◆'' 기준으로 큰 표를 분리한다 +
-  * 2단계: 각 표 안에서 ''▶'', ''■'', ''▷'' 기준으로 내부 구조를 다시 정리한다 +
-  * 3단계: 표별 요약 데이터를 만든다 +
-  * 4단계: 표별 요약을 최종 보고 형식으로 합친다 +
-  * 5단계: 목적지와 accountId를 검증한 뒤 발송한다 +
- +
-이렇게 나누면, +
-어느 단계에서 오류가 났는지 확인하기 쉽고, +
-문제 발생 시 발송 전에 멈출 수 있습니다. +
- +
-===== 19. 권장 예시 2: 정기 알림 + 예외 감지 ===== +
-예를 들어 매일 특정 데이터를 확인해 이상 징후가 있을 때만 알림을 보내는 크론의 경우에도, +
-한 번에 처리하기보다 아래처럼 나누는 것이 좋습니다. +
- +
-권장 방식: +
-  * 1단계: 원본 데이터 조회 +
-  * 2단계: 기준값과 비교해 예외 후보 추출 +
-  * 3단계: 예외 후보 중 실제 알림 대상만 선별 +
-  * 4단계: 알림 문구 생성 +
-  * 5단계: 전송 대상 검증 후 발송 +
- +
-이렇게 하면 ''이상치 탐지''와 ''메시지 발송''이 분리되므로, +
-탐지 로직만 수정하거나 발송 단계만 별도 점검하기가 쉬워집니다. +
- +
-===== 20. 문서화할 때도 단계별로 적는 것이 좋음 ===== +
-크론잡 설명이나 매뉴얼 문서도, +
-작업을 한 문단으로 뭉뚱그려 적기보다 단계별로 적는 편이 좋습니다. +
- +
-좋지 않은 예: +
-  * 매일 아침 데이터를 확인해서 적당히 요약하고 필요한 사람에게 보내기 +
- +
-권장 예: +
-  * 1단계: 문서 A와 시트 B를 읽기 +
-  * 2단계: 누락 행과 예외 행을 분리하기 +
-  * 3단계: 예외 행만 기준 규칙으로 재분류하기 +
-  * 4단계: 지정된 형식으로 보고문 만들기 +
-  * 5단계: 목적지 식별자를 검증한 뒤 전송하기 +
- +
-이런 식으로 문서화하면, +
-실행 주체가 사람이든 에이전트든 동일한 순서로 작업을 재현하기 쉬워집니다. +
- +
-===== 21. 요약 ===== +
-복잡한 크론잡은 한 번에 처리하게 만들수록 실패 확률이 높아집니다. +
-반대로 작업을 단계별로 잘게 나누면, +
-원인 추적, 중간 검증, 예외 처리, 발송 통제가 쉬워져 안정성이 올라갑니다. +
- +
-따라서 복잡한 자동화 작업일수록 +
-''한 개의 큰 지시''보다 +
-''잘게 쪼갠 여러 단계의 지시''로 설계하는 것이 권장됩니다.+
  
 +크론잡을 수행해야 할 때 사용해야 하는 도구를 명시해야 한다. 어떤 도구를 사용해야 할지 모를 때에는 비서에게 지시하고 어떤 도구를 사용했는지 물어보면 된다.
  
ai/assistant_ops_cron.1775711163.txt.gz · 마지막으로 수정됨: (바깥 편집)
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki