.svg)
The question behind the demos
The current generation of AI coding tools demos beautifully, and the demos aren't misleading. Point one at a repository and it will summarize a file, trace a function, and draft a change in seconds. Teams that adopt these tools ship faster, and a leader deciding where to place engineering bets should take that seriously.
There's a harder question underneath the demo, though — not "does this tool work?" but "what would make it work even better on our systems?" On a greenfield service, today's tools perform close to their ceiling. On a large or legacy codebase, the gap between what the tool retrieves and what the system actually means starts to show — and that gap is exactly where the stakes are highest: audits, incident response, and modernization.
Notice how the questions that matter in those moments get phrased. A CTO, an architect, or a compliance reviewer doesn't ask "which function writes to this table?" They ask "under what conditions do we charge this fee, and who is exempt?" Those questions live in the business domain. Most context today is expressed in the language of code.
A CTO, an architect, or a compliance reviewer doesn't ask "which function writes to this table?"
How AI tools get context today
Strip away the branding and today's AI coding tools get their context in one of three ways — and each is a real engineering achievement doing a real job.
The first is a real-time retrieval index: the tool indexes your repository, then retrieves and ranks the snippets most relevant to a given request. It's fast, and for locating relevant code it's excellent.
The second is the agent's runtime context window: the tool reads files on demand and holds them in a large-but-finite window for the duration of a session. This is what makes agents able to reason across files at all, and windows keep getting bigger.
The third is a hand-authored memory file: a document a developer writes to tell the agent about conventions and rules. When it's current, it's a genuine force multiplier.
These three mechanisms are why AI coding tools work as well as they do. But they were all designed to answer one kind of question: code-level questions. They retrieve code, hold code, or describe code. Retrieval is session-agnostic but fragment-shaped; the context window is coherent but temporary; the memory file is durable but hand-maintained. None of them was built to lift what the system does into the business domain — and none of them claims to be. That's not a flaw in the tools. It's a layer of the stack that hasn't existed until now.
The questions that matter are asked in the business domain
Here is the distinction that decides real-world value: the difference between lower-order, code-level questions and higher-order, business-domain questions.
A retrieval index or a big context window can usually answer the code-level questions from raw source — that's what they're for. The higher-order questions need something more: a translation of the code into the business domain, held somewhere persistent enough to be trusted.
The contrast is easiest to see with examples.
Lower-order (code-level)Higher-order (business-domain)"Which modules write to the account-balance table, and what calls the interest routine?""Under what conditions is a customer charged an overdraft fee, how is the amount calculated, and which account types or exemptions override it?""What does the premium-calculation routine compute, step by step?""How is a policy's premium determined for a given risk profile, and which regulatory caps or state-specific rules override the base calculation?"
The left-hand answers describe where and how the code runs. The right-hand answers describe what the business does and why. Decisions, audits, and rebuilds all happen on the right. Both levels matter — you can't act on a business rule without eventually touching code — but the higher-order level is the one your current stack doesn't produce on its own, and it's the one that makes everything at the lower level more reliable.
[IMAGE PLACEHOLDER 2 - insert before this paragraph, upload separately to Webflow assets]
Why higher-order understanding is decisive for modernization
Nowhere does this matter more than modernization, and nowhere is the failure mode more expensive.
The tempting shortcut is transliteration: convert the COBOL to Java more or less line by line. It feels safe because it looks faithful, but in practice it reproduces decades of accidental complexity (dead branches, workarounds, and procedural idioms) inside a language built for object orientation and the JVM. You end up with Java that reads like COBOL: technically running, effectively unmaintainable, and modernized in name only.
The approach that actually works is different. You understand the functionality and business rules the legacy code implements, capture them as a spec, and then re-implement them idiomatically on the new platform: modern frameworks, JVM-appropriate patterns, current conventions. The goal is functional equivalence, not structural equivalence.
What makes that possible is the higher-order, business-domain spec. A spec is platform-independent. Code is platform-bound. The rules of how you price a policy or charge a fee don't care whether they're expressed in COBOL or Java, but the code does, and porting the code carries all of its platform-specific baggage with it.
You cannot safely rebuild what you can only describe at the code level.
This is the reason so many modernization programs stall or overrun. Teams either freeze, afraid to touch behavior no one fully understands, or they transliterate and inherit the mess. Both are expensive. The way out is to work from a spec — and to hand that spec to the AI tools doing the re-implementation.
Changing a live system safely
Most of what happens to a legacy system is not a rewrite. It is maintenance: a steady stream of small changes to code that already runs in production. The case for understanding is just as strong here, though it rests on different ground.
You might rightly point out that a maintenance change does not switch platforms, so the platform-independence point does not apply. What still applies is everything about safety. A change request arrives in business terms, like "add an overdraft-fee exemption for premium accounts," and someone has to find every place that rule lives, understand the invariants around it, and avoid the dependency no one documented. That is a higher-order problem, not a code-search problem — though a good retrieval tool is exactly what you want once you know what to search for.
This is where impact analysis earns its keep. The failure that breaks a live system is the implicit coupling you could not see from the file in front of you: a rule on which another module quietly depends, or an edge case a downstream report assumes. Business-domain understanding surfaces those interactions before the change lands, which is the difference between a safe fix and a 2 a.m. incident.
It also preserves intent. Legacy maintenance is usually done by people who did not write the code, long after the authors have gone, and the "why" behind a rule is exactly what a plausible-looking fix tends to violate. A persistent, code-grounded understanding keeps that intent available to whoever — or whatever — changes the system next.
One honest caveat: a small, well-localized fix rarely needs any of this. The value grows with how coupled the change is and how unfamiliar the person (or agent) making it is.
Spec-driven development, and what it does for the tools you already use
Spec-driven development inverts the usual relationship between code and understanding. The spec, a business-domain description of what the system does and why, becomes the durable source of truth. Code, in any language, is an implementation of that spec, not the reverse. The same spec serves two jobs: you rebuild from it when you modernize, and you change against it when you maintain.
This is the right model for the AI era, and the payoff shows up in three ways across your existing toolchain.
Accuracy. Agents build far better from a precise spec than from raw code plus inference. When an agent knows the business rule behind the code it's changing, it stops producing plausible-looking changes that violate invariants no one wrote down. Grounding agents in a CoreStory spec improves task success rates by up to 44% in CoreStory's SWE-bench evaluation. (Source: CoreStory, Agent Boosting.) Same agents, same models — better inputs.
Speed. Without a persistent spec, every session starts cold: the agent burns time and tokens re-discovering context that was assembled and discarded the session before, and every engineer new to the codebase repeats the same archaeology. A spec that persists across sessions means agents start from understanding instead of exploration, and humans onboard against a readable model of the system instead of raw source.
Optimization across the stack. A spec is shared infrastructure. The same living source of truth serves your retrieval tool, your agent's context window, your memory files, your architects, and your compliance reviewers — so every tool in the stack gets better at once, and they stop diverging from each other. Understanding compounds instead of evaporating.
There's a catch that has held spec-driven development back for years: most specs are written once, by hand, and start rotting the moment the code changes. A stale spec is worse than none, because people trust it.
That's the gap CoreStory closes. CoreStory generates the spec directly from the code and keeps it current. The result is a persistent, code-grounded understanding rather than a document someone has to maintain. It then serves that spec to humans through a dashboard and to AI agents through MCP, so the tools you already use — Claude Code, Copilot, Cursor, and the rest — build from the same living source of truth. CoreStory doesn't replace any of them. It's the layer underneath that makes all of them enterprise-ready.
[SCREENSHOT PLACEHOLDER - Screenshot of the CoreStory dashboard showing a generated spec for a module alongside the underlying code. Paste image here before publishing. Alt text: CoreStory dashboard displaying a business-domain spec generated from source code.]
The spec is generated from source, so it works across the many languages a real enterprise runs, legacy and modern alike. That's what makes spec-driven development practical at scale rather than a whiteboard ideal.
The executive stakes
A CTO or VP of Engineering can reduce the argument to three gaps that a spec layer closes — none of which requires swapping out the tools your teams already like.
Risk to critical systems. An agent working from retrieved snippets alone can produce a change that compiles and still violates a rule no one wrote down. Grounding those same agents in a business-domain spec turns "probably correct" into "verifiably consistent with what the system is supposed to do."
Knowledge that walks out the door. When business-domain understanding lives in a handful of senior engineers' heads, every departure is a loss you can't easily replace. A generated, persistent spec keeps that understanding in the organization — and available to every tool and teammate at once.
Modernization that stalls or overruns. Teams that lack a current spec either freeze or resort to transliteration, and both are costly. Pega's 2025 research estimates the average global enterprise wastes more than $370 million a year on technical debt from unmodernized legacy systems, with nearly $134 million of that tied to slow, resource-intensive legacy transformation. (Source: Pega, October 2025.)
Five questions for your AI development stack
If you're mapping out how AI fits into your engineering organization, these five questions identify whether a spec layer would raise the ceiling on the tools you've already invested in:
- Can your stack answer questions in business-domain terms, or only at the code level?
- Is there a spec current enough to change the system safely today and rebuild it tomorrow?
- Does system understanding persist across sessions and survive turnover?
- Is that understanding grounded in the code and auto-refreshed, or hand-maintained?
- Is it shared across teams and the coding agents you already use, or rebuilt separately inside each tool?
If the answers are mostly "no," the fix isn't replacing your tools. It's giving them a better foundation.
See it on your own codebase
The fastest way to feel the difference is on a system you know well. CoreStory can generate a business-domain spec from your codebase, plug it into the agents you already run, and show you the higher-order questions your whole stack can suddenly answer.
Related reading: [INTERNAL LINK: CoreStory, the persistent spec layer], [INTERNAL LINK: Legacy Transformation use case], [INTERNAL LINK: Boosting AI agent performance] — replace with real internal links before publishing.
FAQ
What do you mean by a "living" spec? A living spec stays in sync with the code. CoreStory regenerates it from the source on each ingestion, so it reflects the system as it is now, not as it was when someone last wrote it down. A static document goes stale the moment the code changes, and people keep trusting it anyway. A living spec updates with the code, which is what keeps it reliable for humans and agents.
What is spec-driven development, in one line? The spec describes what the system does in business terms. It is the source of truth, and code is an implementation of it, not the reverse.
Does this replace our coding agent or IDE? No. CoreStory feeds your existing agents a living spec through MCP, so they work from what the system actually does. It's a context layer underneath the tools you have, not a replacement for any of them.
We already use a code search or retrieval tool. Is this the same thing? No, and you should keep it. Retrieval returns the most relevant code; CoreStory produces business-domain understanding of how the system behaves. They're complementary — retrieval finds the code, the spec explains what it means.
Isn't a bigger context window enough? Bigger windows help, and they pair well with a spec. But size isn't persistence, and holding more code in one session doesn't lift that code into the business domain. A spec gives the window better material to hold.
Isn't AI already good enough to transliterate our COBOL to Java? It can transliterate, but that reproduces legacy complexity in a new language. What you want is functional re-implementation from a spec, which requires business-domain understanding of what the original code actually does — and that spec is exactly what makes your AI tools effective at the re-implementation itself.
