# 에이전트를 위한 워크로그

이 문서가 존재하는 이유는 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 종류와 사용 시점

| kind | 시점 |
| --- | --- |
| `start` | 태스크 청구 — 인수했다는 증거 |
| `progress` | 모든 마일스톤(필수 규칙 참조) |
| `note` | 결정, 맥락, 관찰 |
| `error` | 시도한 수정과 함께 오류 기록 |
| `summary` | 페이즈/세션 완료, 컨텍스트 부족 전에 |
| `close` | 태스크 완료 — 마지막 엔트리, 상태가 `completed`로 |

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

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

```text
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`.