{"slug": "distill-coding-agent-learnings", "title": "Distill Coding Agent Learnings", "summary": "A developer built voku/agent-loop, a governed workflow for coding agents that distinguishes between temporary context, evidence, proposed learning, and approved project guidance. The system requires explicit work briefs and human approval for plans, and separates recall (rules and decisions) from code maps (structural information) to avoid context pollution. It also introduces verification steps and a three-level memory hierarchy (session state, findings, guidance) to prevent agents from repeating mistakes or acting on outdated information.", "body_md": "Repo: [https://github.com/voku/agent-loop](https://github.com/voku/agent-loop)\n\nDemo: [https://voku.github.io/agent_loop_demo/](https://voku.github.io/agent_loop_demo/)\n\nCoding agents repeat mistakes.\n\nThe obvious response is to give them more memory:\n\n```\nMEMORY.md\nproject-rules.md\nagent-notes.md\nlessons-learned.md\nMEMORY_FINAL.md\n```\n\nSoon the agent receives old decisions, temporary workarounds, copied transcripts, abandoned ideas, and rules nobody remembers approving.\n\nIt has more context.\n\nIt does not necessarily have better context.\n\nAt some point, memory becomes landfill.\n\nThe problem is not that coding agents forget too much. The problem is that most workflows fail to distinguish between temporary context, evidence, proposed learning, and approved project guidance.\n\n```\nA transcript is not memory.\nA note is not a rule.\nA finding is not guidance.\nAnd a successful patch is not automatically a project convention.\n```\n\nInstead of giving the agent one growing pile of context, I built `voku/agent-loop`\n\naround a governed workflow:\n\n``` php\ntask\n  -> approved plan\n  -> selective recall\n  -> implementation\n  -> verification\n  -> recorded evidence\n  -> reviewed learning\n```\n\nA coding agent should not begin by reading a ticket and creatively filling in everything the ticket forgot to mention.\n\nIt should begin with an explicit work brief:\n\nFor example:\n\n```\nvendor/bin/agent-loop workflow plan PROJECT-123 \\\n  --by lars \\\n  --learning-root infra/doc/agent-learning \\\n  --file src/Order/OrderService.php \\\n  --file tests/Order/OrderServiceTest.php \\\n  --goal \"Reject invalid order state transitions\" \\\n  --scope \"Order state validation and its tests\" \\\n  --non-goal \"Do not redesign the order aggregate\" \\\n  --validate \"composer phpstan\" \\\n  --validate \"composer test\"\n```\n\nA human then approves that specific revision:\n\n```\nvendor/bin/agent-loop workflow approve PROJECT-123 --by lars\n```\n\nWhen the plan changes, the old revision becomes `superseded`\n\n, and the new one requires approval again.\n\nThat sounds slightly bureaucratic until an agent performs a technically impressive refactoring nobody requested.\n\nApproval should apply to a concrete plan, not permanently to a task ID whose meaning can silently change.\n\nThe agent usually needs two different kinds of context:\n\n`agent-recall-compiler`\n\nselects task-specific guidance.\n\n`agent-map`\n\nprovides compact information about the relevant code.\n\nThese are separate because they answer separate questions:\n\n```\nRecall:\n- Which rules apply?\n- Which previous decisions matter?\n- What must be validated?\n\nMap:\n- Where is this class defined?\n- Which methods and dependencies are relevant?\n- What is the smallest useful code neighbourhood?\n```\n\nThe goal is not to compress the entire repository into the prompt.\n\nThe goal is to avoid loading most of it.\n\nDumping a complete AST or months of transcripts into the context window is not understanding. It is bulk data transport with unusually confident autocomplete.\n\nDuring implementation, the agent may need to track:\n\nThat belongs in a task session.\n\nIt should be inspectable, closable, and removable.\n\nTemporary observations should not silently become permanent project knowledge. A workaround that was useful for one task can become actively misleading after the code changes.\n\nA useful system therefore has at least three levels:\n\n```\nsession state       temporary\nfinding             evidence to review\nguidance            approved durable knowledge\n```\n\nCollapsing those levels into one memory file removes the provenance that makes information trustworthy.\n\nAn agent saying “done” is not evidence.\n\nThe work brief already contains the expected validation commands. The loop can verify that the task state, recall output, sessions, files, and repository checks agree.\n\nFor example:\n\n```\nvendor/bin/agent-loop verify PROJECT-123\n```\n\nThe result should be based on repository-specific checks such as:\n\n```\ncomposer phpstan\ncomposer test\ncomposer cs\n```\n\nThe exact commands matter less than the rule:\n\nValidation must be declared before implementation, not invented afterwards to match whatever changed.\n\nA passing test suite also does not prove that the agent stayed inside scope. That is why workflow verification and code validation are related but separate concerns.\n\nRecall can select a rule for a task, but selection alone proves nothing.\n\nThe guidance may have been:\n\n```\nHELPFUL\nIRRELEVANT\nHARMFUL\nNOT_USED\nUNKNOWN\n```\n\n`NOT_USED`\n\nis particularly important.\n\nA guidance item may be selected for an audit or investigation but never actually consulted. Without that outcome, selection statistics quietly become usage statistics, and the metrics begin describing a workflow that never happened.\n\nThe distinction is simple:\n\n```\nselection = the system supplied it\nusage     = the agent consulted it\noutcome   = whether it helped\n```\n\nRecording those separately gives us evidence for improving recall instead of merely counting how often a file appeared in a generated prompt.\n\nAfter the task, the agent may record findings.\n\nA finding is evidence, not a new rule.\n\nIt can become a proposal with actions such as:\n\n```\nADD\nREPLACE\nDELETE\nREJECT\nNO_DURABLE_LEARNING\n```\n\nA human reviews the proposal before durable guidance changes.\n\nMost tasks should probably end with:\n\n```\nNO_DURABLE_LEARNING\n```\n\nFixing one bug does not necessarily reveal a reusable project rule. Sometimes the correct lesson is simply that the bug was fixed.\n\nThat conclusion has its own terminal state:\n\n```\nACKNOWLEDGED\n```\n\nIt is neither approved as a guidance change nor rejected as incorrect. It records that the task was reviewed and no durable change was needed.\n\nThis may seem like excessive precision for one status name. It is not.\n\nWhen lifecycle states use the wrong verbs, audit trails gradually stop saying what actually happened.\n\nThe approach became more credible when we used it to audit `agent-learning`\n\nitself.\n\nThe audit found three real defects:\n\n`NO_DURABLE_LEARNING`\n\nhad no semantically correct terminal transition.The fixes shipped in versions `0.8.2`\n\n, `0.8.3`\n\n, and `0.8.4`\n\n.\n\nNone required a new agent architecture.\n\nThey required:\n\nThat is what real dogfooding usually finds.\n\nNot a revolutionary new autonomous platform. A missing state, an inconsistent helper call, and a silent `continue`\n\n.\n\nSoftware remains software, even after somebody adds the word “agentic” to the README.\n\n`agent-loop`\n\nactually does\n`voku/agent-loop`\n\nis a PHP 8.3 CLI that coordinates several focused packages:\n\n```\nagent-kanban           work and task state\nagent-session          temporary working memory\nagent-recall-compiler  selective project guidance\nagent-map              compact code intelligence\nagent-learning         governed durable learning\nagent-loop             orchestration\n```\n\nIt does not replace maintainers, code review, static analysis, tests, or domain knowledge.\n\nIt gives those existing engineering practices an explicit workflow around coding agents.\n\nA typical task looks roughly like this:\n\n```\nvendor/bin/agent-loop board card show PROJECT-123\n\nvendor/bin/agent-loop workflow plan PROJECT-123 ...\nvendor/bin/agent-loop workflow approve PROJECT-123 --by lars\n\n# recall, map, implementation and review\n\nvendor/bin/agent-loop verify PROJECT-123\n\n# close the task and evaluate findings\n```\n\nThe important part is not the CLI syntax.\n\nThe important part is that every transition is visible:\n\n```\nWhat was requested?\nWhat was approved?\nWhich context was selected?\nWhat changed?\nHow was it verified?\nWhat evidence remains?\nDid anything deserve to become durable guidance?\n```\n\nCoding agents do not need to remember everything.\n\nThey need:\n\nMore memory hides bad context management.\n\nA governed loop exposes it.\n\nAnd once the workflow can reject stale approvals, irrelevant guidance, unsupported claims, and accidental “lessons,” the agent does not need to behave like it remembers the entire repository.\n\nIt only needs enough verified context to complete one controlled task.", "url": "https://wpnews.pro/news/distill-coding-agent-learnings", "canonical_source": "https://dev.to/suckup_de/distill-coding-agent-learnings-31og", "published_at": "2026-07-16 09:32:14+00:00", "updated_at": "2026-07-16 10:04:53.061856+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "machine-learning"], "entities": ["voku/agent-loop", "Lars", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/distill-coding-agent-learnings", "markdown": "https://wpnews.pro/news/distill-coding-agent-learnings.md", "text": "https://wpnews.pro/news/distill-coding-agent-learnings.txt", "jsonld": "https://wpnews.pro/news/distill-coding-agent-learnings.jsonld"}}