Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Knowledge Management for Coding Agents | AI Pol...

Sponsored · SiteGround - Reliable hosting with speed, security, and support you can count on. →

Knowledge Management for Coding Agents | AI Poland 2026

An agent makes an architectural decision, the session ends, and the repository holds the result without any underlying reasoning. Three months later, someone looks for the rationale and finds the commit. This talk highlights the problems this creates in ongoing projects, ranging from onboarding and code reviews to the question of why an agent proposes the exact same rejected solution for the third time. After that, we explore the countermeasures: documented decisions, logged tool calls, and a wiki that agents can read and write themselves. Projects we implement internally at SHI and with our clients serve as examples, complete with the artifacts that nobody bothered to maintain after three weeks.

Daniel Sogl PRO

November 19, 2026

Transcript

25 slides
  1. Knowledge Management for Coding Agents The repo knows what changed.

    Nobody knows why. Daniel Sogl Director of AI Engineering · SHI GmbH · Microsoft MVP AI Poland · Warsaw Nov 19, 2026
  2. One commit. No body. fix(billing): skip retry on 402 src/billing/retry.ts

    | 1 + Six months later an agent removes the odd special case. Clean diff, green tests. Why was it there? The session that knew is gone. Knowledge Management for Coding Agents AI Poland · 2026 2 / 24
  3. Every session is someone’s first day Onboarding Code review The

    third proposal New people and new sessions start at zero. Your The diff looks clean. The constraint it breaks lives The rejection sits in a PR comment from two weeks agent onboards dozens of times a day. somewhere else. ago. The agent proposes the same thing again. Knowledge Management for Coding Agents AI Poland · 2026 4 / 24
  4. Five kinds of knowledge WRITTEN BY READ BY Rules humans,

    by hand every session Decisions agent drafts, the next agent, via a new ADR human accepts a pointer supersedes it Sessions hooks, automatically Generated docs an agent, from what the code does the code Memory the tool itself how we work why it is this way what happened what a tool learned Knowledge Management for Coding Agents AI Poland · 2026 you, when you need the why KEPT CURRENT BY the PR that changes the code every agent commit every agent claims that go stale that tool only the vendor's rules 6 / 24
  5. The knowledge loop Capture Distill Serve Verify sessions in git

    decisions with “Rejected” one entry point CI fails on stale docs every pull request Entire ADRs AGENTS.md git-ai Copilot Dreaming OpenWiki Knowledge Management for Coding Agents AI Poland · 2026 CI check 8 / 24
  6. 02 Decisions: ADRs Read by the next agent. Kept current

    by the PR that changes the decision.
  7. An ADR written for agents # 0007 Live updates via

    server-sent events Nygard’s format from 2011: context, Status: accepted · Supersedes: 0003 decision, status, consequences Context: dashboard needs updates < 2 s Rejected is what agents need most: a negative constraint ## Decision Server-sent events from the API gateway. Agent drafts, human accepts, in the same PR as the code ## Rejected - WebSockets: the proxy drops idle connections after 60 s. - Polling: 40× the requests at peak, Accepted ADRs are frozen. A new ADR supersedes the old one tried in 0003. Nygard's format plus a Rejected section (MADR: “Considered Options” with pros and cons) Knowledge Management for Coding Agents AI Poland · 2026 10 / 24
  8. One file changes what the agent proposes Without the ADR

    With ADR and a pointer in AGENTS.md Switching the dashboard to WebSockets: lower latency, and ADR 0007 rejects WebSockets: the client library is installed. the proxy drops idle connections. Keeping SSE, fixing the reconnect backoff instead. Knowledge Management for Coding Agents AI Poland · 2026 11 / 24
  9. How Entire captures the why Agent session Hooks Checkpoint Git

    refs 8+ coding agents prompts, transcript, tool calls per commit pushed with the code and more commit 9f3c2a1 fix(billing): skip retry on 402 Entire-Checkpoint: 01J8ZK4M7Q… Knowledge Management for Coding Agents AI Poland · 2026 13 / 24
  10. Reading it back $ entire why src/billing/retry.ts:42 if (err.status ===

    402) throw err; Claude Code · checkpoint 01J8ZK4M7Q… · commit 9f3c2a1 Prompt: "Add backoff to payment retries, but never retry a declined card. The provider flags that as fraud." $ entire checkpoint explain 01J8ZK4M7Q… # full transcript $ entire checkpoint explain --generate … # intent, learnings, open items $ entire search "declined card retries" # hybrid search Knowledge Management for Coding Agents AI Poland · 2026 14 / 24
  11. A wiki the agent writes, with receipts Code changes Claims

    re-checked Agent updates openwiki/ which ones went stale? confirm, revise, retract linked from AGENTS.md, or via MCP { "statement": "Declined cards (402) are never retried; the provider flags retries as fraud.", "evidence": [{ "resource": "repo://src/billing/retry.ts#L38-L57", "version": "repo-lines-v1:sha256:4be1…" }] } Knowledge Management for Coding Agents AI Poland · 2026 16 / 24
  12. The wiki is a graph Onboarding Architecture Billing invoice.ts Deploy

    Webhooks retry.ts webhook.ts Auth session.ts gateway.ts ci.yml top: wiki pages · lines: claims · bottom: source files Knowledge Management for Coding Agents AI Poland · 2026 17 / 24
  13. The wiki is a graph Onboarding Architecture Billing invoice.ts Deploy

    Webhooks retry.ts webhook.ts top: wiki pages · lines: claims · bottom: source files Knowledge Management for Coding Agents AI Poland · 2026 Auth session.ts retry.ts changed gateway.ts ci.yml → 2 claims stale → 2 pages rechecked 17 / 24
  14. Before an agent touches retry.ts Wiki Claim ADR / commit

    entire why what the code does today which lines back it why, and what was rejected the full session, if needed Map, rules, logbook. Read in that order. Knowledge Management for Coding Agents AI Poland · 2026 19 / 24
  15. How we set up a repo AGENTS.md Rules · the

    one file every session loads, points to the rest .claude/rules/ Rules · details and skills, changed in the same PR as the code docs/adr/ Decisions · drafted by the agent, accepted by a human refs/entire/… Sessions · one checkpoint per agent commit openwiki/ Generated docs · every claim cites file and line ~/…/memory Memory · personal, not team knowledge Knowledge Management for Coding Agents AI Poland · 2026 20 / 24
  16. Verify: make stale docs fail the build Wiki behind the

    code? Last run broken? The wiki is older than the code it describes. The generator stopped halfway. The wiki is partially stale. Either yes turns the build red. Now stale docs have a cost. Knowledge Management for Coding Agents AI Poland · 2026 21 / 24
  17. Where to start 1 Step 1 · Serve Short, hand-written

    AGENTS.md. Delete what the README already says. Point to the rest. 2 Step 2 · Distill ADR rule in AGENTS.md. Structural changes get an ADR, small ones a Why and Rejected in the commit body. Same PR. 3 Step 3 · Capture Entire or similar, sessions in git, linked by commit trailer. Check where the data goes first. 4 Step 4 · Serve & verify OpenWiki with claims. The CI check from its first day. Knowledge Management for Coding Agents AI Poland · 2026 22 / 24
  18. Back to the commit fix(billing): skip retry on 402 Why:

    the provider flags retries on a declined card as fraud. Rejected: retry all 4xx with backoff. Same fraud flags. Revisit: if the provider adds a safe-to-retry signal. Entire-Checkpoint: 01J… Three lines of why. Everything else makes sure they get written, and read. Knowledge Management for Coding Agents AI Poland · 2026 23 / 24
  19. Don’t let the why die with the session. Thank you!

    Slides: linktr.ee/daniel_sogl Daniel Sogl Director of AI Engineering · SHI GmbH · Microsoft MVP [email protected] linkedin.com/in/daniel-sogl slides · contact

More Decks by Daniel Sogl

Other Decks in Programming