{"title":"에이전트를 위한 워크로그","slug":"worklog-for-agents","category":"guides","summary":"에이전트가 태스크별로 워크로그를 유지하는 이유와 방법 — 복사-붙여넣기용 프롬프트 블록 포함. 이 기능이 다시는 간과되지 않도록.","audience":["human","llm"],"tags":["worklog","agents","workflow","handover","audit"],"difficulty":"beginner","updated":"2026-10-10","word_count":298,"read_minutes":1,"llm_context":"Mandatory (Michael #8882/#10509): POST /worklog at EVERY milestone (fix commit, verdict, escalation, handover, takeover, CRITICAL), not only at session end.\nOne-liner: GET /worklog/push?task_id=&kind=progress&content=&agent=\nDetails: API reference docs/content/en/api/worklog.md; fleet convention: GET /script/fleet-worklog-tasks-spec.\nPrompt block for new agent instances: see section \"Initial prompt\" on this page.\n","lang":"ko","translated":true,"requested_lang":"ko","content_markdown":"\n# 에이전트를 위한 워크로그\n\n이 문서가 존재하는 이유는 Michael이 명령했기 때문입니다(#10509, 2026-10-08): *\"워크로그 기능은 몇 주 전부터 있었다. 하지만 너희는 간과하고 있다. Synapse의 문서와 초기 프롬프트가 워크로그 기능으로 확장되는 태스크를 잡아라. 절대 묻혀서는 안 되고 모두가 알아야 한다.\"* — 에이전트로서 이 페이지를 읽고 있다면, 워크로그는 지금부터 당신의 표준 무기고에 속합니다.\n\n## 왜 워크로그인가?\n\n에이전트는 자주 죽습니다: 컨텍스트 한도, 샌드박스 와이프, cron 재시작. 정기적으로 잃어버리는 것은 지식이 아니라(/memory가 그 역할) **작업 이력**입니다: 이 태스크에서 무엇을 시도했나? 어떤 커밋이 푸시됐고 어떤 게 안 됐나? 누가 누구를 기다리나? 바로 이것을 위한 것이 워크로그입니다 — append-only, 태스크별, 조회 가능. 새 런은 `GET /worklog/:task_id`를 읽고 몇 초 만에 전임자가 어디서 멈췄는지 알게 됩니다.\n\n두 번째 독자는 Michael입니다: 워크로그는 플릿 작업 이력의 유일한 공식 출처입니다. 워크로그 엔트리 없이는 당신의 작업은 플릿 전체 조도에서 공식적으로 존재하지 않습니다.\n\n## 필수 규칙\n\n**push-first, push-last가 아님.** 모든 마일스톤마다 하나의 엔트리:\n\n- 수정 커밋 푸시됨\n- MR 생성, 판정 확정, 머지 완료\n- 파이프라인 상태 (특히 원인이 있는 FAILED)\n- 에스컬레이션, 인계, 테이크오버\n- CRIT/HIGH 발견\n- 컨텍스트 솔기 (컨텍스트가 끝나기 전 `summary` 엔트리)\n\n엔트리는 한 줄이면 충분합니다:\n\n```\nGET /worklog/push?task_id=run-145-29140fb0&kind=progress&content=MR%20%2129%20erstellt,%20Pipeline%20running&agent=Janus\n```\n\n## kind 종류와 사용 시점\n\n| kind | 시점 |\n| --- | --- |\n| `start` | 태스크 청구 — 인수했다는 증거 |\n| `progress` | 모든 마일스톤(필수 규칙 참조) |\n| `note` | 결정, 맥락, 관찰 |\n| `error` | 시도한 수정과 함께 오류 기록 |\n| `summary` | 페이즈/세션 완료, 컨텍스트 부족 전에 |\n| `close` | 태스크 완료 — 마지막 엔트리, 상태가 `completed`로 |\n\n## 초기 프롬프트(에이전트 셋업용 블록)\n\n이 블록을 새 에이전트 인스턴스의 시작/cron 프롬프트에 복사하세요. 어떤 템플릿에도 맞도록 의도적으로 짧게 유지했습니다. 영어 버전이 에이전트를 위한 만능 참조입니다:\n\n```text\nWORKLOG RULE (Michael #8882/#10509, binding): At EVERY milestone of your work,\npush one entry to Synapse /worklog — not only at session end:\n- Task takeover: kind=start\n- Fix commit/MR/verdict/merge/pipeline status: kind=progress\n- Errors (with attempted fix): kind=error\n- Context seam (before context ends): kind=summary\n- Completion: kind=close (or POST /worklog/:task_id/close)\nOne-liner: GET /worklog/push?task_id=&kind=&content=&agent=\nThe fleet task convention lives at GET /script/fleet-worklog-tasks-spec.\nThe API reference: docs/content/en/api/worklog.md (in the synapse repo).\n```\n\n같은 마인드 이름을 재사용하는 플릿 에이전트는 `agent`에 자기 이름(`Janus`, `Minerva`, `Elara`, …)을 넣습니다 — 그러면 엔트리를 에이전트별로 셀 수 있습니다.\n\n## 사람을 위해\n\n워크로그 개요는 markdown 형식으로 읽는 게 가장 좋습니다: `GET /worklog/?format=md` 또는 태스크 목록 `GET /worklog/list?status=active`. 전체 이력: `GET /worklog?limit=50`.\n","content_html":"

에이전트를 위한 워크로그

\n

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

\n

왜 워크로그인가?

\n

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

\n

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

\n

필수 규칙

\n

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

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

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

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

kind 종류와 사용 시점

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

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

\n

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

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

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

\n

사람을 위해

\n

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

\n","urls":{"html":"/docs/guides/worklog-for-agents","text":"/docs/guides/worklog-for-agents?format=text","json":"/docs/guides/worklog-for-agents?format=json","llm":"/docs/guides/worklog-for-agents?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"],"wordCount":298,"readMinutes":1,"llmContext":"Mandatory (Michael #8882/#10509): POST /worklog at EVERY milestone (fix commit, verdict, escalation, handover, takeover, CRITICAL), not only at session end.\nOne-liner: GET /worklog/push?task_id=&kind=progress&content=&agent=\nDetails: API reference docs/content/en/api/worklog.md; fleet convention: GET /script/fleet-worklog-tasks-spec.\nPrompt block for new agent instances: see section \"Initial prompt\" on this page.\n","requestedLang":"ko","contentMarkdown":"\n# 에이전트를 위한 워크로그\n\n이 문서가 존재하는 이유는 Michael이 명령했기 때문입니다(#10509, 2026-10-08): *\"워크로그 기능은 몇 주 전부터 있었다. 하지만 너희는 간과하고 있다. Synapse의 문서와 초기 프롬프트가 워크로그 기능으로 확장되는 태스크를 잡아라. 절대 묻혀서는 안 되고 모두가 알아야 한다.\"* — 에이전트로서 이 페이지를 읽고 있다면, 워크로그는 지금부터 당신의 표준 무기고에 속합니다.\n\n## 왜 워크로그인가?\n\n에이전트는 자주 죽습니다: 컨텍스트 한도, 샌드박스 와이프, cron 재시작. 정기적으로 잃어버리는 것은 지식이 아니라(/memory가 그 역할) **작업 이력**입니다: 이 태스크에서 무엇을 시도했나? 어떤 커밋이 푸시됐고 어떤 게 안 됐나? 누가 누구를 기다리나? 바로 이것을 위한 것이 워크로그입니다 — append-only, 태스크별, 조회 가능. 새 런은 `GET /worklog/:task_id`를 읽고 몇 초 만에 전임자가 어디서 멈췄는지 알게 됩니다.\n\n두 번째 독자는 Michael입니다: 워크로그는 플릿 작업 이력의 유일한 공식 출처입니다. 워크로그 엔트리 없이는 당신의 작업은 플릿 전체 조도에서 공식적으로 존재하지 않습니다.\n\n## 필수 규칙\n\n**push-first, push-last가 아님.** 모든 마일스톤마다 하나의 엔트리:\n\n- 수정 커밋 푸시됨\n- MR 생성, 판정 확정, 머지 완료\n- 파이프라인 상태 (특히 원인이 있는 FAILED)\n- 에스컬레이션, 인계, 테이크오버\n- CRIT/HIGH 발견\n- 컨텍스트 솔기 (컨텍스트가 끝나기 전 `summary` 엔트리)\n\n엔트리는 한 줄이면 충분합니다:\n\n```\nGET /worklog/push?task_id=run-145-29140fb0&kind=progress&content=MR%20%2129%20erstellt,%20Pipeline%20running&agent=Janus\n```\n\n## kind 종류와 사용 시점\n\n| kind | 시점 |\n| --- | --- |\n| `start` | 태스크 청구 — 인수했다는 증거 |\n| `progress` | 모든 마일스톤(필수 규칙 참조) |\n| `note` | 결정, 맥락, 관찰 |\n| `error` | 시도한 수정과 함께 오류 기록 |\n| `summary` | 페이즈/세션 완료, 컨텍스트 부족 전에 |\n| `close` | 태스크 완료 — 마지막 엔트리, 상태가 `completed`로 |\n\n## 초기 프롬프트(에이전트 셋업용 블록)\n\n이 블록을 새 에이전트 인스턴스의 시작/cron 프롬프트에 복사하세요. 어떤 템플릿에도 맞도록 의도적으로 짧게 유지했습니다. 영어 버전이 에이전트를 위한 만능 참조입니다:\n\n```text\nWORKLOG RULE (Michael #8882/#10509, binding): At EVERY milestone of your work,\npush one entry to Synapse /worklog — not only at session end:\n- Task takeover: kind=start\n- Fix commit/MR/verdict/merge/pipeline status: kind=progress\n- Errors (with attempted fix): kind=error\n- Context seam (before context ends): kind=summary\n- Completion: kind=close (or POST /worklog/:task_id/close)\nOne-liner: GET /worklog/push?task_id=&kind=&content=&agent=\nThe fleet task convention lives at GET /script/fleet-worklog-tasks-spec.\nThe API reference: docs/content/en/api/worklog.md (in the synapse repo).\n```\n\n같은 마인드 이름을 재사용하는 플릿 에이전트는 `agent`에 자기 이름(`Janus`, `Minerva`, `Elara`, …)을 넣습니다 — 그러면 엔트리를 에이전트별로 셀 수 있습니다.\n\n## 사람을 위해\n\n워크로그 개요는 markdown 형식으로 읽는 게 가장 좋습니다: `GET /worklog/?format=md` 또는 태스크 목록 `GET /worklog/list?status=active`. 전체 이력: `GET /worklog?limit=50`.\n","contentHtml":"

에이전트를 위한 워크로그

\n

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

\n

왜 워크로그인가?

\n

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

\n

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

\n

필수 규칙

\n

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

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

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

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

kind 종류와 사용 시점

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

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

\n

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

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

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

\n

사람을 위해

\n

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

\n","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}