Markus Eisele observes that when agents produce code quickly, teams often end up with a separate, stale corpus of documentation sitting next to the repository: requirements, research notes, high- and low-level designs, implementation plans, task lists, review reports and growing stacks of Markdown that explain what the code is supposed to mean. The code may have changed last Tuesday while the documentation was last updated weeks ago.
This effect is not new — code and documentation have evolved in parallel for as long as many can remember — but fast agent-based code generation amplifies the problem. Teams try to control drift by moving more thinking ahead of implementation and making Markdown artefacts the drivers of workflow: requirements, decision records, design approaches and acceptance criteria.
Natural language is limited
A large natural-language specification can fill a significant portion of an agent’s context window before any relevant source code is loaded. Natural-language specs are a weak synchronization mechanism for agents: without ongoing attention, agents tend to shift to stronger signals in the codebase and forget to update prose.
Eisele does not advocate one-shot prompts or "vibe coding": some specification is necessary. The mistake is treating a spec as a permanent prose copy of the software. A useful spec describes the next change, the decisions that drive it, boundaries and verification surface — but most of it should be removed once the change ships.
The change brief
Eisele prefers a short, targeted document he calls a “change brief” rather than a heavyweight “specification.” A change brief describes the delta between current and desired behavior. It should include:
- The intended outcome and non-goals (where necessary)
- Known unknowns and decisions requiring human judgement
- Affected system boundaries and authoritative interface artifacts
- Functional and non-functional constraints that differ from today
- Acceptance criteria / test scenarios covering risky paths
A change brief is temporary by default; after implementation, durable information should move into code, schemas, tests, policies and operational signals.
Code is the fact
Code represents actual behavior. When code is deployed to production, users and connected systems depend on it. Runtime behavior becomes the strongest signal because, over time, even bugs can appear as de facto contracts. For that reason Eisele starts from the production code and operational evidence: reading a natural-language summary cannot substitute for the implemented truth. Code is the ultimate executable specification — albeit written in a deterministic language.
Production code cannot, however, predict policy changes, future feature requests, regulatory retention rules, or customer-specific exceptions. Those contextual inputs must come from elsewhere, but they do not require an everlasting prose description of the entire system. Teams only need enough context to decide the delta.
Discovery during work
A prompt, ticket or change brief captures what is known before work begins. The remainder lives in the codebase, runtime info, configuration and years of decisions embedded in code — some never written down. As agents work they expose unknowns: inspecting a module can reveal an unexpected dependency, a prototype can show awkward UX, tests can uncover edge cases, and prod data can contradict design assumptions.
Discovery happens in three phases:
- Before implementation: inspect the current system and identify decisions that could change architecture or UX; build cheap prototypes when preferences are hard to describe.
- During implementation: record meaningful deviations and reassess when new unknowns change risk or direction.
- After implementation: read the code, run checks, and compare results to the original intent.
The change brief remains part of the loop, but only durable constraints should be promoted.
Keep durable facts in their native form
Promoting durable constraints does not mean converting every decision into permanent Markdown. Many facts are better represented in executable or machine-checkable artefacts:
- API shape and compatibility → OpenAPI, AsyncAPI, protocol schemas, types and compatibility tests
- Data invariants → types, DB constraints, validation and migration checks
- Security rules → access policies, static analysis, dependency policies, runtime enforcement
- Architecture boundaries → module structure, dependency rules, focused architecture tests
- Reliability requirements → load tests, service objectives, telemetry and alerts
- Release rules → CI/CD policies
Natural language still has a role for domain knowledge, business policy and architectural rationale that cannot fit elsewhere. Keep such prose short and placed close to what it explains (e.g., focused Architecture Decision Records) and avoid recording every local choice.
Judgment belongs in the workflow
Heavyweight specification methods try to control quality by prescribing a single path; that tends to focus effort on low-risk work and avoid the deep technical judgement high-risk changes need. Drawing on Simon Willison’s approach, Eisele suggests giving the coding agent the outcome and letting it judge how much process a task requires: some changes deserve minimal process, others need deeper research, prototyping, or human alignment.
Teams must define outcome, safety constraints, ownership and who can accept results. Within those boundaries, the agent chooses tactics and should escalate when uncertainty produces consequences beyond its authority. The workflow should scale to risk:
- Small, familiar changes: short brief → implementation → review (near one-shot prompt)
- Unfamiliar code: factual research before design
- Unclear UX: prototypes and potential user research
- Architectural changes: explicit human alignment
- High-consequence behaviour: stronger independent evidence and approvals
Add processes and artefacts when work becomes risky or unfamiliar; avoid starting every change with full ceremony.
Context is an engineering budget
Large specifications cost more than writing time: they compete with the code and evidence agents need. Every additional requirement, design note or repo instruction consumes limited context and attention. Progressive disclosure works better: give an agent a small map, a few stable rules and pointers to deeper material. A concise AGENTS.md can document build commands, repository layout and architectural boundaries without attempting to narrate every class.
Experience with Research-Plan-Implement shows that huge prompts and plans can reach thousands of lines; teams reviewed plans while treating generated code like compiler output, only to find implementations drifting from the approved plan. Brownfield systems are especially vulnerable.
Modernization and brownfield work
Mature codebases mix durable business logic, platform-constrained code, incident fixes and lingering defects. Modernization requires judgement about what to preserve, verify, redesign or remove. Eisele’s goals for brownfield changes are:
- Preserve durable business invariants and externally required behaviour
- Verify behaviour that appears active but lacks clear ownership or evidence
- Redesign logic tied to obsolete architectural constraints
- Remove dead paths, duplicated logic and confirmed defects
Static analysis and tests help, but Eisele also recommends mutation testing (e.g., PIT) to surface hidden assumptions, and renewed attention to code coverage. Operational context and telemetry are vital to judge existing behaviour.
Small specs still need real evidence
Short specs do not justify loose prompting and hopeful review. Agents can resolve underspecified requests into plausible, internally consistent implementations that hide unapproved business decisions. Research supports focused clarification and independent checks: directly asking models to resolve ambiguity often yields inconsistent or irrelevant results, while targeted repair around identified defects can improve outcomes (~31% improvement in some studies). SWT-Bench found that generated tests can filter proposed fixes and significantly increase repair precision. Attempts to translate natural language into formal specs (e.g., TLA+) by many models achieved limited syntactic and semantic correctness.
These findings argue for clarifying uncertainties that could change outcomes, then verifying implementations with evidence not produced solely by the proposing agent. The strength and independence of evidence should match the consequence of being wrong: ordinary refactors need ordinary tests and reviews; changes affecting security, finance or regulated data need adversarial review and explicit human approval.
A lighter operating model
Eisele proposes a simple five-step workflow:
- Start from the code and operational evidence describing the current system
- Define the intended delta, key boundaries and known unknowns
- Add research, prototypes, design alignment or stronger verification where risk requires them
- Read and review the implementation, not just the plan
- At release, discard temporary reasoning and preserve surviving facts in their native authoritative artefacts
Before implementation the change brief describes the intended delta; during implementation it helps align people and agents while new information changes the plan. After release, code and production behaviour become the primary evidence of what the system does. Durable obligations remain in artifacts we already know how to maintain: schemas, tests, policies, configuration, telemetry and short records for rationale that cannot be encoded elsewhere.
Eisele expects teams to benefit most from coding agents when they are selective: specify what must be decided, discover what the system can answer, verify what carries risk, and let temporary planning expire.
Selected references
- A Field Guide to Finding Your Unknowns, Thariq Shihipar, 2026
- Judgement, Simon Willison, 2026
- Can LLMs Write Correct TLA+ Specifications?, Bisharat et al., 2026
- Automated Repair of Ambiguous Natural Language Requirements, Jia et al., 2025
- SWT-Bench: Testing and Validating Real-World Bug-Fixes with Code Agents, Mündler et al., 2024
- Everything We Got Wrong About Research-Plan-Implement, Dexter Horthy, 2026
- Usage, Effects and Requirements for AI Coding Assistants in the Enterprise, IBM Research, 2026
- From AI Governance to AI Assurance, IBM, 2026
(This article is an original rewrite of Markus Eisele’s piece as republished with the author’s permission.)
