Communitygithub.com

edsmkt/observer-kit

시각적이고 검토 가능한 데이터 변환 워크플로우를 위한 로컬 대시보드 및 에이전트 스킬입니다.

observer-kit란 무엇인가요?

Observer Kit은 AI 에이전트(Codex, Claude, Pi, Command Code, Goose 등) 세션을 두뇌로 유지하면서, 로컬 워크플로우 실행을 위한 하네스(harness)를 제공합니다. 이 스킬은 판단력을 공급하고, CLI는 반복 가능한 파이프라인을 제공하며, 스크립트가 실제 작업을 수행하고, 왓쳐(watcher)가 운영자 메시지를 활성 세션으로 다시 전달합니다. 모든 실행은 '라이브니스(Liveness)'와 '내구성(Durability)'이라는 두 가지 핵심 보장을 중심으로 구축됩니다. 라이브니스는 작업 중 JSONL 이벤트가 지속적으로 기록되어 대시보드가 최신 상태를 유지하도록 보장하며, 내구성은 완료된 결과가 재시작 시 저장된 작업을 이어갈 수 있도록 다시 읽을 수 있는 내구성 있는 저장소에 도달하도록 보장합니다. 결과적으로 개발자는 워크플로우의 진행 상황, 지표, 오류를 대시보드에서 실시간으로 모니터링하고, 중단 시점에서 안전하게 재개할 수 있습니다.

지원 대상✓Claude Code✓Codex CLI~Cursor
npx skills add edsmkt/observer-kit

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Observer Kit

Observer Kit을 로컬 워크플로우 하네스로 사용하세요. 현재 Codex, Claude, Pi, Command Code, Goose 또는 다른 에이전트 세션은 두뇌 역할을 유지합니다. 이 스킬은 판단력을 제공하고, CLI는 반복 가능한 파이프라인을 제공하며, 스크립트는 작업을 수행하고, 왓쳐는 운영자 메시지를 활성 세션으로 다시 전달합니다.

모든 실행을 두 가지 별개의 보장을 중심으로 구축하세요:

  • 라이브니스: 작업이 진행되는 동안 JSONL 이벤트가 기록되어 대시보드가 최신 상태를 유지합니다.
  • 내구성: 완료된 결과가 내구성 있는 경계에서 다시 읽을 수 있는 저장소에 도달하여 재시작 시 저장된 작업을 이어갑니다.

1. 올바른 컨텍스트 로드

이 SKILL.md가 포함된 디렉토리에서 상대 경로를 확인하세요.

다음 위치 중 첫 번째로 사용 가능한 위치에서 Observer Kit README를 읽으세요:

이를 통해 제품 약속, 스킬/CLI 분할, 운영자 여정 및 대시보드 기대치를 학습하세요.

활성 브랜치를 선택하고 해당 참조를 로드하세요:

  • 프로덕션 워크플로우를 작성하거나 적응시키는 경우: references/pattern.md를 전체적으로 읽으세요. 이 파일은 소스 ID, 행, 내구성 경계, 외부 쓰기, 실행 레인, 제어, 왓쳐, 동시성 및 대시보드 이벤트에 대한 단일 진실 공급원입니다.
  • 실행 중인 워크플로우에 응답하는 경우: references/pattern.md의 실행 레인, 제어, 왓쳐 및 복구 섹션을 읽은 다음, 현재 JSONL, 내구성 대상, 프로세스 상태 및 스크립트를 검사하세요.
  • Observer Kit 자체를 변경하는 경우: references/build-guide.md를 읽은 다음, 변경 후 전체 승인 테스트를 실행하세요.

하네스를 설계하기 전에 대상 스크립트와 해당 구성을 읽으세요.

완료 조건: 어떤 브랜치가 활성화되어 있는지, 사용자가 무엇을 감독하기를 기대하는지, 그리고 어떤 파일이 구현을 정의하는지 명시할 수 있어야 합니다.

2. 실제 워크플로우 매핑

입력부터 대상까지 스크립트를 추적하고 다음을 기록하세요:

  • 불변의 소스 ID: 확인된 경로, 시트 ID, 테이블 및 쿼리, 내보내기 ID 또는 이와 동등한 것;
  • 각 소스 엔터티 및 각 파생 엔터티의 안정적인 키;
  • 모든 느린 루프, 풀, 페이지, 재시도, 제공자 호출 및 캐시 채우기;
  • 모든 대상 변경 및 해당 확인 신호;
  • 재개 시 읽는 내구성 저장소;
  • 지출, 쓰기, 속도, 정책 및 품질 상한선;
  • 요청된 실행 레인: 현재 보기를 업데이트하거나 별도의 보기를 생성합니다.

스크립트의 작동 비즈니스 로직과 CLI를 유지하면서 이러한 실제 실행 경로에 하네스를 배치하세요.

완료 조건: 모든 지출과 변경이 매핑된 루프, 소스, 안정적인 키, 내구성 저장소, 대상 및 상한선에 속합니다.

3. 운영자 보기 제안

레코드를 연결하기 전에 간결한 대시보드 형태를 제안하세요:

  • 테이블 및 안정적인 키;
  • 소스, 변환, 추론, 결과, 대상 및 error 필드;
  • 진행률에 사용되는 소스 테이블;
  • 이 워크플로우에 맞게 선택된 3~5개의 헤드라인 지표;
  • 대표적인 드라이런 샘플 크기(보통 5~25행);
  • 이후 보강이 이러한 행을 업데이트할지 아니면 비교 레인을 열지 여부.

사용자에게 제안을 확인하거나 편집하도록 요청하세요. 사람의 주의가 필요한 행에 대해 error를 간결한 메시지로 설정하세요. 성공적인 재시도는 업데이트된 행과 함께 error=''를 내보내므로 Attention 보기에 현재 행 상태가 반영됩니다.

완료 조건: 사용자가 실행이 시작되기 전에 테이블, 열, 카운터, 샘플 및 레인을 시각화할 수 있습니다.

4. 하네스 연결

실제 작업 주변에 start_observed_run()을 사용하고 실제 source=, dry_run, description, todo, progress_table 및 간결한 summary_metrics를 전달하세요.

references/pattern.md의 프로덕션 계약을 적용하세요:

  1. 첫 번째 지출 또는 변경 전에 소스 파생 잠금을 획득하세요.
  2. 매니페스트에 입력 스냅샷, 스크립트/구성 ID, 대상 및 변환 버전을 기록하세요.
  3. --dry-run과 샘플 제한을 요구하고 --full-run을 의도적으로 만드세요.
  4. 작업이 완료되는 루프 또는 완료 콜백에서 안정적인 table= 및 key= 값을 가진 각 엔터티를 내보내세요.
  5. 내구성 경계 순서를 사용하세요: 작업 수행, 실제 결과 저장, 행 내보내기, 완료된 키 또는 청크 체크포인트.
  6. 각 외부 전달을 유효성 검사, 정책 확인, 쓰기 의도, 확인된 저장소 호출 및 쓰기 영수증으로 감싸세요. 동일한 비즈니스 행의 대상 필드를 pending에서 확인된 결과로 업데이트하세요.
  7. 루프 경계 및 쓰기 완료 후 대시보드 컨트롤을 확인하세요.
  8. throttle()로 공유 제공자 계정을 조절하고 코드에서 하드 지출/쓰기 상한을 적용하세요.

단계별 배치 파이프라인의 경우, 각 단계가 권위 있는 출력을 생성하는 즉시 완료된 각 항목이나 경계 청크를 저장하세요. 재개 시 동일한 저장소를 읽고 남은 작업을 선택합니다.

하나의 경계 단위가 내부 페이지 매김을 사용하는 경우, 누산기를 해당 단위로 범위를 지정하고 다음 단위가 시작되기 전에 마지막 페이지 직후에 즉시 저장하세요. 시작 재생은 이 내구성 저장소에서 작업 맵을 다시 빌드할 수 있습니다. 해당 읽기는 완료된 작업을 복원하고 기존 체크포인트를 유지합니다.

완료 조건: 최종 문장 직전에 프로세스를 중지하면 최대 활성 항목 또는 경계 청크만 손실되고, 재개 시 남은 작업을 선택하면서 확인된 지출과 쓰기를 보존합니다.

5. 샘플 증명

사용자가 행이 도착하는 것을 볼 수 있도록 샘플보다 먼저 수명이 긴 대시보드를 시작하세요:

observer-kit init .
observer-kit dashboard .runguard
observer-kit run --state-dir .runguard -- python3 workflow.py --dry-run --limit 10

스킬 디렉토리에서 정적 방출/내구성 검사를 실행하세요:

python3 references/lint_emit.py /absolute/path/to/workflow.py

실제 샘플을 실행하고 다음 모든 표면을 확인하세요:

  • JSONL 이벤트와 대시보드 행이 느린 단계에서 진행됩니다.
  • 내구성 결과 저장소가 완료된 작업과 함께 진행됩니다.
  • 안정적인 키가 기존 행을 업데이트하고 이전 필드를 유지합니다.
  • 대상 영수증이 실제 대상 상태와 일치합니다.
  • 강제된 중간 샘플 실패가 동일한 레인에서 저장된 작업부터 재개됩니다.
  • 동일한 소스에서 동시 시작 시 중복 실행 경고가 표시됩니다.
  • 일시 중지 또는 중지는 스크립트 체크포인트에 도달하고, 승인을 기록하며, 운영자 컨텍스트를 위한 채널을 엽니다.
  • 레코드가 도착하는 동안 스크롤 위치, 필터, 타임라인, 카운터 및 Attention 행을 포함하여 대시보드를 계속 사용할 수 있습니다.

계획된 쓰기, 건너뛰기, 오류, 스키마 발견, 예상 지출 및 관찰된 재시작 경계를 요약하세요.

완료 조건: 린터가 0으로 종료되고, 위의 모든 확인 사항에 대한 직접적인 증거가 있으며, 사용자가 샘플 대시보드를 검토했습니다.

6. 명시적 승인 후 실행

샘플 요약을 제시한 후 명시적 확인을 요청하세요. 승인 후 의도적인 전체 실행 플래그를 통해 전체 데이터 세트를 시작하세요.

하나의 대시보드 서버를 상태 디렉토리에 연결된 상태로 유지하세요. observer-kit run이 여기에 연결되고 실행 범위 왓쳐를 시작하거나, 장기 프로젝트를 위해 모든 실행 왓쳐를 하나 유지하세요:

observer-kit watch .runguard --all --follow
observer-kit run --state-dir .runguard -- python3 workflow.py --full-run

왓쳐 출력을 현재 에이전트 세션으로의 전송으로 처리하세요. 회신하거나 실행을 변경하기 전에 스크립트, JSONL, 내구성 저장소 및 대상을 검사하세요.

완료 조건: 전체 실행에 명시적인 운영자 승인, 실시간 모니터링, 터미널 원장 이벤트, 조정된 영수증 및 간결한 결과 요약이 있습니다.

7. 의도적으로 적응 또는 복구

동일한 소스, 레인, 테이블 및 키를 사용하여 실패를 재시도하고, 스크립트를 수정하거나, 이미 표시된 행에 보강을 추가하세요. 업데이트된 필드를 추가하여 대시보드가 기록을 유지하고 최신 행 상태를 표시하도록 하세요.

깔끔한 재실행, 비교 또는 진정으로 별도의 배치를 위해 새 안정적인 세션 이름이나 --session auto를 사용하세요. 레코드가 증명 가능하게 분리된 경우 병렬 소스를 실행하세요. 이러한 실행 전반에 걸쳐 공유 제공자 스로틀을 사용하세요.

보류 중인 쓰기가 있는 경우 대상을 조정하고 계속하기 전에 일치하는 영수증을 추가하세요. 활성 소스 잠금이 있는 경우 해당 프로세스를 기다리거나 새로 시작하기 전에 명명된 PID를 의도적으로 중지하세요.

완료 조건: 재시도가 권위 있는 내구성 상태를 재사용하고, 현재 행 변경이 제자리에 나타나며, 의도적으로 분리된 작업이 자체 대시보드 보기에 나타납니다.

참조 맵

  • references/pattern.md: 프로덕션 통합 및 운영 계약입니다. 워크플로우 설계 및 적응을 위해 전체를 읽으세요.
  • references/lint_emit.py: 최종 플러시 및 진행 상황에 대한 정적 검사로, 메모리 버퍼 결과와 쌍을 이룹니다. 전체 데이터 세트 전에 실행하세요.
  • references/build-guide.md: Observer Kit 코어, 대시보드, 패키징 및 승인 테스트 계약입니다.
  • runguard.py: 워크플로우 스크립트에서 사용하는 벤더 런타임입니다.
  • run_dashboard.py: 하나의 상태 디렉토리를 위한 로컬호스트 대시보드 서버입니다.
  • watch_chat.py: 활성 에이전트 하네스를 위한 대시보드 메시지 전송입니다.
  • EXPLAIN.md: 운영자에게 표시되는 프로젝트별 의도 설명입니다.

프로젝트 설정 후 observer-kit doctor .를 실행하세요. Observer Kit의 런타임, CLI, 린터, 왓쳐 또는 대시보드를 변경한 후 observer-kit test를 실행하세요.

관련 스킬