The Spec-Driven Development workflow (https://llm-coding.github.io/Semantic-Anchors/spec-driven-development) has demonstrated that LLMs can generate maintainable code from specifications. The documentation artifacts produced in this workflow (PRD, Specification, arc42) appear to capture what Peter Naur described as the "theory" of a program [naur85] — the mental model that, according to Naur, cannot be fully documented. Whether or not Naur was right about human programmers, the Spec-Driven workflow shows that for LLM-generated code, this theory CAN be externalized in structured documentation.

The open question is Brownfield. Legacy software typically has no specification, few tests, and insufficient architecture documentation. Can an LLM extract the necessary documentation from legacy code and thus enable further development using the Spec-Driven workflow?

Answering this directly by applying an LLM to real legacy software is difficult: the quality of the generated documentation is hard to assess without a ground truth to compare against. The evaluation itself would be time-consuming and subjective.

This experiment uses a shortcut. We take an LLM-generated Greenfield project where we can assume that Spec, Tests, and arc42 documentation are of high quality. We transform it into a simulated legacy project by deleting this documentation, then ask an LLM to reconstruct it from the code alone. Because the original Greenfield documentation exists, we can objectively assess the quality of the generated output by comparing the two.

Since we know in advance that not everything can be extracted from code (decisions, rationale, business context), we instruct the LLM to maintain a list of Open Questions. This reveals precisely which information is genuinely missing from the code — and what a Brownfield project would need to provide before an LLM can work on it productively.

Because the experiment is reproducible (same code, same prompt, deterministic comparison), the extraction prompt can be improved step by step.

Bausteinsicht — an architecture-as-code CLI tool that provides bidirectional synchronization between a JSONC architecture model and draw.io diagrams.

The original documentation was not human-written. It was LLM-generated following the Spec-Driven Development workflow from a requirements conversation.

On branch brownfield, the following files were deleted:

Kept intact: all source code, tests, test data, Makefile, go.mod, examples, templates, README.

The prompt uses Semantic Anchors (established methodology terms like "Cockburn", "arc42", "Nygard ADR", "Pugh Matrix") instead of spelling out format definitions. 69 lines total.

The generated artifacts in src/docs/ were compared against the originals from the main branch. Comparison was performed per artifact type (PRD, Spec files, arc42 chapters, ADRs) and per information category (functional requirements, design rationale, quality goals, etc.). Assessment is qualitative (good / partial / poor) based on manual review of content, not automated metrics.

Every claim is traceable to code. The LLM cites function names (sanitizeID, applyRelSwap, StripJSONC), test functions (TestInitCreatesFiles), constants (MaxElementDepth = 50, MaxModelFileSize = 10 MiB), and security codes (SEC-001, SEC-016). The original references no code.

The original has 7 coarse Functional Requirements. The LLM produced 21 FRs in logical groups (Model, CLI, Sync, Views, Validation, Errors). Acceptance Criteria are 69 instead of 40 and reference test function names, making them directly verifiable against code.

The original mentions security only in passing. The LLM extracted 6 SEC codes with enforcement details, documented path traversal validation, and formalized security as an NFR. A positive surprise.

The original describes the sync algorithm narratively. The LLM formalized the three-way diff as a truth table (M==S / D==S combinations), systematically listed 12 edge cases, and extracted layout constants (gap=60, min scope=400x300) from code.

The original had only a placeholder (2 example terms). The LLM correctly defined 31 domain terms.

The original starts with a clear Problem Statement: "Structurizr and LikeC4 have limitation X, Y, Z." The LLM doesn’t know the competitors and cannot derive the strategic positioning. The vision remains generic.

The LLM wrote 6 ADRs, but with different topics than the original:

The LLM can see THAT Go was chosen, but not WHY Python and Kotlin were rejected. The Pugh Matrices in the generated document evaluate plausible but partly different alternatives than those actually evaluated. This aligns with [garcia24]: when given ADR context, LLMs can generate reasonable decisions, but reconstructing context from code alone is a harder, unsolved problem.

The original has three prioritized Quality Goals: Learnability (30-min onboarding), IDE Support (JSON Schema), LLM Friendliness. The LLM identified 6 Quality Goals but the prioritization is missing.

The original defines three stakeholders (Architect, Developer, LLM Agent) with their concerns. The LLM derives stakeholders from CLI UX, but cannot reconstruct skill levels, expectations, and concerns.

UC-7 "Drill-Down Navigation" (zoom-based navigation on a single draw.io page) is described in the original but not fully implemented in code. The LLM did not mention it — it can only document what exists, not what was planned.

Four files in the original have no counterpart:

The original documents: Startup <10ms, Sync <100ms, Binary 10-15MB. The LLM found benchmarks but no thresholds — because thresholds are decisions, not code facts.

The original contains ATAM reviews (808 lines), LASR reviews, and review updates. These are historical artifacts not derivable from code.

Well derivable from code (4 chapters):

Partially derivable (6 chapters):

Poorly derivable (2 chapters):

Before a legacy project can enter the Dark Factory, it needs at minimum:

Everything else the LLM can reconstruct on its own — and in some areas does it better than the original (more FRs, more ACs, better security documentation, complete glossary).

The original relegates security to a separate review document. The generated version integrates security directly into the specification with traceable SEC-IDs (SEC-001 through SEC-018) woven through PRD, CLI spec, and acceptance criteria. A maintainer reading NFR-005 (Security — path containment) can immediately find the test (TestRootCmd_RejectsModelPathTraversal) and the enforcement code (root.go:validatePathContainment).

The original PRD has zero security NFRs. The code has six security mechanisms. That gap is spec drift.

The original uses Gherkin scenarios with no connection to actual tests. The generated version cites test function names inline: AC-001-01: …​ // test: TestInitCreatesFiles. An architect can verify each criterion against the test suite. The original is write-only documentation — readable by humans, unverifiable by machines.

The original describes the three-way diff in prose across multiple sections. The generated version formalizes it as a truth table (M==S / D==S combinations), lists 12 edge cases in a structured table, and names the exact functions. The truth table is verifiable; the prose is interpretable.

The original uses passive voice and generic descriptions. The generated version uses active, verb-first responsibility statements with explicit contracts: patch.go | Byte-range patch operations on raw JSONC. PatchSave, PatchInsert. Preserves comments and indentation.

The original has 4 NFRs written before implementation. The generated version found 12 — including security constraints, robustness bounds (10 MiB file limit, depth 50), benchmark mandates, and quality gates (gosec, nilaway, govulncheck) that were implemented but never added to the PRD. These are real requirements that govern the project’s CI pipeline.

All five areas share the same root cause: the spec was generated from a requirements conversation before implementation, and the code evolved beyond it. The original documentation was not human-written — it was LLM-generated following the Spec-Driven Development workflow. Yet spec drift happened anyway: during implementation, the LLM added security hardening, validation rules, edge cases, and performance tooling that were never part of the original requirements conversation.

This means spec drift is not a discipline problem. It is a structural property of the workflow: the implementation LLM discovers requirements that the specification LLM could not anticipate. Security constraints emerge from code review. Edge cases emerge from testing. Performance bounds emerge from benchmarks. None of these feed back into the spec automatically. The SDD paper [sdd26] defines this as "any divergence between declared system intent and observed system behavior" and identifies it as a core challenge for AI-assisted development.

The Dark Factory workflow is spec-first: write PRD, write spec, generate code. But the experiment shows that even in a Greenfield project with rigorous documentation, the spec drifts from the code within weeks.

The fix is a spec reconciliation step: periodically run the Brownfield reverse-engineering prompt against the current code and diff the output against the existing spec. The diff reveals:

Three natural trigger points:

The reconciliation is cheap: one LLM run, one diff. The cost of NOT doing it is higher: LLM agents working from stale specs produce code that contradicts the actual codebase.

The original Dark Factory workflow is linear: Spec → Code → Ship. With reconciliation it becomes a loop:

The human writes the WHY once and maintains it. The LLM keeps the WHAT synchronized with the code. This division of labor matches what the experiment showed: humans are better at rationale, LLMs are better at completeness.

The anchored prompt (69 lines) produced 3,850 lines of documentation with correct Cockburn format, all 12 arc42 chapters, and Pugh Matrices in the ADRs. The terms "Cockburn", "arc42", "Nygard ADR", "Pugh Matrix", "Gherkin", "C4 model" triggered the full knowledge from training data without the prompt spelling out what those formats contain.

This is empirical evidence that Semantic Anchors work. A single well-chosen term activates a complete methodology in the LLM’s weights. No definition needed, no examples needed. The anchor IS the definition. A systematic literature review [slr25] covering 18 papers on software architecture and LLMs found no prior study examining this compression effect.

The experiment divides documentation into two categories:

In the Spec-Driven Development workflow, human effort should concentrate on the why: Problem Statement, ADR context, quality goal prioritization, stakeholder concerns. The LLM handles the what: functional specs, data models, acceptance criteria, building block views.

This changes the workflow’s cost structure. Writing a PRD is no longer about listing features (the LLM does that better). It’s about capturing the competitive context and strategic intent that code cannot express.

In Shannon’s noisy channel model, the documentation that an LLM cannot derive from code is exactly the channel capacity that must be transmitted. Business context and design rationale are the signal. Code is not a channel for this signal — code is the output, not the decision.

The Brownfield Preparation Checklist (6 items above) defines the minimum information that must travel through the documentation channel before an LLM can work productively on a legacy codebase. Everything below this threshold means the LLM operates with insufficient channel capacity — it will guess at rationale, invent stakeholder concerns, and miss aspirational features. The error rate climbs exactly as Eichhorst’s Principle predicts.

ArchAgent [archagent26] achieves F1=0.966 by combining static analysis (dependency graphs, call graphs) with LLM synthesis. Our experiment uses a pure LLM approach: the model reads source files sequentially with no pre-computed structural information. A preprocessing step exporting dependency graphs, call graphs, or AST summaries could improve the Building Block View and Runtime View, where the LLM currently misses cross-package relationships.

The largest architecture view study [cabrera26] shows that few-shot prompting reduces clarity failures by 9.2%. The user stories paper [userstories25] demonstrates that "a single example lets an 8B model match 70B performance." Our prompt provides no examples.

However, the impact varies by artifact type. Strong Semantic Anchors like "arc42", "Cockburn Use Cases", or "Nygard ADR" carry their definition in the LLM’s training data — books, conference talks, and thousands of documented examples. A few-shot example for arc42 would be redundant and might even constrain the output by biasing towards the example rather than the anchor’s full semantics. The experiment confirms this: all 12 arc42 chapters were generated in the correct structure without examples.

Where few-shot examples would likely help is for non-standard formats that have no anchor in the training data: our Open Questions list (OQ-NNN with Category, Confidence, Best Guess fields) and the Reconciliation Report (NEW/CHANGED/DEAD categories) are custom formats. A single example entry would reduce ambiguity about the expected output structure.

We block git log and git blame because commit messages reference specification IDs from the original documentation. However, commit messages also contain design rationale ("chose X because Y", "rejected approach Z due to performance"). The SDD paper [sdd26] identifies commit history as a valuable signal channel. A more nuanced approach would allow git history but filter out spec-ID references, preserving the rationale signal while blocking the spec-structure signal.

The ECSA 2025 study [ecsa25] uses a Self-Reflection mechanism where the LLM reviews its own output. AgenticAKM [agenticakm26] shows that agentic approaches (iterative refinement with tool use) significantly improve ADR quality over simple LLM calls. Our prompt is a single-shot task with no feedback loop. An agentic workflow where the LLM generates, reviews, and refines its documentation could improve quality, particularly for ADRs and Quality Requirements.

The referenced papers test multiple LLMs (GPT-4, GPT-3.5, Claude, Gemini, Flan-T5) and find significant quality differences between models. Our experiment uses one model (Claude) in one session. This means our results are specific to Claude’s capabilities and may not generalize. A multi-model comparison (same prompt, same codebase, different LLMs) would strengthen the findings. Additionally, a single run provides no statistical significance — repeating the experiment would reveal variance in output quality.

The papers use formal metrics: F1 scores, precision, recall, BLEU scores. Our evaluation is manual and qualitative ("good / partial / poor"). For a publication, we would need a formal evaluation framework — for example, counting requirement coverage (what percentage of original FRs appear in the generated output) and measuring factual accuracy (what percentage of generated claims are correct).

Bausteinsicht is a well-structured Go CLI tool with clear package boundaries, comprehensive tests, and a single-binary architecture. Results may differ for projects with less clean architecture, fewer tests, dynamic languages, or distributed systems. The Brownfield Preparation Checklist should be validated against projects of different sizes, languages, and architectural styles.