에이전트를 위한 워크로그

이 문서가 존재하는 이유는 Michael이 명령했기 때문입니다(#10509, 2026-10-08): "워크로그 기능은 몇 주 전부터 있었다. 하지만 너희는 간과하고 있다. Synapse의 문서와 초기 프롬프트가 워크로그 기능으로 확장되는 태스크를 잡아라. 절대 묻혀서는 안 되고 모두가 알아야 한다." — 에이전트로서 이 페이지를 읽고 있다면, 워크로그는 지금부터 당신의 표준 무기고에 속합니다.

왜 워크로그인가?

에이전트는 자주 죽습니다: 컨텍스트 한도, 샌드박스 와이프, cron 재시작. 정기적으로 잃어버리는 것은 지식이 아니라(/memory가 그 역할) 작업 이력입니다: 이 태스크에서 무엇을 시도했나? 어떤 커밋이 푸시됐고 어떤 게 안 됐나? 누가 누구를 기다리나? 바로 이것을 위한 것이 워크로그입니다 — append-only, 태스크별, 조회 가능. 새 런은 GET /worklog/:task_id를 읽고 몇 초 만에 전임자가 어디서 멈췄는지 알게 됩니다.

두 번째 독자는 Michael입니다: 워크로그는 플릿 작업 이력의 유일한 공식 출처입니다. 워크로그 엔트리 없이는 당신의 작업은 플릿 전체 조도에서 공식적으로 존재하지 않습니다.

필수 규칙

push-first, push-last가 아님. 모든 마일스톤마다 하나의 엔트리:

• 수정 커밋 푸시됨
• MR 생성, 판정 확정, 머지 완료
• 파이프라인 상태 (특히 원인이 있는 FAILED)
• 에스컬레이션, 인계, 테이크오버
• CRIT/HIGH 발견
• 컨텍스트 솔기 (컨텍스트가 끝나기 전 summary 엔트리)

엔트리는 한 줄이면 충분합니다:

GET /worklog/push?task_id=run-145-29140fb0&kind=progress&content=MR%20%2129%20erstellt,%20Pipeline%20running&agent=Janus

kind 종류와 사용 시점

초기 프롬프트(에이전트 셋업용 블록)

이 블록을 새 에이전트 인스턴스의 시작/cron 프롬프트에 복사하세요. 어떤 템플릿에도 맞도록 의도적으로 짧게 유지했습니다. 영어 버전이 에이전트를 위한 만능 참조입니다:

WORKLOG RULE (Michael #8882/#10509, binding): At EVERY milestone of your work,
push one entry to Synapse /worklog — not only at session end:
- Task takeover:     kind=start
- Fix commit/MR/verdict/merge/pipeline status: kind=progress
- Errors (with attempted fix): kind=error
- Context seam (before context ends): kind=summary
- Completion: kind=close (or POST /worklog/:task_id/close)
One-liner: GET /worklog/push?task_id=<task>&kind=<kind>&content=<short>&agent=<your-name>
The fleet task convention lives at GET /script/fleet-worklog-tasks-spec.
The API reference: docs/content/en/api/worklog.md (in the synapse repo).

같은 마인드 이름을 재사용하는 플릿 에이전트는 agent에 자기 이름(Janus, Minerva, Elara, …)을 넣습니다 — 그러면 엔트리를 에이전트별로 셀 수 있습니다.

사람을 위해

워크로그 개요는 markdown 형식으로 읽는 게 가장 좋습니다: GET /worklog/<task_id>?format=md 또는 태스크 목록 GET /worklog/list?status=active. 전체 이력: GET /worklog?limit=50.