Introduction
Over the past few years, we have seen an explosion of tools based on Artificial Intelligence. Every week, new models, agents, frameworks, and promises appear about how AI will completely change the way we build software.
However, after working on real projects, I reached a different conclusion.
AI creates value when it solves concrete business problems and improves the productivity of engineering teams. Everything else is noise.
In one of the projects I led, we had the opportunity to validate this from two different perspectives: using AI to improve the end-user experience through a RAG solution, and using AI to accelerate software development through Specification-Driven Development (SDD) and OpenSpec.
Both initiatives had a common goal: to generate measurable results without sacrificing technical quality.
The Problem: A Traditional Search Engine Had Reached Its Limit
One of our clients had a search engine based on Apache Solr.
The engine worked correctly when users knew the exact keywords they needed to use. However, the experience started to deteriorate when queries became more natural or were phrased as questions.
A user does not always search using the exact name of a product, service, or section of a website.
Very often, they simply ask:
- How can I complete a specific procedure?
- What requirements do I need for...?
- Where can I find information about...?
In that scenario, a traditional search engine based only on text matching starts to show its limitations.
The challenge was to offer a conversational experience without losing control over the information the system was allowed to use when answering.
Designing a RAG Architecture for an Enterprise Environment
Before writing a single line of code, we spent time designing the solution.
As with any architecture project, technology was only one part of the problem.
We had to answer questions such as:
- How can we ensure that answers come only from authorized content?
- How can we reduce model hallucinations?
- How can we keep knowledge up to date?
- How can we integrate the solution with the existing platform?
- How can we ensure an intuitive user experience?
Based on these questions, we defined an architecture using Retrieval-Augmented Generation (RAG), clearly separating each responsibility within the solution.
The architecture was composed of several main components:
- Website content processing.
- Embedding generation.
- A vector database for semantic retrieval.
- Integration with a language model (LLM).
- Prompt engineering to control the assistant's behavior.
- Integration with the new search interface.
This approach allowed us to build a decoupled solution prepared to evolve over time.
More Than a Chatbot: A Search Engine With Semantic Understanding
The goal was never to build a generic chatbot.
The priority was to improve information search within the site.
To achieve this, we implemented a process where each portal document was transformed into embeddings, allowing the system to represent semantic meaning beyond exact words.
When a user submitted a query, the system followed a flow like this:
- Interpret the intent using an LLM.
- Convert the query into an embedding.
- Search for the most relevant documents in the vector database.
- Build a context using only that information.
- Generate an answer exclusively from that context.
This pattern allowed the model to respond using only information available within the site.
Reducing Hallucinations
One of the biggest challenges when working with language models is controlling their answers.
In enterprise applications, creative answers are not enough.
Answers must be correct.
During the project, we dedicated an important part of the work to refining prompts and establishing clear behavior rules.
Among them:
- answer only using the retrieved context;
- indicate when there is not enough information;
- avoid answering questions outside the site's domain;
- maintain a tone consistent with the organization;
- limit ambiguous or speculative answers.
This process was as important as integrating the language model itself.
The quality of a RAG solution depends both on the architecture and on the rules that govern the model.
User Experience Is Also Part of the Architecture
The technical implementation was only one part of the project.
We also worked with the UX/UI team to completely redesign the search experience.
The goal was to make the interaction feel natural for users already familiar with conversational assistants, without losing the simplicity of a traditional search engine.
A good AI solution does not only need good models.
It needs a user experience that inspires trust.
AI for Users... and AI for Developers
While the team was developing the RAG solution, another interesting question emerged.
If AI could help end users, why not use it to improve the way we develop software?
That was when we began incorporating AI into the engineering process itself.
Not as a replacement for developers.
As an accelerator of the work.
Specification-Driven Development
One of the most important changes was adopting an approach based on Specification-Driven Development (SDD).
Instead of starting by building features directly, we first created clear specifications that defined:
- business objectives;
- functional rules;
- technical constraints;
- acceptance criteria;
- architecture decisions;
- dependencies.
These specifications became the main source of knowledge for the whole team and for the AI assistants used during development.
OpenSpec as a Process Organizer
To structure the workflow, we used OpenSpec.
The concept of Vertical Slice became the main unit of development.
Each task represented a complete feature, from problem definition to implementation and validation.
This approach helped maintain much clearer context for both the team and the AI tools.
Instead of generating isolated code, each interaction followed a well-defined sequence:
- understand the requirement;
- analyze the specifications;
- build a plan;
- implement the solution;
- validate results;
- update the state of the work.
AI stopped being just a code generator and became an assistant capable of understanding the full project context.
Documentation as Context for AI
Another important lesson was that AI can only be as useful as the context it receives.
For that reason, we organized project knowledge using a Markdown file structure where we documented aspects such as:
- architecture decisions;
- development standards;
- project conventions;
- business rules;
- required skills;
- reusable patterns;
- technical guidelines.
This documentation did not only help new team members.
It also provided consistent context for AI assistants.
Automating Repetitive Tasks
As the process matured, we started integrating different tools through MCP (Model Context Protocol).
This allowed us to automate activities such as:
- initial task analysis;
- work plan generation;
- specification lookup;
- support for component layout;
- development workflow tracking;
- ticket status updates.
Automation reduced repetitive tasks and allowed the team to spend more time on decisions that truly require technical judgment.
Human Oversight Remains Essential
Although AI accelerated many activities, we never allowed important decisions to become fully automatic.
Human review remained a mandatory part of the process.
Architecture decisions, code reviews, functional validation, and change acceptance continued to be the team's responsibility.
AI accelerated development.
Quality remained the responsibility of people.
Final Reflection
After participating in these projects, I confirmed something I now consider fundamental.
True transformation is not about adopting a language model because it is trendy.
It is about identifying where AI can provide real value.
In our case, that value appeared on two very different fronts.
On one hand, we improved the search experience through a RAG architecture capable of understanding natural language questions and answering using only authorized information.
On the other hand, we transformed our own development process using Specification-Driven Development, OpenSpec, structured documentation, and AI assistants to reduce rework and increase team productivity.
In both cases, technology was a means, not the goal.
Because in the end, the best Artificial Intelligence implementation is not the one that uses the largest model, but the one that helps people make better decisions, build better software, and deliver more value to the business.