Over the past few months, I've been experiencing one of the most exciting periods of my career: programming with AI — and watching it genuinely accelerate what I already do well.

Yes, I'm building a complete platform myself, with multiple services.

And honestly, AI hasn't disappointed me. But here's the key point: I don't use AI to fix code. I use AI to supercharge my engineering process — like steroids for my development workflow.

The Journey: From "Copy and Paste" to Context Engineering

Before reaching this point, I went through the same path as 90% of developers: I copied code into ChatGPT, asked for generic explanations, and tried to fit the results into my project.

Analyze this error.
Tell me how to do such and such.
Kafka or RabbitMQ?
Which language solves problem X better?

It works… until it doesn't.

Then came the era of IDEs with embedded LLMs — Cursor, Windsurf, etc. Now we had context, because they indexed the project. Even so, something was still off. My prompts were zero-shot or few-shot:

"Create a REST endpoint in Java + Spring Boot, analyze the pom.xml dependencies…"

The AI delivered code — it compiled, but ignored my patterns. No tests, no design, no architecture. I fixed it. It fixed it. Infinite loop. When it finally got it right, came the collapse: hallucination.

The Zero-Shot Problem is REAL and Massive

The Stack Overflow 2024 survey showed:

62% of devs use AI — but 65% say it loses critical context during refactoring.

SecurityBoulevard revealed that duplicated code increased 8× since 2020, and 2024 was the first year where copied lines surpassed refactored lines. And according to Qodo, when context is manually selected, AI loses relevance in 54% of cases. But when context is intelligently architected, that number drops to 16%.

The Irony: Seniors vs Juniors

Senior devs (10+ years): 68.2% report quality gains, but only 25.8% trust sending code without review.
Juniors (<2 years): only 51.9% notice improvements, but 60.2% send AI code straight to production.

The result?

Zero-shot prompting: generic in, generic out.

A cycle of purposeless "vibe coding."

From Vibe Coding → Context Engineering

In February 2025, Andrej Karpathy coined the term Vibe Coding.

It exploded.

But in November of the same year, something new emerged: Context Engineering.

"It's not about what you ask the AI. It's about how you structure the world around it."

Context Engineering is an evolution of prompt engineering.

It's not about "finding the right words," but about building the right context — both technical and product.

The "Context Rot" Effect

LLMs suffer from context rot — the more context you add, the more confused they become.

Each token tries to "understand everything," and the result is noise.

It's not about how much context you give.

It's about what context you give.

A good example is worth more than a thousand tokens.

The Anatomy of Good Context

Context engineering isn't about dumping information.

It's about architecting knowledge.

Over the past 5 months, I built a simple app: a bathroom finder (yes, seriously).

My wife and I always felt the need for such an app when traveling — so I decided to turn the pain into an experiment.

Technical Stack

Onion Architecture — clear separation of concerns
Domain-Driven Design — domain guides code, not the database
Reactive Programming — Spring WebFlux, non-blocking
MCP — integration with LLMs (Claude, for example)

All of this? Yes — how would I use AI to assist in this development? Why not?

And the first step?

Generate a context document.

The Prompt That Changed Everything

Based on a model presented by Elemar Júnior in his software architecture mentorship with emphasis on AI, I adapted a Haiku prompt to create a Context Document Generator.

# CONTEXT
You will simulate a multidisciplinary team of experts composed of:
- An **Integration Architect** inspired by Martin Fowler.  
- A **Data Architect** inspired by Zhamak Dehghani (creator of Data Mesh).  
- A **Cloud Architect** inspired by Adrian Cockcroft (former Netflix Cloud Architect).  
- A **Security Architect** inspired by Bruce Schneier.  
- An **Infrastructure Architect** inspired by Gene Kim (author of *The Phoenix Project*).  
- A **Business Designer** inspired by Alex Osterwalder (creator of *Business Model Canvas*).
Each persona must behave consistently with their role and thinking style.  
The team must collaborate with each other and with the user, asking questions to fully understand the problem, business domain, and technical needs.
---
## INTENTION
The team's mission is to help the user **create a highly detailed context document**, necessary to start a software project.  
The document must unite business and technical perspectives.  
Before drafting the document, the team must interview the user, deeply investigating the project's critical points.
---
## Dynamic Rules
- Each persona must ask questions specific to their area.  
- No user response should be accepted passively.  
- The team must **question decisions, challenge assumptions** and suggest alternatives whenever possible.  
- When information is sufficient, the team must generate an **initial version of the context document**.
---
## OUTPUT FORMAT (in Markdown)
```markdown
# [Project Title]
## 1. Overview
Brief view of the system, its purpose and business context.
## 2. The Problem
Clear description of the problem the software aims to solve.
## 3. Expected Object
Definition of the object (system/product) to be developed.
## 4. Scope and Main Features
- What is included in scope.
- What is out of scope.
## 5. Architecture and Approach
High-level technical view of the architecture, chosen approaches and rationale behind them.
## 6. Dependencies and Constraints
- Technical, organizational or legal constraints.
- Risks identified at the start of the project.


From this, the LLM generates a detailed document of context, scope, architecture, and dependencies.

After this well-detailed document, it leads me to another document called dev4dev where I create a "Persona" with the prompt below:

```markdown
You are an experienced Software Architect and your role is to create a technical "Dev for Dev" document aimed at onboarding junior and mid-level developers, based on a technical context provided by the user.

The document must explain how the system works, how it's structured, and how to evolve the code safely, focusing on clarity and engineering best practices defined for the project.

The document must follow an engineer → engineer style, meaning:

Focused on technical clarity, domain understanding, and engineering best practices.

Avoid excessive jargon, but explain patterns and architectural decisions with practical examples.

Always show how and why things work, not just "what it is."

# Mandatory document structure
The final document must follow this section model (you can adapt titles according to the project):


1. Product Vision (TL;DR for Devs)

Contextualize the problem and product solution.

Explain what the system does in 1 technical paragraph, so a dev quickly understands the "why" and "what for."

2. Modules and Responsibilities

Describe the main modules or components of the system and each one's role.

Use a table with columns:

| Module | Responsibility | Main Interactions |
| ------- | ---------------- | -------------------- |
| billing | Billing processing | MongoDB, Kafka |
| api-gateway | HTTP entry interface | REST, Auth |


Show simple examples of relevant classes, packages, or flows.

3. Architecture (Layers / Onion / Hexagonal / Modular)

Show the folder structure and dependencies between layers.

Briefly explain the reason for separations (e.g., "domain isolated for tests", "infra implements persistence interfaces").

Show Ports & Adapters examples only if they exist; otherwise, describe the direct flow (Controller → Service → Repository).

4. Persistence & Integrations

Detail the technologies and integration patterns used:

Database (Mongo, PostgreSQL, etc.)

Messaging (Kafka, Solace, RabbitMQ, etc.)

External APIs / Webhooks

Explain how transactions are handled and if there are patterns like Outbox Pattern or Retry.

5. Code Conventions & Immutability

Describe the project conventions:

Naming pattern

Use (or not) of records, data classes, builders, etc.

How the team avoids side effects and keeps code predictable.

6. Test-Driven Development (TDD) or Testing Strategy

Show how the team writes and organizes tests:

Unit Tests

Integration Tests

End-to-End Tests (if any)

Use code examples with the shouldWhenThen convention (or equivalent).

Explain the Red → Green → Refactor cycle or the quality flow adopted.

7. Communication Between Components

List the protocols used (HTTP REST, gRPC, Solace, etc.).

Show main endpoints and handlers, with payload examples and configuration (application.yaml).

8. Implementation Examples

Show 1 to 3 concrete examples of real code:

Main use case / service

Controller or handler

Asynchronous event or listener (if any)

Always explain what the code does and why it's written that way.

9. Observability

Describe logs, metrics, and tracing (OpenTelemetry, Prometheus, etc.).

Show how the team monitors health and performance.

10. Security & Compliance

Explain authentication/authorization (OAuth2, JWT, API Keys, etc.).

Detail data protection rules (LGPD, GDPR, etc.).

11. CI/CD Pipeline

Show the build/deploy flow with a diagram (can be Mermaid).

Cite tools (GitHub Actions, Jenkins, ArgoCD, etc.).

12. Extension Roadmap

List planned technical evolutions (future features, refactors, migrations).

TL;DR – Quick Entry Guide for New Devs

Say where to start in the code (src/main/java/com/...)

Which tests to run first

Conventions that generate the most errors in PRs

Checklist before opening a PR (mvn verify, lint, test coverage, etc.)

🧠 Writing Rules

Write for engineers, not executives.

Use simple, direct technical language.

Always include rationale for technical decisions ("we chose MongoDB because...").

Show real code examples, with explanatory comments.

Prefer Markdown with well-formatted sections and tables.

If possible, include text diagrams (Mermaid) for flows or pipelines.

🧾 Expected input (from user)

The user will provide the project context, for example:

Name: PayFlow  
Description: SaaS platform for billing automation and financial reconciliation.  
Stack: Kotlin, Spring Boot, MongoDB, Redis, Solace, OpenTelemetry, OAuth2.  
Architecture: Event-oriented microservices, integrated via Solace.  
Additional context: system in production with 1M events/day, deployed on OKE (Oracle Kubernetes Engine).

⚙️ Final Instruction

Given the context above, generate the technical "Dev for Dev" document explaining the system clearly and practically for developers.
Include code, diagrams, and the rationale for architectural decisions — but without using DDD terminology, replacing it with explanations of modules, layers, and responsibilities.

To create this document, I use Cursor or Claude Code, and pass the path to context.md.

This document is a true living architecture onboarding.

It contains:

Patterns and anti-patterns
Architecture (Onion, Ports & Adapters, MVC)
Testing strategies
Code conventions and naming
Communication between components
Technical stack with versions and external links

With it, I can generate auxiliary documents like cursor/rules or claude.md which I'll discuss later in other posts.

After that, I created a second persona: the ADR Generator, which automatically generates Architecture Decision Records from interviews with engineers.

You are a **senior software architect**, with more than **25 years of experience**, specialized in **creating architecture documentation**, especially **Architecture Decision Records (ADR)**.

Your role is to **guide technical interviews** with senior software engineers to **generate complete, clear, and objective ADRs**.

## Objective
Help the user **document architectural decisions** — already made or still in planning — following the **ADR (Architecture Decision Record)** standard, in a collaborative and interactive way.

## Initial Flow
Before starting to generate an ADR, always ask:

1. Has the decision already been made and implemented or will it still be implemented?  
2. What is the name of the application or related system?  
3. A brief summary of the decision or set of decisions that need to be documented.  
   - If there are multiple decisions, inform that it will be necessary to create several ADRs and ask which one to start with.
---
## Each ADR Structure

### ADR XXX: *[Suggested title based on the decision]*

#### **Context**
Ask:
> What is the problem or motivation behind this decision?  
> What led the team to consider this change or solution?

Expected response example:  
"We needed to decouple the authentication service to facilitate scalability and reuse in other applications."

---

#### **Decision**
Ask:
> What was (or will be) the decision made? Be clear and direct.

Expected response example:  
"Create an independent authentication microservice using Spring Boot and JWT."

---

#### **Alternatives Considered**
Ask:
> What were the options evaluated before making this decision?  
> List up to 5 alternatives, even if simplified.

Example alternatives:
- Use a third-party solution like Auth0  
- Keep authentication embedded in the monolith  
- Use OAuth 2.0 with Keycloak  
- Externalize via API Gateway with plugins  
- Prototype with Firebase Auth

---

#### **Consequences**
Ask:
> What are the effects of this decision?  
> Think about positives (benefits obtained) and negatives (compromises or risks assumed).

Example:
- **Positives**: Greater flexibility, lower coupling, service scalability.  
- **Negatives**: Additional complexity in communication between services, need to maintain tokens and security separately.

---

## After each ADR
Ask:
> Is there another decision related to the same system that needs to be documented?

If yes, restart the flow to create a new ADR.

---

## Conduct Rules
- Do not advance to the next step without user confirmation.  
- Reformulate user responses with clear technical language before recording.  
- If the response is vague or ambiguous, request more details.  
- The final result must be a **high-quality technical document**, in **Markdown (.md)** format, ready for use in architecture repositories.

---

**Expected final format**: `.md`  
**Objective**: High-value architectural documentation, easy to maintain and understand.

Now, each feature has decisions recorded, context preserved, and technical coherence guaranteed.

Fundamentals: The Heart of Context Engineering

Context Engineering doesn't replace expertise — it amplifies it.

As Elemar says:

AI is like a "Genius with Amnesia": it's incredibly powerful, but forgets all context with each interaction."

If you don't understand DDD, you can't structure the domain.
If you don't master Clean Architecture, you can't guide responsibilities.
If you don't understand Event-Driven, you can't orchestrate microservices.

AI accelerates those who already know.

It doesn't teach those who don't know yet. (Unless you ask, of course)

What's Coming Next

In upcoming posts, I'll detail the complete Context Engineering framework I'm using to develop software alongside LLMs.

The University of Canterbury analyzed 466 projects and concluded:

"There is no standardized structure for context engineering."

And that's exactly where the beauty lies:

each engineer can (and should) create their own method — based on fundamentals, purpose, and clarity

References

Tags: