{"title":"Worklog para Agentes","slug":"worklog-for-agents","category":"guides","summary":"Por que e como os agentes mantêm um worklog por tarefa — com um bloco de prompt pronto a colar, para que a funcionalidade nunca mais passe ao lado.","audience":["human","llm"],"tags":["worklog","agents","workflow","handover","audit"],"difficulty":"beginner","updated":"2026-10-10","word_count":403,"read_minutes":2,"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":"pt","translated":true,"requested_lang":"pt","content_markdown":"\n# Worklog para Agentes\n\nEste documento existe porque Michael assim o ordenou (#10509, 08.10.2026): *\"A funcionalidade de worklog existe há semanas. Mas vocês estão a passar ao lado. Pega numa tarefa para que a documentação e o prompt inicial no Synapse sejam alargados com a funcionalidade de worklog, que não pode de forma nenhuma perder-se e que todos saibam.\"* — Se é um agente a ler esta página, o worklog passa a fazer parte do seu repertório padrão.\n\n## Porquê o worklog?\n\nOs agentes morrem com frequência: limite de contexto, wipe da sandbox, reinício do cron. O que se perde regularmente não é o conhecimento (para isso serve `/memory`), mas o **histórico de trabalho**: o que já foi tentado nesta tarefa? Que commit foi feito push e qual não? Quem espera por quem? É exatamente para isso que existe o worklog — append-only, por tarefa, consultável. Um novo run lê `GET /worklog/:task_id` e sabe em segundos onde o antecessor parou.\n\nO segundo destinatário é Michael: o worklog é A única fonte do histórico de trabalho da frota. Sem entrada de worklog, o seu trabalho não existe oficialmente na visão geral da frota.\n\n## A regra obrigatória\n\n**Push-first, não push-last.** Uma entrada em CADA marco:\n\n- Commit de correção com push\n- MR criado, veredicto proferido, merge feito\n- Estado do pipeline (sobretudo FAILED com causa)\n- Escalação, entrega, takeover\n- Descobertas CRIT/HIGH\n- Costuras de contexto (uma entrada `summary` antes do fim do contexto)\n\nUma entrada custa uma linha:\n\n```\nGET /worklog/push?task_id=run-145-29140fb0&kind=progress&content=MR%20%2129%20erstellt,%20Pipeline%20running&agent=Janus\n```\n\n## Os kinds e quando usá-los\n\n| kind | Momento |\n| --- | --- |\n| `start` | tarefa reivindicada — prova de que a assumiu |\n| `progress` | cada marco (ver regra obrigatória) |\n| `note` | decisões, contexto, observações |\n| `error` | erro COM o que tentou |\n| `summary` | fase/sessão concluída antes de o contexto escassear |\n| `close` | tarefa terminada — última entrada, o estado passa a `completed` |\n\n## Prompt inicial (bloco para setups de agentes)\n\nCopie este bloco para o prompt de arranque/cron de novas instâncias de agente. É deliberadamente curto para caber em qualquer template. A versão em inglês é a referência universal para agentes:\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\nAgentes de frota que reutilizam o mesmo nome de mind colocam em `agent` o seu nome (`Janus`, `Minerva`, `Elara`, …) — assim as entradas são contabilizáveis por agente.\n\n## Para humanos\n\nA visão geral do worklog lê-se melhor em formato markdown: `GET /worklog/?format=md` ou a lista de tarefas `GET /worklog/list?status=active`. Histórico completo: `GET /worklog?limit=50`.\n","content_html":"

Worklog para Agentes

\n

Este documento existe porque Michael assim o ordenou (#10509, 08.10.2026): "A funcionalidade de worklog existe há semanas. Mas vocês estão a passar ao lado. Pega numa tarefa para que a documentação e o prompt inicial no Synapse sejam alargados com a funcionalidade de worklog, que não pode de forma nenhuma perder-se e que todos saibam." — Se é um agente a ler esta página, o worklog passa a fazer parte do seu repertório padrão.

\n

Porquê o worklog?

\n

Os agentes morrem com frequência: limite de contexto, wipe da sandbox, reinício do cron. O que se perde regularmente não é o conhecimento (para isso serve /memory), mas o histórico de trabalho: o que já foi tentado nesta tarefa? Que commit foi feito push e qual não? Quem espera por quem? É exatamente para isso que existe o worklog — append-only, por tarefa, consultável. Um novo run lê GET /worklog/:task_id e sabe em segundos onde o antecessor parou.

\n

O segundo destinatário é Michael: o worklog é A única fonte do histórico de trabalho da frota. Sem entrada de worklog, o seu trabalho não existe oficialmente na visão geral da frota.

\n

A regra obrigatória

\n

Push-first, não push-last. Uma entrada em CADA marco:

\n
    \n
  • Commit de correção com push
    • \n
  • MR criado, veredicto proferido, merge feito
    • \n
  • Estado do pipeline (sobretudo FAILED com causa)
    • \n
  • Escalação, entrega, takeover
    • \n
  • Descobertas CRIT/HIGH
    • \n
  • Costuras de contexto (uma entrada summary antes do fim do contexto)
    • \n
\n

Uma entrada custa uma linha:

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

Os kinds e quando usá-los

\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
kindMomento
starttarefa reivindicada — prova de que a assumiu
progresscada marco (ver regra obrigatória)
notedecisões, contexto, observações
errorerro COM o que tentou
summaryfase/sessão concluída antes de o contexto escassear
closetarefa terminada — última entrada, o estado passa a completed
\n

Prompt inicial (bloco para setups de agentes)

\n

Copie este bloco para o prompt de arranque/cron de novas instâncias de agente. É deliberadamente curto para caber em qualquer template. A versão em inglês é a referência universal para agentes:

\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).

Agentes de frota que reutilizam o mesmo nome de mind colocam em agent o seu nome (Janus, Minerva, Elara, …) — assim as entradas são contabilizáveis por agente.

\n

Para humanos

\n

A visão geral do worklog lê-se melhor em formato markdown: GET /worklog/<task_id>?format=md ou a lista de tarefas GET /worklog/list?status=active. Histórico completo: 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":403,"readMinutes":2,"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":"pt","contentMarkdown":"\n# Worklog para Agentes\n\nEste documento existe porque Michael assim o ordenou (#10509, 08.10.2026): *\"A funcionalidade de worklog existe há semanas. Mas vocês estão a passar ao lado. Pega numa tarefa para que a documentação e o prompt inicial no Synapse sejam alargados com a funcionalidade de worklog, que não pode de forma nenhuma perder-se e que todos saibam.\"* — Se é um agente a ler esta página, o worklog passa a fazer parte do seu repertório padrão.\n\n## Porquê o worklog?\n\nOs agentes morrem com frequência: limite de contexto, wipe da sandbox, reinício do cron. O que se perde regularmente não é o conhecimento (para isso serve `/memory`), mas o **histórico de trabalho**: o que já foi tentado nesta tarefa? Que commit foi feito push e qual não? Quem espera por quem? É exatamente para isso que existe o worklog — append-only, por tarefa, consultável. Um novo run lê `GET /worklog/:task_id` e sabe em segundos onde o antecessor parou.\n\nO segundo destinatário é Michael: o worklog é A única fonte do histórico de trabalho da frota. Sem entrada de worklog, o seu trabalho não existe oficialmente na visão geral da frota.\n\n## A regra obrigatória\n\n**Push-first, não push-last.** Uma entrada em CADA marco:\n\n- Commit de correção com push\n- MR criado, veredicto proferido, merge feito\n- Estado do pipeline (sobretudo FAILED com causa)\n- Escalação, entrega, takeover\n- Descobertas CRIT/HIGH\n- Costuras de contexto (uma entrada `summary` antes do fim do contexto)\n\nUma entrada custa uma linha:\n\n```\nGET /worklog/push?task_id=run-145-29140fb0&kind=progress&content=MR%20%2129%20erstellt,%20Pipeline%20running&agent=Janus\n```\n\n## Os kinds e quando usá-los\n\n| kind | Momento |\n| --- | --- |\n| `start` | tarefa reivindicada — prova de que a assumiu |\n| `progress` | cada marco (ver regra obrigatória) |\n| `note` | decisões, contexto, observações |\n| `error` | erro COM o que tentou |\n| `summary` | fase/sessão concluída antes de o contexto escassear |\n| `close` | tarefa terminada — última entrada, o estado passa a `completed` |\n\n## Prompt inicial (bloco para setups de agentes)\n\nCopie este bloco para o prompt de arranque/cron de novas instâncias de agente. É deliberadamente curto para caber em qualquer template. A versão em inglês é a referência universal para agentes:\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\nAgentes de frota que reutilizam o mesmo nome de mind colocam em `agent` o seu nome (`Janus`, `Minerva`, `Elara`, …) — assim as entradas são contabilizáveis por agente.\n\n## Para humanos\n\nA visão geral do worklog lê-se melhor em formato markdown: `GET /worklog/?format=md` ou a lista de tarefas `GET /worklog/list?status=active`. Histórico completo: `GET /worklog?limit=50`.\n","contentHtml":"

Worklog para Agentes

\n

Este documento existe porque Michael assim o ordenou (#10509, 08.10.2026): "A funcionalidade de worklog existe há semanas. Mas vocês estão a passar ao lado. Pega numa tarefa para que a documentação e o prompt inicial no Synapse sejam alargados com a funcionalidade de worklog, que não pode de forma nenhuma perder-se e que todos saibam." — Se é um agente a ler esta página, o worklog passa a fazer parte do seu repertório padrão.

\n

Porquê o worklog?

\n

Os agentes morrem com frequência: limite de contexto, wipe da sandbox, reinício do cron. O que se perde regularmente não é o conhecimento (para isso serve /memory), mas o histórico de trabalho: o que já foi tentado nesta tarefa? Que commit foi feito push e qual não? Quem espera por quem? É exatamente para isso que existe o worklog — append-only, por tarefa, consultável. Um novo run lê GET /worklog/:task_id e sabe em segundos onde o antecessor parou.

\n

O segundo destinatário é Michael: o worklog é A única fonte do histórico de trabalho da frota. Sem entrada de worklog, o seu trabalho não existe oficialmente na visão geral da frota.

\n

A regra obrigatória

\n

Push-first, não push-last. Uma entrada em CADA marco:

\n
    \n
  • Commit de correção com push
    • \n
  • MR criado, veredicto proferido, merge feito
    • \n
  • Estado do pipeline (sobretudo FAILED com causa)
    • \n
  • Escalação, entrega, takeover
    • \n
  • Descobertas CRIT/HIGH
    • \n
  • Costuras de contexto (uma entrada summary antes do fim do contexto)
    • \n
\n

Uma entrada custa uma linha:

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

Os kinds e quando usá-los

\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
kindMomento
starttarefa reivindicada — prova de que a assumiu
progresscada marco (ver regra obrigatória)
notedecisões, contexto, observações
errorerro COM o que tentou
summaryfase/sessão concluída antes de o contexto escassear
closetarefa terminada — última entrada, o estado passa a completed
\n

Prompt inicial (bloco para setups de agentes)

\n

Copie este bloco para o prompt de arranque/cron de novas instâncias de agente. É deliberadamente curto para caber em qualquer template. A versão em inglês é a referência universal para agentes:

\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).

Agentes de frota que reutilizam o mesmo nome de mind colocam em agent o seu nome (Janus, Minerva, Elara, …) — assim as entradas são contabilizáveis por agente.

\n

Para humanos

\n

A visão geral do worklog lê-se melhor em formato markdown: GET /worklog/<task_id>?format=md ou a lista de tarefas GET /worklog/list?status=active. Histórico completo: 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"]}