DEV Community: Paulo Eremita

From Documentation to Delivery System: How I’m Evolving SDD Into a Personal Engineering Framework

Paulo Eremita — Wed, 06 May 2026 18:46:04 +0000

For a long time, I treated software documentation the way many teams do:

as something useful, important, and almost always weaker than the code it was supposed to support.

It helped a little.

It organized a few ideas.

It improved communication when people had the patience to keep it alive.

But it was not enough.

So I started pushing my SDD further.

What began as structured documentation gradually turned into something else:

a personal engineering framework for delivery.

Not a framework in the “library” sense.

A framework in the “system for building systems” sense.

The original frustration

The problem was familiar.

Projects often fail long before implementation quality becomes the main issue.

They fail because of:

ambiguity
fragmented decisions
weak context transfer
invisible assumptions
inconsistent execution across sessions, contributors, and tools

The code is only one part of the story.

What breaks first is usually the path toward the code.

That is where I started paying closer attention.

Why I kept evolving the SDD

At first, the SDD was just a way to structure thinking before implementation.

But over time, I realized that the real value was not in the document itself.

The real value was in the repeatability it created.

A good SDD was doing more than describing a solution.

It was:

constraining ambiguity
making tradeoffs visible
preserving context
guiding execution order
helping both humans and AI stay aligned

That is when I stopped seeing it as “documentation” and started seeing it as an operating model.

What it is becoming

Today, I think of it less as a static artifact and more as a delivery framework.

A practical one.

Its purpose is not to produce pretty documents.

Its purpose is to improve how software gets built.

That means the SDD has to support things like:

architecture definition
rule organization
implementation sequencing
decision traceability
reusable structure across projects
compatibility with AI-assisted workflows
validation through real shipped systems

At that point, calling it “just documentation” feels misleading.

It is closer to an internal blueprint system.

A shift that mattered

One of the most important mental shifts for me was this:

a strong engineering artifact should not only explain a project

it should actively shape how the project is delivered

That changed how I structured the work.

Instead of asking:

what should this document contain?

I started asking:

what should this system make easier, safer, and more repeatable?

That leads to a very different kind of artifact.

What the framework is trying to solve

The SDD framework is my way of reducing the gap between intent and execution.

Especially in projects where there is a lot of complexity, moving parts, or risk of drift.

The framework is trying to make these things more reliable:

understanding what is being built
deciding what matters first
preserving why decisions were made
helping new contributors enter with less confusion
making AI collaboration more grounded and less improvisational
turning a one-project success into a reusable way of working

Why AI made this even more important

AI did not make structure less important.

It made structure more important.

If you want AI to be genuinely useful in software delivery, you need more than prompts.

You need context discipline.

You need stable rules, explicit intent, clear boundaries, and enough scaffolding to prevent the workflow from collapsing into guesswork.

That is one of the reasons I kept evolving the SDD.

I wanted something that could support:

human reasoning
machine-assisted execution
continuity across sessions
repeatable delivery patterns

In that sense, the framework is not anti-AI at all.

It is what makes AI collaboration more serious.

Real validation changed everything

The framework became much more interesting once it stopped being theoretical.

I began using it in real projects.

That included:

a deployed psychology research application
migration-oriented Python tools
internal engineering tools for legacy analysis and structured diagnostics

That real usage mattered.

Because now the question is no longer:

is this an interesting idea?

Now the question is:

does this actually improve delivery in practice?

That is a much better question.

What I’m learning

A few things have become clearer as I keep pushing this work forward.

1. Documentation is too small a word

Some artifacts are doing operational work, not just descriptive work.

When that happens, they need to be versioned, governed, and treated like part of the engineering system.

2. Reuse is a design signal

If the same structure keeps helping across different projects, it probably wants to become a framework.

3. Delivery quality depends on pre-code clarity

A lot of engineering pain is not caused by bad syntax.

It is caused by weak framing.

4. AI works better inside disciplined systems

Loose prompting can generate motion.

Structured context can generate leverage.

Where this is going

I’m still evolving this framework.

It is not “finished,” and I’m not especially interested in pretending otherwise.

What interests me is pushing it further as a practical system for:

spec-driven execution
AI-assisted development
repeatable engineering workflows
stronger context continuity across real projects

I want it to keep moving from:

folder of rules
to reusable blueprint
to internal delivery framework
to something robust enough to support broader platform thinking

That is the direction.

Final thought

A lot of people ask whether documentation is still worth investing in.

I think that is the wrong question.

The better question is:

can your documentation evolve into an execution system?

That is what I’m exploring with my SDD.

And the more I work on real projects with it, the more I believe this is where some of the most interesting engineering leverage lives.

Structured Context Before AI: The Rule That Made My Legacy Analysis Tool Useful

Paulo Eremita — Wed, 06 May 2026 18:42:29 +0000

A lot of AI-assisted coding tools fail for a simple reason:

they ask the model to think before the system has done enough work.

That usually leads to one of two outcomes:

vague summaries that sound smart but don’t help much
confident mistakes wrapped in beautiful prose

While building my legacy analysis tool, I kept running into the same conclusion:

if you want useful AI output, you need structured context first

That rule changed the whole design of the project.

The temptation

When working with a legacy codebase, it is very tempting to do this:

grab a file
send it to an LLM
ask: "what does this do?"

Sometimes that works.

But legacy systems are rarely understandable from a single file.

A method may look innocent until you discover:

it depends on includes
it calls another class indirectly
it builds SQL dynamically
it is triggered by a UI flow you haven't seen yet
the real business meaning lives in the database schema, not the method body

If you ask AI too early, it will often fill the gaps with plausible fiction.

That is not intelligence. That is autocomplete wearing a tie.

What I changed

Instead of starting with AI, I designed the workflow to start with extraction.

The tool tries to collect structure before asking for commentary.

Depending on the analysis path, that may include:

file path and class/method identity
dependency chains
include resolution
SQL blocks
tables touched
UI actions and endpoints
schema metadata
procedure summaries
domain map hints

Only after that does AI step in.

So the prompt is no longer:

"please explain this mysterious code"

It becomes closer to:

"here is the method, here are its dependencies, here are the SQL fragments, here are the tables, here is the path it came from, now explain what is actually happening"

That difference is enormous.

Why this works better

Structured context improves AI output in at least four ways.

1. It reduces hallucination pressure

When the model has actual extracted signals, it does not need to invent as much missing context.

That does not eliminate mistakes, but it lowers the odds of polished nonsense.

2. It makes answers more specific

Instead of generic observations like:

"this appears to handle business logic"
"it may interact with the database"

you start getting analysis grounded in real technical evidence:

which tables are involved
which dependencies were resolved
which flow the UI suggests
where the risk points actually are

3. It makes reports reusable

If the context is structured, it can be cached, compared, regenerated, and reused.

That matters a lot in real engineering work, where you often revisit the same area multiple times.

4. It makes AI part of a system, not a gimmick

This is the most important one.

AI becomes one stage in a pipeline.

Not the whole pipeline.

That means the tool still has value even before the model speaks.

And that is a good test of whether your design is serious.

A practical example

Let’s say you are trying to understand a legacy backend action.

A weak workflow is:

open one PHP file
paste it into an LLM
ask for a summary

A stronger workflow is:

identify the real method or action
resolve related includes
extract SQL fragments
detect external class calls
identify likely tables involved
inspect schema when needed
only then generate AI commentary

The first workflow gives you a guess.

The second gives you a technical briefing.

The hidden lesson

This idea goes beyond legacy analysis.

I think it applies to almost every serious AI engineering workflow.

If you want reliable AI assistance, you usually need some combination of:

preprocessing
structure extraction
constrained prompting
typed outputs
caching
human-readable artifacts

In other words:

the quality of the AI output often depends more on the surrounding system than on the model itself.

That is not as flashy as saying "I built an AI tool."

But it is much closer to the truth.

What I believe now

I no longer think the most valuable AI tools are the ones that "do everything."

I think the valuable ones are the ones that:

collect the right context
shape the right questions
constrain the right outputs
fit into real workflows engineers already need

Models matter.

But scaffolding matters more than people want to admit.

Final thought

One of the most useful engineering habits I’m developing is this:

never ask AI to infer what your system could have extracted first

That rule made my tool better.

It also made my trust in the output more rational.

And in applied AI, rational trust is worth a lot more than impressive demos.

If you’re building AI-assisted engineering tools, I’d love to know:

how much of your result comes from the model, and how much comes from the structure around it?

Legacy systems are rarely hard because of syntax

Paulo Eremita — Wed, 06 May 2026 18:38:48 +0000

Legacy systems are rarely hard because of syntax.

They are hard because knowledge is fragmented.

A controller points to a facade.

A facade touches a model.

A model hides SQL.

A UI action triggers behavior through includes, query strings, and conventions nobody fully documented.

The database has its own story.

The team has another one.

And the code sits there like an archaeological site pretending to be an application.

I wanted a better way to understand systems like that.

So I built an AI-assisted workbench for legacy system analysis.

The real problem

When engineers talk about "understanding a legacy system", the usual tools are often too weak for the job:

manual grep is fast but shallow
one-off scripts solve one question at a time
raw LLM prompting without structure can sound smart while being operationally unreliable
database inspection is often disconnected from code inspection
UI behavior, backend flow, and schema meaning are rarely analyzed together

In real maintenance and modernization work, that gap hurts.

You are not just trying to read code.

You are trying to reconstruct intent.

What I built

The project became a Python-based analysis workbench focused on legacy systems, especially codebases where behavior is spread across:

PHP files
includes
facades and models
SQL Server schemas and procedures
UI-triggered backend flows
structural artifacts like GraphML and domain maps

The idea was simple:

don't ask AI to guess the system

first extract structure, then let AI comment on something real

That principle shaped the whole tool.

Core capabilities

The workbench combines multiple analysis layers:

static code scanning for risky and suspicious patterns
method and dependency tracing
include resolution
SQL Server schema inspection
stored procedure analysis
UI flow analysis from HTML and JavaScript surfaces
domain map generation from structural artifacts
AI commentary with prompt templates and response caching

So instead of running isolated scripts, I can move through the system with a more connected workflow.

Why AI is in the loop

I did not want AI to replace analysis.

I wanted it to amplify analysis.

The difference matters.

If you throw raw code at an LLM and ask "explain this system", you may get polished nonsense.

If you first extract methods, dependencies, SQL blocks, tables, actions, and context, then AI has something solid to work with.

In this project, AI becomes:

a technical commentator
a summarizer of structured findings
a helper for generating readable reports
an assistant for identifying risks and improvement opportunities

Not an oracle.

A tool.

That distinction is one of the most important lessons I keep learning in applied AI engineering.

Some design decisions I care about

A few things made this project much better than a simple "LLM + code" experiment.

1. Structured before generative

The system extracts real artifacts before asking for commentary.

That includes things like:

method signatures
dependency trees
SQL fragments
table metadata
UI actions
procedure summaries

This reduces hallucination risk and improves signal quality.

2. Caching AI outputs

If an analysis has already been generated for the same structured input, the tool can reuse it.

That saves cost, reduces latency, and makes the workflow more practical during repeated investigation.

3. Multiple analysis surfaces

Legacy understanding is not only about code files.

Sometimes the truth is in:

a table relationship
a stored procedure
an include chain
a UI event
naming patterns in domain entities

The tool had to support that reality.

4. Markdown-first outputs

I wanted outputs that humans could read, share, compare, and refine.

So a lot of the workflow is oriented around report generation instead of opaque internal state.

What surprised me

The most interesting part was realizing that legacy analysis itself can be treated as a product problem.

Not a script problem.

Not a one-time debugging problem.

A product problem.

Because the real value is not just "finding a file".

It is building a repeatable way to turn unknown systems into understandable systems.

That changes how you think about tooling.

What this project is not

It is not:

a fully autonomous agent
a universal code intelligence platform
a replacement for engineers with domain knowledge

It is a workbench.

A serious one, I hope.

Its job is to help engineers think better and move faster in ugly, under-documented systems.

Why I made a public version

The original tool came from a real internal context, so the public repository is a sanitized case study.

I removed environment-specific paths, generated artifacts, internal identifiers, and project-specific traces.

But I kept the architecture, the workflow ideas, and the engineering intent.

Because I think this is a problem many teams have:

how do we understand legacy systems with more rigor and less guesswork?

Final thought

I like building applications.

But more and more, I also like building the tools that help engineers understand, migrate, and modernize complex systems.

This project sits right in that space.

If you work with legacy code, reverse engineering, modernization, or AI-assisted development, I’d love to hear how you approach this problem.

Repo:
legacy-analysis-workbench