# Mike Bild
> Software architect & engineer in Berlin. More than 30 years of software, a good 15 of them focused on distributed systems, APIs and digital products. These days also agentic engineering.
## Navigation
- [Profile](https://www.mikebild.dev/en/profile/)
- [Blog](https://www.mikebild.dev/en/blog/)
- [Projects](https://www.mikebild.dev/en/projects/)
- [Contact](https://www.mikebild.dev/en/contact/): mike.bild@gmail.com
- [GitHub](https://github.com/MikeBild)
- [LinkedIn](https://www.linkedin.com/in/mikebild)
- [Mike Bild · Blog](https://www.mikebild.dev/en/feed.xml)
- [Mike Bild · Blogcast](https://www.mikebild.dev/de/blogcast.xml): Selected blog articles by Mike Bild as audio versions – software architecture, engineering and method.
- [MCP knowledge server](https://worker.mikebild.dev/workshop-online-api/knowledge/mcp): Articles, slide decks and the workshop catalog for AI assistants, read-only, no login. Guide: https://www.mikebild.dev/en/mcp/
- [Deutsch](https://www.mikebild.dev/llms-full.txt)
## Current projects
- [SubKit](https://subkit.mikebild.dev/en/): Built once with the AI, shared by approval: team workflows with permissions and history. (Beta by invitation)
- [Harmoniqs](https://harmoniqs.mikebild.dev/en/): Develop song ideas with chords, the Looper and BRAIN. (Beta)
- TackTics: A sailing trainer meant to analyze data from on board. (In progress)
## Training
- [JavaScript and TypeScript from scratch](https://slides.mikebild.dev/introduction-javascript-typescript.en.html): You write modern JavaScript and type it with TypeScript so the compiler finds your mistakes before deployment. – Repository: https://github.com/MikeBild/introduction-javascript – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-javascript-typescript/introduction-javascript-typescript.en.pdf?v=7c3d048ab16c – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-javascript-typescript/introduction-javascript-typescript.en.mp4?v=7c3d048ab16c – Deutsch: https://slides.mikebild.dev/introduction-javascript-typescript.html
- [Python for developers with uv, pytest, and Flask](https://slides.mikebild.dev/introduction-python.en.html): You learn modern Python with uv, type hints, and pytest, and build a tested HTTP API with Flask for the workshop shop. – Repository: https://github.com/MikeBild/introduction-python – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-python/introduction-python.en.pdf?v=a9426e4ffd37 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-python/introduction-python.en.mp4?v=a9426e4ffd37 – Deutsch: https://slides.mikebild.dev/introduction-python.html
- [Modern web platform without a framework](https://slides.mikebild.dev/introduction-web-plattform.en.html): You build the workshop shop using only the browser’s HTML, CSS, and JavaScript: accessible, fast, offline-capable, and with Web Components. – Repository: https://github.com/MikeBild/introduction-web-plattform – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-web-plattform/introduction-web-plattform.en.pdf?v=a8018c5e80c1 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-web-plattform/introduction-web-plattform.en.mp4?v=a8018c5e80c1 – Deutsch: https://slides.mikebild.dev/introduction-web-plattform.html
- [Node.js backend, functional and type-safe](https://slides.mikebild.dev/introduction-nodejs.en.html): You build a Node.js service with Express 5 from the first request to container operations, tested, logged, and hardened. – Repository: https://github.com/MikeBild/introduction-nodejs – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-nodejs/introduction-nodejs.en.pdf?v=965710139dd0 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-nodejs/introduction-nodejs.en.mp4?v=965710139dd0 – Deutsch: https://slides.mikebild.dev/introduction-nodejs.html
- [React with TypeScript all the way to production](https://slides.mikebild.dev/introduction-react.en.html): You use React, TypeScript, and React Router to build an app from small components, then ship it to production with tests and good accessibility. – Repository: https://github.com/MikeBild/introduction-react – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-react/introduction-react.en.pdf?v=19f0d4ba8526 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-react/introduction-react.en.mp4?v=19f0d4ba8526 – Deutsch: https://slides.mikebild.dev/introduction-react.html
- [Svelte 5 and SvelteKit with TypeScript](https://slides.mikebild.dev/introduction-svelte.en.html): You build the workshop store with Svelte 5, runes, and SvelteKit 3, from the first component to a tested Node server. – Repository: https://github.com/MikeBild/introduction-svelte – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-svelte/introduction-svelte.en.pdf?v=8ed6ed7c9262 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-svelte/introduction-svelte.en.mp4?v=8ed6ed7c9262 – Deutsch: https://slides.mikebild.dev/introduction-svelte.html
- [Modernize KnockoutJS and migrate step by step](https://slides.mikebild.dev/introduction-knockoutjs.en.html): You maintain a Knockout application with TypeScript, Vite, and tests, close security gaps, and plan the migration in small steps. – Repository: https://github.com/MikeBild/introduction-knockoutjs – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-knockoutjs/introduction-knockoutjs.en.pdf?v=db3087c1f285 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-knockoutjs/introduction-knockoutjs.en.mp4?v=db3087c1f285 – Deutsch: https://slides.mikebild.dev/introduction-knockoutjs.html
- [GraphQL from schema to production](https://slides.mikebild.dev/introduction-graphql.en.html): You build a GraphQL API with Apollo, from the first schema to a public graph that limits cost and can evolve safely. – Repository: https://github.com/MikeBild/introduction-graphql – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-graphql/introduction-graphql.en.pdf?v=a1a1bae43fe5 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-graphql/introduction-graphql.en.mp4?v=a1a1bae43fe5 – Deutsch: https://slides.mikebild.dev/introduction-graphql.html
- [Reactive programming with RxJS](https://slides.mikebild.dev/introduction-reactive-programming.en.html): You describe search, live status, and user input as streams with RxJS and test time-dependent code without real waiting time. – Repository: https://github.com/MikeBild/Reactive-Programming – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-reactive-programming/introduction-reactive-programming.en.pdf?v=51202b99fbfc – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-reactive-programming/introduction-reactive-programming.en.mp4?v=51202b99fbfc – Deutsch: https://slides.mikebild.dev/introduction-reactive-programming.html
- [Docker & Kubernetes](https://slides.mikebild.dev/introduction-docker-kubernetes.en.html): You put the workshop shop API into containers and run it in Kubernetes: from image and Compose to rollout, Gateway API, and hardening. – Repository: https://github.com/MikeBild/introduction-docker – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-docker-kubernetes/introduction-docker-kubernetes.en.pdf?v=dcfe9fd4c4f6 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-docker-kubernetes/introduction-docker-kubernetes.en.mp4?v=dcfe9fd4c4f6 – Deutsch: https://slides.mikebild.dev/introduction-docker-kubernetes.html
- [AWS serverless with Lambda, CDK, and DynamoDB](https://slides.mikebild.dev/introduction-aws-serverless.en.html): You build the workshop shop order flow serverless on AWS, with Lambda, DynamoDB, events, and Step Functions, all as code in CDK. – Repository: https://github.com/MikeBild/introduction-aws – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-aws-serverless/introduction-aws-serverless.en.pdf?v=686d760b188f – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-aws-serverless/introduction-aws-serverless.en.mp4?v=686d760b188f – Deutsch: https://slides.mikebild.dev/introduction-aws-serverless.html
- [Microservices with Node.js, Express 5, and Docker Compose](https://slides.mikebild.dev/introduction-microservices.en.html): You split the workshop shop into services along domain boundaries and connect them with contracts, events, outbox, and sagas. – Repository: https://github.com/MikeBild/introduction-microservices – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-microservices/introduction-microservices.en.pdf?v=755b9c76bf78 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-microservices/introduction-microservices.en.mp4?v=755b9c76bf78 – Deutsch: https://slides.mikebild.dev/introduction-microservices.html
- [Design patterns as functions](https://slides.mikebild.dev/introduction-design-patterns.en.html): You solve recurring problems in the workshop shop with design patterns as functions and recognize them again in Express, React, and Apollo. – Repository: https://github.com/MikeBild/introduction-design-patterns – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-design-patterns/introduction-design-patterns.en.pdf?v=d9e4820e2aef – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-design-patterns/introduction-design-patterns.en.mp4?v=d9e4820e2aef – Deutsch: https://slides.mikebild.dev/introduction-design-patterns.html
- [Architecture: DDD, CQRS, and Event Sourcing](https://slides.mikebild.dev/introduction-cqrs-event-sourcing.en.html): You model the workshop shop with DDD, separate writes and reads with CQRS, and store orders as events, only where it pays off. – Repository: https://github.com/MikeBild/introduction-nodejs/tree/master/EXAMPLES/ARCHITECTURE – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-cqrs-event-sourcing/introduction-cqrs-event-sourcing.en.pdf?v=d420df81ac12 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-cqrs-event-sourcing/introduction-cqrs-event-sourcing.en.mp4?v=d420df81ac12 – Deutsch: https://slides.mikebild.dev/introduction-cqrs-event-sourcing.html
## Blog
- [Interim Review and System View: Taking Stock of the Series](https://www.mikebild.dev/en/blog/interim-review-and-system-view/): Months after the conversation where it all began, it’s time for an honest assessment: which expectations from the opening came true, which didn’t, what remains open – and why the most exciting question is no longer what the models can do, but what organizations make of it.
- [MCP, HTTP, Webhooks and A2A Explained Simply](https://www.mikebild.dev/en/blog/mcp-http-webhooks-and-a2a-explained-simply/): MCP, HTTP with OpenAPI, webhooks and A2A connect systems at different levels. What matters is which responsibility lies at each boundary.
- [A2A: When Agents Work Together](https://www.mikebild.dev/en/blog/a2a-when-agents-work-together/): Agent Card, Message, Task and Artifact explained clearly: how A2A 1.0 connects independent agent systems, what sets the protocol apart from MCP and when delegating to an independent system pays off.
- [Hourly Is Not Real Time](https://www.mikebild.dev/en/blog/hourly-is-not-real-time/): A closed hourly report answers different questions than ongoing operational monitoring – and gets simpler as soon as time windows, delays and measurement gaps are modeled explicitly.
- [Claims: Small, Sourced, Verifiable](https://www.mikebild.dev/en/blog/claims-small-sourced-verifiable/): Claims break wiki pages down into individual statements with subject, predicate, object, confidence, status and a verbatim quote as evidence. This makes agreement and disagreement precise.
- [Products Report Through Their API](https://www.mikebild.dev/en/blog/products-report-through-their-api/): Product statistics stay understandable when every system aggregates its own data and offers it through a small HTTP contract with uniform time semantics.
- [From Org Chart to Product Ownership](https://www.mikebild.dev/en/blog/from-org-chart-to-product-ownership/): AI makes the path from customer problem to impact more continuous.
- [llms.txt: Docs for Machines](https://www.mikebild.dev/en/blog/llms-txt-docs-for-machines/): Context for models, not for ranking: why llms.txt and llms-full.txt help coding agents – and what an MCP server makes of them.
- [Tools That Hold Up: Concepts, Methods, Processes](https://www.mikebild.dev/en/blog/tools-that-hold-up-concepts-methods-processes-article/): You cannot install an agent for your own domain – but you can very well learn the way there. Which concepts hold up, which methods keep the start small and which processes keep rules from going stale.
- [AI Agents per Domain: Rules, Approvals and Evidence](https://www.mikebild.dev/en/blog/ai-agents-per-domain/): How an AI agent enforces domain rules across several tool calls: with case state, checked plans, approvals and traceable execution.
- [MCP Security: Tools, Permissions and Approvals for AI Agents](https://www.mikebild.dev/en/blog/mcp-security-tools-permissions-and-approvals/): How to integrate MCP tools into applications safely: server-side permission checks, human approvals, protection against prompt injection and traceable calls.
- [Agent, Model, Domain](https://www.mikebild.dev/en/blog/agent-model-domain/): The model is rented, the agent can be under your own control – what matters is whether the domain lives as prose in the prompt or as a checked interface in the agent.
- [Knowledge That Survives the Session](https://www.mikebild.dev/en/blog/knowledge-that-survives-the-session/): Session knowledge evaporates when no one curates it – why teams should treat their AI working knowledge like code, and why it’s not the model that gets smarter but the organization that learns.
- [Clean Grounding II: Grounding Answers](https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/): My working model for grounding distinguishes conventions, documents and API descriptions. What stays in the scarce context, I prioritize by task and by the cost of fetching it again.
- [AI in the Enterprise: Faster Development Needs Different Processes](https://www.mikebild.dev/en/blog/ai-in-the-enterprise-faster-development-different-processes/): AI shortens research, design and implementation. If handoffs, ticket hierarchies and approvals stay the same, the bottleneck just moves – so large companies have to rethink workflow and governance together.
- [Clean Grounding I: Why AI Guesses So Convincingly](https://www.mikebild.dev/en/blog/clean-grounding-i-why-ai-guesses-so-convincingly/): Why language models invent plausible things, why more training doesn’t reliably eliminate the problem and what grounding has to do with it.
- [My Success Cannot Be Copied](https://www.mikebild.dev/en/blog/my-success-cannot-be-copied/): A colleague takes over my AI setup and gets different results. Tools, tests and conventions can be transferred; how you cut tasks, how you review and the course of an individual session only to a limited degree.
- [What I Am Critical Of](https://www.mikebild.dev/en/blog/what-i-am-critical-of/): Four observations and one open hypothesis after intense months with AI – from a possible loss of skills to the worry about more uniform solutions, and my practical countermeasures.
- [Good Enough: The Model Is Rarely the Bottleneck](https://www.mikebild.dev/en/blog/good-enough-models/): For the everyday tasks I work on with AI myself, the choice of model is rarely the first bottleneck. How the task is cut, the context and the verification usually matter more.
- [From Tool to Way of Working](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/): How a conversation in Berlin, after more than thirty years of software craftsmanship, got me working daily with Claude, ChatGPT and Claude Code – and why I still distrust my own enthusiasm for now.
- [React Overview: From JSX to Component Architecture](https://www.mikebild.dev/en/blog/react-overview-from-jsx-to-component-architecture/): A complete walk through React the way I teach it today – from declarative rendering through the question of who owns a piece of state to the architecture of a growing application. The details of individual stops will follow later as separate posts.
- [Forms in React 19: Actions, useActionState and useOptimistic](https://www.mikebild.dev/en/blog/forms-in-react-19-with-actions/): React 19 makes the form the actual interface: a function as the form action, plus three hooks for the result, the pending state and instant UI feedback. This post shows how they work together – and where optimistic rendering breaks down without a clean error path.
- [React Server Components and Server Actions: The New Boundary](https://www.mikebild.dev/en/blog/react-server-components-and-server-actions/): Server Components run outside the client bundle and send their result to the browser instead of their code. Server Functions move writes to the server – both are implemented by a suitable framework or bundler.
- [React Router Data Router: The URL as the Place for State](https://www.mikebild.dev/en/blog/react-router-data-router-the-url-as-state/): The data router in React Router makes the URL the point of coordination – a route loads its data via loader before rendering and writes via action, so loading logic disappears from the component body.
- [React Transitions: Non-Urgent Updates with useTransition](https://www.mikebild.dev/en/blog/react-transitions-with-usetransition/): useTransition marks updates as non-urgent and keeps React responsive during expensive or suspending renders. Plus useDeferredValue as the tool for downstream renders.
- [React Testing Without Theater](https://www.mikebild.dev/en/blog/react-testing-without-theater/): Tests tied to visible user behavior are less coupled to DOM structure, component boundaries and internal state. As a result, they survive certain refactorings without changes.
- [Suspense and the use Hook: Rendering as If the Data Were Already There](https://www.mikebild.dev/en/blog/suspense-and-the-use-hook/): Instead of managing a loading state in every component, Suspense lets you describe in a single place in the tree what appears while waiting – and the use hook lets the component below render as if the data had long arrived.
- [Client State vs. Server Cache: The Most Consequential Boundary in the Frontend](https://www.mikebild.dev/en/blog/client-state-vs-server-cache/): Server data is state, but not client-owned state. Why this distinction matters, when useEffect turns into a bad cache and what a server state library takes over.
- [Testing Schedulers and Virtual Time](https://www.mikebild.dev/en/blog/testing-schedulers-and-virtual-time/): Injectable time makes time-dependent rules testable quickly and deterministically. Data, isolation and external systems remain unaffected by it.
- [GraphQL Overview: From Schema to Federated API](https://www.mikebild.dev/en/blog/graphql-overview-from-schema-to-federated-api/): A walk through GraphQL – from the typed schema through queries and resolvers to real time, operations and federated architecture, assessed as of October 2024.
- [HTTP/2 and Server-Sent Events in Node.js](https://www.mikebild.dev/en/blog/http2-and-server-sent-events-in-nodejs/): How HTTP/2 multiplexes many streams over one connection and why Server-Sent Events are often a simpler answer to live data than WebSocket – with a working SSE endpoint in Node and the usual pitfalls.
- [Markdown Reports Instead of Dashboard Mandates](https://www.mikebild.dev/en/blog/markdown-reports-instead-of-dashboards/): Why a diffable Markdown report often does more for traceability, review and operations than a dashboard – and how I set that up architecturally.
- [GraphQL Federation: One Schema from Many Subgraphs](https://www.mikebild.dev/en/blog/graphql-federation-and-subgraphs/): When one team can no longer carry a monolithic schema on its own, Federation splits the graph into subgraphs that a router composes into a supergraph. Using a users and orders example, this article shows how @key and __resolveReference hold entities together across subgraph boundaries.
- [Fuzzy Matching with Explicit Limits](https://www.mikebild.dev/en/blog/fuzzy-matching-with-explicit-limits/): A fuzzy match is a claim with a confidence, not a fact – it only becomes useful through versioned thresholds, three decision zones, and a diffable report of the gray zone.
- [Event Sourcing on AWS: DynamoDB Streams and Lambda](https://www.mikebild.dev/en/blog/event-sourcing-on-aws-dynamodb-streams-and-lambda/): Event Sourcing implemented serverless: DynamoDB as an append-only event store, DynamoDB Streams as the change feed and Lambda as an idempotent projector into CQRS read models.
- [Testing RxJS with Marble Diagrams](https://www.mikebild.dev/en/blog/testing-rxjs-with-marble-diagrams/): Marble diagrams make the timing of asynchronous streams visible. With TestScheduler.run and virtual time, you test RxJS operators deterministically: no real waiting, no flakiness.
- [Invoice Data as a Domain](https://www.mikebild.dev/en/blog/invoice-data-as-a-domain/): Why an invoice import isn’t a CSV job but a domain with its own terms, invariants and time rules – and how explicit types and a rejection report turn silent data errors into explainable data.
- [Testing Node.js: The Test Pyramid with Mocha](https://www.mikebild.dev/en/blog/testing-nodejs-the-test-pyramid-with-mocha/): How to distribute a Node.js test suite sensibly across different test levels and how Mocha, node:assert, sinon and supertest work together along the way.
- [Deterministic CLIs](https://www.mikebild.dev/en/blog/deterministic-clis/): Determinism is an architecture decision: same inputs, same report, reviewable via diff. It pays off wherever an artifact is checked repeatedly.
- [Observability with OpenTelemetry: Logs, Traces and Metrics](https://www.mikebild.dev/en/blog/observability-with-opentelemetry/): Instrument logs, traces and metrics consistently with OpenTelemetry, connect them through trace IDs and export them via OTLP to suitable backends.
- [The GraphQL Client: Apollo Link and Fragments](https://www.mikebild.dev/en/blog/graphql-client-apollo-link-and-fragments/): Apollo Link runs every GraphQL operation through a chain of middleware: authLink sets headers, errorLink handles errors in one place, split routes subscriptions. Plus fragments as reusable field sets and why interfaces need possibleTypes.
- [OCR with a Cache and Distrust](https://www.mikebild.dev/en/blog/ocr-with-a-cache-and-distrust/): Why an OCR pipeline for receipt data only feels reliable once you secure every recognized value with a hash cache, a confidence gate and plausibility rules instead of believing it.
- [The Four Subject Types in RxJS](https://www.mikebild.dev/en/blog/the-four-subject-types-in-rxjs/): Subject, BehaviorSubject, ReplaySubject and AsyncSubject differ in what late subscribers see and in how completion or an error ends their stored behavior.
- [Apollo Client: The Normalized Cache and Optimistic Updates](https://www.mikebild.dev/en/blog/apollo-client-normalized-cache-and-optimistic-updates/): HTTP caching is possible with GraphQL too, but for client state it is often less direct. That is why Apollo normalizes objects and supports optimistic updates in the UI.
- [Securing GraphQL: Query Depth, Complexity and Rate Limiting](https://www.mikebild.dev/en/blog/securing-graphql-depth-complexity-rate-limiting/): A single GraphQL endpoint accepts arbitrarily nested queries – convenient and at the same time a risk of abuse. I show how I build a layered defense against expensive queries with a depth limit, a complexity budget, pagination caps and rate limiting.
- [TypeScript in Node.js: Setup, Types and Tests](https://www.mikebild.dev/en/blog/typescript-in-nodejs/): Setting up TypeScript in a Node project: understand the tsconfig essentials, type async code and handlers, and get the tests running, step by step from project practice.
- [TypeScript in React: Typing Props, Hooks and Events](https://www.mikebild.dev/en/blog/typescript-in-react/): How props and state become verifiable contracts – and your editor reports errors before your users see them. From interface/type through useState generics and event types to useRef and utility types.
- [Resilience Patterns: Timeout, Retry, Circuit Breaker, Idempotency](https://www.mikebild.dev/en/blog/resilience-patterns-timeout-retry-circuit-breaker/): Why resilience is no accident: timeout, retry with backoff and jitter, circuit breaker and idempotency as deliberately designed patterns against the failure modes of distributed systems.
- [GraphQL Subscriptions over SSE: Real Time Without Being Forced into WebSocket](https://www.mikebild.dev/en/blog/graphql-subscriptions-over-sse/): Subscriptions don’t need a WebSocket. Server-Sent Events are enough for the one-way server-to-client channel, while queries and mutations stay plain HTTP, and the schema decides what counts as a domain event in the first place.
- [Contract Testing Instead of an E2E Marathon](https://www.mikebild.dev/en/blog/contract-testing-instead-of-an-e2e-marathon/): Consumer-Driven Contracts check interfaces at the boundary between services instead of in an expensive, flaky end-to-end suite. The result: a faster, deterministic deploy gate and teams that release independently.
- [Errors as Architecture in Node.js: Safety Nets Against the Crash](https://www.mikebild.dev/en/blog/errors-as-architecture-in-nodejs/): Error handling in Node.js is not try/catch cosmetics but a decision about levels, escalation and orderly termination. If you know the four error levels and take graceful shutdown seriously, you build services that die in a controlled way instead of running on in a corrupt state.
- [DORA Metrics: What Really Shortens Development Cycles](https://www.mikebild.dev/en/blog/dora-metrics-what-really-shortens-cycles/): Lead time, deploy frequency, change fail rate, and recovery time are diagnostic values, not vanity velocity. They show where the cycle gets stuck – and why speed and stability don’t have to be opposites.
- [child_process in Node.js: Scaling Without Illusions](https://www.mikebild.dev/en/blog/child-process-in-nodejs-scaling-without-illusions/): Node.js runs on a single event loop – CPU work blocks everything. This post shows when fork, cluster, and worker_threads really help and when they are just overhead.
- [Understanding Lambda Performance and Cold Starts](https://www.mikebild.dev/en/blog/understanding-lambda-performance-and-cold-starts/): What a cold start in AWS Lambda really is, which levers you control – from bundle size through init code and memory to Provisioned Concurrency – and how to measure all of it properly.
- [RxJS in Node.js: Processing Event Streams Reactively](https://www.mikebild.dev/en/blog/rxjs-in-nodejs-event-streams/): RxJS in Node.js: how fromEvent turns an EventEmitter into an observable, how operators transform server-side streams declaratively and why RxJS has no real backpressure.
- [Evolutionary Architecture: Systems That Are Allowed to Change](https://www.mikebild.dev/en/blog/evolutionary-architecture-systems-allowed-to-change/): Architecture is not an end state that you lock down once. Small changes and suitable fitness functions make selected risks visible earlier, but they guarantee neither speed nor quality.
- [From HOCs and Render Props to Custom Hooks](https://www.mikebild.dev/en/blog/from-hocs-and-render-props-to-custom-hooks/): How do I share logic between components without copy-paste? Custom hooks usually avoid nested wrappers for this; HOCs and render props keep a few specific composition tasks.
- [Async Context in Node.js: AsyncLocalStorage, async_hooks and diagnostics_channel](https://www.mikebild.dev/en/blog/async-context-in-nodejs-with-asynclocalstorage/): How to carry request-scoped context such as request ID, user and trace through deep asynchronous call chains without threading it through every function signature – with AsyncLocalStorage, the underlying async_hooks and diagnostics_channel for decoupled tracing.
- [GraphQL Auth: Identity in the Context, Authorization in the Domain Logic](https://www.mikebild.dev/en/blog/graphql-auth-identity-in-the-context/): The GraphQL context carries the identity of a request. Whether that identity may perform an operation is decided by a central policy in the domain logic.
- [Debugging and Profiling Node.js Locally](https://www.mikebild.dev/en/blog/debugging-and-profiling-nodejs-locally/): From the console.log reflex to the built-in inspector: node --inspect, the debug module, nodemon and first CPU and memory profiles for local diagnosis.
- [Developer Productivity: Shorter Cycles with High Quality](https://www.mikebild.dev/en/blog/developer-productivity-shorter-cycles/): Short feedback loops with reliable quality are my mental model for developer productivity. Where the waiting actually happens has to be shown by your own lead time.
- [Slots, Context and Web Components in Svelte](https://www.mikebild.dev/en/blog/slots-context-and-web-components-in-svelte/): Three composition tools in Svelte 3: slots pass content in from the outside, the Context API avoids prop drilling, and custom elements make a component reusable independently of any framework.
- [Build vs. Runtime in Web Projects](https://www.mikebild.dev/en/blog/build-vs-runtime-in-web-projects/): The rendering time is decided per route. Static, dynamic and incremental models can be combined according to data shelf life, cost and failure behavior.
- [Streams in Object Mode: Data Pipelines Beyond Bytes](https://www.mikebild.dev/en/blog/streams-in-object-mode/): Node.js streams carry more than bytes: with objectMode:true they become composable data pipelines that parse, filter and aggregate – including the bridge to async iterators.
- [Reproducible Test Pipelines: No Flakiness, No Chance](https://www.mikebild.dev/en/blog/reproducible-test-pipelines/): Flakiness points to uncontrolled inputs or dependencies. If you make time, data and isolation visible, you can narrow down the cause and make the merge gate trustworthy again.
- [Adapter Design: Where Frameworks End](https://www.mikebild.dev/en/blog/adapter-design-where-frameworks-end/): What a framework adapter really does: the contract over the build output, the translation of request and response, and the silent environment assumptions at the boundary between SvelteKit and AWS.
- [RxJS in React: Observables in the UI Data Flow](https://www.mikebild.dev/en/blog/rxjs-in-react-observables-in-the-ui-data-flow/): RxJS does not shine everywhere in React, only where asynchronous events have to be coordinated – debounced input, canceled autocomplete requests, continuous streams. The post shows the few places where observables really pay off, and where useState is perfectly enough.
- [Motion, Transitions and Animations in Svelte](https://www.mikebild.dev/en/blog/motion-transitions-and-animations-in-svelte/): How Svelte ships motion declaratively and without an extra library: transition directives for fading in and out, svelte/motion for smoothly interpolated values and animate:flip for reordering lists.
- [Buffers in Node.js: Working with Binary Data](https://www.mikebild.dev/en/blog/buffers-in-nodejs-working-with-binary-data/): Why JS strings don’t work for raw bytes and Buffer is Node’s tool for them: alloc versus allocUnsafe, reading and writing encodings cleanly, and the memory trap behind slice and subarray.
- [Svelte Stores: State Outside the Component](https://www.mikebild.dev/en/blog/svelte-stores-state-outside-the-component/): Svelte stores are a minimal model for state that doesn’t fit into a single component: writable, readable, derived – plus the $ shorthand that subscribes and cleans up on unmount.
- [Node.js Streams: Understanding and Using Backpressure](https://www.mikebild.dev/en/blog/nodejs-streams-understanding-backpressure/): Why a fast producer must not overrun a slow consumer – and how pipe, pipeline, the return value of write() and the drain event handle flow control in Node.js.
- [Fitness Functions: Checking Selected Architecture Properties](https://www.mikebild.dev/en/blog/fitness-functions-checking-architecture-properties/): Fitness functions make selected properties such as coupling, dependencies and latency continuously checkable. They don’t replace domain quality or architectural trade-offs.
- [Svelte Reactivity: The Compiler Instead of a Virtual DOM](https://www.mikebild.dev/en/blog/svelte-reactivity-the-compiler-instead-of-a-virtual-dom/): Svelte compiles components at build time into targeted DOM code instead of diffing a virtual DOM at runtime. I show the mental model, reactive assignment with $: and the classic push trap that I keep running into in projects.
- [EventEmitter: The Event Model at the Core of Node.js](https://www.mikebild.dev/en/blog/eventemitter-the-event-model-at-the-core-of-nodejs/): EventEmitter is the common denominator beneath streams, HTTP servers and processes: I show on/once/off/emit, the special behavior of 'error' and how to avoid listener leaks.
- [GraphQL Pagination: Cursors, Connections and the Relay Pattern](https://www.mikebild.dev/en/blog/graphql-pagination-cursors-and-connections/): Why offset/limit produces duplicates and gaps in changing lists, and how cursor-based pagination with the connections pattern stays stable – including the schema, a resolver sketch and the pitfalls from real projects.
- [SvelteKit Adapter AWS: Framework Meets Cloud](https://www.mikebild.dev/en/blog/sveltekit-adapter-aws-framework-meets-cloud/): Why I built my own SvelteKit adapter for AWS and what the translation between the framework build and Lambda, S3 and CloudFront reveals about both sides.
- [Preview Environments per Pull Request](https://www.mikebild.dev/en/blog/preview-environments-per-pull-request/): Ephemeral environments per pull request shorten feedback and make reviews concrete: you click through the change instead of imagining it from the diff.
- [Jamstack as an Architecture Style for Web Applications](https://www.mikebild.dev/en/blog/jamstack-as-an-architecture-style/): Jamstack describes an architecture style with a pre-rendered frontend and decoupled services. This post puts the original building blocks JavaScript, APIs and Markup into context as of 2021.
- [Serverless Transactional Email: SES and Lambda](https://www.mikebild.dev/en/blog/serverless-transactional-email-with-ses-and-lambda/): How SES becomes an event-driven email building block: outgoing confirmation emails from a Lambda Function and incoming Receipt Rules that turn an email into a handler call.
- [State Management in React: Redux Toolkit, Lightweight Stores, MobX](https://www.mikebild.dev/en/blog/state-management-in-react/): When state is truly app-wide, the tool question comes up – Redux Toolkit, a lightweight store such as Zustand or Jotai, or the reactive model of MobX. But why this choice only comes after the counter-check, and usually turns out smaller than expected.
- [DynamoDB Data Modeling: Single-Table Design](https://www.mikebild.dev/en/blog/dynamodb-data-modeling-single-table-design/): DynamoDB rewards a different way of thinking than a relational database: not starting from the data model but from the access patterns. Single-table design combines several entity types in one table through composite keys.
- [CDN Construct: A Small Infrastructure API](https://www.mikebild.dev/en/blog/cdn-construct-a-small-infrastructure-api/): Why a custom CDK construct for static websites is more than saved lines: an opinionated interface over S3, CloudFront, certificates and DNS.
- [Outcome Before Output: Why Velocity Is the Wrong Number](https://www.mikebild.dev/en/blog/outcome-before-output/): Completed tickets are output, but not yet evidence of impact. Why velocity misleads in management reporting and how to align teams with outcomes instead.
- [Data Analysis with NumPy, Pandas, and Matplotlib](https://www.mikebild.dev/en/blog/data-analysis-with-numpy-pandas-and-matplotlib/): From raw data to insight: how NumPy, pandas, and Matplotlib work together – vectorized computation, groupby aggregation, and a quick plot in a small pipeline.
- [When CQRS and Event Sourcing Are Too Much](https://www.mikebild.dev/en/blog/when-cqrs-and-event-sourcing-are-too-much/): For most systems, CRUD is enough. CQRS and Event Sourcing only pay off under clear conditions – this article offers an honest decision guide instead of patterns for their own sake.
- [GraphQL Concepts: Schema, Resolvers, Execution](https://www.mikebild.dev/en/blog/graphql-concepts-schema-resolvers-execution/): The ideas behind GraphQL that last, no matter which server is in fashion right now – the schema as a typed contract, the query as a shape, the resolver model and the order of execution. A conceptual deep dive with diagrams.
- [GraphQL APIs with AppSync and DynamoDB](https://www.mikebild.dev/en/blog/graphql-apis-with-appsync-and-dynamodb/): AWS AppSync moves the GraphQL server out of your own operational responsibility and into a managed service. Using a DynamoDB backend, I show when this build-vs-buy decision holds up and when managed becomes a dead end, including the VTL mapping templates that are the price for it in 2021.
- [Using Context Well: A Distribution Path, Not Secret Global State](https://www.mikebild.dev/en/blog/using-react-context-well/): Context solves distributing data through the tree – but not the question of who owns the state. If you confuse the two, you build a global store through the back door and cause unnecessary renders when provider values change carelessly.
- [Reading Data in Python: CSV, JSON, Excel and Databases](https://www.mikebild.dev/en/blog/reading-data-in-python/): A toolkit for every data source: when the standard library is enough, when pandas pays off, and how to keep encoding, memory and SQL injection from becoming your downfall.
- [Architecture Decision Records: Decisions You Will Still Understand in Two Years](https://www.mikebild.dev/en/blog/adrs-decisions-you-still-understand/): Why did we choose PostgreSQL back then and decide against the message bus? ADRs make the why durable as a versioned Markdown artifact – instead of letting it seep away in hallway talk.
- [A GraphQL Schema That Grows: Evolution Without Breakage](https://www.mikebild.dev/en/blog/a-graphql-schema-that-grows/): How to evolve a GraphQL schema additively instead of versioning it – safe changes, real breaking changes, @deprecated as a tool and a field migration step by step.
- [Serverless Workflows with AWS Step Functions](https://www.mikebild.dev/en/blog/serverless-workflows-with-aws-step-functions/): Step Functions turn nested Lambda handlers into a declarative state machine: a visible flow, explicit retry and catch paths, Standard or Express.
- [Event Sourcing: The Event Store as a Logbook](https://www.mikebild.dev/en/blog/event-sourcing-the-event-store-as-a-logbook/): Event Sourcing doesn’t store the current state but the sequence of events as the source of truth: the event store as a logbook, the state as the result of a fold. Benefits, honest costs and how it differs from CQRS.
- [Testing Flask Apps: The Test Client and Reliable Endpoints](https://www.mikebild.dev/en/blog/testing-flask-apps/): How I test Flask endpoints: with app.test_client() without a running server, pytest fixtures and verified JSON responses.
- [Preserving and Resetting State: React and the Position in the Tree](https://www.mikebild.dev/en/blog/preserving-and-resetting-state-in-react/): React does not store state in the component but at its position in the render tree – once you understand that, you control preservation and reset on purpose instead of by accident.
- [Serverless Auth with Cognito User Pools](https://www.mikebild.dev/en/blog/serverless-auth-with-cognito-user-pools/): Cognito User Pools as a managed identity backend: sign-up, confirm and sign-in without your own auth server, the three tokens properly understood, and an API Gateway endpoint secured by a Cognito authorizer.
- [Trunk-Based Development Instead of a Branch Graveyard](https://www.mikebild.dev/en/blog/trunk-based-development-instead-of-a-branch-graveyard/): Short integration cycles with feature flags beat long-lived branches: daily integration without merge hell and a release that becomes a decision instead of a deploy event.
- [How React Renders and Updates the Tree](https://www.mikebild.dev/en/blog/how-react-renders-and-updates-the-tree/): From the JSX element to the visible pixel – what exactly happens between a state change and the redrawn screen. Render and commit as separate phases, the comparison of two trees and why React almost always touches only a tiny part of the DOM.
- [Team Automation with GitHub Actions](https://www.mikebild.dev/en/blog/team-automation-with-github-actions/): Why I run selected, recurring checks as workflows – and how you can tell whether the automation actually takes load off the team.
- [Web APIs with Flask: From the App to a JSON API](https://www.mikebild.dev/en/blog/web-apis-with-flask/): From Hello World to a JSON API: how routing, request handling and jsonify work together in Flask 1.1 – and why SSR and APIs are the same mechanism.
- [Read Models from Events: Projections Instead of Accidental Caches](https://www.mikebild.dev/en/blog/read-models-from-events-projections/): A read model built from events is a deliberately maintained projection for concrete queries. Origin and rebuild set it apart from an accidentally grown cache, even if the technical view can look cache-like.
- [Cloud Guardrails Instead of Cloud Gatekeeping](https://www.mikebild.dev/en/blog/cloud-guardrails/): Why central approval processes in the cloud breed shadow infrastructure and how technically enforced guardrails – SCPs, Permission Boundaries, Config Rules, budgets – give teams their freedom of movement back.
- [CDK Constructs: Abstraction with Liability](https://www.mikebild.dev/en/blog/cdk-constructs-abstraction-with-liability/): If you publish a CDK construct, you’re not shipping a helper function but operational decisions – about defaults, upgrade paths and what ends up in the consumer’s CloudFormation template.
- [Bounded Contexts Before the Service Split](https://www.mikebild.dev/en/blog/bounded-contexts-before-the-service-split/): Before I split services, I clarify domain boundaries. A bounded context is a language boundary and a possible, but not mandatory, service split.
- [Functional Patterns in Python: Comprehensions, itertools and functools](https://www.mikebild.dev/en/blog/functional-patterns-in-python/): Comprehensions, functools and itertools working together: how I show in projects when a comprehension is a better choice than map/filter, where lru_cache and groupby shine, and which pitfalls are waiting.
- [JSX Precisely: The Rules Behind the Markup](https://www.mikebild.dev/en/blog/jsx-precisely-the-rules-behind-the-markup/): A precise look at JSX – what the compiler turns it into, why curly braces hold expressions rather than statements, how attributes, children, conditions and lists work, and where beginners stumble.
- [AWS Deployment Pipelines Are Architecture](https://www.mikebild.dev/en/blog/aws-deployment-pipelines-are-architecture/): Deployment pipelines are architecture because they determine how often, how safely and how reversibly a system is changed.
- [Advanced Python: Decorators, Magic Methods and Generators](https://www.mikebild.dev/en/blog/advanced-python-decorators-magic-methods-generators/): Three building blocks that make code Pythonic: decorators wrap functions, magic methods bind your own objects to Python’s protocols, generators produce lazy sequences.
- [Policy as Code for CDK](https://www.mikebild.dev/en/blog/policy-as-code-for-cdk/): Policy as code makes a checkable part of your architecture rules executable and versionable.
- [The Aggregate as a Consistency Boundary](https://www.mikebild.dev/en/blog/the-aggregate-as-a-consistency-boundary/): An aggregate is neither an ORM entity nor a table but a consistency and transaction boundary: a cluster of objects that an Aggregate Root protects as a unit. Why a transaction changes exactly one aggregate and other aggregates are referenced only by ID.
- [`ssmenv-cli`: Small CLIs for Big Order](https://www.mikebild.dev/en/blog/ssmenv-cli-small-clis/): A small CLI on top of AWS SSM shows how configuration gets from a named, access-controlled source into local processes and CI – including questions of versions and failures.
- [GitHub Actions with AWS CDK](https://www.mikebild.dev/en/blog/github-actions-with-aws-cdk/): GitHub Actions and AWS CDK connect code changes, infrastructure and deployment into a reviewable pipeline – and make the architecture decision visible in the pull request.
- [PouchDB and Offline-First](https://www.mikebild.dev/en/blog/pouchdb-and-offline-first/): If you allow writes while offline, you move from request/response to replication – and the revision tree of PouchDB and CouchDB turns conflicts into a job for the domain model.
- [Cleanly Separating Commands, Events and Queries](https://www.mikebild.dev/en/blog/separating-commands-events-and-queries/): Command, event and query are three kinds of messages with clear semantics: a request that can be rejected, a fact that has happened and a query without side effects. If you name and separate them cleanly, you gain clarity in the model – without a big CQRS setup.
- [Infrastructure as Code Needs Code Reviews](https://www.mikebild.dev/en/blog/infrastructure-as-code-needs-code-reviews/): Once infrastructure is code, a small diff decides about security, cost and the risk of outages – that is why it belongs in the same review process as application code.
- [Secrets in the Build Are Product Decisions](https://www.mikebild.dev/en/blog/secrets-in-the-build-are-product-decisions/): Secrets in the build are a trust problem: who may see, store and deploy what, and when?
- [Product Discovery Before the First Line of Code](https://www.mikebild.dev/en/blog/product-discovery-before-the-first-line-of-code/): Discovery lowers the risk of efficiently building the wrong thing. I show a continuous track that tests assumptions before they tie up expensive delivery – not a phase before development.
- [CQRS Is a Domain Boundary, Not a Framework](https://www.mikebild.dev/en/blog/cqrs-is-a-domain-boundary-not-a-framework/): CQRS separates the model for writing from the model for reading – a domain decision, not an installable framework. When the boundary pays off, how to start small and which mix-ups get expensive.
- [Node.js Training: From the Event Loop to Architecture Decisions](https://www.mikebild.dev/en/blog/nodejs-training-from-event-loop-to-architecture/): You can’t explain Node.js through a framework. You explain it through the event loop, through streams and through the question of which architecture decision a team will still understand tomorrow – and that is exactly what I practice with participants in the introduction-nodejs repo.
- [CDK Early Days: Infrastructure in a Programming Language](https://www.mikebild.dev/en/blog/cdk-early-days-infrastructure-in-a-programming-language/): With the CDK, infrastructure moves into the same toolchain as application code, which means tests, reviews, and logical identities suddenly decide whether production data survives.
- [AWS Parameter Store in the Build](https://www.mikebild.dev/en/blog/aws-parameter-store-in-the-build/): Parameter Store in the build makes configuration explicit, but it raises hard questions about secrets and reproducibility.
- [Running Your Own Docker Registry](https://www.mikebild.dev/en/blog/running-your-own-docker-registry/): How I set up a private Docker registry with registry:2 in projects: tagging, pushing and pulling images, then securing it with htpasswd and TLS.
- [Kubernetes Basics Under Deployment Pressure](https://www.mikebild.dev/en/blog/kubernetes-basics-under-deployment-pressure/): Under the pressure of a real deployment, the Kubernetes concepts sort themselves by importance – from the pod through deployment and service to the ingress.
- [Central Logging with the ELK Stack in Docker](https://www.mikebild.dev/en/blog/central-logging-with-the-elk-stack-in-docker/): Container logs are scattered across many containers and they are ephemeral. This article shows how an ELK stack of Elasticsearch, Logstash and Kibana in a Compose setup centralizes logs, indexes them and makes them searchable.
- [Micro-Frontends: Team Boundaries in the Browser](https://www.mikebild.dev/en/blog/micro-frontends-team-boundaries-in-the-browser/): Why the real work in micro-frontends is not the integration technique but the team split – shown with a runnable example landscape of a gateway, four applications and a component library.
- [Frontend Interfaces Are APIs](https://www.mikebild.dev/en/blog/frontend-interfaces-are-apis/): Why props, URLs, events, CSS classes and localStorage deserve the same versioning discipline as a REST endpoint – at the latest when several teams work in the same browser.
- [Node.js and Redis with Docker Compose](https://www.mikebild.dev/en/blog/nodejs-and-redis-with-docker-compose/): How I describe a two-container app of Node.js and Redis with Docker Compose in projects: one YAML file for the whole stack, service discovery via the service name, persistence through a volume – and why depends_on doesn’t wait for readiness.
- [Containerization and False Security](https://www.mikebild.dev/en/blog/containerization-and-false-security/): Why “runs in a container” means neither isolation nor reproducibility nor well-run operations – and which steps actually close the three gaps.
- [My Working Definition of an MVP: Learning Instead of Shipping Half-Finished](https://www.mikebild.dev/en/blog/my-working-definition-of-an-mvp/): I use MVP for an experiment that honestly tests a risky assumption. This working definition keeps a merely reduced feature set from counting as learning.
- [A GraphQL Schema in the Domain Language](https://www.mikebild.dev/en/blog/a-graphql-schema-in-the-domain-language/): A GraphQL schema is the best place there has ever been for the ubiquitous language of a domain – and if the domain is German, it may stay German there, too.
- [Angular, React and the Value of Transitions](https://www.mikebild.dev/en/blog/angular-react-and-the-value-of-transitions/): Whether a framework switch becomes a move or a rebuild depends on how cheaply two worlds can run side by side for months.
- [Prototypes: The Object Model Behind JavaScript Classes](https://www.mikebild.dev/en/blog/prototypes-the-object-model-behind-javascript-classes/): class in ES2015 is essentially syntactic sugar over prototypes: if you understand the [[Prototype]] chain, Object.create, and the new sequence, you debug this errors and shared methods with more confidence.
- [Redux as a Protocol for UI Changes](https://www.mikebild.dev/en/blog/redux-as-a-protocol-for-ui-changes/): The store is the most boring part of Redux – the value lies in the message protocol of named, serializable actions that makes UI changes traceable, testable and open to discussion.
- [JavaScript Patterns That Stayed: Modules, Higher-Order Functions, Currying](https://www.mikebild.dev/en/blog/javascript-patterns-that-stayed/): Three JavaScript patterns have survived every framework change: the module pattern for clean encapsulation, higher-order functions for functions as values and currying for specialized variants. Why they form the foundation of modern utility libraries.
- [WebSockets Are Not Always the Answer](https://www.mikebild.dev/en/blog/websockets-are-not-always-the-answer/): Why Server-Sent Events are the simpler choice for most real-time requirements and when the price of a real WebSocket connection actually pays off.
- [KnockoutJS: Fine-Grained Reactivity with Observables and Computed](https://www.mikebild.dev/en/blog/knockoutjs-fine-grained-reactivity-with-observables/): How KnockoutJS solves reactivity: observables as get/set functions, computed with automatic dependency tracking and targeted DOM updates instead of a global tree comparison.
- [PWA Weather: Offline Is a Feature](https://www.mikebild.dev/en/blog/pwa-weather-offline-is-a-feature/): A small weather app built as a Progressive Web App shows why offline behavior is a product decision and how honestly a UI should deal with outdated data.
- [Tic-Tac-Toe with Minimax in React](https://www.mikebild.dev/en/blog/tic-tac-toe-with-minimax-in-react/): An unbeatable tic-tac-toe opponent in React shows why game logic as a pure function must know nothing about rendering – and why immutable moves fit React’s model.
- [Simple Design Can Save Process](https://www.mikebild.dev/en/blog/simple-design-can-save-process/): In many projects, process overhead compensates for a design that is too large or too speculative. Cutting smaller can save coordination; external requirements and real dependencies remain.
- [HTML5, CSS3 and ECMAScript as a Baseline](https://www.mikebild.dev/en/blog/html5-css3-and-ecmascript-as-a-baseline/): In the spring of 2017, CSS Grid, Flexbox, fetch and native ES2015 carry so far that the first architecture question in the frontend deserves to be asked again: How far do I get without a framework?
- [RxJS: Finally Telling Push and Pull Apart](https://www.mikebild.dev/en/blog/rxjs-telling-push-and-pull-apart/): Once you name the producer and the consumer, you see right away whether data is pulled or pushed, and you choose between function, iterator, Promise and Observable without guessing.
- [Node.js: Async I/O Explains Architecture](https://www.mikebild.dev/en/blog/nodejs-async-io-explains-architecture/): The calculation “one thread times 200 connections” shows which systems fit Node.js and which work belongs in separate processes.
- [Babel Node Express: Modern Syntax, Old HTTP](https://www.mikebild.dev/en/blog/babel-node-express-modern-syntax-old-http/): Babel translates syntax, not an execution model – once you keep the two apart, you know why babel-node belongs in the development loop and not in production.
- [API Thinking Before Framework Thinking](https://www.mikebild.dev/en/blog/api-thinking-before-framework-thinking/): If you define operations, data and failure cases before choosing a framework, you can swap the frontend almost at will later – the other way around, you get an API that mimics a framework.
- [Tyrian Rx React: UI as Data Flow](https://www.mikebild.dev/en/blog/tyrian-rx-react-ui-as-data-flow/): A rebuild of the Elm Architecture with RxJS and React – actions as a stream, scan() folds the model, side effects stay at the edge – and what this proof of concept reveals about UI architecture that ages well.
- [GraphQL-Pouch: Local Data with a Schema](https://www.mikebild.dev/en/blog/graphql-pouch-local-data-with-a-schema/): An open-source experiment from the summer of 2016: a GraphQL runtime that generates a complete CRUD API on top of PouchDB from a schema shorthand – including synchronization via the CouchDB replication protocol.
- [Definition of Done as a Quality Gate, Not Bureaucracy](https://www.mikebild.dev/en/blog/definition-of-done-as-a-quality-gate/): The automatable core of a Definition of Done belongs in a green gate of lint, build and test. Business acceptance and other judgments remain shared quality work.
- [React: Components as Interfaces](https://www.mikebild.dev/en/blog/react-components-as-interfaces/): Why props are the public contract of a React component – and what changes when you design them like an API instead of a parameter list.
- [GraphQL as a Question to the System](https://www.mikebild.dev/en/blog/graphql-as-a-question-to-the-system/): Half a year after the specification, this post sorts out what is really new about GraphQL – and which questions nobody had answered yet in early 2016.
- [Build Scripts as Product Code](https://www.mikebild.dev/en/blog/build-scripts-as-product-code/): Build scripts deserve the care of product code, because they determine how reproducible a system actually is.
- [ES6 Memory: Understanding UI State](https://www.mikebild.dev/en/blog/es6-memory-understanding-ui-state/): A memory game in fresh ES2015, built without a framework, makes visible which states a UI really has, where they should live and who may change them.
- [Web Messaging with RxJS](https://www.mikebild.dev/en/blog/web-messaging-with-rxjs/): If you hide incoming messages behind an observable, the transport between browser and server becomes interchangeable – and you notice along the way how far plain HTTP gets you.
- [Functional Styles in Everyday Code](https://www.mikebild.dev/en/blog/functional-styles-in-everyday-code/): Why functional style in everyday team work in 2015 does not mean Haskell, but the discipline of separating pure functions from I/O – and how ES2015 finally makes that convenient.
- [Containers Are Not Architecture](https://www.mikebild.dev/en/blog/containers-are-not-architecture/): Docker makes system boundaries visible and portable – you still have to draw them by hand, and a monolith remains a monolith inside a container.
- [Programming Styles as an Architecture Comparison](https://www.mikebild.dev/en/blog/programming-styles-as-an-architecture-comparison/): The same small task solved in dozens of programming styles is the most compact architecture comparison I know – because every style is a deliberately chosen set of constraints.
- [Docker for .NET, Before It Was Normal](https://www.mikebild.dev/en/blog/docker-for-dotnet-before-it-was-normal/): Packing a small Nancy API under Mono into a Docker container was a detour via Linux in the spring of 2015 – and it taught me more about .NET deployment than any IIS manual.
- [Tests Before There Is a Product](https://www.mikebild.dev/en/blog/tests-before-there-is-a-product/): Early tests help you grasp a problem, even if the code is later replaced entirely.
- [Flood-It: A Game as an Architecture Lens](https://www.mikebild.dev/en/blog/flood-it-a-game-as-an-architecture-lens/): A board of numbers, a move as a pure function and a greedy solver show on a small scale what gets blurry in large systems: the separation of core logic, strategy and presentation.
- [MathParser: Parsers as a Thinking Tool](https://www.mikebild.dev/en/blog/mathparser-parsers-as-a-thinking-tool/): A look back at a parser demo of my own from 2010 shows why a handwritten expression parser teaches more about layers, structure and the boundary between syntax and semantics in a few lines than many a large project.
- [State Mutation on Streams](https://www.mikebild.dev/en/blog/state-mutation-on-streams/): If you compute state as a fold over a stream of events instead of changing it directly, you get undo, replay and traceability almost for free.
- [HTTP APIs: Small, Stable, Readable](https://www.mikebild.dev/en/blog/http-apis-small-stable-readable/): What the Heroku HTTP API Design Guide is worth when you hold it up against your own APIs – and why a few resources, a versioning promise and self-explanatory errors achieve more than any framework.
- [What I Was Looking for in Elixir](https://www.mikebild.dev/en/blog/what-i-was-looking-for-in-elixir/): It wasn’t the syntax that brought me to Elixir but the execution model of the Erlang VM – processes, messages and supervisors, seen through JavaScript and C# eyes.
- [Control Flow Before `async/await`](https://www.mikebild.dev/en/blog/control-flow-before-async-await/): A look at the tiny library cflow shows how Node developers wired asynchronous steps into a chain by hand, and why the missing error channel is the real lesson.
- [Why Katas Are More Than Finger Exercises](https://www.mikebild.dev/en/blog/why-katas-are-more-than-finger-exercises/): A kata is an architecture lab in miniature – because the task stays constant, it reveals what otherwise only the design knows.
---
# Interim Review and System View: Taking Stock of the Series
URL: https://www.mikebild.dev/en/blog/interim-review-and-system-view/
Date: 2026-08-17
The conversation with which [this series began](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/) took place in October of last year; this text takes stock as of August 2026. The opening ended with a resolution: to distrust my own enthusiasm for the time being, look closely and measure every result against more than thirty years of craft. The [last installment](https://www.mikebild.dev/en/blog/tools-that-hold-up-concepts-methods-processes-article/) announced that it would take this resolution at its word. So: which of the expectations came true, which didn’t, what remains open – and what system view has emerged from the individual sessions of the beginning?
*Part 13 of the series “From Session to System” – [the opening post is here](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).*
## The enthusiasm survived the test – barely
The most important thing first, because everything else builds on it: the few days of trial in October have become everyday work, and that is the least spectacular evidence I can offer. I no longer think about these tools, any more than I think about the editor or version control. They are infrastructure. A flash in the pan looks different – you recognize one by the fact that after three months you’re telling stories about it again instead of working with it.
Still, it would be too cheap to simply declare my own perception to be the assessment. In July 2025, the American research institute METR – a nonprofit that measures the capabilities of AI systems with controlled experiments – published a study that has occupied me more than any benchmark: experienced open-source developers were measurably slower with AI support on randomized tasks – by roughly a fifth – and yet afterwards estimated that they had been considerably faster. So exactly the perception I have relied on since the opening can be systematically deceptive. I take that seriously, because it is the same warning I gave myself in the opening: fresh enthusiasm is a poor witness.
That’s why I check against things that can’t be talked up. What is actually done in the evening? Which of the stalled projects are in operation today? How often did I find errors in reviews that would have slipped through without the shift toward checking? By this standard, the assessment is positive – as an observation, not a measurement; I lack reliable numbers on it. That is exactly why the study remains important for my assessment: as long as I don’t measure with comparable rigor, I have to factor in that my perception may deceive me too. The study does, however, measure tasks that were familiar to the developers, in code they knew well. My biggest gain lies elsewhere – in the projects that would never have been started at all without these tools. That doesn’t refute the study; it’s a different calculation. Both can be true at the same time.
## What came true
The opening recorded three observations. All three have survived the months since the opening, but none has stayed the way it was.
The first – generating gets cheap, checking becomes the bottleneck – has turned out to be the load-bearing observation of the entire series. In hindsight, almost every installment is an answer to this one shift: the harness organizes checking around the model, the [house rules](https://www.mikebild.dev/en/blog/what-i-am-critical-of/) defend it against my own convenience, [grounding](https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/) anchors it in real sources, and [rules in the path](https://www.mikebild.dev/en/blog/ai-agents-per-domain/) make it independent of the checker’s form on the day. What I didn’t see yet in November: the bottleneck keeps moving. First checking was scarce, then cleanly writing down what is supposed to apply – by now it is deciding what gets built at all.
The second observation – the drawers open up again – came true, with a limitation I didn’t see coming back then. Some of what had been lying around for years is in operation today: smaller than the original idea, and that is not a defeat but a finding. Because what the tools don’t deliver is a judgment on which of the old ideas were worth it. I shut down two projects again after a few weeks – failed faster than would have been possible before, and that is exactly the underestimated gain: cheap implementation makes discarding cheap too.
The third observation – the tone is always right, even when the content isn’t – was a gut feeling in November. It has since become [a structural explanation](https://www.mikebild.dev/en/blog/clean-grounding-i-why-ai-guesses-so-convincingly/) and then a procedure. The distrust has stayed, but it has moved: from my private vigilance into check steps that don’t depend on whether I’m having a good day. That is perhaps the most compact summary of what these months have done to my way of working – diligence went from being a virtue to being a property of the setup.
## What I expected wrongly
An assessment that only lists hits is advertising. Two expectations didn’t hold.
The most expensive misjudgment: that writing things down is enough. For months I put work into ever better instruction files before I honestly drew up the chronicle of these attempts – written rules remain recommendations, no matter how well they are phrased. From this disillusionment came the most important insight of the series: rules that are supposed to apply need a path that enforces them – check before effect, approvals, evidence. If I could take a single sentence away from these months, it would be this one.
The second misjudgment is more pleasant: I had expected the choice of model to become more important over time – that at some point one model would pull ahead and the question “which one?” would turn into a strategic question after all. The opposite happened. For my tasks, several model changes since the opening felt like quality improvements, and with every jump the choice became [less important, not more](https://www.mikebild.dev/en/blog/good-enough-models/). My way of working hardly noticed the changes. What does make itself felt every time, on the other hand: a badly cut task, a missing piece of context, a rule that only exists in prose. My own share dominates the result – that was there early as a thesis, and by now it concretely decides whether a run holds up: in how the task is cut, in the context provided and in the rules enforced in the path.
## What remains open
Three questions remain unanswered in this interim review.
The junior question. The opening contained a suspicion: the lever works because three decades of judgment stand behind it – and whether it works the same way for someone without that foundation, I didn’t know. I still don’t know today, and the [critical installment](https://www.mikebild.dev/en/blog/what-i-am-critical-of/) sharpened the suspicion rather than dispelled it: if you get working code before the pain sets in from which understanding arises, you may never build up the substance that checking draws on. A suspicion is still not knowledge. But it is the question I consider more important than any model question.
Homogenization. That teams asking the same model build more similar solutions is something I have recognized several times since that one observation in February, but never measured. It remains a concern without evidence, and I deliberately leave it at that instead of inflating it into a thesis.
Unlearning my own craft. The house rules from February hold up about as well as New Year’s resolutions: better than nothing, worse than claimed. The deliberate run without AI does happen, but less often than I had planned. The pull of the convenient option is real, every day. Exactly this experience made me skeptical, for the second half of the series, of everything that relies on discipline – and receptive to everything that moves diligence into the setup.
## The arc, in hindsight
The triad of I, We, System was already there as an intention in the opening. What I hadn’t planned is the mechanism that emerged while writing: each level inherits the unsolved problem of the previous one. The discipline of the individual [doesn’t scale to the team](https://www.mikebild.dev/en/blog/my-success-cannot-be-copied/), so the team writes down its rules; written rules bind nobody, so you need knowledge with owners and [a place that survives the session](https://www.mikebild.dev/en/blog/knowledge-that-survives-the-session/); curated knowledge doesn’t yet answer the question of what is binding, so the hard rules move [into the path of a dedicated agent](https://www.mikebild.dev/en/blog/ai-agents-per-domain/); and so that this doesn’t remain a drawing-board design, you need [concepts, methods and processes](https://www.mikebild.dev/en/blog/tools-that-hold-up-concepts-methods-processes-article/) that keep the beginning small.
```mermaid
flowchart LR
subgraph AKT1["Act 1 · I"]
S["Session generating gets cheap"] --> P["Way of working checking becomes the bottleneck"]
end
subgraph AKT2["Act 2 · We"]
P --> V["Team variance discipline doesn’t scale"] --> D["Instruction files recommendation instead of rule"]
end
subgraph AKT3["Act 3 · System"]
D --> W["Curated knowledge with owners"] --> R["Rules in the path agent per domain"] --> B["System architecture UI, contracts, approvals"]
end
```
The sentence that holds this arc together came up in the installment on curated knowledge: it’s not the model that gets smarter – the organization curates its knowledge.
## Today’s system view
At the center is the property this series has been about from the start: the separation of proposal and effect, built as a dedicated approval boundary, not as a blanket switch. A workflow engine can hold back external writes until confirmation. A publishing system can tie the promotion of a preview to a human. A knowledge system can leave changes standing as a proposal until a human decides. An order control system can tie execution to approved orders. The same principle, cut differently each time – because the question of what “taking effect” means has to be answered differently in every domain. Published content takes effect differently from an approved knowledge revision, and both differently from a workflow that writes into a third-party system.
With that, the question the opening asked has shifted too. It was: what can the models do? It is now: what does an organization make of it? Access to an external model API is not the part of this architecture that the organization permanently controls itself. A UI backed by a cleanly cut domain, machine contracts that other systems can rely on, and approval paths that prevent a proposal from taking effect without the intended human decision: an organization has to build these itself, and that is exactly the share that remains its own, independent of any single model.
## Position instead of prediction
I have no basis for judging model capabilities a year from now, productivity curves of entire industries or labor markets, and above all these months have taught me how quickly such statements age. That’s why I’m not formulating a vision, and I explicitly mark what this interim review is: my limited state of experience, not a prediction about inevitable market or organizational developments.
What I can stand behind, because it has been confirmed repeatedly over these months: the lasting value lies less in the individual model than in your own knowledge, enforceable rules, clear domains and verifiable processes. That is not a statement about the future but a description of what remained after every model change – and of what was missing every time a result didn’t hold up.
And for my own desk, one expectation remains that you can measure me against: the first domain agent that has been in operation long enough for its rejections to tell stories – correct noes, overly tight noes, special cases that deserve a verb of their own. Only then will it show whether the cycle from the last installment holds up or just sounds good.
## Interim review, not a final word
This series pauses here, for a simple reason: the supply of observations is used up. What would come now would be extrapolation, and there is enough of that. What this interim review lacks is time in operation. When enough new material has come together again, when the noes of the first domain agent have something to tell, I’ll keep writing. Until then, the resolution from the opening applies unchanged: distrust your own enthusiasm, measure against real tasks, check every result against your own craft. Looking closely pays off, and it doesn’t stop.
## Further reading
- [Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity (METR, July 2025)](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) – the study that puts measured slowdown and perceived speedup side by side
- [The Anthropic Economic Index](https://www.anthropic.com/economic-index) – ongoing data collection on what AI is actually used for in the economy
- [Things we learned about LLMs in 2024 (Simon Willison)](https://simonwillison.net/2024/Dec/31/llms-in-2024/) – a sober annual review as an antidote to prediction prose
---
# MCP, HTTP, Webhooks and A2A Explained Simply
URL: https://www.mikebild.dev/en/blog/mcp-http-webhooks-and-a2a-explained-simply/
Date: 2026-08-17
Four connections can all run over HTTP technically and still serve four fundamentally different purposes. An agent application discovers a tool. A fixed program calls a documented endpoint. A service reports an event that has already happened. An independent agent takes on a task with its own lifetime.
MCP, HTTP with OpenAPI, webhooks and A2A describe these boundaries. None of them replaces the domain decision about who may read, write, approve or publish. A product can offer several of these machine interfaces and also have its own web UI for people. It still remains one domain with one authoritative product state and the same domain rules.
## Four questions instead of a ranking
An interface is an agreed boundary between systems. It defines inputs, results and errors. The transport, however, doesn’t yet answer which responsibility is handed over at this boundary.
| Technique | Guiding question | Typical task |
| --- | --- | --- |
| MCP | Which capabilities can an agent application discover and use? | Providing tools and context for an open-ended task |
| HTTP with OpenAPI | Which known machine command can a client execute? | Calling and checking a stable service contract |
| Webhook | Which event that has occurred should another system learn about? | Triggering a downstream process promptly |
| A2A | Which bounded task can an independent agent take on? | Delegating stateful work to another agent system |
The four options are not ranked, and they don’t sit on the same technical layer. HTTP is a transport protocol, OpenAPI describes an interface, webhooks use HTTP to deliver events, and MCP and A2A each bring their own interaction contracts. An A2A agent can call MCP tools and ordinary HTTP APIs internally.
## MCP provides capabilities for agent applications
MCP stands for Model Context Protocol. With it, an agent application can, for example, discover a knowledge service’s search as a tool; the visibility of this tool is not yet a domain permission and no substitute for a fixed workflow.
A server can run locally as a process or remotely as a web service. The word “server” describes its role in the protocol, not its location.
```json
{
"mcpServers": {
"knowledge": {
"type": "http",
"url": "https://knowledge.example.com/mcp"
}
}
}
```
After connecting, the agent application can check the input schema and call the tool. This doesn’t give the model a blanket permission. The host controls which capabilities are visible and which calls require consent. The server authenticates and authorizes the call. The responsible service additionally enforces its domain rules for the operation.
MCP fits open-ended tasks. An agent application can search a knowledge service for approved knowledge, read sources and, depending on the result, decide which next step makes sense. For repeated publications with an identical sequence of steps, this freedom is unnecessary. A stored, approved workflow is easier to check and repeat there.
## HTTP and OpenAPI form an explicit machine contract
HTTP governs request and response. OpenAPI describes the APIs built on top of it in a machine-readable way: paths, methods, inputs, responses and security schemes. People can read the description, programs can generate clients from it, and checks can compare the implementation with the contract.
The following call is a schematic example:
```http
POST /v1/sites/demo/previews HTTP/1.1
Host: content.example.com
Authorization: Bearer
Content-Type: application/json
{
"revisionIds": ["rev-123", "rev-456"]
}
```
The call requests a preview. It says nothing about who reviewed the content from a domain point of view or whether this preview may be published. OpenAPI can make the technical contract precise. The approval rule belongs in the domain and in the controlled process.
In a publishing system, the HTTP and OpenAPI interface can serve fixed integrations, a remote MCP endpoint can offer selected capabilities to agent applications, and a web UI can carry the human work in the same publishing domain. All three access paths then work with the same revisions, previews, releases and permission boundaries; none of them introduces a second persistence path.
## A webhook reports an event
With a normal API call, the client actively asks. With a webhook, the event source sends an HTTP request to a previously registered address. That way, the receiver doesn’t have to keep checking whether something has changed.
```http
POST /webhooks/knowledge HTTP/1.1
Host: orchestration.example.com
webhook-id: evt-789
webhook-timestamp: 1785585600
webhook-signature: v1,
Content-Type: application/json
{
"type": "proposal.approved",
"data": {
"space": "product-docs",
"concepts": ["integration-options"]
}
}
```
The event type in the example is deliberately generic. In this flow, the webhook only carries the event and the reference to the authoritative state. The receiver checks signature and age, detects duplicate deliveries via the event ID and then reads the state from the responsible system with its own permissions.
Duplicate delivery is part of the normal failure pattern. The receiver has to work idempotently: the same event ID may only take effect once in domain terms. It responds quickly and moves longer work into a stored process. A knowledge service can deliver signed Standard Webhooks for this. A workflow engine can bind such an input – with signature checks and protection against replays – to exactly one versioned workflow, without taking over the knowledge or publishing rules of the systems involved.
## A2A delegates to an independent agent system
A2A stands for Agent2Agent. The protocol connects a calling agent with an independent remote agent system. The client knows its published capabilities, but not its internal plan, memory or tools. The remote agent remains responsible for how it handles the task within its boundaries.
An Agent Card describes identity, endpoint, capabilities and authentication requirements. A message carries a conversation step made of text, files or structured data. Longer-running work gets a task with its own ID and a lifecycle. Results are returned as artifacts. Follow-up questions and other necessary decisions appear as state transitions of the task.
That distinguishes delegation from a tool call. With MCP, an agent application calls a described capability. With A2A, one agent hands a goal to another system that can plan on its own, use tools and carry out several steps.
## Web UIs and machine interfaces serve different purposes
A web UI for people is not a fifth kind of integration. MCP, HTTP with OpenAPI, webhooks and A2A connect machines. The web UI and the machine interfaces work with the state of the same domain and don’t introduce a second persistence path.
Each web UI uses the terms and decisions of its own domain for this. In a knowledge service, a pending knowledge change is a change proposal; in a workflow engine, an execution belongs to a specific workflow version.
Two boundaries follow from this separation:
- A web UI doesn’t become a second domain system with diverging rules.
- A machine protocol doesn’t become an unintended way around the human decision.
## No protocol grants permissions by itself
Authentication answers: who is making the request? Authorization answers: what may this identity do? A valid key shouldn’t lump reading, writing and publishing together across the board.
An agent searching for knowledge only needs read permissions. A step that builds a preview needs the write permissions required for that. A publication may require its own permission and a visibly bound human approval. If an operation is offered via several interfaces, the same domain approval boundaries must apply to it.
Reliability doesn’t come from the name of the protocol either. An HTTP call can break off after successful processing, before the response reaches the client. A webhook can arrive more than once. An A2A task can wait a long time for a decision. Every writing step therefore needs a stable identifier, a clear retry rule and a stored state.
For integrations that write or require approval, three contracts have to fit together:
- The technical contract describes inputs, results and errors.
- The domain contract defines which system owns knowledge, approval and publication.
- The operational contract governs time limits, retries, logging and how outages are handled.
## A flow with all four boundaries
```mermaid
flowchart LR
U["Human states a goal"] --> A["Agent application works on an open task"]
A -->|"MCP search and read"| K["Knowledge service reviewed knowledge"]
A -->|"MCP or HTTP / OpenAPI revision and preview"| C["Publishing system publishing domain"]
K -->|"signed webhook approval event"| S["Workflow engine versioned workflow"]
S -->|"HTTP / OpenAPI defined steps"| C
A -.->|"A2A delegate a bounded task"| R["Agent system independent task"]
H["Human in the respective web UI"] -.-> K
H -.-> S
H -.-> C
H -.-> R
```
The first run can be supervised. An agent application reads from the knowledge service, generates Markdown and builds a preview in the publishing system. A person sees the results and can still change the order.
As soon as the sequence repeats reliably, it belongs in a workflow engine as a versioned workflow. The workflow reads a specific approved knowledge revision, creates a content revision and builds a preview. It doesn’t publish automatically just because a webhook started it. The publishing system keeps the approval and release boundary.
A2A comes in when an independent agent system actually takes on a bounded task with its own lifetime. Calling something an “agent” doesn’t turn a simple API call into delegation.
## The decision comes before the protocol
The table only helps once three questions are answered: which system owns the state? Which identity may change it? Which effect requires a human decision? From these follow the rules for retries and the view in which a person can check the current state.
First you decide who owns state and approval. Then comes the protocol.
## Further reading
- [Model Context Protocol: Architecture](https://modelcontextprotocol.io/docs/learn/architecture)
- [Model Context Protocol: Introduction](https://modelcontextprotocol.io/docs/getting-started/intro)
- [OpenAPI Specification](https://spec.openapis.org/oas/)
- [Standard Webhooks](https://www.standardwebhooks.com/)
- [A2A: Key concepts](https://a2a-protocol.org/latest/topics/key-concepts/)
- [A2A and MCP compared](https://a2a-protocol.org/latest/topics/a2a-and-mcp/)
---
# A2A: When Agents Work Together
URL: https://www.mikebild.dev/en/blog/a2a-when-agents-work-together/
Date: 2026-07-22
An agent system needs a limited code change in someone else’s repository. It could load tools itself, read the code and draft the change. But it can also hand the job over to an independent system that runs in a different environment, has its own permissions and later reports back a verifiable result.
A2A 1.0 – the abbreviation stands for Agent2Agent – describes, for this second case, how a job is handed over and tracked between independent systems. The published specification of the open protocol covers how a client finds a remote agent, sends it messages, tracks longer-running tasks and receives results. It doesn’t prescribe which language model, which programming language or which framework works internally.
## Independent is the key word
Not every named role is a separate agent. If an application runs three prompts one after the other and manages all tools, credentials and state centrally, then from an architecture perspective, those are three work steps in one agent system. A2A brings little there.
A remote A2A agent, by contrast, is an independent service. Within its job, it decides for itself how it works. The calling agent sees the offered capabilities and the exchanged data, but not automatically the other system’s internal memory, reasoning or tools. This encapsulation separates the permission and task boundaries of both systems: the remote agent works with its own access rights, and only what the job calls for should be exchanged.
In the protocol, an A2A client makes contact on behalf of the user. The A2A server provides the remote agent. Client and server are communication roles, not classes of systems: for a different job, the same system can take on the other role.
```mermaid
flowchart LR
U["User sets a goal"] --> C["Calling agent A2A client"]
C -->|"Read Agent Card"| S["Remote agent A2A server"]
C -->|"Message job and context"| S
S -->|"Task state and follow-up questions"| C
S -->|"Artifacts results"| C
S --> M["Internal models, tools and data sources"]
C -.->|"no automatic access"| M
```
## The Agent Card is the description, not the permission
Before a client sends a job, it has to know what the other agent offers and how it can be reached. That is what the Agent Card is for, a JSON document with metadata. The published A2A 1.0 specification describes in it, among other things, identity, supported interfaces and offered skills; as ways to obtain it, it names a standardized address (`https://{domain}/.well-known/agent-card.json`), as well as catalogs or a fixed configuration.
The following fictional publishing example is reduced to the fields needed here and doesn’t claim to be a complete A2A 1.0 Agent Card.
```json
{
"name": "Publishing Agent",
"description": "Builds previews and prepares approved releases",
"supportedInterfaces": [
{
"url": "https://publishing.example.com/a2a",
"protocolBinding": "HTTP+JSON",
"protocolVersion": "1.0"
}
],
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": true
},
"defaultInputModes": ["text/plain", "application/json"],
"defaultOutputModes": ["text/markdown", "application/json"],
"skills": [
{
"id": "prepare-publication",
"name": "Prepare publication",
"description": "Creates a preview from approved knowledge",
"tags": ["publishing", "preview", "content"]
}
]
}
```
The Agent Card is comparable to a public service description. The fact that a skill is listed there doesn’t yet permit a call. Authentication and authorization remain separate security decisions: for every job, the server has to check who is asking and what this client is allowed to do. A public Agent Card should also not reveal internal capabilities or confidential endpoints.
## Message, Part, Task and Artifact
Message, Part, Task and Artifact denote different building blocks of a job.
| Term | Meaning | Example in delegated work |
| --- | --- | --- |
| Message | A conversational turn by the user or the agent | “Analyze this dependency and propose a change.” |
| Part | A component of a Message or an Artifact | Instruction as text, a file or structured data |
| Task | A stateful unit of work with a unique ID | The job is waiting for an answer to a question or keeps working |
| Artifact | A result produced by the agent | Analysis report, prepared change, preview URL |
A Message can be answered immediately with another Message. That fits a short conversation without a lasting work state. If the work has to keep running or be preserved across several conversation rounds, the remote agent responds with a Task.
The Task is more than a technical request ID. It holds the state of a domain unit of work. The client can read it later, answer a follow-up question or request a cancellation. According to the specification, several Messages can belong to the same conversation context via a `contextId`; a `taskId` denotes the concrete work. A simplified, non-normative example:
```http
POST /message:send HTTP/1.1
Host: agents.example.com
Authorization: Bearer
Content-Type: application/a2a+json
A2A-Version: 1.0
{
"message": {
"role": "ROLE_USER",
"messageId": "msg-123",
"parts": [
{
"text": "Prepare a limited change proposal. Do not merge it."
},
{
"data": {
"repository": "product-service",
"scope": ["dependency-upgrade"]
},
"mediaType": "application/json"
}
]
}
}
```
The Parts separate different kinds of content within the same Message: text carries an instruction, a file hands over a document, structured data allows an agreed schema without parsing it out of prose again. The recipient has to check the media type, size, origin and permission of each piece of content.
Artifacts are the work results, not just conversational turns. According to the specification, a Task can deliver several Artifacts, and an Artifact can be extended step by step during a stream. The client should therefore store the Artifact ID and Task ID instead of just copying the last visible text. A typical first response looks like this – the server has accepted, but not finished yet:
```json
{
"task": {
"id": "task-456",
"contextId": "context-789",
"status": {
"state": "TASK_STATE_WORKING",
"timestamp": "2026-08-07T10:05:00Z"
},
"artifacts": []
}
}
```
## The lifecycle makes longer work visible
A2A is designed for asynchronous tasks. A server can return a Task immediately and keep working in the background. For updates, the specification provides three delivery paths: queries, a continuous stream or push notifications.
```mermaid
stateDiagram-v2
[*] --> SUBMITTED
SUBMITTED --> WORKING
WORKING --> INPUT_REQUIRED: follow-up question
INPUT_REQUIRED --> WORKING: further Message
WORKING --> AUTH_REQUIRED: additional approval
AUTH_REQUIRED --> WORKING: permission granted
WORKING --> COMPLETED
WORKING --> FAILED
SUBMITTED --> REJECTED
WORKING --> CANCELED
COMPLETED --> [*]
FAILED --> [*]
REJECTED --> [*]
CANCELED --> [*]
```
The diagram simplifies the state space defined in the version 1.0 specification. `INPUT_REQUIRED` means that the agent needs further domain information. `AUTH_REQUIRED` signals an authorization needed during the job; credentials don’t belong in a Message as plain text but go through a separate, previously agreed path. The specification defines `COMPLETED`, `FAILED`, `CANCELED` and `REJECTED` as final states. A client must not revive a final state by blindly retrying, but has to deliberately create a new Task.
Polling, streaming and push solve the same delivery problem in different ways. With polling, the client asks for the Task at sensible intervals – simple, but wasteful during long pauses. With streaming, a connection stays open and the server sends status and Artifact updates as events; after an interruption, the client has to read the stored Task again, because a stream is not an archive. Push notifications spare you the permanent connection, but require a secured HTTP endpoint on the client side, including authentication, protection against internal target addresses and handling of duplicate deliveries.
## Delegation creates no new permission
A2A doesn’t make any security decision for a system. A calling agent should not trust an Agent Card it found just because it is formally correct. Before a job, it has to be clear which provider your own system trusts, which data may leave it and which effects the remote agent can trigger.
The A2A server has the same obligation: for every job, it has to check who is asking and what this client is allowed to do, and treat Messages as untrusted input. The most important principle behind this: delegation must not create new permissions. Whoever submits a job must not gain more rights in the target system by doing so, and the executing agent must not silently inherit the rights of its client. The job stays limited.
A target system can make this limitation explicit: a delegated job is then bound to an active, human-approved job state. What this state doesn’t allow, even a technically correct A2A call cannot trigger. A human approval step thus remains a domain decision in the target system – an agent must not infer an approval from friendly wording in a Message.
## MCP, A2A and a web UI are different access paths, not labels
MCP provides an agent application with tools and context; responsibility for the open task stays with the application. A2A connects independent agent systems: the client hands over a goal, the remote agent is responsible for the execution and runs its own Task lifecycle. MCP and A2A thus model different responsibilities and lifecycles.
| Question | MCP | A2A |
| --- | --- | --- |
| Counterpart | Capability server | Independent agent system |
| Discoverable description | Tools and context sources | Agent Card with skills and interfaces |
| Typical work | Select and call a tool | Delegate a goal or subtask |
| Longer-running state | Modeled by the application | Task lifecycle is a protocol concept |
| Result | Tool result or resource | Message or one or more Artifacts |
| Internal implementation | Capability with a defined schema | Remote agent stays independent internally |
On top of that comes a web UI as an access path for people. These access paths have different jobs, and a system can offer several of them without that turning into several domain models.
For example, a system can offer limited analysis and change jobs via A2A 1.0, while REST, MCP, A2A and the web UI read the same structured task and result record.
## When A2A makes sense
A2A pays off when several conditions apply at the same time: the agents involved are developed or operated independently. The work may take longer than a single request, needs follow-up questions or produces several results. The client defines the goal and the permitted effect; the remote agent is responsible for the internal execution.
For a known sequence of fixed steps, a deterministic workflow is usually simpler. Merely different role names, several language models or separate prompts don’t yet justify a distributed agent architecture – they only create an additional network boundary without an additional boundary of responsibility.
The decision can be anchored in who carries the responsibility for the open task. If it stays in your own application and only needs tools or context, MCP may be enough. If an independent system takes over a limited job with its own Task lifecycle, A2A is the right contract. If you keep these levels apart, you don’t build unnecessary agents – and you recognize the features of the delegation described here: an Agent Card, an authenticated call, a traceable Task and a limited job.
## Further reading
- [A2A Protocol Specification 1.0](https://a2a-protocol.org/latest/specification/)
- [A2A: Core Concepts](https://a2a-protocol.org/latest/topics/key-concepts/)
- [A2A: Life of a Task](https://a2a-protocol.org/latest/topics/life-of-a-task/)
- [A2A and MCP compared](https://a2a-protocol.org/latest/topics/a2a-and-mcp/)
- [Model Context Protocol: Architecture](https://modelcontextprotocol.io/docs/learn/architecture)
- [MCP, HTTP, Webhooks and A2A Explained Simply](https://www.mikebild.dev/en/blog/mcp-http-webhooks-and-a2a-explained-simply/)
---
# Hourly Is Not Real Time
URL: https://www.mikebild.dev/en/blog/hourly-is-not-real-time/
Date: 2026-07-20
An hourly report doesn’t ask about the current state but about the hour that just closed. Whatever happens at 14:00:00 UTC already belongs to the next time window. So the run only starts once the time window is closed, and it publishes its state a few minutes later. For an alert, that would be far too late. For a reliable summary, it’s exactly the delay you want.
This timing decision separates the hourly report from ongoing operational monitoring. A closed report answers a different question than monitoring: it records a bounded period as a verifiable state of the observations, while monitoring has to react to new signals. The difference isn’t primarily in Prometheus, Grafana or Markdown. It lies in how quickly a new value has to trigger a reaction and whether the statement in question may still change later.
The article [“Markdown Reports Instead of Dashboard Mandates”](https://www.mikebild.dev/en/blog/markdown-reports-instead-of-dashboards/) already describes the difference between a fleeting view and a verifiable state. This one is more narrowly about the timing mechanics of a regular product report: closed time windows, late data, retries and the boundary to real operational monitoring.
## Two time axes, two jobs
Monitoring works as close to the event as possible. An error rate rises, an alert is evaluated, someone opens logs and traces. New data keeps changing the display. A report, on the other hand, waits until its period has ended. It can then determine which sources were complete, hash its facts and deliver the same state again later.
```mermaid
flowchart LR
E["Event"] --> M["Live metric seconds to minutes"]
M --> A["Alert or investigation"]
E --> W["Closed hourly window"]
W --> R["Immutable report"]
R --> V["Comparison and context"]
```
Both paths may see the same event and still arrive at different results. Monitoring can react at 13:42 to five errors in two minutes. Later, the hourly report records that in the time window from 13:00 to 14:00, five errors occurred across 1,200 executions, which sources were covered and whether the cluster stands out compared with earlier time windows.
A continuously updated UI for the second job would show incomplete intermediate states. While the time window is running, counters are incomplete. A value of zero at 13:01 says almost nothing about the hour. A growing bar invites you to compare unmarked intermediate states with closed hours. Without accounting for the different coverage, that comparison doesn’t hold up.
## The boundaries of the time window
Collection uses half-open UTC intervals. Start included, end excluded. This notation prevents an event at the boundary from ending up in two reports.
```ts
type ClosedWindow = {
from: string; // inclusive RFC 3339 timestamp
to: string; // exclusive RFC 3339 timestamp
bucket: "hour";
};
const window: ClosedWindow = {
from: "2026-07-18T13:00:00.000Z",
to: "2026-07-18T14:00:00.000Z",
bucket: "hour"
};
```
UTC avoids an unpleasant special case: in Europe, the day of the daylight saving time switch doesn’t always have 24 local hours. Storage and collection therefore stay in UTC. The report page can localize a date for its readers later without changing the domain boundary.
Between the end of the time window and the freshness check, this process provides an explicitly defined buffer. If collection grows more extensive, start time, timeout and check boundary have to be adjusted together. A secretly extended buffer would only make real delays visible later.
## Keeping late data and missing runs apart
An HTTP call can fail temporarily. A workflow can abort after writing the artifact but before updating its status. A release can succeed even though the response never reaches the client. That’s why a retry must not simply mean “everything again.”
Each run has a unique time window. Cadence-tagged reports are treated here as immutable publications: once an hourly state is published, it doesn’t change anymore. A repeated successful attempt must therefore not make a second, different hourly report visible for the same time window.
Only after the intended buffer does the distinction between late and missing apply. A late run can still complete successfully and publish the same report. A missing run leaves a gap in the expected sequence of hours. Lateness, measurement gap and closed time window thus remain three separate facts that the report should name separately.
## What follows from a missing observation
A critical case for an hourly report is an hour without data. An observation service should explicitly distinguish four states for this: a source has never been observed, it was checked and the expected content isn’t there, it is access-protected, or it is actually broken. A missing observation must be reported neither as a healthy state nor as the numeric value zero.
For an hourly report, this means: if there’s no measurement for an hour, there’s no value for that hour. The report then must not claim there were zero events, because that statement would imply a measurement that never took place. Instead, it has to show that the source wasn’t observed in the period in question and the statement remains open. If, on the other hand, the source was checked and the expected content wasn’t found, that state is observed; but that doesn’t automatically mean a general error counter of zero.
## When you would miss Prometheus and Grafana
Tools like Prometheus and Grafana support, among other things, ongoing investigation: you can adjust a query during the analysis and shift the time range. This way of working is valuable when the question wasn’t fixed in advance.
A UI for hourly reports, on the other hand, can be geared toward closed report periods. That focus fits as long as the UI is meant to explain closed periods. For an incident analysis, though, warnings would come too late, and hourly resolution isn’t enough to trace a cause down to individual requests. An hourly report replaces neither alerting nor ongoing operational monitoring; it assumes both as separate jobs.
## Four questions before choosing a tool
“Dashboard or report?” is too coarse. Four questions separate the requirements: reaction time, mutability, investigation and resolution.
The first concerns reaction time. If someone has to act within seconds or a few minutes, the observation belongs in a monitoring and alerting system. If a team can check the state in the next regular work cycle, an hourly or daily report may be enough.
The second concerns mutability. If the same URL should show new values tomorrow, a live query fits. If exactly the state from July 18 still has to be readable later, you need an immutable artifact or an explicitly stored snapshot.
The third concerns investigation. If the questions are known in advance – number of releases, errors, source coverage – a limited schema can represent them precisely. If the questions only arise when you look at an anomaly, a query language, variable time ranges and drill-down become important.
The fourth concerns resolution. An hourly counter can show that something failed more often. It can’t explain which individual request was slow or which log line belongs to a trace. For that investigation, the high-resolution data has to stay in its operational tool.
```yaml
decision:
reaction_time: next_work_cycle
immutable_history: required
questions_known_in_advance: true
per_request_drilldown: false
result: scheduled_report
```
As soon as one answer flips, the right tool can change too. A report and a live system may observe the same service, as long as they don’t pretend to do the same job.
## The scheduler is part of the statement
A manually generated report only proves that someone pressed a button at some point. A scheduled run additionally makes visible whether the expected regularity was kept. A check of this regularity therefore has to distinguish between scheduled and manually triggered runs: manual runs must not cover up a missed scheduled hour, otherwise the check counts successes that say nothing about the promise of regularity.
A pause isn’t an error either, if it was explicitly set during a release. But it has to be visible and deliberately lifted after the rollout. A forgotten pause switch isn’t a data problem but a broken promise about regularity.
## What an hourly report has to explain
Without stated source coverage, an operator can read a measurement gap as a result. An hourly report therefore has to explain for itself what it’s based on. Overview, question, conclusion and next action can be derived from the same semantic report document; a second, separately maintained dashboard dataset isn’t needed for that. A suitable UI shows this answer in decreasing order of importance: first state and exception, then a few signals, then evidence and provenance.
A page with thirty metrics and no question is harder to check than a page with one clear question, one supported state and one named next decision. For this, the fact definition also has to represent data gaps: it should name available, missing and stale sources separately, so that an open statement doesn’t look like an answered one.
```md
## Data quality
The source window is complete for four product APIs.
External acquisition data is not connected yet and is shown as unavailable.
No value is inferred from missing input.
```
Aggregation needs an explanation too. A weekly median runtime answers a different question than the maximum of the slowest hour. The report names the period, the expected and available sub-windows and the aggregation used. Otherwise, a precise number looks more verified than it is.
## Rolling up over larger periods
Daily, weekly, monthly and yearly reports are built from already closed artifacts. A daily report can build on the immutable hourly states instead of querying the same sources again for each hour, and in doing so show which hourly windows it’s missing. Cadence-tagged reports remain immutable publications; a rollup doesn’t replace an hourly state, it condenses it.
```mermaid
flowchart TD
H["24 hourly artifacts"] --> D["Daily report"]
D --> W["Weekly report"]
W --> M["Monthly report"]
M --> Y["Yearly report"]
H --> Q["Coverage and missing windows"]
Q --> D
```
A daily report that’s missing individual hourly windows can still be more helpful than no report at all – but only if it clearly marks itself as incomplete. It must not radiate the same visual certainty as a fully covered period. Data quality belongs next to the metrics, not in a footnote.
A UI can place the latest closed period ahead of further decision horizons and a limited history. Which question each coarser report answers is a design decision. An obvious split: the hour checks the data flow and fresh technical signals. The day answers what needs attention today. The week compares daily patterns and recurring exceptions. The month puts activity patterns, operational risks and measurement gaps in context for the next round of planning. The year condenses only the evidence that can support a strategic decision. Just widening the date filter would be formally correct and weak in substance.
Numbers aren’t just values here either. A fact definition should distinguish counters, stocks, durations, ratios and data volumes, name the unit and specify whether a rollup prefers the sum, the last value or the mean. A machine then doesn’t have to guess from a metric name how the value should be read across several intervals.
## Simple technology needs a clear boundary
The hourly approach can get by without an additional, permanently running analytics platform if existing systems take over collection, scheduling and publishing. Its questions are fixed before the run, and its result appears as an immutable publication. What matters is the boundary of responsibility: the report collects, closes and publishes; ongoing observation stays with the systems built for it.
This simplicity only survives if the system stands by its job. A report may show a missing data source instead of secretly building in new data collection. It may point to an external incident view instead of becoming the control room itself. And it may leave a question unanswered if there’s neither a fact nor a connector for it.
Hourly here doesn’t mean “almost live.” It means: regular, closed, repeatable and slow enough to verify a complete state. If you have to react faster, you need monitoring and alerting. If you want to trace later what was known in a clear period, you need an hourly report. Both exist side by side, with clearly assigned jobs: monitoring delivers ongoing signals, alerting triggers a reaction from them, and the hourly report preserves the closed, verifiable state of observation.
## Further reading
- [Prometheus Overview](https://prometheus.io/docs/introduction/overview/)
- [Grafana Dashboards](https://grafana.com/docs/grafana/latest/visualizations/dashboards/)
- [W3C Trace Context](https://www.w3.org/TR/trace-context/)
---
# Claims: Small, Sourced, Verifiable
URL: https://www.mikebild.dev/en/blog/claims-small-sourced-verifiable/
Date: 2026-07-20
“Our publishing is secure, fast and reliable.” The sentence sounds good and is hardly usable as a claim. It contains three judgments, none of them has a criterion, and a source could at most support parts of it. A reviewer would have to accept or reject the whole sentence, even though they might only be able to confirm a documented rollback mechanism as part of reliability.
A knowledge base should therefore store small statements as `subject / predicate / object`. The page text stays readable for people. Beneath it, claims form the units that can be cited, checked, disputed and retired one by one. Confidence and status answer different questions.
## A claim says exactly one thing
The subject names the thing, the predicate the relationship or property, and the object the concrete value. A good claim can be understood without the rest of the paragraph on the page.
```json
{
"subject": "content-release",
"predicate": "rollback_mechanism",
"object": "switch the active pointer to an immutable revision"
}
```
The form resembles a simple RDF triple, but it doesn’t force you to model the entire domain as a universal graph. Within a space, a controlled vocabulary emerges that fits its questions. `rollback_mechanism` can make sense where releases are compared; in an HR space it would be meaningless.
Claims that are too large combine several verifiable statements. Claims that are too small lose their meaning. `content-release / uses / pointer` would be atomic, but it doesn’t explain what the pointer is used for. The wording should be narrow enough for a contradiction and complete enough for a reader.
```mermaid
flowchart TD
A["Statement from source"] --> Q{"one domain assertion?"}
Q -->|several| S["split into several claims"]
Q -->|one| C{"understandable without the paragraph?"}
C -->|no| E["make the object more precise"]
C -->|yes| V["add quote and status"]
```
## The quote carries the statement
Every claim points to one or more sources via citations. A citation contains a verbatim excerpt and, optionally, a locator. A quote check can make sure the quote appears verbatim in the archived source text. A claim whose evidence is only paraphrased or made up should be discarded before it reaches review.
```json
{
"subject": "content-release",
"predicate": "rollback_mechanism",
"object": "switch the active pointer to an immutable revision",
"confidence": 0.94,
"citations": [
{
"source_id": "source_release_docs",
"quote": "Rollback changes the active release pointer to a previous immutable revision.",
"locator": "Rollback"
}
]
}
```
A quote has to support the statement within its scope. If the source only talks about a preview environment, the claim must not turn that into a general production rule. This check can’t be done with string matching alone. The reviewer reads the context.
Several citations are useful when a statement is supported jointly by a contract and observed behavior. The API documentation can describe the intended mechanism, a production report can document its actual use. Many weak sources, however, don’t automatically make a claim stronger.
## Confidence is not a truth scale
`confidence` describes how sure the generating synthesis was about its mapping. It can help the reviewer look at uncertain proposals first. It is not a substitute for status and not a probability that a statement is true in the world.
```ts
type ClaimStatus = "proposed" | "verified" | "disputed" | "deprecated";
type Claim = {
subject: string;
predicate: string;
object: string;
confidence: number;
status: ClaimStatus;
};
```
A claim with `confidence: 0.99` stays `proposed` until approval. An approved claim with `confidence: 0.78` can be `verified` because a person checked the source and the wording. Later, new evidence can make it `disputed` without reinterpreting the old confidence value.
This separation prevents a convenient shortcut. A threshold like “approve automatically from 0.9” would confuse model self-confidence with domain authority. It makes more sense to turn every knowledge change into a change proposal, regardless of the value in `confidence`. It is only adopted after human approval.
## Status models the lifecycle
`proposed` is staging and invisible to normal readers. `verified` marks an approved statement. `disputed` makes a traceable conflict visible. `deprecated` keeps an outdated statement in the history without treating it as the current state.
The lifecycle allows more precise answers than deletion. If a service used a static retry value up to version 2 and shares a budget since version 3, both statements are historically relevant. The old one isn’t removed from all revisions. It gets a status and stays connected to its source.
```mermaid
stateDiagram-v2
[*] --> proposed
proposed --> verified: human approval
proposed --> [*]: rejection
verified --> disputed: conflicting evidence
disputed --> verified: conflict resolved
verified --> deprecated: superseded
disputed --> deprecated: superseded
```
The transition from `proposed` to `verified` doesn’t happen automatically but only after a human decision. The visible page text can then explain the current state fluently. The claims beneath it preserve which individual statements carry that explanation and which conflicts are still open.
## Functional predicates make conflicts exact
Some relationships may have several objects at the same time. A system can support several export formats. `supports_format=markdown` doesn’t contradict `supports_format=okf`. Other relationships should have only one current value per subject, such as `primary_database`.
A space can declare such functional predicates. If two different objects for the same subject and predicate meet there, the knowledge base can mark both claims as `disputed` and connect them via `contradicts`.
```json
{
"settings": {
"functional_predicates": [
"primary_database",
"current_owner",
"default_retention_days"
]
}
}
```
This rule stays deterministic. A model doesn’t have to decide whether two freely worded paragraphs collide semantically. The controlled predicate states in advance exactly where a single current value is expected.
Too many functional predicates would be harmful. Marking `supports_format` as functional would wrongly put complementary facts in conflict. The vocabulary is therefore a domain decision of the space and belongs in review.
## Breaking a paragraph into claims
A practical example shows the sizing decision. Suppose a source says: “The service runs as a single binary, migrates PostgreSQL on startup, and exposes health and readiness endpoints.” This should not turn into one claim with the object `single binary with migrations and probes`. Three properties change independently of each other.
```json
[
{
"subject": "service-runtime",
"predicate": "distribution",
"object": "single self-contained binary"
},
{
"subject": "service-runtime",
"predicate": "database_migration",
"object": "runs automatically on startup"
},
{
"subject": "service-runtime",
"predicate": "exposes_probe",
"object": "/health and /ready"
}
]
```
If a sidecar is added later, it affects the distribution claim. The migration and the probes can stay unchanged. A reviewer sees exactly the small diff. An agent can keep using the two confirmed statements while the first one is being checked.
The cross-check helps: would a change to the object automatically change the other parts of the statement? If not, several claims are appropriate. If a claim would be misleading without its neighboring sentence, it needs a more precise subject or object.
Time and scope belong in the wording too. `uses PostgreSQL` fits a current architecture if the source describes the whole service. If it only refers to the production deployment, the subject should be `service-production-deployment`. Precision often comes more easily from a narrower subject than from a long object text.
A claim is not a complete sentence for blog prose. It may stay machine-readable and terse. The concept page then explains how the three properties work together.
## A concept is more than its claims
Claims alone don’t make a readable explanation. A concept still has a title, a summary, Markdown and relationships to other concepts. The page can explain an example, limitations and the historical context.
The claims serve a different purpose. They let you:
- trace a single statement back to the original quote;
- mark a contradiction without rejecting the whole page;
- check only the statements that actually changed in a new revision;
- limit search hits and agent answers to visible, approved units.
Page text and the structured layer should be revisioned together. A proposal must not already show new text while its claims are invisible or incomplete for readers. Atomic approval makes the new revision current as a unit.
## Relations connect, claims provide evidence
Besides claims, a knowledge base can know directed relationships between concepts: `related`, `part_of`, `depends_on`, `contradicts` and `supersedes`. A relation answers how two pages are connected. It doesn’t replace a claim or a citation.
```json
{
"from_slug": "content-release",
"kind": "depends_on",
"to_slug": "immutable-revision"
}
```
The relation enables navigation and context. The documented fact stays as a claim on one of the pages. Otherwise a mere link would carry a domain statement without naming its wording or its source.
`contradicts` can arise as a consequence of the functional predicate logic. `supersedes` fits a traceable replacement where the new term or the new rule replaces the old state. Relations themselves are reviewed and published with the concept revision.
## Revisions answer the question of time
A current claim alone doesn’t explain when it was introduced. A concept history should keep approved, rejected and proposed revisions together with their provenance: which model and which prompt version generated the proposal, which sources were used and which person approved it.
This information doesn’t make a model the author in a legal or domain sense. It documents which technical synthesis path generated the proposal. Reviewer, note and timestamp explain the human decision. Approval, status and revision together make visible how a statement entered the valid body of knowledge – and how it can leave it again.
The history allows a time-related question: which statement was visible in March, before the retention rule was changed? A knowledge service that always returns only the current paragraph can’t answer it reliably. Revisions preserve the state at the time without presenting old claims as valid today.
For teams, this trail becomes especially useful after model or prompt changes. If a new synthesis version proposes noticeably different claims, the affected revisions can be identified and checked specifically. That way, besides the source, you can also trace which model and which prompt version generated the proposal.
## A step beyond “Clean Grounding II”
[Clean Grounding II](https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/) sorted grounding into conventions, documents and API descriptions. The central question was which material belongs in the scarce context for a specific task and how expensive it would be to retrieve it again. That was a working model for individual sessions.
What’s added is a smaller, durable unit between document and context: the claim. An agent doesn’t have to treat a whole page as uniformly binding every time. It can read the current concept revision, check visible claims including their status and open their citations when needed. “Matching document into the context” becomes “matching, approved statement with a way back to the source.”
The older article [Fuzzy Matching with Explicit Limits](https://www.mikebild.dev/en/blog/fuzzy-matching-with-explicit-limits/) separated a claim with confidence from a fact. The same caution applies here. Confidence helps sort a proposal. Only evidence, review and status determine how the statement appears in the knowledge base.
## Checking claims in review
For a new proposal, four questions are enough. Does the claim assert exactly one thing? Is it understandable without the surrounding paragraph? Does the quote cover exactly this scope? Would a different new value be recognizable as a clear contradiction?
If an answer is no, the claim gets split, worded more narrowly or rejected. This is not a formal word exercise. Small claims reduce the effort later. A changed retention rule then doesn’t require a complete rewrite of the page about storage. Only the affected statement and its explanation get adjusted.
Only statements that matter for search, review, conflicts or provenance get structured. The point is not to map every sentence as a universal ontology. Everything else stays prose; no claim is created for it.
## Further reading
- [W3C RDF 1.1 Concepts](https://www.w3.org/TR/rdf11-concepts/)
- [W3C PROV-O](https://www.w3.org/TR/prov-o/)
- [Clean Grounding II](https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/)
- [Fuzzy Matching with Explicit Limits](https://www.mikebild.dev/en/blog/fuzzy-matching-with-explicit-limits/)
---
# Products Report Through Their API
URL: https://www.mikebild.dev/en/blog/products-report-through-their-api/
Date: 2026-07-19
A statistics API is a product feature. That sentence sounds obvious, but while working on cross-product reporting, it only became clear after two worse designs. At first, a central collector was supposed to access several PostgreSQL databases directly. After that, special private reporting endpoints and dedicated keys were on the table. Both would have built the report deeper into the products than its purpose requires.
What remained was a smaller contract. A publishing system, a knowledge base and an orchestrator aggregate their own data themselves and offer their view through normal, authenticated HTTP endpoints. A downstream process combines the aggregates for explicitly bounded time windows – it sees neither tables nor Markdown, names, keys or internal IDs.
This split is not a special trick for dashboards. Every authorized consumer can use the same statistics resources: a capacity report, a quality check, a local analysis or a later export tool.
## Data ownership is more than storage location
Whoever owns a table knows its meaning. A publishing system knows when a revision was created and when a release was actually activated. A knowledge base distinguishes a started ingest from a verified state of knowledge. An orchestrator aggregates its execution data where the runs actually take place. A central collector would have to rebuild these meanings and keep up with every product change.
Direct SQL makes this rebuilding particularly easy – and therefore dangerous. A query works even though it may count an intermediate status that the product itself would never show as complete. A new migration can break the report without the public product API having changed. Database access also bypasses the normal permission check and pulls the credentials of several systems into one place.
With a product API, the domain aggregation lives where the state change is implemented:
:::process{title="Domain aggregation stays in the product" role="primary" preferredPattern="connected-process"}
1. Product action · creates a domain-defined state transition
2. Own data store · keeps the product’s authoritative domain state
3. Aggregation · translates internal states into bounded domain metrics
4. Statistics API · delivers authenticated values with time range and meaning
5. Collector · combines compatible responses without redefining them
6. Report · explains the frozen shared state
:::
The collector may combine the responses, but it may not reinterpret what a successful release or a verified claim is. These terms belong to the product.
## Time is uniform, the domain is not
A shared contract doesn’t mean that all products deliver the same metrics. That would be artificial leveling. The only shared properties are the ones a collector needs for reliable time windows:
- `bucket` determines the resolution: hour, day, month or year.
- `from` is the inclusive start of the window.
- `to` is the exclusive end.
- `tz` makes the time zone explicit, UTC throughout here.
- `buckets` contains a dense series, including empty intervals.
- `totals` summarizes exactly the requested window.
The payload keeps its domain names. A publishing system can, for example, provide site-scoped aggregates for releases, content and reader access, a knowledge base space-scoped aggregates for usage, coverage and reviews, an orchestrator tenant-scoped runtime statistics for executions and connectors. No product has to adopt another product’s terms; all of them have to fulfill the same time contract.
```json
{
"bucket": "hour",
"tz": "UTC",
"from": "2026-07-18T10:00:00.000Z",
"to": "2026-07-18T12:00:00.000Z",
"buckets": [
{ "ts": "2026-07-18T10:00:00.000Z", "items_created": 2 },
{ "ts": "2026-07-18T11:00:00.000Z", "items_created": 0 }
],
"totals": { "items_created": 2 }
}
```
The half-open notation `[from,to)` prevents double counting. The window from 10 to 11 o’clock contains an event at 10:59:59, but none at 11:00:00. The next window starts exactly there. A retry queries the same time window again and gets the same meaning.
## Measured zero, missing observation, incomplete window
A dense time series also contains empty buckets. That is practical, because the collector doesn’t have to guess or fill in missing hours. A zero is a measured value: the product evaluated the window and found no matching event.
Two other states have to be distinguished from this. Missing means that there is no observation for the metric – for example, because a source isn’t connected or a ratio cannot be calculated without a base. In the reporting process described here, the downstream report also determines incompleteness: an expected snapshot is missing, or the window had not yet closed at the time of collection. These three cases must not look the same in the report, because they carry different consequences: zero technical errors are reassuring, zero page views can be correct, a missing analytics connection is an open connection and not a measurement.
A product can make the distinction between measured and missing part of the response and label values, for example, with `value_state` and `value_kind`. A ratio without observations carries the state `missing` and is not output as a measured zero:
```json
{
"metric": "engagement_rate",
"value_kind": "ratio",
"value_state": "missing"
}
```
For someone reading a report, this state matters more than another decimal place. Time window, data state and the meaning of a measurement therefore belong in the contract itself – not in a footnote on the report page.
## Privacy starts with the shape of the response
Aggregates should leave out information the purpose doesn’t need. A statistic can count successful, failed and rate-limited reader requests without storing user names, IP addresses, session IDs, Markdown content, URLs, job IDs or credentials in the statistics table. A knowledge base doesn’t have to output source texts through its statistics resources.
Such a negative list belongs in the documentation and in contract tests. “We currently don’t return any names” is weaker than a schema that has no field for names at all. The collector then cannot accidentally carry a sensitive value over into a JSON artifact or a report page.
Trace data also stays limited to its purpose. W3C Trace Context standardizes `traceparent` and `tracestate` so that a call can be correlated across several services. The W3C recommendation explicitly warns against transporting personal or other sensitive information in these headers. A trace ID connects technical steps; it doesn’t describe a person.
```http
GET /v1/sites/example/stats/releases?bucket=hour&from=2026-07-18T10:00:00Z&to=2026-07-18T11:00:00Z
Authorization: Bearer
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
```
## Zero-config means using existing terms
Telemetry is rarely completely configuration-free. A service needs at least durable storage and information about whether it runs in development, test or production. “Zero-config” is meant more narrowly here: for the reporting process, no special mode is activated in the product, no special key is created and no report target is entered.
The statistics endpoints can use existing product boundaries: a publishing system, for example, the site and a normal read key, a knowledge base the space and its read scope, an orchestrator the tenant.
OpenTelemetry provides a usable shared vocabulary for this. `service.name` names the logical service, `deployment.environment.name` distinguishes `development`, `staging`, `production` and `test`; as of August 2026, the older key `deployment.environment` is marked as deprecated in the OpenTelemetry conventions. Standardized fields like these prevent one service from treating `prod`, another `live` and a third `production-eu` as the same concept. The product sets these values once for its runtime; the reporting collector doesn’t have to repair labels.
The shared name alone is not enough, though. If an aggregator reads different field names than an older write path still delivers, successful calls can show up as errors. Such a transition can be made compatible in both directions: the reader understands old and new fields, the writer delivers both for the time being, and tests use real audit rows instead of hand-built ideal objects.
## Bounded queries instead of hidden load
A general statistics API needs hard limits, such as a maximum window length per resolution. Invalid or oversized windows return `422` instead of burdening the product database with an unexpected full evaluation.
These limits belong to the product contract, because only the product knows its costs. A collector should not try to get around them with many overlapping queries. For a long period, it uses the coarser resolution or works in distinct, non-overlapping pages.
The same applies to retention. Anonymous raw events can have their own retention period in the product. A report artifact can live longer if its aggregated content is meant for that. Raw event, product aggregate and published report have different lifecycles; they don’t have to end up in one store.
## Existing keys instead of a back door
A dedicated “reporting key” seems tidy at first, but it creates a second security logic. What may this key read? Does it apply to a site, a space or the whole product? Who rotates it? As soon as every product gives a different answer, the supposedly simple collector becomes a special case with far-reaching permissions.
The statistics APIs should therefore use existing scopes. A read-only key for a site may then read exactly the statistics of the site it was issued for. A read key for the knowledge base stays limited to its space. Without a matching key, each of these endpoints stays closed.
So the same rule applies to the collector as to other API users: a separate key per product, as narrow as possible; secrets only in the credential store; no keys in the workflow definition, JSON artifact, log or report. The workflow only knows a `credential_ref`; the actual value is inserted at the HTTP call and appears neither in the stored process nor in its result. This separation can be tested: a call without a key must return `401`, a key without a matching scope `403`, a correct key `200`.
## PostgreSQL is internal, not forbidden
Rejecting direct database queries doesn’t mean that aggregates have to live outside the product database. For a publishing system or a knowledge base, PostgreSQL may be exactly the right place. Events and domain state can be recorded transactionally there, scoped by site or space and evolved with the same migrations as the rest of the product.
What matters is the direction of the dependency. The product may know its own database. An outside collector must not need to know it. Whether a response comes from a precomputed table, a bounded SQL aggregation or a cache remains an internal decision. What counts is that each product can design its internal storage according to its own operating model and, toward the outside, fulfills the same reliable time contract.
## Documentation is part of the contract
A new endpoint is only done when OpenAPI, `llms.txt`, `llms-full.txt`, the README and the detailed product documentation tell the same story. Otherwise, a person finds a scope in the README, a client generates from an older OpenAPI file and an agent reads a third variant.
That is why the repositories check their generated documents for drift. Contract tests send valid, invalid, oversized and unauthorized windows to the handlers. Integration tests use the real product storage. A binary test makes sure that the shipped file contains the same routes and the same version number as the source. These checks prevent the collector from depending on an outdated or internally known-only response shape.
## APIs make exchange possible
The immediate effect of this separation shows up in testing. Every product API can be checked against its own schema with a fixed window. The collector gets fixtures without database access. A product release can be rolled back independently at the API level, as long as the published contract is preserved.
A new consumer doesn’t need a new table in the product. Another reporting tool can call the same API just as well. A product may change its internal storage without the statistics resource having to be reinvented.
That also keeps the products understandable. Each product keeps its role – as a publishing system, knowledge base or orchestrator. Their statistics resources describe their own work as bounded aggregates with domain names. Everything else happens outside their boundaries. As long as the published contract is preserved, one part can be replaced without adjusting the others.
## What has changed since then
The post [HTTP APIs: Small, Stable, Readable](https://www.mikebild.dev/en/blog/http-apis-small-stable-readable/) described an endpoint in 2014 as a long-term promise to unknown clients. Small resources, unambiguous timestamps, stable meanings and readable errors were meant to prevent every client from building its own defensive layer. These requirements still apply.
What’s new is the view of internal product statistics. A statistics path is not built for a specific dashboard but as a bounded projection of the product’s own data. It uses existing keys and scopes, delivers time boundaries and data state along with the values and publishes only aggregates. This keeps the API small, regardless of whether a person, a workflow or an agent calls it.
## Further reading
- [W3C Trace Context](https://www.w3.org/TR/trace-context/)
- [OpenTelemetry Service Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/resource/service/)
- [OpenTelemetry Deployment Attributes](https://opentelemetry.io/docs/specs/semconv/registry/attributes/deployment/)
- [HTTP APIs: Small, Stable, Readable](https://www.mikebild.dev/en/blog/http-apis-small-stable-readable/)
---
# From Org Chart to Product Ownership
URL: https://www.mikebild.dev/en/blog/from-org-chart-to-product-ownership/
Date: 2026-07-18
An AI assistant produces a draft – and afterwards the work item waits for approval, review and release just as before. Who carries it from the observed customer problem to measurable impact? No draft generation, however fast, answers this question. AI can make the flow of work from the first customer signal through plan and implementation to review and impact more continuous – if responsibility for problem, decision, review and impact is brought together in one place.
AI doesn’t remove organizational boundaries automatically. It lowers the cost of getting up to speed on the next step. Whether this results in one connected piece of work or merely a faster feed into the same waiting points is decided by the organization, not by the model.
## The flow of work from customer problem to impact
By flow of work I mean a concrete chain here: a customer signal is observed, it leads to a hypothesis, the hypothesis to a plan, the plan to an implementation, the implementation to a review with domain acceptance, then a release and finally an observable impact that flows back as a signal into the next cycle.
```mermaid
flowchart LR
S[Customer signal] --> H[Hypothesis and plan]
H --> E[Design and implementation]
E --> Q[Review and acceptance]
Q --> R[Release]
R --> W[Observe impact]
W --> S
A[AI: context, variants, tests and documentation] --> H
A --> E
A --> Q
```
The starting hypothesis is that in organizations built on division of labor, this chain is rarely continuous: one ticket describes the wish, another person decides on the design, a third builds the interface, a fourth checks the release. Each role can do its job very well while the result for the customer still remains incomplete. If you only see a small slice, you can hardly judge whether a new feature solves the customer problem or merely makes a subprocess tidier.
What AI mainly changes about this chain is one cost factor: getting up to speed on the next step. An assistant can explain an unfamiliar service, gather existing decisions, sketch a data flow and suggest suitable tests. It doesn’t replace domain knowledge in the process. It lowers the barrier to bringing in domain knowledge from other parts of the organization in time – before a decision is made, not after a finished solution has been delivered.
## Handoffs don’t get shorter automatically
My thesis is: AI can shorten handoffs if responsibility for problem, decision, review and impact is brought together. This is a hypothesis about organization, not a proven law. If responsibility stays as distributed as before, AI merely speeds up the production of intermediate results that still wait for the same approvals.
The [post on faster development and unchanged processes](https://www.mikebild.dev/en/blog/ai-in-the-enterprise-faster-development-different-processes/) describes this downside: if an organization just fills the same old process faster, the bottleneck moves. More drafts wait for the same reviewers, and more documents contradict each other. The gain only comes when the freed-up time flows into understanding the whole piece of work.
Bringing responsibility together doesn’t mean that one person has to be product manager, designer, security expert and operations lead at the same time. It means that a clearly bounded slice of the product is followed through by the same place: from the observed problem through a hypothesis and a change to feedback from usage. Specialist disciplines remain indispensable. The difference lies in the timing: specialists are brought in earlier and more deliberately instead of receiving a finished solution at the end of a long chain.
The org chart doesn’t disappear because of this. People need clear responsibilities, development prospects and decisions that don’t get lost between teams. But the continuous flow of work can become more important than the boundaries between the boxes – where responsibility actually has been brought together.
## Vertical slices as a testable hypothesis
Vertical work packages make this thesis testable. Instead of breaking a change down by technical layers – first the data model, then the API, then the UI – a small, usable slice is carried through all layers. Such a slice has a clear purpose, a visible impact and a manageable number of open decisions.
This way of working made sense even without generative AI. One possible obstacle was the effort of getting into unfamiliar parts of the system: a developer knew the frontend, say, but not the rules in the backend. The product team knew the impact for users, not the consequences for operations or the data model. So work packages were cut along responsibilities and then pieced back together over many meetings.
```mermaid
flowchart TD
P[Product problem] --> V[Vertical slice]
V --> U[UI]
V --> F[Domain logic]
V --> D[Data and contracts]
V --> B[Operations and observation]
U --> X[One verifiable result]
F --> X
D --> X
B --> X
K[AI: make dependencies and suggestions visible] --> V
```
Smaller vertical slices are a testable organizational hypothesis, not a blanket statement about every team. The hypothesis is that a team with AI support can explore more of this context on its own – which services are affected, which contracts change, which test cases are missing, which documentation needs to be updated. Whether the observations in a concrete context support this hypothesis can be checked using waiting time, number of handoffs, rework and time to user feedback. The values are collected with identical definitions before and after a limited pilot; other process changes have to be recorded, because such a comparison doesn’t prove a clear cause. If the measurement turns out differently than expected, the hypothesis is not confirmed for this context for now – the team hasn’t failed.
A vertical slice must not become a pretext for offloading every specialist discipline onto a few people. Where security, regulation or deep domain knowledge are needed, collaboration remains mandatory. The slice changes the order of involvement, not its necessity.
## Technology becomes an option again
Many technology choices arise from what a team happens to know. That’s understandable: an unfamiliar platform demands research, small experiments and the worry of being left alone with it later. That’s why requirements are sometimes adapted to the existing tools, even though a different path might fit better.
AI changes this calculation. It can search documentation, explain examples from a repository, compare variants and prepare a small prototype. That alone doesn’t turn an unfamiliar technology into a good decision. But it becomes cheaper to make the decision based on a real experiment instead of habit.
A useful investigation keeps several possibilities open:
- What is the smallest change with which we learn something about the customer problem?
- Which existing systems, data and contracts do we really need to understand?
- Which assumption does the AI make, and how can it be checked?
- What impact do we expect after the release, and how would we notice the opposite?
The answers don’t always have to be documented like an architecture decision. For a small change, a clean pull request with tests and a short rationale is often enough. What matters is that the AI doesn’t just produce more options but helps evaluate options faster and discard bad ideas earlier.
## Creating gets cheaper, review and acceptance become more important
The most visible result of AI is often a draft: code, a test, a summary, an API description, a release note. The draft can be surprisingly good. But it can also carry a false premise forward with great conviction. The cheaper creating becomes, the more the value of review and domain acceptance grows.
Review here means more than the pull request. It includes the domain check of a requirement, the look at contradictions in existing knowledge, the test under realistic conditions and the question of whether the release improves the product. Quality assurance is therefore not a last gate before rollout. It accompanies the entire slice.
```yaml
review_focus:
product_question: "Does this solve the observed customer problem?"
domain_question: "Which business rule could make this wrong?"
technical_question: "Which contract or dependency can break?"
quality_signal: "What evidence would change our decision?"
release_check: "Can we observe the result and recover safely?"
```
This example is not a new checklist for every little thing. It shows the shift: with AI-assisted drafts, the bottleneck can move from generation to review. What then becomes more important is deciding quickly and reliably what to keep, change or discard from a draft.
The NBER study “Generative AI at Work” provides a limited empirical hint on this. Among more than 5,000 customer support agents, an AI assistant increased the number of cases resolved per hour by 14 percent on average, with less experienced workers benefiting in particular. I read this finding about the less experienced workers as a hint that AI can spread proven practices – that is my interpretation, not a direct finding of the study. In any case, the study is not evidence of the same effect in every task, let alone in product development. What remains for product work is mainly this: the first draft becomes more accessible. That doesn’t devalue experience. Experience becomes more visible where it counts – in choosing a direction, in recognizing an atypical case and in judging quality.
## Anchoring responsibility technically
If this thesis is meant seriously – responsibility for problem, decision, review and impact brought together – then it also has to be reflected in the systems through which work flows. Otherwise it remains a good intention. Two examples show what such anchoring can look like.
A request control layer can route HTTP, MCP, A2A, webhooks and chat into the same planning path and bind execution to explicit task authority, budgets, contracts, evidence and review. That is the technical form of this bundling of responsibility: no matter which channel a request arrives through, it goes through the same planning, and execution is bound to explicit authority.
A workflow engine can model recurring work across several systems as an approved, logged workflow and hold back steps with external effects until confirmation. Here too, the design separates preparation and execution from the confirmed external effect: a piece of work may be prepared, checked and repeated, but the step that has an external effect waits for acceptance.
Transferring this to the organization is a hypothesis, not a guarantee. If knowledge can be found, if releases are prepared so that a team can follow a change in a controlled way all the way to its impact, and if product and service information comes from the same verified sources instead of aging in separate copies – then one piece of work can close more gaps at once: a product change delivers test cases, operational information and a draft of the customer documentation at the same time. Recurring support questions show early which product rule or explanation is missing. Errors and follow-up questions flow back into rules, tests and later work packages. Whether these conditions are met, every organization has to check against its own flow of work.
## One complete slice as a test
The change doesn’t start with a new org chart. It starts with a real, limited product problem. A team takes a piece of work that has several handoffs today and carries it through completely once: understand the customer question, check the assumption, build the change, assess quality, release and look at the impact.
```yaml
vertical_slice:
customer_problem: "Describe the observed problem"
smallest_change: "Deliver one useful outcome"
ai_support:
- "Find relevant context"
- "Prepare tests and documentation"
human_review:
- "Validate domain assumptions"
- "Accept quality and release risk"
outcome_signal: "Measure customer use and failures"
```
After that, the discussion about roles and structure becomes more concrete. Perhaps it turns out that a team can own an interface itself. Possibly a shared source of knowledge is missing. Or a specialist remains a permanent part of the process. What matters is that the organization learns from observed work and not from an abstract restructuring plan – and that it discards the hypothesis where the measurement speaks against it.
AI doesn’t make end-to-end product development easy. It makes it possible more often where responsibility, review and impact belong together and aren’t spread across many stations. Research, drafting, tests, documentation and release preparation move closer together. The org chart stays. But the decision every organization can make now is concrete: take ownership of one selected, limited flow of work end to end once, and measure by its impact whether the hypothesis holds.
## Further reading
- [NBER: Generative AI at Work](https://www.nber.org/papers/w31161)
- [AI in the Enterprise: Faster Development Needs Different Processes](https://www.mikebild.dev/en/blog/ai-in-the-enterprise-faster-development-different-processes/)
---
# llms.txt: Docs for Machines
URL: https://www.mikebild.dev/en/blog/llms-txt-docs-for-machines/
Date: 2026-07-15
`llms.txt` sits in the root directory of a website, which makes it look like the next signal for search engines – a neighbor of `robots.txt` and `sitemap.xml`, created in the hope of visibility. Exactly this conclusion misses the point. The file was never meant as a ranking signal, and there is no evidence of any ranking effect. Its value doesn’t lie in crawler signals but in providing agents with curated documentation context.
There are two files, `llms.txt` and `llms-full.txt`. They look like marketing infrastructure, and their value lies somewhere else: in the question of how a model gets clean, curated context without first working its way through navigation bars, cookie banners and JavaScript. Both files are machine-readable self-documentation of a product.
## Two files, one problem
Jeremy Howard, co-founder of Answer.AI, published the proposal on September 3, 2024; the description is at `llmstxt.org`. The starting point is a sober observation: models increasingly rely on web content, but their context window is too small to take in an entire website in one go. And turning raw HTML into usable text is tedious and imprecise – between the actual content there is a lot of clutter that only eats up space.
The answer consists of two building blocks that you should keep clearly apart.
`llms.txt` sits in the root directory of a site and is a curated index in Markdown. The format is deliberately narrow: an H1 heading with the project name, below it a blockquote with a short summary, optionally a few sentences of context, then H2 sections with lists of links. Each link carries a brief description. A separate `## Optional` section marks what a model may drop first when space is tight. This is how compact it looks:
```markdown
# Orderflow API
> Orderflow is a REST API for creating, tracking, and refunding orders.
> These docs are written for LLMs and coding agents.
Every write endpoint accepts an `Idempotency-Key` header, so retries stay safe.
## Core Documentation
- [Quick Start](https://docs.example.com/quickstart.md): Authenticate and create your first order
- [API Reference](https://docs.example.com/api.md): Endpoints, parameters, and error codes
- [Webhooks](https://docs.example.com/webhooks.md): Event types and signature verification
## Optional
- [Changelog](https://docs.example.com/changelog.md): Version history and breaking changes
```
`llms-full.txt` is the second building block and conceptually simpler: the full text of the important pages, concatenated into a single Markdown file. No longer an index, but the whole content in one piece, without HTML noise. An agent or client can load the bundled content with a single request instead of working its way through page by page – whether all of it fits the specific task is another question.
In addition, Howard suggests also providing individual pages as a clean Markdown version at the same address with `.md` appended – `.../api` becomes `.../api.md`. That’s the glue between index and content: the index points to pages that already exist in the form a model processes best anyway.
The distinction matters, because a lot gets mixed up here. `robots.txt` governs what a crawler may touch. `sitemap.xml` helps with indexing. `llms.txt` does neither: the file puts things in context and curates them, intended for the moment of inference, not for the crawl. An agent that reads it gets an editorial statement about what matters in a product – not a promise to a search engine. The three files don’t exclude each other; they answer different questions.
```mermaid
flowchart TD
A[Coding agent] -->|knows llms.txt| B[llms.txt curated index]
B --> C{Which page do I need?}
C -->|targeted| D[page.md clean Markdown version]
C -->|everything at once| E[llms-full.txt entire content]
A -.->|alternative without llms.txt| F[Crawl the HTML page navigation, ads, JS]
F -.->|lots of noise| G[Context window full, content diluted]
```
## Why this helps
When integrating a third-party library, an agent without a Markdown view often loads the complete HTML page or improvises missing signatures. In the first case, it pulls in the menu, the footer and three code examples it doesn’t need at all – a noticeable part of the window is gone before the actual task begins. In the second case, it guesses. In a code review, I noticed that an agent had simply made up an API signature, plausible and wrong, because fetching the exact reference was too expensive for it. Both are symptoms of the same problem: too much noise per token, too little reliable substance.
`llms.txt` addresses exactly this. Curated Markdown without layout ballast means more of the window is left for the actual content. The index also forces a decision: not every page is equally important, and someone with domain knowledge has to name which thirty to a hundred pages make up the core. And when the model needs the exact error message or the exact parameter, it fetches the matching `.md` page instead of improvising.
The point about curation is often overlooked. A good `llms.txt` isn’t an arbitrary list of links but an editorial statement about what matters in a product. This decision is the actual work – not the file itself.
## Where it pays off
For a blog or a marketing site, `llms.txt` brings little: there is no evidence of a ranking effect, and if you create the file hoping for better visibility, you’ll be disappointed. Anyone who promises such an effect promises too much.
The exception is narrow but real: technical documentation and coding agents. An API reference, a component library, an SDK – content that is maintained in Markdown anyway and that an agent in the IDE looks up in a targeted way.
For pure marketing pages without demonstrable agent usage, the maintenance effort usually doesn’t justify the file; for regularly queried technical documentation, it can pay off. Server logs with requests to `/llms.txt` give you a hint of usage, but they don’t carry the decision on their own: a lack of direct requests doesn’t necessarily prove a lack of usage, for example when the same content is retrieved through other paths such as MCP resources.
## Generated from the source, not maintained by hand
A central risk when using these files is organizational, not technical: two versions of the same content that are maintained separately. The page for humans here, the Markdown version for models there. If `llms-full.txt` lags behind the real docs, you feed models outdated content – and that’s worse than no file at all, because it creates false trust. Without automatic generation from the same source, drift is only a matter of time.
That’s why both files belong in the build, not in the editor. The build can generate `llms.txt`, `llms-full.txt` and Markdown twins per site and locale from the published state. What matters is the shared source for human-readable and machine-readable outputs; a second, hand-maintained documentation would make drift possible again.
That’s the second half of the curation work. A human makes the editorial decision about what belongs in the index. The build takes care of generating the files. If you do both by hand, you have taken on a second set of docs that easily deviates from the published state.
## What an MCP server makes of it
Up to this point, `llms.txt` is a static file that someone picks up at some point. MCP adds targeted access to resources and operations on top of the static index. The Model Context Protocol is the open protocol that Anthropic introduced at the end of 2024, through which an agent talks to external tools and data sources in a standardized way.
As an index, `llms.txt` describes which content exists and where it lives; an MCP server provides resources and operations in a targeted way. With `mcpdoc`, the LangChain team built exactly such a docs server. It receives a list of `llms.txt` addresses and provides the agent with two tools: one that lists the registered sources and one that fetches a specific page from them.
An MCP docs server designed for this can load context in a targeted way, make calls loggable and restrict access – three improvements over simply downloading the file.
First, dosage. Instead of dumping all of `llms-full.txt` into the window, the agent uses the index to request only the one page that fits the task – the range between “no context at all” and “everything at once.”
Second, traceability. With a docs server like `mcpdoc`, fetching runs through tool calls that you can inspect: which address was loaded and what came back. This doesn’t automatically apply to resource reads; there, you need your own logging on the server side. A direct download of the file doesn’t necessarily leave this trail in the agent workflow. For internal or protected documentation, this auditability can justify the additional operational effort.
Third, access control. You can restrict the server to allowed domains, and for internal or protected docs you put authentication in front of it. If you need permission-bound access, you can offer the documentation as a resource through an authenticated MCP server and check permissions there for every read. This way, the convention also works behind the company firewall: the server points to a private `llms.txt`, and models in the team get curated knowledge without the content being openly available on the web.
If both come from one product, it can offer a remote MCP interface alongside the generated files. In such a setup, MCP resources are application-managed context that the server offers the client as documentation. Tools stay separate from this: they represent domain operations and should only become visible with the matching scope. Such a system can additionally provide its own `llms.txt` documentation as an MCP resource, so that a client can read the tool model and API boundaries without guessing a web page. So MCP adds targeted access and operations to the static documentation; this access only becomes permission-bound once the server authenticates and authorizes resource reads. The documentation doesn’t replace MCP – without generated, up-to-date machine views, these documentation resources would lack a reliable foundation.
```mermaid
flowchart LR
H[Agent host Cursor, Claude Code] --> M[MCP docs server e.g. mcpdoc]
M -->|list sources| L[llms.txt registered indexes]
M -->|fetch page| P[only the needed .md page]
P --> H
```
`llms-full.txt` in particular gains from this combination. You can attach the file directly to an MCP server as a knowledge source – without an embedding pipeline, without a vector database. More accurate than “a replacement for RAG” is to describe it as a tool-based, auditable variant of it: not unpredictable retrieval from a large vector index, but traceable access to curated pages.
## Where it falls short
`llms.txt` is a proposal, not an adopted standard. There is no committee behind it and no guarantee that a particular model reads the file. You provide it; you can’t force it to be consumed.
Size is a real limit. An `llms-full.txt` that is several megabytes in size may, depending on tokenization, model and client limits, not fit completely into the available context and then only gets loaded in fragments – and with that, the advantage of “everything in one request” is gone. For large sites, you stick with the curated index of the truly central pages, complemented by targeted fetching of individual `.md` versions.
And finally, the question of trust. As soon as an agent takes over a third-party `llms-full.txt` without checking it, it takes over content it doesn’t control. That’s the same attack surface as with any external data source that ends up in the context – a good reason to go through an MCP server with a domain restriction instead of collecting arbitrary addresses.
## Conclusion
`llms.txt` and `llms-full.txt` are machine-readable self-documentation. The index says what matters and where it lives; the full version delivers the content in one piece; the `.md` mirrors provide individual pages in the form models prefer. None of them is a reliable ranking factor, and if you create the files with that expectation, you’re measuring against the wrong goal. Their value arises where documentation meets agents – with SDKs, API references and coding tools.
Two decisions follow from this. First: the files are generated from the same source as the documentation for humans, or you leave them out – a hand-maintained duplicate drifts and undermines exactly the trust it’s supposed to build. Second: if you need targeted or permission-bound access, you can offer the documentation as a resource through an authenticated MCP server and check permissions there. In this way, MCP can complement the static views with measured, auditable and – with server-side authorization – permission-bound access; it still depends on the documentation behind it being correct.
## Further reading
- The original proposal and the format description: [llmstxt.org](https://llmstxt.org/)
- Repository for the proposal: [AnswerDotAI/llms-txt](https://github.com/answerdotai/llms-txt)
- MCP docs server that reads `llms.txt` as a source: [langchain-ai/mcpdoc](https://github.com/langchain-ai/mcpdoc)
- Model Context Protocol: [modelcontextprotocol.io](https://modelcontextprotocol.io/)
---
# Tools That Hold Up: Concepts, Methods, Processes
URL: https://www.mikebild.dev/en/blog/tools-that-hold-up-concepts-methods-processes-article/
Date: 2026-07-15
There is no installation package for an agent that represents a domain in a binding way. You can install available model weights and runtimes; you can implement or connect protocols. Model weights and runtimes alone, however, do not enforce a domain approval and do not produce meaningful domain evidence of who decided what. The binding part only emerges when you engage with your own domain – with its terms, its rules and the people who stand behind both. The way there can be learned, though, and it is less spectacular than many framework debates suggest.
*Part 12 of the series “From Session to System” – [start with the opening post](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).*
The [previous post](https://www.mikebild.dev/en/blog/ai-agents-per-domain/) described what such an agent has to be able to do: check plans before they take effect; approvals that no model can talk its way around; evidence that answers the questions of the day after tomorrow. What remained open was the way there. It leads through three kinds of tools: concepts that hold up. Methods that keep the start small. And processes that keep the whole thing alive in operation once attention moves on. One at a time.
## Concepts: none of this is new
If you go through the list of capabilities from the previous post, you will not find a single AI invention in it. Domain language and domain boundaries – that a system should speak the terms of its domain and that those terms are only unambiguous within a defined context – were described by Eric Evans a good twenty years ago in “Domain-Driven Design” as ubiquitous language and bounded context. Every organization that reviews changes before rolling them out knows the separation of proposal and effect, from the four-eyes principle in accounting to `terraform plan` and `apply`. Validation, authorization and audit are the basic toolkit of any serious business application. And that answers [have to rest on real sources instead of plausible guessing](https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/) and that [curated knowledge needs a cycle with owners](https://www.mikebild.dev/en/blog/knowledge-that-survives-the-session/) was covered in the middle posts of this series – at its core that, too, is documentation and library work, not magic.
The only new thing is the consumer: a loop in which a model acts, instead of a UI where people click. For choosing concepts, that is a small shift. Since then, one simple test question has helped me: did this concept hold up before there was AI? Domain boundaries, approval workflows, versioning, audit – yes, for decades. An orchestration framework that has existed for four months – probably not. That is not a dismissal of everything new; somewhere the next concept that holds up is actually emerging right now. But the burden of proof lies with the new, not with the proven.
A natural building block shows that the old concepts carry over directly into agent systems: a workflow engine can separate mission, plan, run and the authority granted for it – and use the same planning path for HTTP, MCP, A2A, webhooks and chat. That is the old separation of proposal and effect, applied consistently to every input channel: no matter where an initiative comes from, it takes the same planning path.
For the reflex to design the whole organization as an agent landscape right away, there is an old concept as well, and it hits harder than any technical question. John Gall phrased it in the seventies as an observation about systems: “A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over, beginning with a working simple system.” Twelve connected agents on a whiteboard are the design from scratch. The first process that actually runs and delivers a verifiable result is the beginning of the system.
## Method: take inventory of the rules first
The first of the three questions from the end of the previous post was: which rules belong in the path, and which may stay prose? The answer does not start with technology, but with an inventory that is less popular than it needs to be. For the inventory, I would first check four places: the wiki, instruction files such as CLAUDE.md or AGENTS.md, code review comments – and heads, as in the knowledge of that one colleague you ask before every price change, just to be safe. This list is not complete; depending on the organization, tickets, policies, configuration or business procedures come on top. The inventory brings the rules into one place and notes four things for each: where is it written? How binding is it meant to be? What happens if it is violated? And how often was it actually violated recently?
The last column is the most important, because it replaces opinion with findings. In the chronicle of my instruction files, the sobering lesson was that written rules remain recommendations; in the [post about tools](https://www.mikebild.dev/en/blog/agent-model-domain/), that turned into a transition criterion: when the same rule shows up in an instruction file for the third time and has been ignored for the second time, it is a candidate for enforcement in the path. The inventory turns this gut feeling into a list:
```yaml
# rule inventory, one entry per rule
- rule: "Credit notes above 500 EUR require team lead approval"
source: wiki, AGENTS.md
violation_impact: money leaves the company
violated_recently: twice in Q2
decision: enforce # goes into the path
- rule: "Use the customer number, not the invoice number, in replies"
source: onboarding notes
violation_impact: confusion, no damage
violated_recently: unknown
decision: prose # stays a convention
```
For classifying them, I consider three questions a solid starting point, and they match the criteria that have gradually emerged in this series: does a violation move money, personal data or effects to the outside? Does someone have to be able to prove afterwards who decided what and when? Was the rule broken repeatedly despite clean documentation – by people or by the model? A yes to any of these questions is my starting point for taking the rule into the path: check, approval, evidence. It remains a starting heuristic, though – where the possible damage is small, a mistake is easy to undo or existing controls catch it anyway, a rule can stay prose even with a yes. Three times no, and it stays prose – as a convention that the model reads and mostly follows, and whose remaining risk has been explicitly accepted.
The inventory has a second yield that is easy to overlook: it finds dead rules. Requirements that nobody has needed for years, whose reason disappeared long ago, but which are still dragged along in every document. Those go – not into the path, but out entirely. An agent that represents a domain is also an opportunity to declutter the domain itself.
## Method: cut the first domain small
The second question: how do you cut the first domain without overreaching? The short answer: one process, not one department. A department bundles many states and responsibilities that are never finished at the same time; a process has a verifiable beginning and a verifiable end. “Accounting” is therefore not a cut but a box on an org chart. “Credit notes and dunning stops” is one – a well-delimited process with a beginning, an end and a handful of verbs.
How you recognize a suitable first candidate:
- The process has a clear beginning and a clear end – no permanent state, no umbrella term.
- A handful of verbs is enough: at the latest when the tool list reaches double digits during modeling, I would review the cut again.
- There is already a person responsible for the domain today – the role that approves and decides even without AI.
- The pain is documented: violations have actually happened in the past and demonstrably caused trouble.
- The damage potential justifies the effort but stays manageable – credit notes yes, international payments maybe only in the second year.
The last point deserves a moment. The first domain agent is not just a tool; it is also the piece on which a team builds and operates the three capabilities – check, approval, evidence – for the first time. You choose such first pieces so that mistakes are instructive, not existential.
A small cut also calls for a small transition. Nobody tears down the existing way of working and replaces it with the agent; the prose version remains the prototype from which rules move into the path one by one, as soon as their binding nature has been proven. For this pattern – the new grows along the old until the old is no longer needed – Martin Fowler coined the image of the strangler fig that grows around a tree. Applied to rules: first the 500 euro rule applies as a sentence in the instruction file, then additionally as a check in the path, and at some point the sentence is just documentation of the check. No big switchover day, no risky migration over a weekend.
The rest of the big sketch does not die in the process – it becomes backlog, sorted by exactly the criteria above. That can feel like a retreat. It is the opposite: the first step that can actually be taken and delivers a verifiable result.
## Processes: owner, change path, rhythm
That leaves the third kind of tool, and it is the one most easily underestimated. You can learn concepts, you can apply methods – processes you have to sustain in operation. I consider three of them load-bearing.
First: every rule has an owner, and that owner sits in the business unit. Engineering owns the enforcement – the code that checks, the gate that waits, the log that writes. But whether 500 euros is the right threshold, whether “goodwill” and “pricing error” take different paths, is decided by the business side that has always carried this responsibility. The discussion about proposing, reviewing and approving rules is not an obstacle on the way to the process. It is the process – if you skip it, you have rules without legitimacy, and they erode at the first conflict.
Second: rule changes take the same path as rules. Proposal, review, approval, versioning – the same care that is a given for code. That the evidence records the rule version in force was a side detail in the previous post; in operation it becomes the precondition for touching rules at all without reinterpreting the past. Two building blocks show what this can look like: a knowledge system can keep domain guidelines in a versioned charter that people are responsible for, and route changes to the derived knowledge base through a review process. A workflow engine can describe approved procedures as workflows that run repeatably and log every run – work that has not been described and approved is not improvised. Both are expressions of the same principle: the change path is built into the system.
Third, and most important: learn from the noes, at a fixed rhythm. In operation, the agent produces two streams – executions and rejections. For rules that are too narrow or missing, the rejections are often the more fruitful starting point; samples of successful runs are still necessary, because an execution that was waved through can also contain a wrong decision. The rejection log therefore belongs on the table regularly – at first at a fixed interval of a few weeks, later depending on the rejection rate and damage potential – with three questions: which noes were right and stay? Which were too narrow and need an adjusted threshold or a new reason for a credit note? And which special cases come up so regularly that they deserve their own verb? This is the same cycle that [the post about curated knowledge](https://www.mikebild.dev/en/blog/knowledge-that-survives-the-session/) described, just with rules instead of insights: operations deliver candidates, curation turns them into something binding – the organization changes rules and interfaces in the process; the model stays unchanged.
```mermaid
flowchart LR
I["Inventory collect and assess rules"] --> K["Classification path or prose"]
K --> B["Build verbs · check · approval"]
B --> O["Operation executions and rejections"]
O --> S["Review at a rhythm learn from the noes"]
S --> I
```
Together, the three processes deliver what the previous post merely claimed: that such an agent is a product with a lifecycle. A product has owners, a change path and a cadence at which it gets better. If one of these is missing, it decays – faster with rules than with code, because an outdated threshold does not fail a build and therefore has to be caught deliberately through review or operational metrics.
## Fads you can skip
And the opposite list? I consider four patterns attention sinks that improve neither check nor approval nor evidence – that is a judgment, not a measurement.
The multi-agent orchestra from day one: many agents sending each other messages before even one of them enforces a single binding rule – the design from scratch cast in software. Frequent framework switching, where the domain logic sinks a bit deeper into vendor conventions each time; the antidote – domain logic in your own services, the tool layer as a thin adapter – was already in [the post about agent, model and domain](https://www.mikebild.dev/en/blog/agent-model-domain/). The model comparison table as a substitute for strategy, which [this series argued against early on](https://www.mikebild.dev/en/blog/good-enough-models/): whether several models solve your own tasks well enough is shown by a concrete check against exactly those tasks – and where that is the case, the energy belongs in your own share, not in the table. And endless polishing of wording: when the same instruction is reworded for the third time so that the model “finally understands” it, that is not a writing problem. It is the signal that the rule belongs in the path, not in nicer words.
The test question is always the same, and it keeps the list short: does it help build check, approval or evidence – or does it just feel like progress? Many of the frameworks and agent patterns currently under discussion can be left to mature in peace. They are not going anywhere, and whatever holds up will still be there in a year.
## Where things stand
With that, the three questions from the end of the previous post are answered, as well as I can after these months: with an inventory that delivers findings instead of opinions, a cut the size of one process, and processes that define owner, change path and rhythm. So I would start with a documented rule violation in a process that has already been cut small – that is where the pain is documented, the cut is small and the result is verifiable. The concepts behind it are old, and that is their most important property: they have held up before.
A good eight months ago, this series began with a session on my computer and the observation that my work was changing; now the path ends, for the time being, at organizations that put rules, knowledge and responsibility into their own agents. The next post checks the expectations from the opening: what came true, what did not – and where does all of this lead?
## Further reading
- [Domain-Driven Design Reference (Eric Evans)](https://www.domainlanguage.com/ddd/reference/) – ubiquitous language and bounded context as design work
- [John Gall: Systemantics](https://en.wikipedia.org/wiki/John_Gall_%28author%29) – why working complex systems evolve from simple working systems
- [Martin Fowler: Strangler Fig Application](https://martinfowler.com/bliki/StranglerFigApplication.html) – the pattern for transitions without a big switchover day
- [Building Effective AI Agents (Anthropic)](https://www.anthropic.com/engineering/building-effective-agents) – the advice to start with the simplest setup that works
---
# AI Agents per Domain: Rules, Approvals and Evidence
URL: https://www.mikebild.dev/en/blog/ai-agents-per-domain/
Date: 2026-07-14
An AI agent per domain connects the tools of a field of work with its rules, permissions and case state. What matters is not another chat but an executable path that checks related actions before they take effect. This article shows which responsibility lies with the model, with the tool and with the agent system you operate.
A constructed example: an agent is supposed to refund 740 euros as a goodwill gesture. Anything over 500 euros needs approval from the team lead. The tool call for 740 euros is rejected; two calls for 370 euros each, however, would pass a check that only looks at individual calls. Each call would be allowed on its own, but their combined effect would not. This is exactly the gap a rule over the whole case has to close.
*Part 11 of the series “From Session to System” – [the opening post is here](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).*
The example describes a possible weakness, not an observed incident. Whether a model would actually propose two partial amounts is an open question. The architecture still has to prevent this kind of workaround: a rule about a case cannot be expressed as an isolated check of individual calls alone.
This installment thus keeps two promises the series has left open. The chronicle of my instruction files ended with the finding that only what the environment enforces is a rule. The [last installment](https://www.mikebild.dev/en/blog/agent-model-domain/) closed with the question of why binding rules lead to a dedicated agent tied to the domain – and what that agent has to be able to do. The credit note construction gives the short answer: rules need a place where the context is visible.
## A tool sees the call, not the case
A reminder of where the series stands: the last installment moved the domain from the prompt into the tools – typed operations whose names come from the domain language, whose inputs are validated and whose calls are authorized. The check now runs in the executable path instead of in the prompt: the 500-euro rule went from a recommendation the model can read and weigh to code that decides the same way on every call.
In this example, the check sees only one call. A tool can also load and check case state; what matters is that this responsibility is implemented explicitly. Without it, three things stay hidden.
The context. Domain rules are rarely rules about calls – they are rules about cases. “No more than 500 euros in goodwill” means per case, per customer, per period. Two credit notes of 370 euros for the same case violate the rule without any single call violating it. An authorization that only receives the input of the current call cannot notice this – not because the tool is technically incapable, but because it lacks the bound case state.
The effect. Some errors don’t show in a single step but only in the overall picture – in what will exist after twenty steps. If you only check after execution, you check too late; by then the credit note has already reached the customer.
The memory. Whether a pattern is suspicious is decided across sessions: the same invoice, three times in two weeks, triggered by two different people. The individual call knows nothing about that, and neither does the individual tool.
What the individual tool call lacks, the agent can bring together: the history, a materialized plan and persistent case state – provided these states are stored explicitly and bound to the case. That is why enforcement moves up one level – out of the tool and into the agent that runs the loop. The agent is then no longer an interchangeable accessory but the place where the binding rules of a domain live: an operated software system with a plan, permissions, approvals, evidence and clear ownership.
## From proposal to evidence: five stations
What does this enforcement look like? The core idea is old and doesn’t come from the AI world: separate building from executing. If you run infrastructure as code, you know it as `terraform plan` and `terraform apply` – first you get a complete preview of what would change, then you decide separately whether it actually happens. Between proposal and effect sits a check, and it doesn’t look at a single move but at the whole undertaking.
Applied to agents, the path from idea to effect has five stations.
It starts with the model proposal: a textual or structured output, as eloquent as it is non-binding. Whether the model delivers prose or fully formatted tool calls – at first it only produces a statement of intent without authorized effect. Second, this becomes an executable plan: an ordered sequence of typed operations with concrete parameters, stored as an immutable revision and bound to the checked state; the operations and parameters are machine-readable, while a rationale can remain free text. Third, domain authorization: the plan is checked as a whole against the rules of the domain. This is where two credit notes for the same case stand out, where sum and frequency rules apply, and where it is decided whether the undertaking is allowed, rejected or requires approval. Fourth, where the rules demand it, human approval: a confirmation by a domain role that the model can neither grant nor replace – it may make proposals but may not confirm a human decision itself. And fifth, evidence, in two forms: decision evidence for every rejection and every approval, and execution evidence for every operation actually executed – who, what, when, with what result, under which rule version.
```mermaid
flowchart LR
M["Model proposal textual or structured, non-binding"] --> P["Plan all planned operations"]
P --> R{"domain authorization rules of the domain"}
R -- "violated" --> N["Rejection justified and logged"]
R -- "requires approval" --> H["human approval"]
R -- "allowed" --> D{"bound state still current?"}
H -- "confirmed" --> D
H -- "rejected" --> A
D -- "yes" --> E["Execution"]
D -- "no" --> R
E --> A["Decision or execution evidence who · what · when · rule version"]
N --> A
```
Anyone who works with coding agents knows this on a small scale: first the diff, then the commit. The difference is that there a human looks voluntarily – and on a Friday afternoon sometimes doesn’t. In an agent that is responsible for a domain, the check is not a habit but part of the path. It happens whether anyone remembers it or not.
## A no that stays a no
The second capability follows directly from the construction at the start. A model that runs into a rejection can rephrase, negotiate, look for detours. That wouldn’t be malice: searching on is exactly the behavior we appreciate elsewhere, when a model tackles a test failure three different ways until the build is green. Instead of trying to train this persistence away, you can give it a limit that is not up for negotiation.
For that, the approval has to live outside the conversation. An operation that requires approval waits until a human confirms it – and no text in the context, however eloquent, moves this gate, because the gate doesn’t even read the text. The model can propose its two 370-euro credit notes as often as it likes: the sum rule triggers on the plan, the approval stays pending, and the case sits with the responsible human. What matters here is who gives this yes: not “some admin” but a role from the domain – the team lead who decides on 500-euro goodwill payments even without AI. The approval maps an existing domain responsibility; it doesn’t invent a new one.
Sketched on the tool definition from the last installment, the extension looks roughly like this. The code block is a simplified, illustrative sketch: the API `defineTool` and the role `billing_team_lead` are freely chosen placeholders.
```ts
const issueCreditNote = defineTool({
name: "issue_credit_note",
input: z.object({
invoiceId: z.string(),
amount: z.number().positive(),
reason: z.enum(["complaint", "goodwill", "pricing_error"]),
}),
approval: {
required: ({ input, history }) =>
input.amount + history.totalCreditedFor(input.invoiceId) > 500,
approvers: ["billing_team_lead"],
},
audit: { record: ["user", "input", "approval", "result"] },
});
```
The crucial line is the one with `history`. The approval requirement doesn’t depend on the individual amount but on the sum across the case. The authoritative state lives in the domain, not in the conversation: the agent binds a checked state of the case to the plan and passes it as input to the authorization – exactly the view the isolated single-call check lacks. Binding alone isn’t enough, though: so that parallel calls can’t exceed the 500-euro limit after all, execution has to recheck the bound state against the current domain state beforehand and abort or reauthorize if it has changed in the meantime.
## Evidence instead of memory
The third capability is the least conspicuous: every execution leaves evidence behind. Who triggered the case, which plan revision was checked, what exactly was executed, with which inputs, what came out, who approved it – and, easy to overlook: which version of the rules applied. Domain rules change. 500 euros becomes 300, an approval path gets rebuilt. When someone asks three months later why a credit note went through back then, the answer has to be able to say: under the rules as of March it was allowed, here is the entry.
Such a log doesn’t exist because someone remembered to take notes. It exists because the path produces it – rejections included. The no leaves a trace too, and it is precisely the noes that show where rules are too tight or tools are cut too coarsely. Auditability is not a compliance exercise you bolt on afterwards. It is a property of the path, or it doesn’t exist.
## Why per domain
So far, I have argued why binding rules belong in checkable state transitions and authorization boundaries rather than only in prompt prose. The second part of the question from the last installment is still open: why a *dedicated* agent per domain – and not one big agent that can do everything?
Because each of the three capabilities requires domain knowledge. A plan check can only evaluate what it understands: that two credit notes belong to the same case, that a customer is in dunning, that “goodwill” and “pricing error” have different consequences – these are terms and relationships of a domain, not generic concepts. The approval needs roles that only exist there. The evidence has to be kept in the language in which someone will ask later. A generic agent can read files and run commands; it cannot know what an inadmissible credit note is.
Then there are the permissions. An agent that carries the tools of all domains may need a correspondingly broad set of permissions if rights are not delegated and limited per call – and with such permanent rights it becomes a worthwhile target. OWASP lists “Excessive Agency” among its top 10 risks for LLM applications: too many tools, too broad permissions, too much autonomy in a single system. With his “lethal trifecta”, Simon Willison named the most toxic combination – access to private data, exposure to untrusted content and the ability to communicate externally, united in one agent. Cutting along domains is therefore also a security decision – but it only becomes an enforceable boundary with separate identities, permissions, states and interfaces: few tools, narrowly scoped permissions, a clear blast radius. The credit note agent cannot trigger deployments, and the deployment agent doesn’t know any customer data.
And finally, knowledge. Curated insights, [grounded answers](https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/), [knowledge that survives the session](https://www.mikebild.dev/en/blog/knowledge-that-survives-the-session/) – all of this always belongs to a particular domain. An agent that is responsible for a domain carries its sources, its conventions, its special cases. Not as a cross-domain grab bag, but as a maintained, manageable collection with owners.
This also closes the loop to the [variance from the team part of this series](https://www.mikebild.dev/en/blog/my-success-cannot-be-copied/). Back then, the finding was: results vary between people, tasks and sessions, and files with rules change little about that. The domain agent doesn’t solve this problem by making people the same. It moves the line below which variance can do damage. Above it, everything stays different: how someone phrases, explores, delegates, which path a session takes. Below it, everything is the same: whatever takes effect in the end goes through the same authorization, the same approval, the same evidence – for the experienced colleague just as for the intern, on Friday afternoon just as on Tuesday morning.
## What your own agent has to be able to do
With that, the question from the last installment can be answered compactly. An agent that is supposed to represent a domain in a binding way needs:
- tools in the domain language – typed, validated, authorized
- the separation of model proposal and effect, with a check of the whole plan instead of individual calls
- rules about cases: sums, frequencies, relationships across calls and sessions
- approvals in the path, outside the conversation, by roles of the domain
- evidence of every execution and every rejection – with plan revision, rule revision, approval decision, caller, result and error status
- the permissions of the respective caller instead of its own omnipotence – narrowly scoped, domain-specific
- curated knowledge sources of the domain, with owners and maintenance
Nothing on this list is something an experienced team wouldn’t have built long ago: validation, authorization, workflow, audit, permission model. The only new thing is what it’s for – not for a UI where people click, but for a loop in which a model acts. If you build an agent like this, you wrap ordinary, solid software around variable model proposals. That is exactly why the task is doable.
Doable doesn’t mean on the side. What emerges here is an operated software system with a lifecycle, not a weekend project – the counter-calculation from the last installment still applies, from maintenance effort to the risk of building, out of sheer caution, a form with a chat UI. And it doesn’t belong to anyone alone: the rules come from the business side, enforcement comes from engineering, and neither can take over the other’s part. Regardless of the implementation effort, the team has to clarify who may propose, check and approve such rules in the future – that is organizational work.
## Where things stand
The path of this series can now be told in three stations. Rules as prose: read, weighed, occasionally overruled – recommendations, the kind I spent half a year tightening in vain. Rules in the tool: checked on every call, reliable in detail, blind to the context. And rules in the path: a dedicated agent that knows the domain, checks plans before they take effect, obtains approvals no model can talk its way around, and produces evidence that answers the questions of the day after tomorrow. Only at this stage has the recommendation become a rule that holds even when nobody is looking.
What this installment deliberately leaves open: the path there. No installed product automatically ships the rules of a domain – they emerge from engaging with the domain itself, and that immediately raises practical questions. How does a team find out which rules belong in the path and which may stay prose? How do you cut the first domain without overreaching? Which concepts, methods and processes hold up – and which fads can you safely skip? The next installment is about these tools.
## What SubKit contributes
[SubKit](https://subkit.mikebild.dev/de/) is my tool for recurring processes: an assistant designs the workflow, a person checks it and approves its scope. Execution follows the defined steps; permissions and results become traceable. AI clients can use approved workflows as tools via MCP.
This doesn’t replace modeling the domain. A case-based goodwill limit, shared case state and the handling of parallel requests have to be implemented explicitly in the respective process and the connected systems. SubKit doesn’t automatically supply the business rules for this. The [use cases](https://subkit.mikebild.dev/de/anwendungsfaelle/) show possible starting points; the article [MCP: When Software Offers Capabilities](https://www.mikebild.dev/en/blog/mcp-security-tools-permissions-and-approvals/) explains the role of the interface.
## Further reading
- [Terraform: plan and apply](https://developer.hashicorp.com/terraform/cli/commands/plan) – separating proposal and effect in everyday infrastructure work
- [OWASP Top 10 for LLM Applications: Excessive Agency](https://genai.owasp.org/llmrisk/llm062025-excessive-agency/) – too many tools, too broad permissions, too much autonomy
- [Simon Willison: The lethal trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/) – why the combination of data access, untrusted content and external communication is dangerous
- [Domain-Driven Design Reference (Eric Evans)](https://www.domainlanguage.com/ddd/reference/) – domain language and domain boundaries as design work
---
# MCP Security: Tools, Permissions and Approvals for AI Agents
URL: https://www.mikebild.dev/en/blog/mcp-security-tools-permissions-and-approvals/
Date: 2026-07-13
# MCP Security: Tools, Permissions and Approvals for AI Agents
An MCP tool can read data, publish a revision or call an external service. That turns a model response into an action with consequences. For developers and operators, the security question is therefore: Who may run which operation, on which data and after which approval?
The Model Context Protocol standardizes the connection to such capabilities. You still have to enforce the rules of your application yourself. This article shows how, using a constructed publishing example: the same permissions across the web UI, HTTP and MCP, a verifiable approval before publishing, and a traceable way of handling retries and untrusted content.
For context on the interfaces, here are the [differences between MCP, HTTP, webhooks and A2A](/en/blog/mcp-http-webhooks-and-a2a-explained-simply/).
## Not the app, but the capability
The Model Context Protocol is an open standard that lets AI applications connect to external systems. The official documentation describes MCP as a connection between AI applications and data sources, tools and workflows. The specification talks about hosts, clients and servers: an LLM application is the host, a client sits inside it, and a server provides context or capabilities.
At first, this sounds like integration infrastructure. In fact, it contains a bigger shift. An application is then no longer just a UI for humans. It is also a set of addressable capabilities for agents.
The classic operating path looks like this:
```mermaid
flowchart LR
Human[Human] --> UI[UI]
UI --> App[Application]
App --> Result[Result]
```
The human opens a UI, looks for the right place, fills in fields, clicks preview, clicks publish, then checks the feed and search. The application is the visible bundle of interaction, domain logic and state.
With an agent, a second path is added:
```mermaid
flowchart LR
Human[Human] --> Agent[Agent]
Agent --> Validate[validate_markdown]
Agent --> Preview[create_preview]
Agent --> Publish[publish_revision]
Agent --> Rollback[rollback_release]
Agent --> Search[rebuild_search_index]
```
The UI doesn’t disappear because of this, and it doesn’t become secondary either. But it’s no longer the only access to the work. An agent doesn’t need to know where the button is. It needs to know which capability exists, which inputs it expects, which results come back and which rules apply.
That’s the core: MCP makes software capabilities addressable for agents. What it doesn’t do: replace the product domain or push aside its human UI.
## A publishing system as an example
The following publishing system is a constructed architecture example, not a finished integration and not a customer case. The flow is familiar: Markdown comes in, a preview is built, someone reviews it, and then a revision is published. If something goes wrong, you need a rollback. After the release, the index, feed and cache have to be right.
In a classic UI, these steps are tied to pages and buttons. For humans, that makes sense: a good GUI shows context, can block invalid input and makes states such as approval status visible. For an agent, the same UI is a detour and a source of errors. It would have to click, wait, read from HTML, interpret, click again. That’s automation at the wrong level.
As an MCP capability, the same step would look different:
```ts
const publishRevision = defineTool({
name: "publish_revision",
description: "Publish an approved content revision",
inputSchema: {
type: "object",
properties: {
site: { type: "string" },
revisionId: { type: "string" },
reason: { type: "string" }
},
required: ["site", "revisionId", "reason"]
}
});
```
The important part isn’t the specific syntax. The important part is the shift: an operating path becomes a named capability. `publish_revision` isn’t “click the green button.” It’s a domain operation with inputs, a result, permissions and errors.
Once the operation exists in this form, an agent can work with it. It can call `validate_markdown` first, ask back when there are warnings, request a preview, check the approval status and only then publish. The agent doesn’t operate a screen. The MCP server described here gives it domain tools with an input schema and a permission check.
## Three access paths, one domain
Such a publishing system can provide a domain-oriented tool surface under `/mcp` that runs through the same publishing domain as REST and the web UI. The MCP tools stay bound to the product scopes.
What matters is what this construction is not: MCP isn’t a second system next to the product. The web UI, HTTP and MCP access the same publishing domain with its revisions and permission boundaries. The shared domain logic decides what applies – not the channel the request came through.
This has a practical consequence for the tool list itself. Tools that the current principal isn’t allowed to use don’t need to appear in the list at all. So the agent only discovers capabilities its scopes allow. And where a human approval is required, the agent doesn’t provide that approval itself – it remains a separate step outside its reach.
This filtering is more than convenience, but it’s visibility, not the actual protection. An agent that doesn’t see a tool in the list won’t discover it the regular way. Protection against unauthorized calls comes from server-side authorization; the tools stay bound to the scopes of the respective product. That’s why you can’t obtain a missing release permission by switching from the web UI to MCP. The access path changes, the permission doesn’t.
## Tool access is a permission
An agent that writes text can produce nonsense. An agent that calls tools can produce effects. It can read data, change files, trigger releases or notify external systems. That’s why tool access isn’t a convenience feature but a permission. A tool being discoverable is not yet permission to act; the call remains an authorized operation that the system checks. In a remote MCP setup, these duties are split: according to the MCP specification, getting the user’s consent before a tool call is the host’s job, while the product checks every call on the server side against the principal’s scopes.
The MCP specification itself says that such capabilities raise security and trust questions: users must be able to understand and control data access and operations, tools must be treated with caution, and hosts must obtain consent before tool calls. Consent and access control therefore belong in the execution path of every tool call.
So in a production system, a tool definition isn’t enough. It needs a policy next to it:
```ts
type ToolPolicy = {
tool: string;
allowedRoles: string[];
requiresApproval: boolean;
requiresIdempotencyKey: boolean;
maxRuntimeMs: number;
};
type ToolAuditEntry = {
tool: string;
inputHash: string;
idempotencyKey?: string;
decision: "allowed" | "blocked" | "approved";
outcome: "succeeded" | "failed" | "unknown";
actorId: string;
runId: string;
};
```
This turns “the agent may publish” into a verifiable rule. Who was allowed to make which call? Which input was used? Was an approval required? Was the call executed or blocked? For write operations, there is one more question: What happens if the agent repeats the same call after a timeout? An idempotency key only helps if the server binds it to the operation and its inputs, catches concurrent retries and stores the result reliably. With external side effects, the downstream service also has to recognize retries, or the system has to reconcile the unclear outcome. A key alone doesn’t guarantee a single execution.
MCP standardizes how a tool is discovered and called. It doesn’t make the operation safe from a domain perspective, nor automatically idempotent or auditable. The capability being offered has to carry these properties itself.
## Prompt injection: content must not grant permissions
An article that gets read in can contain instructions, for example to publish a different revision or to send data to an outside address. Treat such content as untrusted data. A prompt that tells the model to ignore such instructions isn’t sufficient access control. The allowed operations, target addresses and approvals have to be checked outside the document being read.
Tool descriptions and labels like “read-only” aren’t proof of how a third-party server actually behaves either. Check which server you connect and which permissions you give it. The [security principles of the MCP specification](https://modelcontextprotocol.io/specification/2025-06-18#security-and-trust--safety) name this trust boundary explicitly.
For a remote MCP server, securing authentication comes on top: check whether an access token was issued for your server; don’t pass received tokens on to downstream services unchecked. Request only the permissions you need. The official documentation on [MCP Security Best Practices](https://modelcontextprotocol.io/docs/2025-11-25/tutorials/security/security_best_practices) describes these measures and the risks of token passthrough.
For the publishing example, I would check at least the following cases before going into production:
- A user without publishing permission calls the tool directly: the server rejects it, even if the tool name is known.
- An approval applies to revision A, but the call names revision B: the server rejects it.
- A document asks for data to be sent to an outside address: the configured boundary stays in effect.
- A call runs into a timeout: before another write attempt, its result is clarified or the retry is effectively deduplicated.
- A failed or rejected operation appears in the history with its actual result.
This is a checklist for this architecture example, not complete evidence of security.
## The wrong split and the right one
I don’t believe that applications will fall apart into small MCP services and stop being products. A good application bundles more than functions: it bundles understanding, interaction, data model, permissions, feedback and responsibility. But at the edges, capabilities that used to be tied to operating paths become individually addressable.
A capability is well cut when it’s understandable from a domain perspective, technically verifiable and operationally accountable. The wrong split would be a generic `run_sql` or `click_button` – a tool that bypasses the domain rules instead of carrying them. The better split is an operation with domain intent: `publish_revision`, `rollback_release`, `create_preview`. The agent shouldn’t work around the database. It should work within the same rules that apply to the web UI and HTTP.
A standard takes away integration work, but not product responsibility. Anthropic introduced MCP at the end of 2024 to address exactly the problem that every new data source needed its own integration. The specification standardizes the exchange over JSON-RPC and describes resources, prompts and tools. Bad capabilities stay bad, even when they are offered in a standardized way.
## What happens to UIs
The strongest version of the claim about the future goes like this: when agents operate software, GUIs become secondary. I think that’s wrong.
Routine paths will shift. If I can tell an agent to review a draft, build a preview and show me only the deviations, I don’t want to click through five forms for that. This is especially true for recurring work that is well described and cleanly bounded.
But humans need UIs for exploration, control, exceptions and trust. A preview is a GUI. A diff is a GUI. An audit log is a GUI. An approval dialog is a GUI. Precisely when agents execute more, good control UIs become more important. The control UI exists so that a human understands what an agent has done and steps in where their judgment is needed.
So the control UI and MCP don’t compete for the same job. The control UI is aimed at human operation and control, MCP at agentic calls. Both are subject to the permission boundaries of the same domain.
## What I take away from this
For me, MCP is less a spectacular technology than a good reason to describe software differently. Not only through the data a system holds, and not only through the UI it offers – but through the work it can do safely, traceably and verifiably.
That’s an architecture question. If you publish capabilities only as a thin wrapper around internal functions, you’re probably building new risks. A domain split, permissions, idempotency and auditability create a controllable foundation for agents – they are not a quality guarantee.
Not every application needs an MCP server right away. Many systems are better served by a good API, a CLI or a clear UI. Where it fits, though, this holds: software meant to be used by agents has to make its capabilities explicit – and it has to enforce the same permission boundaries across every access path.
## Where SubKit fits in
In [SubKit](https://subkit.mikebild.dev/de/), AI helps you design a workflow. A person reviews the preview and approves its scope. After that, the defined workflow runs; the AI doesn’t decide on the further path during execution. Every run is checked for permissions and recorded.
MCP is used in both directions: a workflow can serve as a tool for an AI client, and an external MCP server can be connected as a connector. Which external tools may be used is defined separately. The additional access path replaces neither the approval nor the permissions of the calling person.
This is a concrete product reference, not a claim that SubKit makes every MCP server secure or automatically knows domain rules. The rules of your domain and the permissions of external systems still need to be checked. The article [AI Agents per Domain: Rules, Approvals and Evidence](/en/blog/ai-agents-per-domain/) goes deeper into how such rules can be separated from model decisions.
:::note
**Context and sources**
The publishing system and the code snippets are constructed and illustrate architecture decisions. This article uses the MCP specification from June 18, 2025 and the linked Security Best Practices. The security sections were checked against these primary sources on November 9, 2026; this implies no statement about the security of any specific installation. The SubKit section is based on the confirmed product description from November 8, 2026.
:::
## Further reading
- [Model Context Protocol: Specification 2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18)
- [Model Context Protocol: Security Best Practices](https://modelcontextprotocol.io/docs/2025-11-25/tutorials/security/security_best_practices)
- [Model Context Protocol: Introduction](https://modelcontextprotocol.io/docs/getting-started/intro)
- [SubKit: workflows, approvals and operations](https://subkit.mikebild.dev/de/)
---
# Agent, Model, Domain
URL: https://www.mikebild.dev/en/blog/agent-model-domain/
Date: 2026-07-13
Some time ago, I sat in a meeting at a large enterprise that was supposed to decide on an “agent strategy” for the coming year. On the wall, a slide with three columns: three vendors, with checkmarks for features below them, prices per user, compliance seals. For an hour, the conversation revolved around the question of which agent was the best. At some point I asked a different question: What of all this actually belongs to us afterward? If we switch vendors in three years – what do we take with us? The room went quiet. Not because the question was particularly original, but because the slide had no answer to it.
*Part 10 of the series “From Session to System” – [start here with the opener](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).*
The [last episode](https://www.mikebild.dev/en/blog/knowledge-that-survives-the-session/) ended with the question of whom I hand curated knowledge to – and where the generic agent reaches its limits. To answer it, I first have to take apart everything that gets packed into the word “agent.” Because the silent minute in the conference room had a simple reason: the group talked about agents as if they were a device you buy, set up and use. That picture is misleading – and precisely at the point where it gets expensive for the company.
## An agent is software
What an agent really is can be said in one sentence. In the fall of 2025, Simon Willison put forward a useful working definition: an agent is a model that runs tools in a loop to achieve a goal. There is nothing more to it. No consciousness, no intent, no magic.
There is a loop: the model gets a task and the history so far, proposes the next step, the agent executes it, the result flows back – until a stop condition applies. There are tools: functions that the agent offers the model and whose calls it executes. There is context: everything the agent gives the model, from files and search results to instructions. There is state: what persists between steps and beyond the session. And there are permissions: what the agent is allowed to execute at all, with whose rights, with what evidence.
Each of these five things is ordinary software. In episode 3, I described how exactly this frame – the harness – makes the difference between an impressive tool and a useful one. Back then I meant it personally: my machine, my tools, my way of working. Today I read the same sentence organizationally. What applies to my command line applies all the more to the company: the model produces outputs, such as suggestions, classifications and wording. The agent determines the loop, context, state, permissions and tool integration. These parts can be designed.
## What you rent and what you can control
This division of labor deserves a close look, because economically it describes two completely different things.
A proprietary model that you get through a vendor’s API is rented: it belongs to the vendor, and you have a say in version changes only within the frame set by the API contract and the vendor. You own nothing of it – and that is acceptable as long as several models solve your own, concretely checked tasks well enough. If you build your strategy on “the best model,” you build on something you neither own nor control. I laid out this thought in detail [early in this series](https://www.mikebild.dev/en/blog/good-enough-models/).
The agent layer, on the other hand, can be under your own control. The loop, the context building, the state, the permissions, above all the tools – all of this can be your own code and your own configuration, versionable, testable and reviewable. The integration is also becoming less proprietary: since December 2025, MCP, together with AGENTS.md and goose, sits with the Agentic AI Foundation under the umbrella of the Linux Foundation. That is no guarantee that every vendor provides the same capabilities in the same way.
```mermaid
flowchart TB
subgraph rented["rented – interchangeable"]
M["Model Suggestions · Classification · Language"]
end
subgraph owned["designable – under your own control"]
A["Agent Loop · Context · State · Permissions"]
W["Tools and interfaces typed operations"]
F["Domain Terms · Rules · Processes"]
A --> W
W --> F
end
A -- "requests" --> M
M -- "suggests steps" --> A
```
If the model is rented and the integration increasingly standardized, one particularly important part remains your own: what a company puts into the agent. Its terms, its rules, its processes, its data – in short: its domain. That raises the question of this post. Where does the domain live?
## Option A: the domain as prose
The obvious place is the prompt. In practice, that means instruction files such as CLAUDE.md or AGENTS.md, system prompts, attached policy documents. They then contain something like: “Credit notes over 500 euros may only be issued by a team lead. Customers in an ongoing dunning process receive no goodwill credit. Price changes apply only from the following month.”
I do not want to belittle this option. It is fast: if there is an approved way to maintain it, the business department can change the text without touching the business application. The changed version is available to the model as soon as the agent loads it. For exploratory work, that is often enough – and at the beginning it is almost always the right way, because you first have to find out which rules are needed at all.
But it is fragile, and structurally so, not just in its craftsmanship. First, prose is unchecked: nobody validates it, no compiler reports that sentence 12 and sentence 47 contradict each other, no type check notices that “500 euros” meant gross in one place and net in another. Second, for the model, prose is a recommendation, not a reliable enforcement mechanism – that was the central disillusionment of my futile attempts with instruction files: the model can follow instructions, but you cannot enforce compliance with them this way. Third, the session lottery kicks in: the same sentence is heeded today and skipped tomorrow, depending on what else is in the context. And fourth – in a company, this weighs heaviest – you can version the file, but not the behavior. The instruction file alone provides no deterministic, blocking check that prevents a credit note that breaks the rules; without an additional check, the violation only shows up afterward.
Prose scales with the amount of knowledge. It does not scale with how binding that knowledge is.
## Option B: the domain as an interface
The alternative: do not put the domain knowledge next to the agent but build it into its tools. Instead of giving the model generic database and file access and placing the rules next to it as text, the agent gets typed operations whose names come from the domain language and whose inputs are checked:
```ts
const issueCreditNote = defineTool({
name: "issue_credit_note",
description: "Issue a credit note for an existing invoice",
input: z.object({
invoiceId: z.string(),
amount: z.number().positive(),
reason: z.enum(["complaint", "goodwill", "pricing_error"]),
}),
authorize: ({ user, input }) =>
input.amount <= 500 || user.hasRole("team_lead"),
execute: (input, ctx) => billing.issueCreditNote(input, ctx.audit),
});
```
The difference is more fundamental than the short code block suggests. The 500-euro rule is no longer a request but code: it is checked on every call, the same in every session, regardless of the model’s mood of the day or the state of its context. It exists exactly once, it has an owner, a review, a test. The AI does the wording; the interface decides what is possible at all.
This is the logical continuation of two thoughts from the last episodes. [Episode 8](https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/) was about grounding answers: looking things up instead of guessing, real sources instead of plausible assumptions. A tool is grounded knowledge in executable form – the agent does not have to guess the credit note rules; it can only act within them. And [episode 9](https://www.mikebild.dev/en/blog/knowledge-that-survives-the-session/) was about knowledge that survives the session: a tool definition survives it on its own, because it is part of the system and not part of the conversation.
The tool names connect directly to Domain-Driven Design: they become the binding domain language. What Eric Evans called “ubiquitous language” a good twenty years ago – a shared, precise language between the business side and development – gets a very tangible form of existence. If `issue_credit_note` and `waive_dunning_fee` are the only verbs the agent knows, the organization has to agree on what exactly these verbs mean. Modeling the tools is domain work, not infrastructure work. The interface can reliably check the inputs and permissions of individual calls; process rules spanning several calls need additional state checks and, where necessary, a check of the planned process.
## The counter-calculation
So much for the opportunity. The same calculation includes lock-in, maintenance effort, responsibility and over-constraining.
First, lock-in. Tool definitions, skill formats and agent configurations follow vendor conventions today. MCP standardizes the transport, not the semantics: the protocol defines how a tool is called, not how my credit note logic is structured. If you pour your domain logic directly into the formats of an agent framework, that is exactly where it will be in three years – and moving costs money. The remedy is an old one: put the domain logic into your own services and build the tool layer as a thin adapter. But you have to do it; it does not happen on its own, and under deadline pressure, the opposite happens regularly.
Then the maintenance effort. Your own tool layer causes ongoing maintenance and operating effort. Business rules change: the 500-euro threshold becomes 300, a new credit reason is added, a role is restructured. Someone has to maintain, prioritize, test and roll that out – next to everything else. The prose option was so tempting partly because it hid this effort. The tool option makes it visible, and visibility at first feels like it makes things more expensive, even though the effort was only somewhere else before: in the corrections afterward.
Third, reviewability and responsibility. Who is liable for a tool definition? The question sounds legal, but it is above all organizational. With purely advisory use, a human can reject the answer. If the agent may execute tools without approval, an error in their authorization can take effect immediately: a wrong upper limit then applies reliably wrong, in every session, for every user. Tool definitions therefore need the same care as any production interface: review, tests, clear ownership, change history. And responsibility shifts noticeably: away from the individual who wrote a prompt, toward the team that defined the tool. That is consistent and right – but an organization has to want it, decide it and bear it.
And finally, over-constraining. After the first incident, it is tempting to define away every conceivable deviation until the agent knows only a single, narrow path. Then you have built a form with a chat UI in front of it – more expensive, slower and moodier than the form would have been. The model’s strength lies precisely in the unforeseen: in the special case, in the follow-up question, in the connection between two cases that nobody thought of during the design. If you give the agent tools only for the expected, you could have had classic automation more cheaply. Tools that are too narrow can limit risks, but they can also take away so much room for action that classic automation would be the better fit.
## When generic tools are enough – and when they are not
For my decision, four criteria matter: the kind of work, the people responsible, the potential for damage and the maturity of the domain knowledge. Generic tools – file access, shell, search – go surprisingly far as long as a few conditions come together:
- The work is exploratory: analyzing, prototyping, researching, migrating – tasks whose result a human reviews anyway.
- A single person is working who owns the result and can judge it themselves.
- The potential for damage is small: everything is reversible, nothing leaves the building, no money moves.
- The domain knowledge is still in flux – it would simply be too early to pour it into interfaces.
Conversely, the domain belongs in the agent as soon as the picture flips:
- A process repeats in the team: the same operation, many people, different levels of care and experience.
- Rules are binding, not recommended – they must also hold at 5 p.m. on a Friday afternoon.
- There are audit or evidence obligations: who triggered what and when, with what justification?
- The potential for damage is high: money, personal data, external impact.
In between, I use a pragmatic transition: the prose option is the prototype of the interface. When the same rule shows up in an instruction file for the third time – and has been ignored for the second time – it is a candidate for a tool for me. That way, the domain moves piece by piece from recommendation into structure, following how binding it actually is rather than a big up-front plan.
## Where things stand
For me, the series so far shifts responsibility from the session to the system. It started with the session: the experience that the models are good enough for my work and that the difference lies in my own frame – tools, context, way of working. Then came the team: the disillusionment that my success at work cannot be copied by file and that instruction files remain recommendations, however carefully you write them. Then knowledge: clean grounding instead of convincing guessing, curated insights that survive sessions. And now the system: the insight that the model is rented and stays rented – and that the part you can control in the long run lies in the agent. More precisely: in the tools through which the agent touches the domain.
What remains open is the question of how binding rules are enforced across individual tool calls. Tools decide what is possible in a single call – beyond that, you need approvals before something takes effect; traceability after it has taken effect; a no that stays a no, even when the model keeps phrasing things politely. Why this ultimately leads to an agent of your own, bound to the domain – and what it has to be able to do – deserves a post of its own.
## Further reading
- [Building Effective AI agents](https://www.anthropic.com/engineering/building-effective-agents) – Anthropic’s distinction between workflows and agents
- [Writing effective tools for AI agents](https://www.anthropic.com/engineering/writing-tools-for-agents) – tool design for agents from practice
- [Designing agentic loops](https://simonwillison.net/2025/Sep/30/designing-agentic-loops/) – Simon Willison on loops, tools and stop conditions
- [Model Context Protocol](https://modelcontextprotocol.io/) – specification and documentation of the tool protocol
- [Founding of the Agentic AI Foundation](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) – MCP, AGENTS.md and goose under the umbrella of the Linux Foundation
---
# Knowledge That Survives the Session
URL: https://www.mikebild.dev/en/blog/knowledge-that-survives-the-session/
Date: 2026-06-23
Tuesday morning, the third session this week. I’m typing the same explanation for the third time. Our error model distinguishes between expected and unexpected errors; expected errors come back as values, and there should be no try/catch cascades around service calls. The session before knew that. It had understood it, applied it and even cleanly solved an edge case I wouldn’t have thought of myself. Now I’m sitting in a new session again without that explanation and writing it once more, in different words, a bit more impatiently than last time.
*Part 9 of the series “From Session to System” – [the opening post is here](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).*
This is session amnesia as an everyday experience. Not as a theoretical problem of context windows and token budgets, but as the quiet annoyance of working with a tool that hears from me for the first time every morning. The vendors are working on it. As of August 2026, there are different storage mechanisms for this: Anthropic’s Memory Tool lets agents store information outside the immediate context window in files and load it again later; Claude Code provides project instructions through hierarchical CLAUDE.md files and personal notes through Auto Memory, both across sessions. Personal Auto Memory starts with the individual person; shared, jointly maintained CLAUDE.md files are a different matter. None of these features solves the variant of the problem that really occupies me on its own.
Because the team variant is worse. On Wednesday, a colleague tells me he explained our error model to “his” session. I ask how. He explained it differently than I did. Not wrong – differently. Different terms, different examples, one nuance I would leave out, one I’m missing. A third colleague didn’t explain it at all, because he didn’t know there was anything to explain; his session built try/catch cascades, and the pull request looked like it. Four people, four private explanations of the same convention, four slightly different results. This is exactly the variance problem I described in [“My Success Cannot Be Copied”](https://www.mikebild.dev/en/blog/my-success-cannot-be-copied/) – except that here it’s not about ways of working but about knowledge. Each of us feeds our sessions with our own oral tradition of what the team should actually know together. Personal Auto Memory doesn’t change that: it remembers my version of the explanation, not ours. Versioned, jointly maintained CLAUDE.md files would be the place for a shared version – but only if the team curates them deliberately.
So the core question of this episode is: how does session knowledge become team knowledge – and eventually company knowledge? How does what comes out of a good session get into the next session of another person?
## Two kinds of knowledge
To talk about this sensibly, a distinction helps me that I carried around only implicitly for a long time: curated knowledge and emergent knowledge.
Curated knowledge is deliberately distilled. Someone sat down and put an experience or a decision into words, someone else proofread it, and the result sits in a place where it gets found. Architecture decisions in ADRs, conventions in a CLAUDE.md or AGENTS.md, a runbook for the deployment edge case that strikes every six months. Curated knowledge is expensive – it costs the time of one person who writes it down and of a second who reviews it. In return, it is addressable: I can point to it, link to it, hand it to a session.
Emergent knowledge comes about on the side. In Tuesday’s session, half a dozen small insights came up: that our test setup has a quirk when mocking the message broker, that a certain library in version 4 has a different default behavior than our docs say, that my prompt framing for refactorings works better when I put the target picture before the constraints. I wrote none of it down. The session ended, and with it everything evaporated that didn’t solidify into code or a commit message. Emergent knowledge is cheap to create – and not reliably available to later sessions unless it was saved.
The gap between the two is the real problem. Teams today produce more emergent knowledge in AI sessions than ever before – every session is a small lab where someone tries things out, phrases things, fails, readjusts. And almost none of it survives. What survives is the code. But the code contains only the result, not the reasoning, not the discarded wrong turn, not the phrasing that untied the knot.
## Treating knowledge like code
A team’s distilled working knowledge deserves the same treatment as its code. Versioned. Reviewed. With ownership. And with a lifecycle that includes dying. That is where this episode is headed.
At first that sounds trivial – Docs as Code means treating documentation with the same versioned ways of working as source code, including review and automated checks. But in the AI context, each of these four properties gets a new edge:
- Versioned, because the knowledge is now consumed by machines. When an instruction file changes, the behavior of the sessions that load it can change. Such changes affect the behavior of the system – and behavior changes belong in the history, with a diff and a date and the option to go back.
- Reviewed, because a wrong convention now misleads not only human readers but also several sessions. A person reading a bad wiki article often notices that something is off. A session can’t recognize the error and will apply the wrong convention, as I described in [“Clean Grounding II: Grounding Answers”](https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/): whatever is in the context becomes the session’s reality, whether it’s true or not.
- With ownership, because no one maintains knowledge that belongs to no one. Every convention file, every runbook needs a person who feels responsible. That’s not bureaucracy – it’s the simple answer to the question “Whom do I ask whether this still applies?”
- With a lifecycle, because outdated knowledge is worse than none. This is the point I see underestimated most often. A session without a matching source can guess or ask; a session with outdated grounding guesses with a citation. It quotes the convention from 2024 that we dropped in the fall, and sounds so well-supported that no one checks.
The last point deserves its own paragraph because it is counterintuitive. We are trained to see documentation as “better than nothing.” In the AI context, that’s no longer true. Wrong, old, half-baked knowledge in a session’s grounding is actively harmful, because it turns the model’s uncertainty into false confidence. An empty directory forces me to think about what the session needs to know. A full directory that has never been cleaned out fools me into thinking that’s been taken care of. That is why the lifecycle also includes regular checks against the sources: does the convention still apply? Does the runbook still describe the system that is running?
## The cycle
If you take this distinction seriously – emergent knowledge is created all the time, curated knowledge has an effect – a cycle follows almost inevitably. From these observations I derive four stations.
First: learn from real runs. Not from opinions, not from blog posts, but from what actually happened in your own sessions. Which explanation worked? Where does the same follow-up question come up repeatedly? Which error shows up independently in several pull requests? The raw material is lying around – you just have to recognize it as raw material.
Second: a human curates and approves. This is the decisive station, and it is deliberately not automated. Distilling means selecting, condensing, throwing away. Ten observations become one paragraph; one paragraph may become one line in the convention file; eight of the ten observations are discarded because they were one-offs. The team has to make this decision, because only the team can define what is binding from now on: what is a rule here, what was an exception and what should apply starting tomorrow. And the approval – a second pair of eyes, a real review – turns a private note into a shared commitment.
Third: the distillate flows into the grounding of the next session. It sits in the file every session reads, or in the knowledge source that is pulled in during work. From that moment on, not every colleague has to explain the error model to “his” session orally and differently – the explanation is the same, for everyone, reviewed.
Fourth: the next piece of work can get better. Not dramatically, not all at once. Whether the cycle works can be checked with concrete questions: does the follow-up question that kept repeating come up less often? Does the recurring error still show up in new pull requests? And the next runs produce new raw material – ideally at a slightly higher level.
```mermaid
flowchart LR
A["Real runs and experiences"] --> B["Observe and collect raw material"]
B --> C["Human curates, review approves"]
C --> D["Distillate in the grounding of the next session"]
D --> A
```
This is not a framework and not a ceremony. To get started, a regular, short pass is enough, in which the team discusses what stuck, plus the discipline to treat changes to the knowledge files like code changes: branch, review, merge. How much effort is appropriate depends on the team, the scope and the risk.
## It’s not the model that gets smarter
The point of this cycle only became clear to me over time, and it changed how I see the whole model debate: in this cycle, the model doesn’t get smarter. The organization learns: people select insights, justify them and make them reusable for others. The selected insights show up as versioned changes to the curated knowledge – not in a model retaining more context.
At the end of the quarter, the model hasn’t automatically retained anything from our sessions as team knowledge. The version on offer may well have changed during that time – that doesn’t mean it knows our error model. What has improved is the layer around it: our curated knowledge, our explanations, the quality of what we give each session. And – this is the decisive difference – this layer belongs to us. We can read it, check it, correct it, roll it back. We can steer it. Which model version a vendor ships and how it behaves is something we can influence far less.
If you locate the learning ability of your AI work in the model, you have a steering problem: you’re waiting for progress you can’t influence. If you locate it in curation, you have a work problem – more strenuous, but solvable. I consider that the most sober answer to the question of where a team should invest: in the part it owns.
## The anti-patterns
Most of the attempts I’ve seen to capture session knowledge have failed. And in three recognizable ways.
The prompt collection in the wiki. Someone creates a page: “Our best prompts.” For three weeks people contribute, then never again. After half a year, the page contains outdated prompts without context of use: for models no one uses anymore, for problems no one has anymore, without saying when they work and when they don’t. No one dares to delete, no one wants to maintain. The mistake is already in the form: a prompt without the situation it was distilled for is not knowledge but a souvenir.
The instruction file dump. I already looked at this from a different angle in “Futile Attempts: Skills, AGENTS.md and the Limits of Recommendation”: convention files that everyone writes something into now and then and from which nothing ever drops out. After a year, there are two thousand lines in which rules contradict each other because the one from March doesn’t know the one from October. The sessions read everything and weight it somehow – the result is a lottery. A knowledge file without deletion discipline is not a knowledge file but a sediment basin.
The written-down-once. The third variant is the quietest: in a good week, a motivated colleague writes everything down – thoroughly, structured, really useful. Then it’s never touched again. No ownership, no review rhythm, no occasion to update it. Twelve months later, parts of it may be outdated, and because no one knows which ones, no one trusts the rest anymore. The one-time heroic effort is the natural enemy of the cycle: it feels like a solution and prevents exactly the routine that would be one.
All three patterns lack the same thing: the way back from the real work into the knowledge. They treat writing things down as an event instead of a cycle.
## The opportunity that costs work
And still – or precisely because of this – I consider this moment an unusual opportunity. Organizations have been talking for decades about making implicit knowledge explicit. Knowledge management initiatives, wikis, communities of practice: my thesis is that the lack of an immediate consumer contributed to many of these initiatives petering out. Whoever wrote down their knowledge wrote for an abstract “later” and a hypothetical “someone.” The feedback was missing; writing things down remained a sacrifice without visible return.
That is changing right now. AI sessions form an additional immediate consumer for explicit knowledge. If you distill a convention cleanly today, you can check it in the next session: does the AI behave differently? Does the pull request follow the convention? Does the familiar follow-up question stay away? The feedback loop that was missing in these cases can become much shorter in such workflows. AI thus creates an immediate incentive to make implicit knowledge explicit – and the next session gives early hints about whether what was written down holds up.
I don’t want to hide the criticism of this. Curating costs the time of exactly the people who have the least of it. There is a real risk that the cycle gets out of hand and every line of convention has to pass through its own approval committee. And not all knowledge wants to be frozen – some of it is deliberately in flux, and if you distill it too early, you cement an interim state. The answer to that is moderation, not abstinence: start small, distill only what has repeated itself, and take deleting as seriously as writing.
What keeps me busy at the end of this episode is a question one level deeper. Suppose the cycle is in place: the team curates, the knowledge survives the session, the organization learns. Then there is a growing body of distilled conventions, domain terms, decisions – and session after session, I hand it to a generic assistant that knows nothing about my domain and reconstructs everything from the context every time. At some point the question arises of whom I’m actually entrusting this knowledge to: is the generic agent with good grounding enough – or does the domain need a counterpart built for it? Where exactly the generic agent ends is the question of the next episode.
## Further reading
- [AGENTS.md – the open format for agent instructions](https://agents.md/)
- [Anthropic: Memory Tool – knowledge across sessions](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool)
- [Claude Code: How Claude remembers your project](https://code.claude.com/docs/en/memory)
- [Ikujiro Nonaka: The Knowledge-Creating Company (Harvard Business Review)](https://hbr.org/2007/07/the-knowledge-creating-company)
- [Write the Docs: Docs as Code](https://www.writethedocs.org/guide/docs-as-code/)
---
# Clean Grounding II: Grounding Answers
URL: https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/
Date: 2026-06-03
A few weeks ago, a colleague and I sat in front of a half-finished piece of integration. The AI was supposed to write a client for an internal API, and it did what it always does: it suggested `customerId`. In our system, the field is called `customer_ref` – for historical reasons that no one defends anymore but everyone knows. We had already explained that to the assistant twice that week. This time I did something different: I didn’t contradict it; I put the OpenAPI description of the API into the context. The next suggestion was right. Not roughly, but exactly – including the somewhat idiosyncratic pagination that no model in the world could have made up, because it was simply a decision of ours. Same model, same day, same task. The difference: it no longer had to guess.
*Part 8 of the series “From Session to System” – [the opening post is here](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).*
In the [last episode](https://www.mikebild.dev/en/blog/clean-grounding-i-why-ai-guesses-so-convincingly/), I described why AI guesses so convincingly: a language model uses symbols to refer to symbols, not to my systems. It knows a thousand APIs that look similar to mine – and that is exactly why it invents plausibly. That was the diagnosis. This episode is the constructive side: how do I give the AI my reality? For myself, I call this clean grounding – grounding answers instead of leaving them hanging in the air. And as so often, the core is less a tool than a sorting: what knowledge is there at all, where does it come from, and when does it belong in the context?
## My working model: three layers of knowledge
When I look at what gives my answers solid ground in practice, I keep ending up with three layers. This is my sorting for this work, not a general taxonomy of knowledge. The layers differ not only in content but in their character – and that is the real point.
```mermaid
flowchart TB
subgraph Schichten["Three layers of knowledge"]
K["Conventions how we work prescriptive, curated"]
D["Documents runbooks, specs, decisions descriptive, aging"]
S["API descriptions OpenAPI, GraphQL introspection, schemas machine-checkable"]
end
K --> E["Grounding while building and preparing"]
D --> E
S --> E
E --> A["Checked work result document, plan, code, configured flow"]
```
The first layer is our **conventions and ways of working**. This is prescriptive knowledge: not “this is how the world is,” but “this is how we do it here.” Error handling belongs to the caller, migrations never run automatically, commit messages explain the why, reviews check the interface first. None of this is in an API description, and none of it can be guessed by a model – these are decisions, not facts. In episode 6, I told how I tried to pack exactly this knowledge into instruction files like AGENTS.md or CLAUDE.md – and where recommendations reach their limits. Giving up was not the lesson. This layer has to be small, dense and curated: a short list of rules the team stands behind can be followed and enforced in review. A long collection of hints competes with itself for attention.
The second layer is our **documents**: runbooks, specifications, architecture decisions, operations notes. This is descriptive knowledge – it describes what applies here and why it came about this way. A recorded architecture decision can prevent the AI from overriding three-year-old system boundaries with its suggestion. A runbook explains what really needs to be done for a particular alert, instead of what sounds generically sensible. But I’ve learned to approach this layer with a certain skepticism: documents age. They describe the state of back then, not of today. A runbook that no one has touched in two years can mislead the AI just as much as its own guessing – only then the answer sounds even more convincing because it cites “our docs.”
The third layer is **real API descriptions** – and it’s my favorite, because it has a character the other two lack: tools can read their structure, even if schema and runtime behavior can drift apart. An OpenAPI description, a GraphQL schema queried via [introspection](https://graphql.org/learn/introspection/), a JSON Schema, a database schema – that is not a colleague’s memory of the system but a machine-readable description of structure or API. Introspection shows the schema this environment offers at this point in time: if the field is called `customer_ref`, that’s what it says there. That proves neither correct resolvers nor agreement with other deployments or with data-dependent responses. Depending on the artifact, I can read field names, types or endpoints from it instead of guessing them from conventions or documents.
The three layers answer different questions, and they don’t replace each other:
- Conventions say **how** something should be built – style, boundaries, responsibilities.
- Documents say **why** things are the way they are – context and history.
- The respective API description names fields, types or endpoints. Whether the implementation matches this state and works has to be checked separately.
If you supply only the third layer, you get code that matches the described contract but doesn’t necessarily work at runtime. If you supply only the first, you get stylistically clean code against an invented API. Only together do they ground an answer.
## Look it up instead of guessing
The principle behind all three layers is the same, and it’s so unspectacular that it’s easy to read past: **look it up instead of guessing**. The easiest way to understand it is through an analogy everyone knows from the editor: IntelliSense.
When I type `customer.` in my editor, the editor doesn’t guess which fields a customer probably has. It looks them up. A type-based editor derives suggestions from the available type definition, not from statistical similarity. Exactly this derivation is what a language model lacks when we let it work without grounding.
An agent with suitable tools and read permissions can look things up. It can read an OpenAPI file, query a GraphQL schema via introspection, open a type definition in the repository. The [Model Context Protocol](https://modelcontextprotocol.io/) provides tools and context sources for this through a protocol contract. And such an agent can go one step further, beyond IntelliSense: it can **try** endpoints. A read-only call against the real API, a look at the actual response structure, and the next suggestion is based on observed data instead of invention. “This field probably exists” becomes “I have seen this field – in this response, with these permissions, in this environment and at this point in time.” That is a categorical difference, not a gradual one, even if a single response doesn’t prove the behavior for other data, permissions, environments and points in time.
Exploratory read access must be authorized; whether it is free of side effects in domain terms has to be clarified beforehand. Such calls are valuable for research. Writing calls “just to try it out” are a topic of their own with their own safeguards – I’ll come to that later in this series. For grounding answers, the reading side is almost always enough.
## Grounding of repeatable workflows belongs at build time
The second principle took longer to sink in for me, and it’s the one with the biggest consequences: **when** does grounding happen? Wherever a repeatable workflow has an artifact that can be checked in advance, grounding belongs at build and preparation time – not in the critical path of execution. If, on the other hand, the question only arises at runtime, the grounding has to happen there too.
The diagram above shows this case for an artifact that can be checked in advance.
At this point I have to place RAG, because it’s the first word in the room as soon as someone says “our own knowledge” and “AI” in the same sentence. Retrieval-Augmented Generation – described in 2020 by [Lewis and colleagues](https://arxiv.org/abs/2005.11401) – means: at query time, matching text passages are searched in a corpus and passed to the model. That is exactly right when the question only arises at runtime and the answer has to come from a body of documents – an assistant that answers questions about the handbook, a search across internal notes, support cases. Such cases correspond to the pattern of retrieval and generation described in the RAG paper.
It goes wrong when RAG becomes the reflex for everything. Because retrieval at runtime has two properties that hurt in day-to-day work: additional latency and possible changes in results when the index, ranking or search method changes. Every execution searches anew, and what gets found depends on embeddings, rankings and the state of the index – the same workflow can see different text passages today than yesterday and therefore behave differently. For an exploratory question, that’s tolerable. For a workflow that runs every night and whose result people rely on, changing hits can lead to non-reproducible results.
That is why, for such repeatable workflows, I pull grounding forward. The knowledge – the conventions, the documents, the API descriptions – flows in while something is being **created**: a document, a plan, a piece of code, a configured workflow. This work result is checked, by me or by a colleague, and from then on it is fixed. The later execution doesn’t roll the dice again; it executes what was checked. The difference is the same as between a program that guesses its dependencies from the network on every start and a build with pinned versions: all the uncertainty belongs in the fleeting, creative moment – it doesn’t belong in what then runs again every night.
This is not a rejection of RAG but a clarification of responsibilities. Search across documents at runtime, where the question arises at runtime. Grounding at build time, where the result is an artifact that is meant to last. In my work, the second case is the more common one – yet it is still discussed in the vocabulary of the first.
## Context economics: what goes last
The third principle sounds trivial and decides a surprising amount in practice: context is scarce. Yes, the windows have gotten big. But if you work with agent sessions for a while, you know that “big” doesn’t mean “inexhaustible” – long sessions, files read, tool outputs and intermediate states fill every window, and at some point things get trimmed, summarized, left out. Anthropic put this in a nutshell under the term context engineering: context is a finite resource; relevant information is found deliberately and loaded only when needed. A large, unfiltered context is not a mark of quality – the source that is authoritative for the task belongs in it at the time of the work.
For my grounding, this leads to a prioritization rule: when something has to leave the context under pressure, I first remove material that can be looked up again in a targeted way. A long runbook stays in the context only with the paragraphs that are relevant right now. Small, task-relevant conventions I hold on to longer, because their loss is harder to notice. For a different task, this order can look different; what matters is relevance and the cost of fetching it again, not the name of the layer.
That’s why I keep convention documents small and tailored to the task. A sprawling document competes with sources and tool outputs for space. Curating here means deciding deliberately what has to stay in the context for the next step.
## What grounding doesn’t do
Honesty includes the counter-calculation, and I don’t want to squeeze it in at the end as if it were a footnote. Grounding doesn’t eliminate guessing. With the OpenAPI description loaded, the next suggestion contained no invented field names or structures. But a language model remains a language model: it can have a correct specification in the context and still draw a conclusion from it that doesn’t hold. It can read two documents together that contradict each other and elegantly bridge the contradiction instead of reporting it. And it can be grounded in an aged runbook – then the answer is cleanly reasoned and still wrong, only harder to recognize as wrong.
So checking remains mandatory. The grounded work result is a better candidate, not a final verdict. What has changed for me is the kind of checking: I search less often for freely invented fields and more often for wrong conclusions from correct sources. That’s a better problem – the same kind of problem I would have with a human colleague who had conscientiously read up. But it is a problem, and grounding replaces neither consistency checks nor tests – without such checks, wrong conclusions can go undetected.
One question hasn’t let go of me since. Everything I’ve described here grounds one session: the conventions, the documents, the interfaces flow into one working context, and at the end there is a checked result. But the session ends. The window closes, the context is gone – and with it everything the AI learned in those two hours about our system, our quirks, our corrections. Tomorrow I’ll explain `customer_ref` for the third time, or I’ll have found a way for knowledge to survive the session. What that can look like – without accumulating outdated, unfindable or unsupported entries – is the subject of the next episode.
## Further reading
- [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) – Anthropic’s engineering post on context as a finite resource
- [Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks](https://arxiv.org/abs/2005.11401) – the original RAG paper by Lewis et al. (2020)
- [GraphQL Introspection](https://graphql.org/learn/introspection/) – how a GraphQL schema provides information about itself
- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html) – the standard for machine-readable HTTP API descriptions
- [Model Context Protocol](https://modelcontextprotocol.io/) – an open standard for giving AI tools access to real data sources and systems
---
# AI in the Enterprise: Faster Development Needs Different Processes
URL: https://www.mikebild.dev/en/blog/ai-in-the-enterprise-faster-development-different-processes/
Date: 2026-05-19
If implementation takes two days instead of five, but the change then waits twelve days for reviews, approvals and a shared test window, the product hardly reaches users any sooner. The local work got faster. The overall process did not.
This is exactly the shift that AI exposes in large companies. A developer can prepare code, tests and a first draft of the documentation in a fraction of the previous time. In research and development (R&D), hypotheses can be tested faster and prototypes shown earlier. At the same time, dependencies between teams, contradictory documentation and long-grown approval rounds stay the same. The bottleneck moves from implementation into the organization.
This is not an argument against large companies. Their formalities rarely came from a pure love of bureaucracy. Regulation, product liability, changing staff, distributed systems and software that has run for decades all need traceability. It becomes a problem when nobody can tell anymore which formality controls a real risk and which one only administers an old uncertainty.
## AI amplifies the workflow you already have
At first glance, the productivity numbers don’t add up. Three field experiments at Microsoft, Accenture and another Fortune 100 company with a total of 4,867 developers found that users of a coding assistant completed about 26 percent more tasks; the effect varied with experience and context. A randomized METR study with experienced open-source developers, on the other hand, found 19 percent longer completion times with early-2025 tools. In February 2026, METR reported signs of better results with newer agentic tools, but itself considered the data too uncertain, due to selection effects, to put a number on the size of the benefit.
The findings contradict each other less than it seems. Task, codebase, experience, tool and acceptance criteria all change the outcome. The [DORA Report 2025](https://dora.dev/research/2025/dora-report/) sums up the organizational part well: AI acts as an amplifier. Good feedback loops, well-maintained internal data and small changes benefit. Unclear ownership and cumbersome processes get amplified too.
A survey result from the [Atlassian State of Developer Experience Report 2025](https://www.atlassian.com/teams/software-development/state-of-developer-experience-2025) points in the same direction: developers reported time saved through AI and, at the same time, weekly time lost to organizational friction. Self-reports like these are not a stopwatch. As a diagnosis, they are still useful: faster code does not remove waiting time.
## The ticket tree is not the product
In a large company, a product idea can first become an initiative, below it an epic, several features, stories and subtasks. The business description lives in Confluence, an architecture decision in a comment, the acceptance condition in a ticket and the actual rule in the code. Each level makes sense on its own. Together, they create several truths.
This often leads to a half-agile, half-waterfall approach. The team works in sprints but has to fix the content months in advance for budget, dependencies and committees. Questions end up as ticket comments because the spoken word doesn’t count as reliable. So people write more, without the documentation becoming any more consistent. When several systems are integrated, the number of alignment meetings grows faster than the number of domain decisions.
AI should not fill this apparatus automatically. Otherwise you just get more epics, longer summaries and even more convincing-sounding comments. The better approach starts with a single, small description of the intent. Everything else is derived from it and stays versioned with the change.
```yaml
change:
id: customer-address-v2
outcome: reduce failed deliveries
constraints:
- preserve existing API clients
- keep customer consent auditable
owners:
product: customer-experience
technical: customer-platform
evidence:
- contract-tests
- migration-report
- rollback-plan
risk: medium
```
This is not a new mandatory form. It is an example of a small, versioned change artifact that you can have a meaningful argument about. With read access to an indexed body of code and decisions, an agent may use it to gather the affected repositories, earlier decisions, contracts and tests. It may propose a plan, acceptance examples and documentation changes. Outcome, constraints, risk and owners are still decided by the team.
The difference from the ticket tree lies in the direction: people don’t maintain five representations of the same change. The different views are generated from a few versioned sources. The ticket points to the artifact, the pull request shows the diff, and the documentation points to the decision. A summary for management may look different from the technical view, but both have to trace back to the same state.
## Integration needs contracts, not more alignment
AI does not automatically make complex integration simple. An agent can read an unfamiliar service quickly and still miss a domain assumption that only the team running it knows. That is exactly why collaboration should depend less on prose and more on verifiable contracts.
In the example of the changed customer address, the relevant event could exist as a schema:
```json
{
"$id": "CustomerAddressChanged.v2",
"type": "object",
"required": ["customerId", "address", "consentId"],
"properties": {
"customerId": { "type": "string" },
"address": { "$ref": "Address.v2.json" },
"consentId": { "type": "string" }
}
}
```
The AI can search the code for producers and consumers, write a compatibility report, add contract tests and prepare test data. The compatibility report has to cite repository, revision and location for every statement – for example, that the CRM already delivers `consentId`, that the shipping service ignores the field and that an old export works with `Address.v1`. That way, the research can be checked before a decision is based on it.
It doesn’t have to make the decision. Whether an old address may still be processed is a domain question. Whether both versions run in parallel or an adapter is needed is an architecture decision. The agent collects evidence; the teams involved own the contract. This is exactly where [ADRs](https://www.mikebild.dev/en/blog/adrs-decisions-you-still-understand/) and executable specifications are valuable: they don’t record every conversation, only the result and its reasons.
## Documentation is derived, not abolished
Confluence stays useful for explanations, entry points and overviews. It just shouldn’t be the third manually maintained copy of what the ticket and the code also describe. A page needs a named owner, a verifiable link to a contract, ADR or repository, and a visible update date. If that link is missing, an agent may flag the page as possibly outdated, but must not quietly declare it the truth.
AI can generate different views from an approved change: release notes for users, a technical integration note and a short summary for the portfolio. Each text stays verifiable because it points to the same artifacts. People then don’t have to write every sentence three times. They check whether the derived view is right for its readers. This makes the documentation more consistent and the obligation smaller at the same time: what gets recorded is the decision, the contract and the operational consequence – not every intermediate stage of the discussion.
```mermaid
flowchart LR
Idea[Product idea] --> Ticket[Ticket hierarchy]
Ticket --> Docs[Separate documentation]
Docs --> Meetings[Alignment rounds]
Meetings --> Build[Large implementation]
Build --> Test[Shared test window]
Test --> Approval[External approval]
Intent[Versioned intent] --> SmallChange[Small change]
SmallChange --> Evidence[Tests, contract and diff]
Evidence --> Review[Peer Review]
Review --> Release[Release]
Release --> Feedback[User and operations signal]
Feedback --> Intent
```
## You become agile through the cost of a change
Agility is not a particular board or a number of meetings. The original Agile Manifesto values working software over comprehensive documentation and responding to change over following a plan. Neither statement calls for carelessness. Both call for new information to actually be able to change the state of the work.
Whether AI shortens research, prototyping or test design in a specific value stream has to be measured there. If it does, the cost of small experiments drops. R&D can then work more with hypotheses: What do we want to learn, which smallest experiment delivers evidence, and which result would change our direction? Product development can use the same rhythm.
The prerequisite is small batches. More code generated in parallel makes the flow worse if review capacity stays the same. The result would be a new kind of inventory – half-finished pull requests instead of half-finished tickets. As with [developer productivity](https://www.mikebild.dev/en/blog/developer-productivity-shorter-cycles/), what counts is therefore not typing speed but the time to reliable feedback. [DORA metrics](https://www.mikebild.dev/en/blog/dora-metrics-what-really-shortens-cycles/) help with the diagnosis; they must not become a target for individual employees.
## Governance without a blanket queue
Control is still necessary, but not every change deserves the same path. A text correction, a backward-compatible API extension and a new permission model have different potential for damage. Good governance makes this difference executable. The NIST AI Risk Management Framework follows the same idea at the level of the AI systems themselves: it structures risk management through governance, measurement and ongoing management instead of a single blanket approval.
```yaml
approval_policy:
- risk: low
requires: [tests, policy-checks, peer-review]
decision: peer-approved
- risk: medium
requires: [tests, contract-checks, owner-review, rollback-plan]
decision: peer-approved
- risk: high
requires: [security-review, compliance-review, business-owner, audit-record]
decision: manually-approved
```
This YAML file, too, is only a sketch, not a finished policy language. Automated checks produce the same evidence for every change. People review where context, liability or effects that are hard to reverse come into play. DORA recommends replacing heavyweight external change approvals with peer review, continuous testing, monitoring and targeted extra review of risky changes. That means less bureaucracy and more precise control at the same time.
```mermaid
flowchart TD
Change[Change with evidence] --> Risk{Risk class}
Risk -->|low| Guardrails[Automatic guardrails]
Guardrails --> Peer[Peer Review]
Peer --> Release[Release]
Risk -->|medium| Owner[Domain and technical owner]
Owner --> Release
Risk -->|high| Specialist[Security, compliance and business]
Specialist --> Approval{Approval}
Approval -->|yes| Release
Approval -->|no| Rework[Rework or discard]
```
The EU AI Act makes a second distinction important. Article 4 of [Regulation (EU) 2024/1689](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32024R1689) on AI literacy has applied since February 2, 2025: providers and deployers must take measures to ensure that people who work with AI systems on their behalf have a sufficient level of AI literacy. Annex III, point 4 of the regulation covers – depending on the intended purpose – among other things systems that evaluate or monitor employees or allocate tasks based on individual behavior or personal traits. A productivity ranking built from process data does not automatically fall under it. But if it is used for HR decisions, performance evaluation or task allocation, it sits in a legally particularly sensitive area. Governance should protect the work, not put people under general suspicion.
## The organization has to follow the workflow
A new assistant alone doesn’t change an org chart. In the long run, though, an organization with many handoffs is a poor fit for a way of working that is supposed to learn in short loops. For value streams with frequent cross-team changes, three structures become more important:
- long-lived, cross-functional product teams that own an outcome from idea to operation and can approve small changes themselves
- an internal platform that offers secure access to code, documentation, test environments and approved AI models as the default path
- governance, security and architecture groups that design rules, reference solutions and exceptions instead of waving through every normal change individually
This matches the pattern I already described for [simpler design and less process](https://www.mikebild.dev/en/blog/simple-design-can-save-process/): first make the change small and its expectations explicit, then remove the process step that this makes unnecessary. A locally measured time saving does not replace this architecture work.
For the roles involved, the focus shifts:
| Role | New focus |
| --- | --- |
| Developers | Slicing tasks, providing context, reviewing generated changes, designing tests and operational signals |
| Architects | Designing system contracts, automated architecture rules, reversibility and safe default paths |
| Product owners | Sharpening outcomes, acceptance examples and user feedback instead of managing the ticket backlog |
| Project management | Reducing dependencies, risks, waiting times and work in progress instead of planning activities in detail up front |
None of these roles disappears. On the contrary: the cheaper it becomes to generate proposals, the more valuable selection, judgment and responsibility become. The [result of a single AI power user cannot simply be transferred to an enterprise](https://www.mikebild.dev/en/blog/my-success-cannot-be-copied/). Teams need shared review criteria, time to learn and a workflow that makes differences visible.
## Start small and measure the whole cycle
A company-wide transformation program would be a contradictory start. A single value stream with a recurring change whose risk is known works better. There you can map today’s path from request to operation: How long is work being done, how long is it waiting, how often is the same information transferred, and where does rework happen?
A first attempt needs only a few steps:
- define a versioned change artifact and the leading sources
- give the AI read-only access and log its context in a traceable way
- generate tests, contract checks and documentation diffs automatically as evidence
- at first, send only small, reversible changes through the new path
- compare lead time, waiting time, number of handoffs, rework, change fail rate and time to user feedback
I would not measure generated lines of code, closed tickets or individual prompt activity. Numbers like these reward volume. I would measure the inventory of half-finished work, the share of a predefined sample of documents that contradicts a named contract, ADR or repository state, and the time from opening a review request to the first approval or concrete change request. The share of releases that go through the controlled path measures process coverage, not impact.
## Conclusion
The cumbersome processes of large companies are not a law of nature, but they are not just past stupidity either. They preserve ownership, knowledge and control where technical means were long insufficient. AI changes this calculation because it can gather context faster, prepare evidence and support recurring checks.
The gain only materializes when the organization doesn’t fill the freed-up time with more output. Then changes get smaller, contracts replace part of the alignment and versioned artifacts avoid contradictory copies. Approvals follow risk instead of a blanket queue. People keep the decisions where domain knowledge, liability and consequences matter.
That is how AI can actually make development and R&D more agile: not by filling out the old process faster, but by helping to make its detours unnecessary.
## Further reading
- [DORA – State of AI-assisted Software Development 2025](https://dora.dev/research/2025/dora-report/)
- [DORA – Capability Catalog](https://dora.dev/capabilities/)
- [DORA – Streamlining Change Approval](https://dora.dev/capabilities/streamlining-change-approval/)
- [DORA – Working in Small Batches](https://dora.dev/capabilities/working-in-small-batches/)
- [DORA – Repository](https://github.com/dora-team/dora.dev)
- [Microsoft Research – The Effects of Generative AI on High-Skilled Work](https://www.microsoft.com/en-us/research/publication/the-effects-of-generative-ai-on-high-skilled-work-evidence-from-three-field-experiments-with-software-developers/)
- [METR – Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/)
- [METR – We Are Changing Our Developer Productivity Experiment Design](https://metr.org/blog/2026-02-24-uplift-update/)
- [Atlassian – State of Developer Experience Report 2025](https://www.atlassian.com/teams/software-development/state-of-developer-experience-2025)
- [Manifesto for Agile Software Development](https://agilemanifesto.org/)
- [NIST – AI Risk Management Framework](https://airc.nist.gov/airmf-resources/airmf/5-sec-core/)
- [European Commission – AI Literacy: Questions & Answers](https://digital-strategy.ec.europa.eu/en/faqs/ai-literacy-questions-answers)
- [Regulation (EU) 2024/1689 – Artificial Intelligence Act](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32024R1689)
---
# Clean Grounding I: Why AI Guesses So Convincingly
URL: https://www.mikebild.dev/en/blog/clean-grounding-i-why-ai-guesses-so-convincingly/
Date: 2026-05-06
A few weeks ago I was sitting in a review of generated code. The assistant had suggested retry logic for our internal HTTP client – a client that exists only at our company, a thin TypeScript layer over `fetch` with a few in-house conventions. The suggestion: `client.withRetry({ backoff: "exponential", maxAttempts: 3 })`. Cleanly named, in the style of our codebase, with a comment on why exponential backoff was the right choice here. Plus a short explanation in the chat of how the method relates to our timeout handling.
The method doesn’t exist. It never existed. Our client configures retries in a completely different place, when the instance is created, not at the call. But the frightening part wasn’t the mistake. I make mistakes too. The frightening part was the quality of the invention: the name fit our conventions perfectly, the signature looked like one of ours, the reasoning was sound from a domain point of view. If a human had suggested the method, I would have said: this person really knows our code well. Except that the suggestion was a complete guess – and was delivered with the same confidence as the twenty correct suggestions before it.
*Part 7 of the series “From Session to System” – [the series opener is here](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).*
If you work seriously with Copilot, Claude Code or Cursor, you can run into something like this. At first, I looked at such errors like a bug that should disappear with the next model generation. Today I don’t rely on that. Better models can reduce hallucinations, but they don’t reliably eliminate them – and since that became clear to me, I work differently with these systems.
## The model doesn’t reliably know the limit of its knowledge
To understand why the invention sounded so convincing, I had to remind myself what a language model actually does: it continues text. From billions of examples it has learned which continuation is likely after a given beginning. That is not a disparaging simplification but the mechanism – and it is astonishingly powerful, as I described [in part 2 of this series](https://www.mikebild.dev/en/blog/good-enough-models/). But it has a property that can’t be argued away: true and false statements both arise as likely continuations; a truth check doesn’t automatically follow from this mechanism.
A human developer – fallible as they are – has a sense of whether they know something or are guessing. If I ask a colleague about a method in our internal library, they answer either “it’s called this” or “I’d have to look it up”. This having-to-look-it-up is metacognition: knowledge about your own knowledge, a sense of your own uncertainty. Exactly this faculty is missing in the model. It has no inner state that distinguishes between “this appeared a thousand times in the training corpus” and “this sounds the way it ought to sound”.
That’s why the confidence that irritates us so much is not arrogance but an artifact. The tone of a text is part of the continuation. Technical documentation, Stack Overflow answers, code comments – the material the model learned from is overwhelmingly written in a tone of certainty. Nobody documents an API with “I think this method exists”. So the invented method sounds like documentation too. The confident tone is not a signal of correctness. It never was.
Two papers support parts of this explanation. In 2024, Ziwei Xu and colleagues argued formally that hallucinations cannot be completely eliminated for large language models. And in a publication of its own – available online as of August 2026 – OpenAI describes a second mechanism: training and evaluation incentives can push models toward guessing instead of admitting uncertainty. A model that says “I don’t know” when uncertain can score worse on benchmarks that reward correct answers but don’t properly account for abstentions than one that guesses confidently – just as a multiple-choice test teaches students to tick a box at random when they don’t know instead of leaving the field empty.
## Symbols that refer to symbols
There is an even deeper level, and it is older than the current models. In 1990 – long before today’s large language models – the cognitive scientist Stevan Harnad formulated the *Symbol Grounding Problem*. His question: how does meaning get into a system that only manipulates symbols according to formal rules? His image: try to learn Chinese exclusively from a Chinese-Chinese dictionary. Every character is explained by other characters, and those in turn by more characters – you go around in circles without ever arriving at the thing itself. Symbols refer to symbols; nowhere does the system touch the world.
I usually hesitate to drag cognitive science papers into everyday debates, because that often creates more fog than clarity. But here the analogy fits uncomfortably well. A language model knows text about the world, not the world. It has read what people have written about HTTP clients, about retries, about exponential backoff – and has learned statistical relationships between tokens from it. In any case, the answer in my opening scene gave no hint of a check against the thing itself: no compiler rejecting the call, no test turning red, no production alerting at three in the morning. Where I as a developer have calibrated my concepts against experience, the model has calibrated its concepts against other concepts. The dictionary explains itself, and it explains itself fluently.
You don’t have to adopt Harnad’s problem in its full philosophical sharpness to see the practical core: a system whose entire “knowledge” consists of text statistics can’t tell a plausible invention from a fact, because both are made of the same stuff. For the model, `withRetry` was just as real as any method that actually exists – a likely symbol among other symbols.
## Why bigger models mitigate the problem but don’t solve it
The objection is obvious: the models have gotten better, haven’t they? In my work, at any rate, I now rarely catch current models making things up freely when it comes to public, well-documented knowledge.
But “more rarely” only means “less often”, not “fundamentally different”. The mechanism stays the same: a bigger model has learned finer statistical relationships – it guesses less often because it has seen more, not because it has stopped guessing. At the point where its material ends, it still produces the most likely continuation, in the same confident tone. The line between knowledge and guesswork moves outward, but it doesn’t disappear, and the model still doesn’t show it to me. That is exactly what makes the remaining cases so treacherous: the rarer the error, the less I expect it – and the more unchecked the suggestion goes through.
## Without internal sources, organization-specific facts remain guesswork
And that brings me to the point that occupies me most in my daily work. Everything said so far applies to public knowledge – React, PostgreSQL, the AWS APIs. There I rarely see the model guess – the public material is huge. But the moment I open the door to a specific organization, the ratio flips. Because what counts there isn’t reliably accessible to the model without provided internal sources:
- the internal libraries and services with their actual signatures and quirks
- the in-house conventions – how errors are handled, how modules are split, what a deployment has to go through
- the terms of the domain that mean something precise inside the company and something else or nothing at all outside it
The case from the opening scene showed me how far this goes. The model had never seen our HTTP client, so it invented it – and did so in the way such a client typically looks. That’s why the suggestion was so good: it was the ideal form of an internal HTTP client, distilled from public patterns. Just not ours. Without an internal source, the actual signatures couldn’t reliably be derived by the model; the invention was an obvious move and looked deceptively similar to real knowledge, because the model is so good at continuing the style of a codebase.
In hindsight, this also explains why my attempts with instruction files went so sobering – I told that story in detail in the last part. Back then I still thought the problem was compliance: the AI doesn’t stick to our rules, so the rules have to be stated more clearly, more strictly, more prominently. But even if an AGENTS.md were followed perfectly, it answers the wrong question. An instruction tells the system how to behave. It can’t give it what it actually lacks: the facts. “Don’t invent methods” is a helpless instruction to a system that doesn’t notice when it invents. The model doesn’t lack the will; it lacks the material. I was working on the motivation of a system that doesn’t have a motivation problem but a knowledge problem.
## Grounding: providing internal facts in the working context
For this answer to the knowledge problem, I use the term grounding here – anchoring answers in verifiable facts. At its core, the idea is simple. If the model can’t know my reality from training, then I have to give it that reality at the time of the work: the real signature instead of the likely one, the actual schema instead of the typical one, our convention instead of the industry standard. Not as a rule of behavior, but as material. The model should be able to look things up instead of having to guess – roughly the way a good IDE with type information keeps me from typing method names from memory.
Here I use grounding for providing concrete source material in the working context, and I thereby distinguish it from mere instructions that formulate rules of behavior. Grounding is not a product and not a feature you switch on. It is first of all an insight about the division of labor: the model provides language understanding, pattern recognition and synthesis – the facts about my world have to come from my world itself. And, to be honest, it isn’t a complete solution either. A grounded model can still connect the facts it was given incorrectly, and if you have ever tried to dump “simply all the documents” into the context, you know that this brings new problems. The difference lies elsewhere: with a grounded system, I argue about the quality of my sources. Without sources, I check free additions drawn from general patterns.
With that, the conclusion of this part is settled, even if it saves no one any work: better models and stricter instructions don’t reliably eliminate convincing wrong answers. Grounding provides concrete source material where the system would otherwise have to fill in from general patterns. Which is where the real work begins – because “provide internal facts” is quickly said. Which facts, exactly, in what form, at which point in the workflow? That is not a rhetorical question but the next part.
## Further reading
- [Stevan Harnad: The Symbol Grounding Problem (Physica D, 1990)](https://doi.org/10.1016/0167-2789(90)90087-6) – the original paper with the dictionary argument
- [Ziwei Xu et al.: Hallucination is Inevitable – An Innate Limitation of Large Language Models (2024)](https://arxiv.org/abs/2401.11817) – the formal argument that hallucination cannot be eliminated for this class of models
- [OpenAI: Why Language Models Hallucinate](https://openai.com/index/why-language-models-hallucinate/) – why training and evaluation incentives can reward guessing (retrieved in August 2026)
- [Lilian Weng: Extrinsic Hallucinations in LLMs (2024)](https://lilianweng.github.io/posts/2024-07-07-hallucination/) – a detailed overview of causes, measurement and countermeasures
---
# My Success Cannot Be Copied
URL: https://www.mikebild.dev/en/blog/my-success-cannot-be-copied/
Date: 2026-03-04
In February, a colleague – an experienced developer with good judgment, no beginner – asked me whether he could have my setup. He had watched me work with Claude Code for weeks and wanted the same: the same tools, the same configuration, the same results. I gave him everything. The complete toolchain. My instruction files, grown over months. My prompt collection for recurring tasks, my checklists for reviews, even my notes on which tasks I delegate and which I do not. There was no secret remainder. He really had everything I have.
*Part 5 of the series “From Session to System” – [start here with the opener](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).*
Two weeks later, we sat down for coffee, and he was disillusioned. Not frustrated in the sense of “the tool is useless” – he had had some genuinely useful moments. But what he had seen with me, the matter-of-factness with which tasks go out and checked results come back, did not happen for him. For him, the AI went in the wrong direction three times, built things he did not want, and he spent more time cleaning up than he used to spend writing the code himself. His sentence stuck with me: “I have your setup. Why don’t I have your results?”
The question occupied me longer than any tool problem of the past months. Because the obvious answers are all wrong. It was not the model – we used the same one. Not the configuration – it was identical, file for file. Not a lack of experience as a developer – he is at least as good as I am. What he was missing was not in any of the files I had given him. And that is exactly the point where this series has to make the leap: from me to the team. So far, I have described why the harness matters more than the model and [what makes me uneasy about my own way of working](https://www.mikebild.dev/en/blog/what-i-am-critical-of/). Both were the perspective of an individual. As soon as a second person comes into play, a problem shows up that I had previously only suspected: variance. And on three levels at once.
## First level: the same task, two sessions, two results
The first level has nothing to do with my colleague yet. I can demonstrate it on my own machine.
I give the same AI the same task twice – under largely the same visible conditions: same prompt, same repository, same instruction files. Session one decides to read the tests first, finds an existing pattern there and extends it cleanly. Session two jumps straight into the production code, considers a helper function unused, removes it “while it is at it” and delivers a solution that runs but is cut differently from everything around it. Both sessions got the same assignment. Both report confidently that they are done. The results differ in structure, style and side effects.
In my runs, even early decisions differed – for example which file was read first or which pattern served as the model. After that, the subsequent steps diverged too.
For me alone, that is manageable. I have learned to check results instead of prescribing paths, and in episode 3 I described how much of this the harness catches: tools, feedback loops, check steps. But even here, the mistake of confusing “best practices” with reproducible results becomes apparent: the same success case cannot be repeated exactly. When I show my colleague how great a session went yesterday, I am showing him a single run – even for me, the next one would look different.
## Second level: the knowledge that is in no file
The second level is the one where my colleague actually failed. And it is more uncomfortable, because it disguises itself as a tool question but is a question of experience.
When we talked through his disillusioning two weeks, I noticed: he did the same things I do – just in different places. He delegated, but the wrong tasks. He checked, but looked at the wrong things. He stopped, but too late. Three examples from our conversation:
- He gave the AI a task I would never delegate as a whole – a change across three modules with unclear domain logic – and was surprised by the chaos. I would have cut it into three checkable chunks beforehand. This cut is not in any of my prompts; I make it in my head before I even start typing.
- He read the AI’s explanations and found them convincing. I hardly read the explanations anymore – I look at the diff, the tests and the places where, in my experience, unwanted side effects occur. Where you look is judgment, not configuration.
- He had a session make three rounds of fixes before he gave up. I stop after the first failed fix attempt and rephrase the task, because I have learned: once the direction is wrong, steering back costs more than starting over. That is not written down anywhere either – this stopping rule comes from repeated failed attempts.
How you cut tasks, where you look when reviewing, when you stop – that is tacit knowledge in the classic sense. You acquire it through friction, not through reading. My instruction files are the sediment of this knowledge, but they are not the knowledge itself. They tell the AI what to do. They do not tell my colleague what *he* should do while the AI is working.
The [METR study from summer 2025](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) made a related effect measurable: for experienced open source developers, tasks with early-2025 AI tools took 19 percent *longer* on average – even though the participants expected to save time. You can argue about how far the study generalizes; the conditions were special. But the documented finding fits what I saw with my colleague: expected time savings and measured working time can diverge.
## Third level: there is no identical run
The third level is often overlooked because it sounds so banal: my colleague works on different tasks than I do.
Not fundamentally different – same company, related systems, a similar stack. But his specific task on a specific Tuesday is never my specific task. His module has a different history, different legacy, different unwritten conventions. His bugs sit in different places. Even if he had my judgment and the session lottery went his way: he still could not reproduce my success, because the experimental setup “same task” simply does not exist in real work.
That fundamentally distinguishes AI tools from almost everything we have introduced in teams before. Formatters and CI pipelines aim for reproducible execution under the same version, configuration and environment; a framework API provides the same contract. With these tools, the rule is: one person finds the good configuration, everyone adopts it, everyone gets the benefit. This exact pattern is what we all have in mind when we say “share the setup” – and this exact pattern does not apply here. The benefit of an AI session comes from the interplay of task, context, person and chance. Three of these four factors are different for every team member.
## What organizations regularly conclude wrongly from this
At the organizational level, these differences can lead to false productivity assumptions. Because the individual observation “it works for Mike” invites three fallacies.
The first fallacy: license bought means team productive. An enterprise procures access for all developers, books it as “AI adoption” and expects the productivity leap that the power users showed in the pilot project. But the power users were fast precisely because they had built up tacit knowledge over months. The license buys the tool, not the second level. The [2025 DORA report](https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report) puts it in a formula I have been quoting constantly ever since: AI amplifies what is already there. Teams with good feedback loops and clean architecture get better; teams with weak processes get their weaknesses back amplified.
The second fallacy: sharing a prompt library is a rollout. That was my own mistake with my colleague, just on a small scale. Prompts and instruction files are sediment – useful, but dead without the practice they came from. A shared prompt collection without shared judgment produces people who read convincing explanations instead of checking diffs. The [2025 Stack Overflow survey](https://survey.stackoverflow.co/2025/ai/) shows the consequences at scale: AI tools are widely used, but trust remains limited, and a frequently cited frustration is code that is “almost right.” Recognizing almost right is exactly the ability that cannot be distributed by file alone.
The third fallacy: what works in the pilot scales linearly. It does not, because of all three levels of variance at once. A pilot can include motivated power users (person variance), selected tasks that are easy to cut (task variance) and selectively reported success stories – failed sessions may be missing from the management presentation (session variance). If you build a projection for 200 developers from that, you may be calculating with an unrepresentative average.
I put it pointedly because I already used the sentence in [episode 4](https://www.mikebild.dev/en/blog/what-i-am-critical-of/) and here it describes the organizational consequence: the success stories of individuals are real, and they are still not a blueprint. Tools, tests, conventions and acceptance criteria can be copied. My concrete result also arises from task, context, review judgment and the course of the session. No setup file transfers that part.
## Variance is also a source of learning
This sounds bleaker than I mean it. Because the same variance that prevents copying is a useful diagnostic source for a team.
When my colleague and I dissected his two weeks, something remarkable happened: for the first time, I had to say out loud *why* I cut tasks the way I do. Why I ignore explanations and read diffs. Why I stop after one failed fix attempt. That was tacit knowledge that I had not perceived as knowledge myself – for me, it was simply “how you do it.” Only the difference between his way of working and mine made it visible. Exactly where two people do the same thing differently, the tacit knowledge lies in plain sight. You just have to look instead of dismissing the difference as a failure of the slower one.
My conclusion after that February: if individual experiences are to flow together in a team, the prompts are not the valuable part. The differences are. Two developers, the same class of task, different results – that is not an annoyance; it is a finding. Each of these differences points to an unspoken rule, a heuristic, a piece of judgment that so far existed only in one head.
By the way, my colleague still works with the setup – now with his own instruction files that differ more and more from mine, and with much better results. Not because he copies me better now, but because he stopped trying. What he took over from me is not the files. It is the questions he asks himself before every delegation.
And that brings me to the consequence that every team sets out to draw at this point, mine included: if the decisive knowledge is tacit, then we simply make it explicit. We sit down, spell out the rules that so far existed only in heads and write them down – in exactly the files the AI reads in every session. Task cutting, review rules, stopping criteria, all of it goes in. That has to be enough. Why it is not – and why the AI follows our carefully written rules surprisingly selectively – is what the next episode is about.
## Further reading
- [METR: Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/)
- [Google Cloud: Announcing the 2025 DORA Report](https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report)
- [Stack Overflow Developer Survey 2025: AI](https://survey.stackoverflow.co/2025/ai/)
---
# What I Am Critical Of
URL: https://www.mikebild.dev/en/blog/what-i-am-critical-of/
Date: 2026-02-10
On a Thursday evening in January, I almost waved through a pull request that I had commissioned myself. Claude Code had written a database migration, cleanly formatted, with comments, with a rollback path. I read it, nodded, already had the mouse pointer over the merge button – and then, more out of habit than mistrust, I took a look at the affected table in the staging system after all. The migration would have worked. It would just, on the side, have renamed a column that a report accesses, a report the session could not have known about. No drama, quickly found. But the moment before still occupies me today: I had not checked. I had read it the way you read a well-written text – benevolently, going with the flow.
*Part 4 of the series “From Session to System” – [the series opener is here](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).*
In the last installment, I described why delegating to AI only works for me with a good harness – with tools, feedback and guardrails around the model. At the end there was an unease that has grown louder with every delegated task. Today I want to take this unease seriously. Not as an alarm – I keep working with these tools every day, gladly and productively. But as what criticism should actually be: looking closely before you carry on. In doing so, I separate four observations from one open hypothesis.
## If you only review, you unlearn building
When I rarely write code myself, I now have to distinguish more carefully: am I only missing an API signature, or am I missing practice in the routine? If you need a rarely used library function, you look up its signature – that has always been the case and is not a problem. The problem would be the direction of the movement: if it is no longer just the exception that gets looked up but the routine disappears altogether, the repetition from which fluency arises is missing. Whether and how fast this happens to me, I cannot measure. That is why I deliberately do certain routine tasks without AI and pay attention to where I lack practice.
The CHI 2025 study by Microsoft Research and Carnegie Mellon surveyed 319 knowledge workers on this. In the self-reports, higher confidence in generative AI was associated with less critical thinking being applied. That is a correlation in a survey, not evidence that skills have already eroded. My worry goes one step further than the study’s result: if you hand off routine work and only deal with the exceptions, you could lose exactly the practice you need for the exceptions.
For me, this is a creeping risk that I can actively manage. What concerns me more is what the math looks like for people starting their careers. I learned my craft by falling flat on my face often enough: hunting memory leaks myself, building race conditions myself and understanding them myself. If, during the learning phase, you mostly review generated code, you may get fewer opportunities to build up this substance – that is a guess, not a measurement, and the survey cited says nothing about it. Concretely, what would then be missing is the experience that makes good reviewing possible in the first place: being able to judge whether a timeout, a lock or an error handling approach fits your own system, because you have made such decisions yourself and borne their consequences.
## Plausible is not correct
The scene from the beginning has a name: automation bias. A systematic review by Goddard, Roudsari and Wyatt describes it as the tendency to follow automated recommendations and overlook contradictory cues – the research on it is older than the current language models. In my migration, the clean formatting, the comments and the included rollback path amplified exactly this impression of trustworthiness: I almost approved what I had not checked.
Whether review and the four-eyes principle work systematically worse against such plausible output than against visibly sloppy code, I cannot prove.
In line with this, Perry and colleagues showed in a controlled study that participants with an AI assistant wrote insecure code more often and at the same time were more convinced that they had written secure code. The study does not examine code reviews. For my review practice, the combination is therefore a warning sign, not evidence of effectiveness.
## “That’s how the AI did it” is not an answer
In a review, “That’s what the AI suggested to me” is not enough as a justification for me. The sentence explains the origin, but not the decision. Why is the timeout set to thirty seconds here? Why is that right for our system? If no answer follows, the decision is not justified in the review – because the session that chose the value ended long ago and took its reasons, if there were any, with it.
In a review, there is no third party. There is the person who submits the code and the person who approves it – both with names, both reachable, both still around tomorrow. What the tool suggested is as relevant as the question of which editor the code was typed in. If you open a pull request, you are saying: I stand behind this. If this commitment dissolves because “the AI” is in the room as a diffuse co-author, the review loses its core. Then two people review something nobody feels responsible for.
## Debt that nobody took on
Technical debt can arise from deliberate shortcuts: we build the quick solution now and clean up later. You knew the shortcuts you took deliberately and their consequences. Next to that, I see a possible second variant: code that works, passes all tests – and that nobody on the team really understands. Not because it is incomprehensible, but because nobody ever had to understand it. It was generated, it ran, it was merged.
If a team only roughly follows a generated mechanism when it is built in, the next change may require reconstructing assumptions and the reasons behind decisions before the mechanism can be changed safely. Then technical debt may have arisen without anyone having taken it on deliberately – no note, no decision, no “we’ll clean up later.” Such debt can arise unnoticed because no deliberate shortcut was documented. A system that consists to a larger extent of such code is not broken. It is something worse: not understood while fully functional.
## When everyone asks the same model, designs can become more similar
The last worry is an open hypothesis. A thought experiment makes it tangible: four groups get the same open-ended design task, and all four ask their first question to the same model. How different do the results turn out? If everyone starts with a very similar first answer, that answer can shape the rest of the design. The effect has not been measured and depends, among other things, on the prompt, context, sampling and model. The Microsoft study mentioned does not examine it.
You can shrug and say: converging on proven patterns is a good thing. That is partly true – I am the last person to find an unusual solution good just because it is unusual. But architectural diversity is not an end in itself; it is a search process. Different designs make alternative assumptions and trade-offs visible. My worry is therefore: if many design decisions run through the same filter, the space of seriously considered alternatives narrows. I cannot measure that.
## Criticism does not mean rejection
At this point, the text could tip over – into cultural pessimism, into “back then we still did real programming.” That would be convenient and wrong. None of these points is an argument against the tools. Each one is an argument against a particular way of using them: the passive one. Skills do not decay because AI exists but because I stop practicing. Automation bias strikes because I confuse plausibility with correctness. Responsibility diffuses because I let it diffuse. That is the catch: the answer does not lie in the next model release. It lies with me.
I have set up a few rules for myself. No words of wisdom, more like house rules:
- Regularly work deliberately without AI. Not a ritual of renunciation, more like a run without a watch: certain tasks – an algorithm, a data model, a tricky bug fix – by hand, to feel where it snags. Where it snags, I check whether I lack practice or whether I just do not have a rarely used API at hand.
- An obligation to understand before the merge. Nothing goes into the main branch that I could not explain to a colleague at the whiteboard – line by line for critical spots. Critical spots are, for example, possible data loss, permission checks, concurrency and public APIs. “Roughly followed” does not count.
- My own judgment first, then the model. For design questions, I write down my position in three sentences before I ask. It does not have to be the better one; it is an anchor against the plausible first answer – deviations then become real information.
- Name the origin, keep the responsibility. When code was generated, I say so openly in the review – and take it on anyway as if I had typed it.
None of this is original. The extra review costs me time, but it makes the approval more traceable. And I notice: it takes effort. In everyday work, it is easier to skip it.
But this is exactly where the reach of this text ends. Everything I have described here are measures of an individual – my rules, my discipline, my house rules. That reaches exactly as far as my self-control does, and on bad days it reaches surprisingly little. A team cannot rely on the private discipline of its members; ten people with ten different sets of house rules do not yet make a shared way of working. What happens to these observations when not one person works like this but an entire team – with different experience, different levels of care and deadline pressure on top – that is the question I have set myself for the next installment.
## Further reading
- [The Impact of Generative AI on Critical Thinking (Microsoft Research / Carnegie Mellon, CHI 2025)](https://www.microsoft.com/en-us/research/publication/the-impact-of-generative-ai-on-critical-thinking-self-reported-reductions-in-cognitive-effort-and-confidence-effects-from-a-survey-of-knowledge-workers/)
- [Kate Goddard, Abdul Roudsari, Jeremy C. Wyatt: Automation bias – a systematic review of frequency, effect mediators, and mitigators (JAMIA, 2012)](https://academic.oup.com/jamia/article/19/1/121/732254)
- [Neil Perry, Megha Srivastava, Deepak Kumar, Dan Boneh: Do Users Write More Insecure Code with AI Assistants? (arXiv, 2022)](https://arxiv.org/abs/2211.03622)
---
# Good Enough: The Model Is Rarely the Bottleneck
URL: https://www.mikebild.dev/en/blog/good-enough-models/
Date: 2025-12-09
*Part 2 of the series “From Session to System” – [start with the opening post](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).*
End of November, an architecture review with a team I support, day two, first coffee break. A developer walks over to me, cup in hand, and asks the question that has come up in every team conversation and every hallway chat at conferences for two years: “Which model do you use?” This time with particular urgency, because November 2025 was wild: GPT-5.1 on the 12th, Grok 4.1 on the 17th, Gemini 3 on the 18th, Claude Opus 4.5 on the 24th. Four flagship announcements in twelve days, plus the usual benchmark screenshots making the rounds on the timelines. His team, he tells me, has been discussing for weeks whether they need to switch.
I used to answer this question seriously, with model names and reasons. Every one of those answers was outdated after six weeks. These days I answer differently: “That is the second question. Let’s talk about the first one.”
## The convergence nobody likes to talk about
Looked at soberly and without vendor loyalty: for the large block of everyday tasks I use AI for, the big models were close enough to each other in my own trials at the end of 2025. Reading and explaining code, proposing a refactoring, designing tests, reviewing a concept paper, summarizing API documentation, sketching a migration path – I got that done in usable quality with GPT-5, Claude Sonnet 4.5 and Gemini. Not equally well in every single run, but well enough that the choice of model was rarely my first construction site.
Of course they are not identical. Every model has its own tone, its own preferences, its own weaknesses, and for individual tasks the differences can be large. Public benchmarks only help me to a limited extent, because they reflect neither my context nor my review criteria and shift quickly with new versions. For an architecture decision, I therefore need measurements on my own tasks rather than a general ranking.
I do not like to be the first to say this in such meetings, because it cools down the discussion everyone was looking forward to. The model comparison is entertaining, it feels like engineering work, and it has the charm that you do not have to change anything about your own way of working. But it answers the wrong question.
## The noise in daily work is larger than the difference between models
When a session with Claude or ChatGPT goes wrong for me, it is almost never because of the model. It is because I stated the task unclearly. Because the model did not know the context that was decisive for the solution – the architecture decision from two years ago, the unwritten convention in the team, the reason why this one service is built differently from all the others. Or because I did not check the result and the mistake only surfaced in review.
An example from a team conversation at a large enterprise, anonymized as always: two colleagues, the same model, the same task – understand a piece of legacy code and propose a restructuring. One got a usable, concrete plan. The other got generic textbook text. The difference was not the model, not even the prompt in the narrow sense. One had given the model the relevant files, the test cases and the constraints. The other had typed a question into an empty window.
In my own sessions, the result often varies more with how the task is cut, the context and the verification than with switching between the top models under consideration. That is not a general measurement of the market, but an observation from this work. For me it follows: before I switch models, I first check whether task, context and acceptance criterion are clean enough.
## If you bet on the best model, you bet on a commodity
That brings me to the thesis I consider the most important in this post: if you build your way of working, let alone your product, on “the best model,” you are betting on a commodity you do not own.
The models belong to a handful of vendors. I rent access through an API key or a subscription, just like my competitor, just like every other team. I cannot control when a version is deprecated, when behavior quietly shifts after an update, when the price drops or the next model upends the ranking. November demonstrated this: if you based your choice in October on a benchmark lead, you saw that lead change hands three times within two weeks.
What I can own, on the other hand, is the layer around the model. That is not a platform and not a product, but simply everything I have in my own hands before and after the model computes:
- how the tasks are cut, meaning the ability to break work down so that a piece of it becomes delegable
- the context a session gets at the start, instead of the model having to guess my reality
- the team’s knowledge in retrievable form, from conventions to the reasons behind old decisions
- the process that governs when the AI works, when a person reviews and what may go into the main branch
- the verification itself, meaning reliable ways to determine whether a result is correct before it has any effect
This layer is the opposite of a commodity. It is specific to my team, my codebase, my domain. Nobody can take it away from me with a release, and the competitor cannot simply rent it too. Above all: it survives model changes. An hour I invest in better task descriptions, in a well-maintained CLAUDE.md or AGENTS.md, in review criteria still pays off with the model after next. An hour of studying benchmarks is devalued with the next release.
There is a pleasant side effect that I know from architecture work: if you own the layer, your switching costs drop. When task cutting, context and verification are solid, the model behind them is as replaceable as a dependency behind a clear interface. Then I can even switch calmly when there is a real reason – because my actual capital does not hang on the model name.
## Where the choice of model does matter
Honesty is part of this, otherwise the thesis turns into dogma. There are situations in which the choice of model plays a real, measurable role. I run into three of them regularly.
First, the special cases. If you work with exotic languages or niche frameworks, have strongly multimodal tasks or have to stay on-premises for data protection reasons, you quickly end up with smaller open models – and there the quality differences are real and the trade-offs are different. “Good enough” applies to the large frontier models for everyday tasks, not to every class of model for every task.
Second, cost and latency. As soon as models no longer run interactively but in volume – classification in a pipeline, autocompletion in the editor, processing thousands of documents – price per token and response time become hard criteria. Between models there are factors there, not percentage points, and measuring pays off.
Third, long, agentic tasks. This is where the models still really differ noticeably at the end of 2025: how long they stay focused on a multi-step task, how reliably they operate tools, how they deal with their own mistakes. It is no coincidence that Claude Sonnet 4.5 in September and Opus 4.5 in November were promoted on exactly this capability. If you delegate entire work packages instead of individual questions, you may be picky about the choice of model.
But – and this matters more to me than the three exceptions themselves – all of this is the second question. It can only be answered seriously once the first one has been answered. Without a clear cut of the task and without reliable verification, I cannot compare models at all; I am then only comparing gut feelings on different days. Only when the layer is in place does the choice of model become what it should be: an optimization with measurements, roughly as exciting as choosing a database index. And as there, the rule is: reassess occasionally, pin versions deliberately, take behavior changes after updates seriously. “Good enough” means neither “all the same” nor “forever” – it just means: not the bottleneck.
## The first question
Back to the coffee break. Stick with the model you have, I told him, and put your team’s discussion energy into the questions before and after. How do you recognize that a result is correct? What would a session need to know about your system so it does not have to guess? Which of your tasks are even cut in a way that lets you hand them off? If you answer these three questions well, you get more out of any of the current models than your neighbor with the benchmark winner and an empty context window.
He was visibly unhappy – the answer is less spectacular than a model comparison, and it means work. But it has a consequence that has occupied me ever since and that carries the rest of this series: if the model is rarely the bottleneck, then something else makes the difference between the session that delivers and the one that burns time. For me, it comes down every time to the environment the model works in – how much it shows the model, what it allows it to do and what it checks its results against. That is exactly where the next post picks up.
## Further reading
- [Anthropic: Introducing Claude Opus 4.5](https://www.anthropic.com/news/claude-opus-4-5)
- [Google: Gemini 3 – Google’s most capable model yet](https://blog.google/products/gemini/gemini-3/)
- [Simon Willison: Claude Sonnet 4.5 is probably the best coding model in the world (at least for now)](https://simonwillison.net/2025/Sep/29/claude-sonnet-4-5/)
- [Anthropic Engineering: Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
---
# From Tool to Way of Working
URL: https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/
Date: 2025-11-18
*Opening of the series “From Session to System”.*
Some time ago, I sat down with [Sebastian Korfmann](https://skorfmann.com/) in Berlin. I know Sebastian as a software engineer from the cloud and infrastructure world – someone who doesn’t judge tools by marketing slides, but by whether they take work off his hands in everyday life. He told me about his experiences with AI tools: what he builds with them, how his work has changed, where things get stuck. I listened with interest – and noticed that I had surprisingly little to contribute myself.
I need to explain that. I have been working on software for more than thirty years, a large part of it on distributed systems – Node, TypeScript, GraphQL, cloud architectures – and for many years I gave training for software developers and architects. What appeals to me most about this work: building digital products, and doing it holistically. Really understanding the domain, making decisions about direction, shaping things – for a long time now, it hasn’t been just about programming and architecture for me. Over the years, my focus has shifted too: away from having every fine detail in my own hands, toward structure, consistency, processes, productivity, methods and concepts. Still, I had never worked with AI up to that point. Not a single session, no Copilot. Not out of rejection – fundamental skepticism toward new technology isn’t my style. It simply had never come up. The hype since the launch of ChatGPT at the end of 2022 was impossible to miss – headlines, conference keynotes, colleagues talking about it – but what I heard and read sounded to me like impressive demos, and my days were full. If anything, I was a little reserved – the way you are reserved about things you haven’t tried yourself yet.
There was something else, too, and I don’t like talking about it much, because it has nothing to do with technology and everything to do with me. I had grown tired. Not of the profession, but of a particular kind of undertaking: my own, larger projects, digital products I had carried around in my head for a long time. I know the complexity of such undertakings well enough to know that I can’t deliver many of these topics alone at the quality I expect of myself. The ideas were there, some of them worked out in detail, in notes and half-started repositories. What was missing was the energy for the sheer amount of implementation work – alongside a job and everything else. If you have ever tried to build a complete product on your own, you know the ratio: for every hour in which you really shape something – a decision about direction, a concept, a piece of the domain – there are twenty hours of grunt work. Boilerplate, configuration, forms, error handling, deployment, documentation, plus all the organizational stuff around it. At some point, I stopped opening new drawers, because the old ones were already full.
That was the state I was in when I met Sebastian. What grabbed me about the conversation was the way he told it: no superlatives, no “this changes everything” rhetoric, but the sober way you tell a colleague about a tool that has proven itself in everyday work. I knew that tone, and it made me curious. So I resolved to finally try it out myself. Not for ten minutes, but for a few days, on real tasks.
## The first days
I started with Claude and ChatGPT, in the browser, on tasks from my actual everyday work: reviewing an architecture concept, sketching an API migration, writing a data import I would otherwise have kept putting off. Shortly afterward, Claude Code and Codex joined in – the tools that don’t just answer, but work directly on the repository in the terminal: reading files, changing them, running tests. Anthropic had released Claude Sonnet 4.5 at the end of September, and OpenAI its Codex update at about the same time; without planning it, I got started at a pretty good moment.
And then something happened that I hadn’t expected: within days, I was very taken with it. Not mildly interested – taken. Three things got me:
- The speed. Tasks for which I would have planned half a day were, within an hour, in a state I could seriously review.
- The productivity across the whole day. Not a single impressive moment, but the sum: in the evening, measurably more was done than before.
- The quality. I had expected that least of all. The generated code wasn’t bug-free, but considerably better than I would have expected after everything I had heard and read about generated code – structured, with sensible error handling, often with tests.
The few days of trying turned into weeks of daily work. By now, I work with these tools every day and keep going deeper – Anthropic has just followed up with skills, a way to give Claude reusable working instructions, and I notice that I am starting to read such announcements the way I used to read Node release notes.
A few weeks are not experience. I am aware of that, and that is exactly why I am writing this down. If you become a daily user this quickly, you should distrust your own enthusiasm for now – fresh enthusiasm is a poor witness. So I try to look closely and note down what I actually observe – with the only touchstone I have: more than thirty years of craft against which I can measure every result.
## Observation one: generating gets cheap, checking becomes the bottleneck
I noticed the first shift after just a few days, and it is more fundamental than it sounds. The expensive part of my work was always generating: writing code, wording documents, working out concepts. Checking – reviews, proofreading, acceptance – was the smaller item. That ratio is flipping right now. Generating is suddenly cheap; in one hour, more text and code come into being than I used to manage in a day. What hasn’t gotten cheaper: judging whether what was generated is right. My work is visibly shifting from writing to reading, from producing to assessing.
In a conversation with a colleague, I found a phrase for this that stuck: the tool is less an assistant, more a secretary. An assistant, as the product names promise, adds a line here and suggests a word there – the work stays mine. A secretary in the old sense takes on entire matters: I dictate the intent, they draw up the document, and I sign off. That sounds more convenient, but it is a different responsibility. With an assistant, I check suggestions in passing; with a secretary, I really have to read the finished piece, because my signature is underneath. If you sign without reading, you haven’t delegated, you have capitulated. I suspect that the real overhaul of my way of working lies in this shift – not in the tool itself.
## Observation two: the drawers open again
The second observation is more personal, and it surprised me more than any benchmark. The tiredness I wrote about above isn’t gone – but it has lost its reason. The product ideas that were left lying around because implementing them was too big for one person are suddenly within reach again. Not because the AI builds the product. But because it takes over exactly the part that wore me down: the twenty hours of grunt work around the one hour that really requires thinking. The form scaffolding, the test coverage, the import adapter, the deployment script – all of this now comes into being so fast that, as the saying goes, I can strike while the iron is hot.
Maybe that is also why the whole thing won me over so quickly: over the years, my focus had shifted to exactly where these tools take nothing away anyway – structure, consistency, concepts, the domain, the decisions about direction. The detailed work, on the other hand, and the recurring tasks, including the organizational ones, come more easily to me again now. Not all of them. But enough that it is fun again.
Over the last few weeks, I have been building my own things again in the evenings, voluntarily and with a joy I hadn’t felt for a while. This is where I have to choose my words carefully, because it is so easily inflated into a gospel. So, soberly: for me, AI is above all a lever for the individual with experience right now. The emphasis is on both. The lever works because, after thirty years, I know what I want to build, how it has to be cut and how I can tell that a result is any good. Whether the same lever also works for someone who doesn’t have this judgment yet, I simply don’t know – I have a suspicion, but suspicion is not knowledge, and for this series I want to keep the two cleanly apart.
## Observation three: the tone is always right
I am only noting the third observation briefly, because I don’t understand it well enough yet to make more of it. I notice *how* these systems answer. In German working life, there is a tongue-in-cheek acronym for it: SABTA – “sicheres Auftreten bei totaler Ahnungslosigkeit”, confident demeanor despite total cluelessness. Psychology knows the pattern as the Dunning-Kruger effect: those who know the least often come across as the most confident. That is exactly how these systems strike me – the right answer and the wrong one come in the same calm, competent tone. In a code review, an unsure colleague gives themselves away through their wording – “I think”, “should actually”. Here, that signal doesn’t exist. Twice in the past few weeks, I almost adopted a claim that turned out, when checked, to be completely made up – an API signature that never existed, delivered with confidence. Both times, only my habit of looking things up saved me. This confident demeanor deserves fundamental distrust, and I want to understand where it comes from – structurally, not anecdotally. I am saving that for later in this series, once I have gathered enough observations.
## What this series is meant to be
I am starting a series here because I suspect the story is bigger than my desk. Right now, I am observing myself: one individual in the session, with direct control over every result. But I don’t work alone – I work in and with teams, and a team is something other than the sum of individual sessions. And above the teams are companies with their processes, their knowledge, their responsibility. I want to walk through this arc step by step in the coming installments: from me through us to the system. Not as theory, but along what I actually experience and try out – including the dead ends, of which there will predictably be a few.
The next question is already pressing. In the team, at lunch among colleagues, most recently in a conference hallway: after a few minutes, the conversation lands in the same place. Which model is the best? Claude or GPT, which version, which benchmark. I have had this discussion myself and developed an unease I am only gradually able to place: after these first weeks of daily work, I notice that the choice of model has changed my results less than pretty much everything else about my way of working. Everyone is talking about the best model – but is that even the right question? I will pursue it in the next installment.
## Further reading
- [Introducing Claude Sonnet 4.5](https://www.anthropic.com/news/claude-sonnet-4-5) – Anthropic’s announcement of the model I started with (September 2025)
- [Claude Sonnet 4.5 is probably the “best coding model in the world”](https://simonwillison.net/2025/Sep/29/claude-sonnet-4-5/) – Simon Willison’s sober first assessment
- [Introducing upgrades to Codex](https://openai.com/index/introducing-upgrades-to-codex/) – OpenAI’s Codex update with GPT-5-Codex (September 2025)
- [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) – Anthropic’s engineering post on skills (October 2025)
---
# React Overview: From JSX to Component Architecture
URL: https://www.mikebild.dev/en/blog/react-overview-from-jsx-to-component-architecture/
Date: 2024-12-30
# React Overview: From JSX to Component Architecture
React takes rendering off your hands, not architecture. The library computes a UI from a state and writes the differences to the DOM – but where this state lives, how long it lives and who may change it is something it never decides. Right there, at this inconspicuous boundary, the problems arise that you can no longer clean up later with any hook or library.
That’s why this post goes through React in one go – from the first piece of JSX to the point where individual components turn into a system. It is deliberately an overview. For most of the stops I only touch on briefly here, separate posts that dig deeper will follow. Today the goal is to have the big picture in your head before you get lost in a detail.
I rely on two repositories that I’m currently merging: `introduction-react` for the fundamentals and `advanced-react` for the advanced patterns. Neither is a slide deck in text form; both are runnable code that we practice on together. The version I describe here is React 19 – the stable release from late 2024, with everything that has become everyday practice since.
## The mental model: the UI is a function of state
Before a single line of JSX makes sense, one idea has to sink in. React flips the way you think about a UI. Instead of describing step by step how the DOM should change – insert an element here, change an attribute there, remove a node over there –, you only describe what the UI should look like for a given state. React takes care of getting there.
You can put this into a single sentence that carries everything else: the UI is a function of state. When the state changes, React calls the function again, compares the result with the previous one and writes only the actual differences to the real DOM. This reconciliation runs on an internal, lightweight representation of the tree, often called the Virtual DOM. The name matters less than the consequence: you describe the destination, not the route. I show how this reconciliation works step by step in detail in the post [How React Renders and Updates the Tree](https://www.mikebild.dev/en/blog/how-react-renders-and-updates-the-tree/).
```mermaid
flowchart LR
State["State"] --> Render["Component renders"]
Render --> View["Described UI"]
View --> DOM["React reconciles and writes to the DOM"]
User["User interaction"] --> Event["Event / setState"]
Event --> State
```
The second load-bearing idea is unidirectional data flow. Data flows from top to bottom, from the parent component to the child, via props. Events flow in the other direction, upward as callbacks. There is no mysterious two-way binding in which an input field and a variable magically stay in sync. At first this feels more cumbersome than in older frameworks, but it is the reason React applications can still be explained after two years: for every spot in the UI, you can say where its data comes from and who may change it.
## JSX and components: the smallest unit is a function
JSX looks like HTML inside JavaScript, but it’s just a convenient notation for function calls. A `