DEV Community: Matsu

The AI Engineering Concepts I Wish Someone Explained Simply

Matsu — Wed, 21 Oct 2026 12:00:00 +0000

It’s fascinating how AI is changing the day-to-day work of software engineers.

We used to spend a lot of time learning syntax (or should I say memorizing it? haha) and understanding the abstractions behind frameworks and libraries.

Then AI-assisted coding became part of our daily work, and we started hearing about the "vibe coding": using AI to build something while focusing mostly on the outcome, sometimes without paying enough attention to the bigger picture—architecture, reliability, security, and best practices.

Then came agentic coding, which I think is where many developers are right now: using agents to generate code, navigate repositories, run commands, and help implement changes.

Now there’s this idea of Agentic Engineering, which goes a bit further. Instead of just asking an agent to write code, it's about optimizing our day-to-day work by delegating tasks to agents that are configured with the right context.

I was watching an IBM video about Agentic Engineering linked in this article, and one idea that stuck with me was this shift from writing to shaping.

Instead of writing everything ourselves, we start shaping the environment around agents—defining rules, skills, context, tools, and what we actually expect from them - so they can work in sync with what we need. And IMO, this is where the future of software engineering is going.

Agentic Engineering goes way beyond just writing code. With the right setup and context, you can have agents handle many of the tasks that are part of your everyday engineering work. Need to understand what happened with a specific request? Have an agent investigate the logs. Want to check if an implementation actually follows the tech spec? Let an agent compare them. Need to investigate a bug, review some code, or figure out why something isn't working as expected? Those are tasks you can delegate to an agent too.

The idea is simple: instead of using agents only to write code, you can use them to do the engineering work around the code. The interesting part is that our job starts becoming less about writing everything ourselves and more about shaping how the work gets done.

But once you start exploring this, you run into a bunch of terms: agents, tokens, context engineering, skills, MCP, orchestration... and it isn't always obvious what each one means or how they fit together. And that's exactly why I wanted to write this post.

I've been learning about these concepts while exploring different tools and ways of working with AI, and I realized that some of them sound way more complicated than they actually are.

So I decided to put together a glossary of the AI Engineering concepts I think every SWE should at least be familiar with. Nothing too academic or overly technical, just simple explanations, practical examples, and how these concepts connect to each other.

Let's get into it!

1. The Foundation

LLM (Large Language Model)

An LLM is a type of AI model trained on large amounts of data to understand and generate language. At its core, it works by predicting tokens based on the context it receives. That might sound simple, but this ability allows LLMs to write code, explain complex topics, summarize documents, reason through problems, and much more.

Think of an LLM as the engine behind tools like ChatGPT, Claude, and other AI assistants.

Models

You've probably heard names like GPT, Claude, Gemini, or DeepSeek. These are different families of AI models, developed by different organizations, with different capabilities, limitations, and costs.

And choosing a model isn't always about picking the "smartest" one. Some models are better at complex reasoning, others are faster, cheaper, or more suitable for specific tasks.

For example, you probably don't need the most expensive reasoning model just to summarize a log file. But investigating a complex issue across multiple services might benefit from a more capable one.

If you're curious about how models compare in terms of performance, pricing and speed, Artificial Analysis is a useful resource.

System One Models (Jev)

Here's something interesting: not every AI model is designed to generate text.

In September 2026, TypeSafe AI announced Jev, a different kind of model they call a System One Model.

While traditional LLMs generate text token by token, Jev is designed to make fast, structured decisions. Instead of asking it to write an explanation, you provide some information and define the possible answers. The model then returns a structured decision with scores that can help the application evaluate the result.

For example, imagine you're building a system that processes incoming support tickets. Instead of asking an LLM to read every ticket and generate a response explaining which team should handle it, you could use Jev to classify the ticket directly into categories like billing, technical, or account.

And because the possible outputs are defined in advance, your application can use the result without having to interpret free-form text. The interesting part is that Jev doesn't generate text autoregressively like traditional LLMs. It's designed to produce structured decisions in parallel, making it potentially faster and cheaper for certain constrained decision tasks. Those benefits depend on the workload and should be benchmarked rather than assumed.

Of course, this doesn't mean it replaces LLMs. You wouldn't use Jev to write an entire application or explain a complex architecture. Think of general-purpose LLMs as flexible language engines and Jev as an example of a model designed for constrained decisions. “System One Model” is TypeSafe AI’s terminology here, not a universally adopted model category.

And this is another reason why choosing the right model for the right task matters.

Tokens

Tokens are the units of text that language models process. A token isn't necessarily a word. It can be a whole word, part of a word, punctuation, or even whitespace.

For example, a sentence might be split into several tokens depending on the model's tokenizer. Why does this matter?

Because tokens affect cost, performance, and how much information a model can process. When you send a prompt, include documentation, attach logs, or receive a response, you're consuming tokens. That's why dumping thousands of lines of logs into an agent isn't always the best idea.

Context

Context is the information available to a model when it's generating a response. It can include your instructions, conversation history, source code, documentation, logs, tool results, and anything else provided to help it understand the task. For example, imagine asking an agent: Why is this API request failing?

Without context, the model can only make assumptions or suggest generic debugging steps. But if you provide relevant logs, architecture documentation, and request details, it has a much better chance of finding the actual problem. And this leads to something we'll explore later: Context Engineering.

Context Window

The context window is the maximum amount of information a model can process at once, measured in tokens.

Think of it as the model's available working space. Your instructions, conversation history, code, documentation, and tool responses all compete for that space.

And here's something important: a larger context window doesn't automatically mean better results. Even when a model can technically handle a huge amount of information, irrelevant or poorly organized context can make it harder to find what's actually important.

That's one of the reasons why managing context becomes so important when working with agents.

2. Anatomy of an AI Agent

Now that we've covered the basics, let's talk about agents.

We've been using this word a lot, but what actually makes something an agent? And how is it different from simply asking ChatGPT a question?

To understand that, let's break down the concepts behind an agent, how it works, and how agents can collaborate with each other.

Agent

An AI agent is a system that uses an AI model to work toward a goal, make decisions about what to do next, and interact with tools or its environment to accomplish a task.

The important part here is that an agent doesn't just generate a response. It can take actions.

For example, when you ask an LLM to investigate a bug, it might suggest where to look or what could be causing the problem. But an agent with the right tools and permissions could actually inspect the code, search through logs, run tests, identify a possible cause, and suggest or implement a fix.

And it doesn't necessarily have to follow a fixed sequence of steps. Based on what it discovers, it can decide what to investigate next. Of course, that doesn't mean agents are always correct or should have unlimited permissions. Their work still needs appropriate boundaries and verification.

But here's something interesting: agents can also delegate work to other agents. And that's where subagents come in.

Subagent

A subagent is simply an agent that receives a task delegated by another agent or a coordinating system. Think about how we work in engineering teams.

When you're investigating a complex issue, you might ask another engineer to check the logs while you inspect the code. You're both working toward the same goal, but focusing on different parts of the problem. Agents can work in a similar way.

For example, imagine an agent investigating why an API request is failing. Instead of doing everything itself, it could delegate:

Log analysis to one subagent.
Code inspection to another.
Documentation review to a third.

Each subagent works on its assigned task and returns its findings to the main agent, which can then combine the results. A subagent isn't necessarily a different kind of AI. It's still an agent, but operating as part of a delegated workflow.

It might use the same model as the main agent, a different model, or even have a completely different set of tools and instructions. And depending on the system, subagents can work sequentially or in parallel.

Scout

A scout is an agent specialized in exploration, research, or gathering information.

The term isn't universally standardized, so its exact meaning can vary depending on the tool or framework you're using. But the general idea is simple: instead of having the main agent explore everything, you delegate the discovery work to a scout.

Imagine you're working in a large codebase and need to understand how authentication works. You could ask a scout to:

Find the files responsible for authentication.
Identify the relevant services and dependencies.
Locate related technical documentation.
Report how the authentication flow is implemented.

The scout explores the codebase and returns a summary of its findings. This can help the main agent focus on the actual task without having to perform every investigation itself. And here's an important distinction:

Subagent describes the relationship between agents. Scout describes what an agent specializes in.

A scout can be used as a subagent, but it doesn't necessarily have to be one.

Persona

A persona defines the role, behavior, or perspective we want an agent to adopt.

For example, you might configure an agent to behave like a senior backend engineer, a security reviewer, an SRE, or a technical lead. But a persona isn't just saying "You are a senior engineer" and expecting magic to happen. 😅

A useful persona can also define responsibilities, constraints, priorities, and how the agent should communicate its findings. For example, an SRE-oriented persona might instruct an agent to:

Prioritize evidence from logs and metrics.
Avoid making production changes without approval.
Clearly distinguish confirmed findings from hypotheses.
Provide a structured incident investigation report.

But here's something that can be confusing at first: A persona isn't the same thing as an agent.

Think of it this way:

Agent: The system that performs the work.
Persona: The role and behavior assigned to that system.

You could have two agents using exactly the same LLM but with different personas, tools, and responsibilities. One might act as a code reviewer, while the other acts as an incident investigator.

And depending on the framework, a persona might be defined in a Markdown file, a system prompt, or another configuration format. But simply creating a persona doesn't necessarily create a new runnable agent. That depends on how the system is configured to load and execute agents.

Tools

Tools are what allow agents to interact with the world outside the model.

An LLM by itself doesn't automatically have access to your terminal, filesystem, databases, APIs, or monitoring systems.
But when connected to tools, an agent can perform actions such as:

Reading and editing files.
Running terminal commands.
Searching documentation.
Querying logs and databases.
Calling external APIs.
Executing tests.

For example, imagine an agent investigating a production issue. It might use one tool to search application logs, another to inspect the relevant source code, and another to retrieve technical documentation.

The model can select actions, while tools provide the capabilities to carry them out.

Of course, the agent can only use the capabilities exposed to it, and those capabilities should be restricted according to the task and required permissions.

Tool Calling

Okay, but how does an agent actually use those tools? That's where tool calling comes in.

Tool calling is the mechanism that allows a model to request the execution of a tool, usually by producing a structured call containing the tool name and its arguments. The application running the agent receives that request, executes the tool, and returns the result to the model. For example, imagine asking an agent:

Find out why request ABC failed.

The process might look like this:

The model decides it needs to search the logs.
It generates a tool call to query the logging system.
The agent's runtime executes that call and returns the results.
The model analyzes the logs and decides what to investigate next.
If necessary, it makes additional tool calls until it has enough information to provide an answer.

This process can repeat multiple times until the agent reaches a conclusion, encounters a limit, or needs human input. One important detail: the model doesn't execute the tool itself. The surrounding software handles the execution.

And this distinction becomes important when we talk about Agent Harnesses.

Agent Harness

This is one of those terms that sounds more complicated than it needs to be.

An agent harness is the software environment around the model that makes agentic behavior possible. Remember when we talked about tool calling?

The model can request a tool, but something needs to actually execute it, return the result, manage the conversation, and determine when the agent should continue or stop.

That's part of what the harness does. Depending on the implementation, a harness can manage:

The agent's execution loop.
Tool availability and execution.
Context and conversation history.
Permissions and safety boundaries.
State and persistence.
Error handling and retries.
Delegation to other agents.

Think of the model as the reasoning engine and the harness as the system that allows that engine to operate.

The same model can behave very differently depending on the harness it's running in.

And that's an important idea because improving an agent isn't always about switching to a more powerful model. Sometimes, improving the environment around it makes a bigger difference.

Orchestration

Now that we know agents can delegate work to subagents, how do we coordinate everything?

That's where orchestration comes in. Orchestration is the process of coordinating tasks, agents, tools, and their results to accomplish a larger goal.

Imagine you're investigating a production incident involving multiple services. Instead of having one agent investigate everything sequentially, you could organize the work like this:

A main agent analyzes the incident and creates an investigation plan.
A scout explores the codebase to identify the relevant services.
Another subagent searches logs for errors related to the incident.
A third subagent checks recent deployments and changes.
The main agent collects their findings, compares the evidence, and decides whether more investigation is needed.
Finally, it produces a report explaining the likely root cause and supporting evidence.

That's an example of a multi-agent workflow. But orchestration doesn't necessarily require multiple agents. It can also coordinate tools and tasks within a single-agent workflow. And here's another important distinction: Orchestration isn't an agent or a persona. It's the coordination of the work.

You can have an agent responsible for orchestration, often called an orchestrator agent, with a persona that defines how it should plan, delegate, and validate tasks.

Orchestration can also be handled by the harness or by predefined application logic. So, to summarize:

Agent: The system doing the work.
Subagent: An agent working on a delegated task.
Scout: An agent specialized in exploration and information gathering.
Persona: The role and behavior assigned to an agent.
Orchestration: How tasks and agents are coordinated.

And the interesting part is that these concepts can work together. An orchestrator agent can have a technical lead persona, delegate investigations to scouts and other subagents, and use tools to validate their findings. All of this without requiring every agent to use the same model or have the same capabilities.

3. Engineering the Agent's Environment

So, we have models, agents, tools, and a harness that connects everything together.

But here's the thing: having a powerful model and a bunch of tools doesn't automatically mean you'll have a useful agent.

The agent still needs to understand your project, know where to find information, follow your team's conventions, and have clear instructions about what it's supposed to do.

And this is where some of the most interesting AI Engineering concepts come in.

Prompt Engineering

You've probably heard this one a thousand times already. Prompt engineering is the practice of designing instructions that help an AI model produce better results.

Instead of just asking: Review this code.
You could be more specific: Review this implementation for potential bugs, security issues, and performance problems. Follow our team's coding standards, explain your findings, and prioritize them by severity.

The second prompt gives the model a clearer objective and expectations. But there's a limitation: a good prompt alone doesn't guarantee a good result.

If the model doesn't have access to the relevant code, documentation, or tools, there's only so much it can do.

And that's where Context Engineering comes in.

Context Engineering

This is one of my favorite concepts because it changes how we think about working with AI. While Prompt Engineering focuses on how we ask, Context Engineering focuses on what information the model has available when it needs to do the work.

Context engineering is the practice of selecting, organizing, and delivering the right information to a model at the right time.

And it's not just about adding more context.

Imagine asking an agent to investigate why an API request failed. You could dump thousands of lines of logs, the entire codebase, and all your documentation into the context window. But would that actually help?

Maybe. Or maybe the important information would get buried under a bunch of irrelevant data.

A better approach might be to provide the request ID, the relevant service architecture, and tools that allow the agent to retrieve specific logs or documentation as needed.

The goal isn't to give the agent all the information. It's to give it the right information.

This can involve retrieving documents, summarizing previous interactions, filtering tool results, managing conversation history, and deciding what should remain in the context window.

Harness Engineering

Remember the Agent Harness we talked about earlier? Harness Engineering is the practice of designing and improving that environment so agents can work more effectively, reliably, and safely.

If Context Engineering is about managing the information available to the model, Harness Engineering is about designing the system in which the agent operates.

For example, imagine you're building an agent that reviews pull requests. You might configure its harness to:

Retrieve the PR description and changed files.
Load the team's coding standards.
Provide tools to inspect the repository and run tests.
Restrict which commands the agent can execute.
Require evidence for every issue it reports.
Run automated checks to validate its findings.

Notice that we haven’t changed the underlying model. We’ve improved the environment around it.

And that's the interesting part: sometimes the biggest improvement doesn't come from a better model, but from a better setup.

Context Engineering and Harness Engineering overlap quite a bit, but they're not exactly the same thing.

Context Engineering focuses on the information the model receives, while Harness Engineering covers the broader execution environment, including tools, permissions, workflows, and feedback loops.

RAG (Retrieval-Augmented Generation)

Okay, another acronym, haha. RAG stands for Retrieval-Augmented Generation. It's a technique that allows an AI system to retrieve relevant information from external sources and use it when generating a response.

Instead of relying only on what the model learned during training, the system can look up information from documents, databases, knowledge bases, or other sources.

For example, imagine you have hundreds of internal technical specifications.

You ask: Does this implementation follow the authentication specification?

A RAG-based system could search those documents, retrieve the relevant sections, and provide them to the model so it can compare the implementation against the requirements.

A common approach uses embeddings and vector databases to find semantically similar content, but RAG isn't limited to vector search. Keyword search, hybrid search, and other retrieval methods can also be used.

RAG is one way of providing relevant context to a model without putting everything into the prompt upfront.

And while RAG can help ground responses in real information, the model can still misinterpret what it retrieves. The quality of the sources and retrieval process matters.

MCP (Model Context Protocol)

MCP is another term you'll hear everywhere when working with agents. And I think it's easy to misunderstand at first. MCP is a standard protocol that allows AI applications to connect to external systems that expose tools, resources, and prompts.

Think of it as a common interface between AI applications and external capabilities.

Without a shared protocol, each AI application might need a custom integration for every service it wants to use.

With MCP, a compatible client can communicate with MCP servers through a standardized protocol.

For example, you could have MCP servers that provide access to:

GitHub repositories and pull requests.
Jira tickets.
Internal documentation.
Observability platforms.
Databases and other services.

An agent using an MCP-compatible application could discover available tools and call them to perform tasks, subject to the application's permissions and configuration.

But here's an important distinction: MCP isn't the tool itself. It's the protocol used to expose and access capabilities. And not every tool needs MCP. Agents can also use tools through native integrations, APIs, or other mechanisms.

Skills

Skills are one of the concepts I find particularly useful for everyday engineering work.

A skill is a reusable package of instructions, workflows, and sometimes supporting resources that helps an agent perform a specific kind of task.

Think about a task you perform regularly, like investigating an incident.

You probably have a process in your head:

Identify the affected services and request.
Retrieve the relevant logs.
Check for related errors or recent deployments.
Compare the behavior against the expected implementation.
Summarize the findings with supporting evidence.

Instead of explaining that process to an agent every single time, you could define it as a skill.

Depending on the agent platform, skills might be stored as Markdown files with instructions, scripts, templates, or other resources that the agent can load when relevant.

And here's a distinction I think is worth remembering: Tools give agents capabilities. Skills teach agents how to use those capabilities to accomplish a task.

For example, a logging tool gives an agent the ability to search logs. An incident investigation skill tells it how to approach the investigation, which information to collect, what to verify, and how to report the results.

Skills don't necessarily provide new capabilities on their own, although some can include scripts or other executable resources. And when you combine skills with the right context and tools, you can start building agents that understand and follow your team's engineering workflows.

At this point, we have most of the building blocks. We have models that can reason about tasks, tools that let agents interact with external systems, context that provides relevant information, skills that guide how work should be done, and a harness that brings everything together.

But what happens when a task is too large or complex for a single agent? That's where subagents, scouts, and orchestration come into the picture.

4. What Counter-Strike Can Teach Us About AI Agents 🎮

Okay, actually nothing... Let's use Counter-Strike as an analogy. And if you've never played CS, don't worry, the idea is pretty simple. 😅

Imagine you're playing a match with a team of bots.

The Agent Is Your Player

Think of an AI agent as a bot playing Counter-Strike.

The bot has an objective, can make decisions, interact with the environment, and use the equipment available to it. But the bot doesn't magically know everything that's happening in the match. It needs information, capabilities, and a system that allows it to act.

Sound familiar? That's basically what we've been discussing about AI agents.

The Model Is the Brain, and the Harness Is the Game System

The LLM is like the decision-making engine behind your bot. It analyzes the available information and decides what to do next.

The harness is the software that connects those decisions to actions, similar to how the game system allows a bot to move, shoot, use equipment, and interact with the map.

And just like two bots with different decision-making capabilities might perform differently, different AI models can produce different results.

But even a great model won't be very useful if the environment around it doesn't provide the capabilities it needs.

Personas Are the Roles on Your Team

In Counter-Strike, players have different roles. You might have:

IGL (In-Game Leader): Coordinates the team and calls strategies.
Entry Fragger: Takes the first fights and creates space.
AWPer: Focuses on holding angles and getting picks with the AWP.
Support: Uses utility to help teammates.
Lurker: Operates separately to gather information, control areas, or catch rotations.

These roles don't create new players. They describe how the players are expected to behave. It's the same idea with personas.

You can configure an agent to behave like a technical lead, an SRE, a code reviewer, or an orchestrator.

The agent is the player. The persona is the role assigned to that player.

And here's an important detail: giving a bot an AWPer persona doesn't automatically spawn another bot.

You still need an actual player configured and running.

Similarly, installing a persona doesn't necessarily create a new runnable AI agent.

Tools Are Your Weapons and Equipment

An AK-47, an AWP, a smoke grenade, or a flashbang gives a player different capabilities. But having an AWP doesn't automatically make someone a good sniper, right? haha

The same applies to AI agents.

Giving an agent access to a terminal, a logging platform, or a database doesn't automatically mean it knows how to use those tools effectively.

It still needs the right instructions, context, and decision-making capabilities. And tool calling is like the bot deciding when and how to use its equipment.

Context Is Your Game Information

Imagine playing Mirage without knowing where your teammates are, how much time is left, or whether the enemy team is stacking A or B.

Good luck with that.

In Counter-Strike, information comes from your radar, teammate callouts, sound cues, the economy, and what you've observed during the round.

That information helps you make better decisions. For AI agents, context plays a similar role.

An agent investigating a production issue needs relevant logs, request details, architecture documentation, and other information to understand what's happening.

And Context Engineering is like making sure your team receives the right callouts at the right time. You don't need every teammate shouting everything they see simultaneously. You need useful information that helps you make the next decision.

Skills Are Your Strategies and Playbooks

Think about a well-practiced A-site execute on Mirage.

Everyone knows the strategy: where to position, which smokes to throw, when to flash, and how to enter the bombsite. You don't need to explain the entire strategy from scratch every round.

That's similar to how skills work with AI agents. A skill provides reusable instructions and workflows for accomplishing a particular task.

For example, an incident investigation skill could define how to retrieve logs, correlate errors, inspect recent deployments, and report findings.

Tools give you the equipment. Skills give you the playbook for using it.

Subagents and Scouts Are Your Teammates

Now imagine you're the IGL.

You don't need to personally check every corner of the map. You can ask one teammate to watch mid, another to check B apartments, and another to prepare utility for an A execute.

In our analogy, those teammates represent subagents working on delegated tasks. And a scout is like the teammate you send to gather information before deciding what to do.

For example, you might ask a scout to check whether enemies are holding mid before committing to a strategy.

In AI Engineering, a scout might explore a codebase, locate relevant documentation, or investigate which services are involved in a request.

Remember: subagent describes the delegation relationship, while scout describes the specialization.

Orchestration Is Your IGL Calling the Round

Now let's imagine your IGL is an AI agent.

The objective is simple:

Win this round on Mirage.

The IGL might coordinate the team like this:

Ask the scout to gather information about mid.
Tell the support player to prepare smokes for A.
Ask the entry fragger to get ready.
Wait for the scout's callout.
Decide whether to execute A or rotate B.
Coordinate the team's actions based on what happens.

That's orchestration.

The IGL isn't necessarily doing every task. It's planning, delegating, collecting information, and adapting the strategy.

And this is exactly what an orchestrator agent can do in an engineering workflow.

For example, imagine asking an agent:

Investigate why our API is returning 500 errors.

It could delegate log analysis to one subagent, code inspection to another, and deployment investigation to a third. Then it collects their findings, compares the evidence, and produces a report.

The orchestrator is an agent performing a coordination role. Orchestration is the activity of coordinating the work.

And that's the distinction.

So, What's the Point?

The interesting thing is that you don't necessarily need a completely different AI model for each role.

Just like players on the same Counter-Strike team can have different responsibilities, agents using the same model can behave differently depending on their personas, tools, skills, and context.

And sometimes you don't even need multiple agents. A single well-configured agent might be enough for the task.

The goal isn't to build the biggest team of agents possible.

It's to give the right responsibilities, information, and capabilities to the right agents, and make sure their work is coordinated effectively.

And that's where Agentic Engineering starts to make a lot more sense.

5. Tools Worth Exploring

Okay, enough theory. What if you actually want to try some of this stuff?

There are plenty of tools out there for working with AI agents, and now that we've covered the concepts, I think it's easier to understand what these tools actually do.

Here are two interesting examples.

OMP (Oh My Pi) — An Agent Harness

Remember when we talked about Agent Harnesses?

Oh My Pi (OMP) is a practical example of one.

It provides an environment where AI models can interact with tools, execute commands, manage context, and work on engineering tasks.

And one of the interesting things is that you can configure specialized agents with different models, personas, tools, and permissions.

For example, you could have an orchestrator agent responsible for planning and delegating tasks, while other agents focus on implementation, investigation, or code review.

The important part is that OMP provides the environment where those agents can actually operate.

Herd — Multi-Agent Orchestration

Now, remember when we talked about subagents, scouts, and orchestration?

Herd is an example worth exploring when looking at multi-agent workflows. (Check the project’s current documentation and availability before adopting it.)

The idea is to coordinate multiple specialized agents working toward a common goal, rather than relying on a single agent to handle everything.

Think about our Counter-Strike analogy: instead of one player trying to do everything, you have an IGL coordinating teammates with different responsibilities.

That's the kind of problem multi-agent orchestration aims to solve.

And the interesting part is that orchestration isn't about having more agents just for the sake of it. It's about organizing the work so each agent can focus on what it does best.

Which One Should You Use?

I wouldn't focus too much on choosing the perfect tool right away.

The important thing is understanding the concepts behind them.

Once you understand models, harnesses, personas, tools, skills, and orchestration, it becomes much easier to explore different setups and understand what each one brings to the table.

And remember: you don't need a whole army of agents to practice Agentic Engineering.

Sometimes, a single well-configured agent with the right context and tools is exactly what you need.

6. Where to Start

If all of this sounds interesting but a little overwhelming, start small. You don't need a multi-agent system on day one.

Pick a task you already do regularly—investigating a failed request, reviewing a pull request, or checking an implementation against a technical specification. Give one agent a clear objective, access to only the tools it needs, and a simple checklist of what a good result looks like.

Then review what it produces. Did it find useful evidence? Did it make assumptions? Could you reproduce its conclusions? Improve the instructions, context, and permissions based on what you learn.

Only introduce subagents or orchestration when there's a real reason to split the work. More agents can also mean more cost, coordination overhead, and opportunities for mistakes.

For me, that's the most exciting part of Agentic Engineering. We're not just learning how to ask AI to write code. We're learning how to design better engineering workflows around it.

The goal isn't to automate judgment away. It's to give engineers better tools to investigate, build, and verify software.

I'm still exploring these ideas myself, so I'd love to hear how you're using agents in your day-to-day engineering work.

Transactional Outbox Pattern - Improving how we deal with atomicity

Matsu — Wed, 21 Oct 2026 11:18:47 +0000

Transactional Outbox Pattern: Solving the Dual-Write Problem with Atomicity

When building distributed systems, we often need to perform multiple operations as part of a single business action.

Imagine you're developing an e-commerce application using Node.js, PostgreSQL, and Kafka.

When a customer creates an order, your application needs to:

Save the order in PostgreSQL.
Publish an OrderCreated event to Kafka so other services can react.

Sounds simple, right?

async function createOrder(orderData) {
  const order = await db.orders.create(orderData);

  await kafka.publish("OrderCreated", {
    orderId: order.id
  });

  return order;
}

But what happens if PostgreSQL successfully creates the order and Kafka becomes unavailable?

We now have an order in our database, but the other services don't know about it.

This is where things start getting interesting.

Understanding the Dual-Write Problem

The dual-write problem happens when an application needs to write to two independent systems as part of the same logical operation.

In our example:

PostgreSQL stores the order.
Kafka distributes the event.

The problem is that these systems don't share the same transaction.

Let's consider two scenarios.

Scenario 1: Database first

Create order in PostgreSQL  ✅
Publish event to Kafka     ❌

The order exists, but the event was never published.

Scenario 2: Kafka first

Publish event to Kafka     ✅
Create order in PostgreSQL ❌

Now other services might receive an event about an order that doesn't exist.

Reversing the operations doesn't solve the problem. It just changes which inconsistency we might encounter.

So how do we guarantee that our business operation and the intent to publish its event succeed or fail together?

Before answering that, we need to understand atomicity.

What Is Atomicity?

Atomicity is one of the four ACID properties of database transactions:

Atomicity: All operations within a transaction succeed, or none of them do.
Consistency: Transactions preserve the database's integrity constraints.
Isolation: Concurrent transactions follow defined rules about how their operations interact.
Durability: Once committed, changes survive failures.

Let's focus on atomicity.

Imagine transferring $100 between two bank accounts.

Account A: -$100
Account B: +$100

Both operations belong to the same logical transaction.

We cannot accept a situation where Account A loses $100 but Account B never receives it.

That's why databases support transactions:

BEGIN;

UPDATE accounts
SET balance = balance - 100
WHERE id = 1;

UPDATE accounts
SET balance = balance + 100
WHERE id = 2;

COMMIT;

If an operation fails before the transaction commits, the database can roll back the entire transaction.

But here's the catch:

A PostgreSQL transaction cannot normally control a Kafka publication.

Even if we write:

await db.transaction(async (tx) => {
  await tx.orders.create(orderData);

  await kafka.publish("OrderCreated", event);
});

Kafka is still an independent system.

If Kafka accepts the event but the database transaction later fails to commit, we have an inconsistent state.

We need another approach.

Introducing the Transactional Outbox Pattern

The Transactional Outbox Pattern solves this problem with a simple idea:

Instead of publishing the event directly to Kafka, persist the event in the same database transaction as the business operation.

We introduce a new table called outbox.

Our transaction becomes:

BEGIN;

INSERT INTO orders (id, status)
VALUES (42, 'CREATED');

INSERT INTO outbox (
  id,
  event_type,
  payload
)
VALUES (
  'evt-123',
  'OrderCreated',
  '{"orderId": 42}'
);

COMMIT;

Now both operations happen inside PostgreSQL.

That means we have two possible outcomes:

Order created ✅
Outbox event created ✅

Or:

Order created ❌
Outbox event created ❌

We no longer have a committed order without its corresponding outbox record.

That's the fundamental benefit of the pattern.

Notice that we didn't make PostgreSQL and Kafka atomic.

Instead, we moved the atomicity boundary to something PostgreSQL can actually guarantee.

But How Does the Event Reach Kafka?

Good question!

We introduce another component, usually called an Outbox Relay or Outbox Publisher.

Its responsibility is to read unpublished events from the outbox table and forward them to our messaging system.

Our architecture becomes:

      Node.js Application
              |
              v
     PostgreSQL Transaction
       /             \
      v               v
  Orders Table     Outbox Table
                        |
                        v
                   Outbox Relay
                        |
                        v
                       Kafka
                        |
                        v
                 Other Services

A simplified relay could look like this:

async function publishPendingEvents() {
  const events = await db.outbox.findPending();

  for (const event of events) {
    await kafka.publish(event.event_type, event.payload);

    await db.outbox.markAsPublished(event.id);
  }
}

This is intentionally simplified. A production implementation needs to handle concurrent workers, failures, retries, and message ordering.

The important part is that the event is persisted before we attempt to publish it.

If Kafka becomes unavailable, the event remains in our database and can be retried later.

Polling vs. Event-Driven Relays

A common implementation uses a background worker that periodically queries the outbox table.

For example:

SELECT *
FROM outbox
WHERE published_at IS NULL;

But what if we don't want to wait for the next polling interval?

With PostgreSQL, we can use LISTEN/NOTIFY.

When an outbox event is inserted, the database can emit a notification to wake up the relay.

The relay then queries the outbox and publishes pending events.

However, there's an important distinction:

The notification is not the event itself. It's just a signal that new work might be available.

Notifications aren't a durable queue. If the relay is disconnected, it may miss them.

That's why the outbox table remains our source of truth, and the relay should also query for pending events on startup, reconnection, and periodically.

Another approach is Change Data Capture (CDC), using tools such as Debezium to observe committed database changes and forward outbox events without application-level polling.

What About Duplicate Events?

Here's another interesting problem.

Imagine the relay performs these operations:

1. Read event from outbox        ✅
2. Publish event to Kafka       ✅
3. Mark event as published      ❌

What if the relay crashes immediately after Kafka accepts the message?

The event was published, but the database still considers it pending.

When the relay restarts, it might publish the same event again.

This is why the Transactional Outbox Pattern commonly provides at-least-once delivery, assuming the relay continues retrying and the underlying infrastructure eventually recovers.

That means an event can be delivered more than once.

To handle this safely, consumers should be idempotent.

For example, a consumer can track processed event IDs and avoid applying the same business operation twice.

Receive evt-123
      |
      v
Already processed?
   /       \
  Yes       No
   |         |
 Ignore    Process

In practice, the consumer should atomically record the event ID and apply its business changes, so concurrent duplicate deliveries don't create duplicate effects.

What About Multiple Relay Workers?

As our system grows, we might want multiple relay workers processing events concurrently.

But imagine two workers querying the same pending event.

Worker A → evt-123
Worker B → evt-123

Without coordination, both workers might publish it.

PostgreSQL provides a useful mechanism called FOR UPDATE SKIP LOCKED.

SELECT *
FROM outbox
WHERE published_at IS NULL
ORDER BY created_at, id
LIMIT 100
FOR UPDATE SKIP LOCKED;

When used inside a transaction, this allows workers to lock available rows while skipping rows locked by other transactions.

This helps distribute work across workers.

For longer publishing operations, we can instead claim rows in a short transaction and use leases or timeouts to recover work from crashed workers.

There's also message ordering to consider. If OrderCreated and OrderPaid belong to the same order, we may need to preserve their relative order, even while processing different orders concurrently.

These are important implementation decisions, but they don't change the fundamental purpose of the pattern.

When Should We Use Transactional Outbox?

Transactional Outbox is especially useful when:

A business database change must reliably produce an event.
Losing an event could leave other services inconsistent.
We need reliable asynchronous communication between services.
We want to tolerate temporary messaging infrastructure failures.

However, the pattern also introduces additional complexity: outbox storage, relays, retries, monitoring, cleanup, idempotency, and potentially ordering guarantees.

Not every event requires that complexity.

For example, losing an occasional non-critical analytics event may be acceptable.

As with most architectural patterns, the decision should depend on the business requirements.

Final Thoughts

The biggest lesson I've learned about the Transactional Outbox Pattern is that we don't need to make every component of a distributed system participate in one giant transaction.

Instead, we can use the atomicity guarantees of a local database transaction to persist both our business changes and the intent to publish an event.

Then we rely on asynchronous delivery, retries, and idempotent consumers to propagate that change safely.

The mental model I like is:

Atomic locally.
Eventually propagated globally.
Duplicates handled safely.

Transactional Outbox doesn't eliminate every challenge in distributed systems, but it gives us a reliable foundation for handling one of the most common problems: keeping business state and event publication consistent.

And sometimes, the most valuable architectural patterns aren't about introducing something complex. They're about moving the problem into a boundary where we already have strong guarantees.

How Relational Databases Find Database: Understanding Table and Index Scans

Matsu — Thu, 12 Mar 2026 10:08:04 +0000

When creating indexes it's important to understand how they work. In my previous post, I've explained the basics of indexes and the EXPLAIN command. Now we can go a step further and look at the different types of reads a database can perform.

Understanding these access patterns is crucial because it helps us evaluate the trade-offs of creating (or not creating) an indexes. It also gives us insight into what happens under the hood when a query is executed.

At a high level, databases retrieve data in two main ways:

Scanning the table directly (reading rows sequentially);
Using an index to locate rows more efficiently;

The query planner decides which strategy to use based on statistics, table size, and how selective the query conditions are.

Since different databases use slightly different terminology, I've included the names used by each database engine for reference.

1. Full table scan (FTS)

Oracle DB: Full table scan
SQL Server: Table Scan
MySQL: Table Scan
PostgreSQL: Sequential scan (Seq Scan)

This is generally the least efficient scan, with O(n) complexity. The database reads the entire table sequentially, checking each row to see if it matches the query conditions.

When is it used?

For small tables, the query optimizer may decide that a full table scan is actually more efficient than using an index;
For queries that need most of the rows in the table;

Sequential scans are not always bad. Modern databases can read tables very efficiently using sequential disk access, which can sometimes outperform index lookups when a large percentage of rows must be returned.

Full table scans can lead to high I/O, increased CPU usage, and slower response times, especially on large datasets. Monitoring queries and minimizing unnecessary full table scans is a key part of database performance tuning.

2. Index Scan

Oracle DB: Index Range Scan
SQL Server: Index Seek
MySQL: Index Lookup / Range Scan
PostgreSQL: Index Scan

An Index Scan uses an index to locate relevant rows and then fetches the full row from the table (often called the heap in PostgreSQL).

This means the database performs two steps:

Find matching entries in the index
Follow pointers to retrieve the actual rows in the table

When is it used:

Queries filtering on columns with an index;
When only a small subset of rows matches the criteria;

Because the database must jump between the index and the table, index scans can involve random I/O. For queries that return many rows, this can become slower than a sequential scan.

3. Covering Index Scan

Oracle DB: Index Fast Full Scan
SQL Server: Index Seek (covering)
MySQL: Covering Index
PostgreSQL: Index Only Scan

A covering index scan can satisfy the query using only the index, without reading the main table. This avoids additional I/O and can be extremely fast.

In PostgreSQL, this appears as an Index Only Scan, although the database may still access the table if it needs to check row visibility.

When is it used:

Queries that only request columns included in the index;
Read-heavy queries where performance is critical;

Indexes require additional storage. They are most effective when queries are frequent and selective, and less useful if the query needs columns that are not part of the index.

4. Bitmap Index Scan

Oracle DB: Bitmap Index Scan
SQL Server: Bitmap Filter
MySQL: Not implemented the same way
PostgreSQL: Bitmap Index Scan & Bitmap Heap Scan

The database first scans one or more indexes and builds a bitmap representing the locations of matching rows. It then reads the table pages in a more optimized order.

When is it used:

Queries with multiple indexed conditions (e.g., WHERE status='active' AND type='premium');
Medium to large tables where reading rows individually would be slow;

More memory usage to build the bitmap. Very efficient for combining multiple indexes, but not ideal for very small or highly selective queries.

Choosing the right scan

The query planner decides which scan to use based on several factors:

Table size
Index availability
Selectivity of the query
Table statistics

Because of this, adding an index does not guarantee it will be used. If the planner estimates that most rows will be returned, it may choose a sequential scan instead.

Understanding these access methods helps interpret EXPLAIN output and design indexes that actually improve performance.

Console You Later!

"The API Is Slow, Fix It!" – What I Learned About `EXPLAIN` and Indexing

Matsu — Thu, 29 May 2025 13:52:40 +0000

During a technical interview, the situation was something like this:

“Your manager tells you: the API is too slow. Fix it!”

So I started walking through what I’d do — checking logs, measuring response time, analyzing the stack. Eventually, we narrowed it down to the database, suspecting a slow query.

I mentioned I’d try to optimize it based on “feeling” and maybe throw in some indexes. Then the interviewer dropped a simple but powerful tip:

“Have you tried running it with EXPLAIN?”

That’s when I learned something new and honestly, it changed the way I look at query performance.

What Does `EXPLAIN` Actually Show?

When you write a query, the database doesn’t just run it blindly, it builds an execution plan. And EXPLAIN reveals exactly how it plans to execute that query.

Think of it like saying: “Show me how you're going to fetch these results before you actually do it.”

With it, you can discover:

If it’s doing a full table scan;
If your indexes are being used or totally ignored;
What kind of join is being applied (Nested Loop, Hash Join, etc.);
How many rows it thinks it will read;
And how “expensive” the query is, cost-wise.

It’s simple to run:

EXPLAIN SELECT * FROM users WHERE email = 'hi@devmatsu.com';

Why Not Add Indexes Everywhere?

Another key part of the interview was when we discussed indexing. I first said, "maybe because of storage cost?" — but the better answer was:

"Indexes speed up reads, but make writes more expensive."

Every time you run an INSERT, UPDATE, or DELETE, the database also has to update every related index. So the trade-off is:

Too many indexes → fast reads, but slow writes.
Too few indexes → fast writes, but slow reads.

That’s why indexing is a design choice, not a default solution. And again, EXPLAIN helps you check if your index is actually being used or if it’s just sitting there eating up space.

What I Took from That Interview

EXPLAIN isn’t optional, it’s your ally for understanding performance;
Indexing is powerful, but it comes at a cost. Use it with intention;
And most of all: interviews aren’t just tests. Sometimes, they’re great learning moments.

Console You Later!

Setting a Default Node Version for Your Project with .nvmrc

Matsu — Thu, 24 Apr 2025 20:12:08 +0000

I used to switch between projects and wonder why some things just... broke.

Then I realized the issue: each project was using a different Node.js version.

Sometimes one needed Node 18 for a modern API, while another was still running on 16.

That’s when I found out about .nvmrc.

What is `.nvmrc`?

It’s a simple file that you add to the root of your project to define the Node.js version that should be used.

No JSON. No config object. Just the version number.

18.16.1

How does it work?

When using NVM (Node Version Manager), you can run:

nvm use

And NVM will automatically switch your Node.js version to the one specified in .nvmrc.

This is super helpful when you clone a repo and want to make sure you're using the right environment.

Why it matters

Keeps your local version consistent with the project
Prevents bugs caused by incompatible Node versions
Makes onboarding easier for teams

If you're working with multiple Node projects, this tiny file can save you hours of debugging.

Console You Later!

How JavaScript Gets Updated: ECMAScript, V8 and Your Runtime Explained

Matsu — Sun, 13 Apr 2025 19:37:10 +0000

I remember when I started coding in JavaScript, I used to think:

"Okay... so JavaScript gets updated like any language... just update and that's it."

But that's not exactly how things work here. JavaScript runs in different environments like browser, Node.js, Deno — and what actually decides if you can use that new fancy feature you saw on X (the old Twitter) is your runtime.

In this post, I’ll explain how new JavaScript features are released, how ECMAScript fits into this process and why your runtime decides what features you can use (or not).

What is ECMAScript?

ECMAScript is the official specification of the language and JavaScript is just an implementation of that spec.

Every year, a group called TC39 (the committee that defines the language) releases a new ECMAScript version — adding new features, syntax, and behavior.

Examples of features introduced by ECMAScript versions:

Version	Year	Features example
ES6	2015	`let`, `const`, arrow functions, classes
ES2020	2020	Optional chaining `?.`, Nullish coalescing `??`
ES2022	2022	`#privateFields` in classes, top-level `await`

But How Do We Get Those Features?

That's the point. It's not about updating JavaScript. It depends on the JavaScript Engine you’re running.

What is a JavaScript Engine?

A JavaScript Engine is what reads, parses, and executes your JavaScript code. Each environment (browser, Node.js) uses an engine.

Popular engines:

V8 → used by Chrome and Node.js
SpiderMonkey → used by Firefox
JavaScriptCore (Nitro) → used by Safari

When Do You Get New JavaScript Features?

Environment	How do you get new features?
Browser	By updating the browser
Node.js	By updating your Node.js version

It's simple as that. If you want to use new features just need to update the browser or the Node.js version

Why Is This Important?

Because when you’re writing code locally — in your machine — you can probably use everything that your Node.js or browser supports. But when you're writing code for production (especially frontend), you need to care about your users' environment.

Example:

If your users still use old browsers like IE11 (hope not) or very old Android versions — you can’t use optional chaining ?. directly.

The browser wouldn’t even understand that syntax.

That’s why tools like: Babel, TypeScript, Webpack, Vite and others exist — to transpile your code and convert modern JavaScript to old compatible syntax.

Final Thoughts

JavaScript is updated every year through ECMAScript but you only get those new features when your environment supports them — either by updating the engine (browser, Node.js) or transpiling your code for compatibility.

Now every time you see a new JavaScript feature, remember:

It’s not about "updating JavaScript" — it’s about your engine.

Console You Later!

Closures vs Classes in JavaScript: What I Learned Solving LeetCode #2622

Matsu — Tue, 08 Apr 2025 13:56:07 +0000

I was solving LeetCode #2622 – Cache With Time Limit and the goal was to create a function that returns a caching system with TTL (time-to-live).

My first instinct? Use a closure. It's a common pattern — just define a variable outside the function and the inner function can reference it.

🔁 Closure-style cache:

function createCache() {
  const store = new Map();

  return {
    set(key, value, ttl) {
      store.set(key, { value, expiry: Date.now() + ttl });
    },
    get(key) {
      const cached = store.get(key);
      if (!cached || cached.expiry < Date.now()) return -1;
      return cached.value;
    }
  };
}

Easy. It works, it's scoped and no one can touch store from the outside — classic closure encapsulation. But the LeetCode problem expected us to extend a function via its prototype — and that threw me off. I was like: "How the heck do I create a private variable across prototype methods?"
That’s when the light bulb went on.

Using `this` + Classes = Encapsulation

I realized I needed to treat it like a class and that’s when I remembered: when using prototypes (or classes), you can store shared data inside this.
So I did:

var TimeLimitedCache = function () {
  this.cache = new Map();
};

TimeLimitedCache.prototype.set = function (key, value, duration) {
  const expiredAt = Date.now() + duration;
  const existed = this.cache.has(key);
  this.cache.set(key, { value, expiredAt });
  return existed;
};

TimeLimitedCache.prototype.get = function (key) {
  const entry = this.cache.get(key);
  if (!entry || entry.expiredAt < Date.now()) return -1;
  return entry.value;
};

Now everything lives inside this.cache. No need for an external closure and it works great across all methods.

Private Fields in Classes

At that point I thought: "Wait, so this whole thing is basically behaving like a class!". And if it’s a class, can we go one step further? What about private fields?
In the past, we'd use a naming convention like _cache, but that was just a signal, not actual protection.
But now with modern JavaScript (since ES2022), we can use native private fields with the # symbol:

class TimeLimitedCache {
  #cache = new Map();

  set(key, value, duration) {
    const expiredAt = Date.now() + duration;
    const existed = this.#cache.has(key);
    this.#cache.set(key, { value, expiredAt });
    return existed;
  }

  get(key) {
    const entry = this.#cache.get(key);
    if (!entry || entry.expiredAt < Date.now()) return -1;
    return entry.value;
  }
}

That’s real encapsulation!

What I Learned

Closures are a great way to encapsulate state, especially for factory functions;
Classes with this are a powerful alternative when you want to work with prototypes or build something that feels more like an object;
Modern JavaScript gives us native private fields (#);

No matter what pattern you choose, closures or classes, the key is to understand the trade-offs and when each tool fits better.

Solving this problem gave me a new perspective on how classes and closures can often solve the same thing in different ways.

Console You Later!

What happens when both try and finally return in JavaScript?

Matsu — Mon, 07 Apr 2025 03:05:26 +0000

What do you think will happen if we run this code?

function test() {
  try {
    throw new Error("oops");
  } catch (e) {
    return 'catch';
  } finally {
    return 'finally';
  }
}

console.log(test());

At first you might think:

"Okay, it throws an error, so it goes into the catch block and returns 'catch'... right?”

But not quite! Actually this code will return finally! But why? Let me explain.

How `try`, `catch` and `return` Work

We usually think of return as an immediate exit, but in JavaScript, that’s not exactly how it works under the hood. When the JS engine hits a return, it creates something called a Completion Record.

Think of it as a sticky note that says:

"Hey, we're done here. The reason is return and here's the value to give back"

This record is kept internally by the JavaScript engine until the function truly finishes.

The flow with `finally`

Here's a real-world metaphor:

You go to the market (that's your function)

You try to buy apples (try), but if they’re out of stock, you get bananas instead (catch).

As you're about to check out, your mom calls and says:
“Forget that — just buy milk!” (finally).

So no matter what you were planning to bring home (apples or bananas), you end up bringing milk.

Here's the code version:

function goToMarket() {
  try {
    throw new Error('No apples today!');
    return 'Apples';
  } catch (e) {
    return 'Bananas';
  } finally {
    return 'Milk';
  }
}

console.log(goToMarket()); // 'Milk'

Why Does This Happen?

The try block tries to return 'Apples', but an error is thrown.
The catch block handles it and returns 'Bananas'.
Before the function can return 'Bananas', the finally block runs and its return 'Milk' overrides everything.

So 'Milk' is the final return value.

ECMAScript Spec (in simple terms)

According to the ECMAScript spec:

A return in try or catch doesn't immediately return — it creates a Completion Record;
The finally block is always executed, regardless of what happened in try or catch;
If the finally block has its own return, it overwrites any previous return;

That’s why finally becomes the actual return value.

Reference

This behavior follows the ECMAScript specification, which details how CompletionRecords are handled during function execution.

Final Thoughts

The finally block isn't just a "cleanup" section — it can take control of your function's return value if you’re not careful. Even if try or catch has a return, a return inside finally will override it.

So next time you're writing error handling, think twice before returning inside a finally block, it might silently change your function’s behavior.

Understanding this little quirk helps you avoid unexpected bugs and gives you more control over your code flow.

Console You Later!

What is Immutability in JavaScript?

Matsu — Sun, 06 Apr 2025 03:43:58 +0000

Immutability is a powerful concept in programming and especially important in JavaScript, even if we don't always think about it. It affects how we manage data, state and side effects in our applications.

In this post, we'll break down what immutability means, why it matters and how you can work with it in practice.

What is Immutability?

Basically Immutability means something cannot be changed after it's created. For example in JavaScript, primitive values like numbers, strings and booleans are immutable. This doesn't mean the variable can't be reassigned, it means the value itself can't be changed in place.

Example with a string:

let name = 'Matsu';

// Trying to change just one character (this won't work)
name[0] = 'B';

console.log(name); // 'Matsu' → Still the same

// But we can reassign the variable
name = 'John';
console.log(name); // 'John'

So the string itself is immutable but the variable name can be reassigned to a new string. In contrast, objects and arrays are mutable by default, which means you can change their contents directly.

Example with an object:

const user = { name: 'Matsu' };

// Modifying the object
user.name = 'John';

console.log(user); // { name: 'John' }

This can lead to unintended side effects, especially when multiple parts of your code are referencing and modifying the same object or array, such as shared data or state.

What Can Immutability Do?

Avoid side effects (accidentally changing shared data);
Make debugging easier (state doesn't change in hidden ways);
Improve performance in some cases (e.g. with reference checks);
Work better with frameworks like React, which rely on state changes via new objects;

Working with Immutability in JavaScript

To keep data immutable, we usually create new copies instead of modifying the original.

Copying Arrays

const numbers = [1, 2, 3];

// Instead of: numbers.push(4)
const newNumbers = [...numbers, 4];

console.log(numbers);     // [1, 2, 3]
console.log(newNumbers);  // [1, 2, 3, 4]

Copying Objects

const user = { name: 'Matsu', age: 28 };

// Instead of: user.age = 29
const updatedUser = { ...user, age: 29 };

console.log(user);        // { name: 'Matsu', age: 28 }
console.log(updatedUser); // { name: 'Matsu', age: 29 }

Attention with Deep Copy vs Shallow Copy

Most techniques (like spread (...) and Object.assign) create shallow copies. This means only top-level properties are copied. If the object contains nested objects, those nested references remain shared between the original and the copy.

const person = {
  name: 'Matsu',
  address: { city: 'Tokyo' }
};

const clone = { ...person };
clone.address.city = 'Osaka';

console.log(person.address.city); // 😱 'Osaka'

Even though we used the spread operator, person.address and clone.address still point to the same object in memory, so changing one affects the other.

To truly copy all levels of an object, you need a deep clone. One common approach is using cloneDeep from Lodash:

import _ from 'lodash';
const deepClone = _.cloneDeep(person);

This creates a new object where even the nested structures are fully cloned, breaking the reference between the original and the copy.

You can check my post about Exploring Object Cloning Techniques in JavaScript to dive deeper.

Enforcing Immutability in JavaScript

You might think using const would make an object or array immutable, but that's not the case. const only prevents reassignment, not mutation.
By default, JavaScript objects and arrays are mutable. But there are ways to partially enforce immutability at runtime using built-in methods like:

`Object.freeze()`

Prevents adding, removing or modifying properties of an object making the object shallowly immutable.

const config = Object.freeze({
  apiUrl: 'https://api.example.com',
  retries: 3,
});

config.retries = 5;
console.log(config.retries); // 3 — change is ignored or throws in strict mode

⚠️ Note: This only works on the first level. If the object has nested properties, they’re still mutable unless you recursively freeze them.

Example: Freezing an Array

You can also use Object.freeze() to prevent changes to an array, for example, if you want to enforce a fixed set of values (e.g. length, content):

const roles = Object.freeze(['admin', 'editor', 'viewer']);

roles.push('guest');         // ❌ won't work
roles[0] = 'superadmin';     // ❌ won't work
roles.length = 0;            // ❌ won't work

console.log(roles); // [ 'admin', 'editor', 'viewer' ]

This is useful when you want to protect reference lists, roles, or static options in your app.

`Object.seal()`

Prevents adding or removing properties, but you can still modify existing ones.

const settings = { theme: 'dark' };
Object.seal(settings);

settings.theme = 'light';      // ✅ allowed
settings.language = 'en';      // ❌ can't add new property
delete settings.theme;         // ❌ can't delete property

console.log(settings); // { theme: 'light' }

These methods are great for protecting config objects, shared constants or preventing accidental mutations especially in larger codebases.

When to Use Immutability?

When managing application state (especially in React or Redux);
When writing pure functions;
When you want predictable and reliable behavior in your code;

Final Thoughts

Immutability is not about never changing anything, it's about changing things safely by creating new versions instead of modifying existing ones. You can also "lock" objects and arrays using Object.freeze() or Object.seal() to help prevent accidental changes.

It leads to better, cleaner and more bug-resistant code, especially as your project grows. So embrace immutability and you'll avoid a lot of hidden side effects and unexpected behavior.

Console You Later!

Programming Paradigms Explained with Code Examples

Matsu — Fri, 04 Apr 2025 14:12:18 +0000

When you're learning to code or expanding your knowledge, you'll often hear the term "programming paradigms" but what does that actually mean?

A programming paradigm is a way to approach problem-solving using code. It's about how you structure your logic and instructions. Different paradigms shape the way you think and organize your solutions.

Let's explore some of the main ones with simple examples.

1. Imperative Programming

This is one of the most common and intuitive paradigms. You tell the computer how to do something, step by step.

Example (in JavaScript):

let sum = 0;
for (let i = 0; i <= 5; i++) {
  sum += i;
}
console.log(sum); // 15

2. Declarative Programming

You focus on what you want instead of how to do it. SQL and even parts of React are declarative.

Example (SQL):

SELECT * FROM users WHERE age > 18;

Example (React - .jsx file):

function Greeting() {
  return <h1>Hello, world!</h1>;
}

It may not look declarative at first, but the point is: React uses JavaScript under the hood, the way you define UI with JSX is declarative because you're describing what should be rendered based on the current state or props, not how to manually build or update the DOM.

3. Object-Oriented Programming (OOP)

This paradigm organizes code that encapsulate both data and behavior. It's great for modeling real-world entities.

Example (TypeScript):

class Animal {
  name: string;

  constructor(name: string) {
    this.name = name;
  }

  speak(): void {
    console.log(`${this.name} makes a sound.`);
  }
}

class Dog extends Animal {
  speak(): void {
    console.log(`${this.name} barks.`);
  }
}

const dog = new Dog('Rex');
dog.speak(); // Rex barks.

4. Functional Programming

In functional programming, you use pure functions and avoid mutating data. It's about composition, immutability and statelessness.

Example (JavaScript):

const double = (x) => x * 2;
const result = [1, 2, 3].map(double);
console.log(result); // [2, 4, 6]

Final Thoughts

Modern languages like JavaScript, Python and TypeScript are multi-paradigm so you can combine functional, object-oriented and imperative styles depending on what fits best.

Here are some languages commonly associated with each paradigm:

Paradigm	Languages
Imperative	JavaScript, TypeScript, Go, Python, Java, Rust
Declarative	SQL, JavaScript (JSX), Elixir
Object-Oriented	TypeScript, Python, C#, Java, Kotlin
Functional	JavaScript, TypeScript, Python, Kotlin, Elixir

If you're aiming to grow as a developer, understanding paradigms is a powerful step. Knowing the fundamentals helps you understand what you're doing and why you're doing it that way.

Console You Later!

Memoization and Caching: Are they the same in JavaScript?

Matsu — Tue, 01 Apr 2025 01:55:47 +0000

At first glance, Memoization and Caching might seen like the same thing. After all, both techniques involve saving results to avoid doing the same work again. But while they are related, they're not exactly the same and understanding the difference between them will make you have a strong fundamentals.

In this post, we'll break down what memoization and caching really are, compare them side by side and walk through practical examples so you'll never confuse them again.

What is Memoization?

Memoization is a specific form of caching that's focused on functions. It stores the result of a function based on its inputs arguments.

If the function is called again with the same arguments, the stores result is returned instead of running the function again.
It's typically used for:

Pure Functions (functions that always return the same output for the same input);
Expensive calculations that are repeated often;
Variables in outer functions that are preserved through closures (e.g., for storing cached values);

It usually stores values in memory, like in a plain object or closure.

What is Caching?

Caching is a broader concept. It referes to storing any kind of data so it can be accessed faster in the future, not just functions results.

It's used everywhere

API responses;
Database query results;
Images, files, computed reports;
Session data, user info, etc;

And it can be stored anywhere:

In memory;
In a Redis store;
In the browser (localStorage, indexedDB);
On disk

Key differences

Feature	Memoization	Caching
Scope	Function-level	Global / application-level
Purpose	Store function results	Store any reusable data
Based On	Function arguments	Keys like URL, ID, custom cache key
Typical Storage	In-memory (object or closure)	Memory, Redis, disk, browser
Use Cases	Recursive calculations, pure logic	API calls, DB queries, static files
Invalidation	Rare (input-based)	TTL, manual purge, cache strategy needed
Example	`factorial(n)`, `fibonacci(n)`	Cached API response by user ID

Memoization in code

Let's look at a simple example using the factorial function, which is a great case for memoization because each result depends on the previous one.

Without Memoization:

function factorial(n) {
  if (n <= 1) return 1;
  return n * factorial(n - 1);
}

console.log(factorial(5)); // 120
console.log(factorial(5)); // Recalculates everything again

With Memoization:

function memoizedFactorial() {
  const cache = {};

  return function factorial(n) {
    if (n in cache) {
      console.log('From cache:', n);
      return cache[n];
    }

    if (n <= 1) return 1;

    const result = n * factorial(n - 1);
    cache[n] = result;
    return result;
  };
}

const factorial = memoizedFactorial();

console.log(factorial(5)); // Calculated
console.log(factorial(5)); // Cached!
console.log(factorial(6)); // Uses cached factorial(5)

This shows how we avoid redundant work by reusing previous results.

Caching in code (Example with Redis)

Now let's say we have a function that fetches user data, possibly expensive if it hits a DB or API.
Instead of recalculating or re-fetching it every time we cache it using Redis.

async function getUser(userId) {
  const key = `user:${userId}`;
  const cached = await redis.get(key);

  if (cached) {
    console.log('Returned from Redis cache');
    return JSON.parse(cached);
  }

  const user = await fetchUserFromDB(userId);
  await redis.set(key, JSON.stringify(user), 'EX', 60); // Cache for 60s
  return user;
}

This is not memoization, but it is caching. It's not tied directly to a function's input/output relationship in memory. It's stored in an external cache layer and used across multiple calls.

When to Use Each

Use memoization when:

You're working with pure functions;
You want to optimize repeated calculations;
You don't want to introduce external storage (just use in-memory);

Use caching when:

You want to store data fetched or computed from external sources;
You need to share results between processes or requests;
You need expiration, invalidation or disk/network-level persistence;

Final thoughts

Memoization and caching are related but they solve different problems.

Memoization is about functions calls: if I call this again with the same input, don't recompute it.

Caching is about data reuse: if I already fetched this, let's avoid doing it again.

Quick recap:

Memoization is a type of caching;
All memoization is caching, but not all caching is memoization;
Both can drastically improve performance if used in the right context;

Console You Later!

What is an IIFE in JavaScript and Why Would You Use It?

Matsu — Fri, 28 Mar 2025 21:32:28 +0000

In JavaScript, you might have seen a function that seems to call itself right after it's defined. That’s called an IIFE, short for Immediately Invoked Function Expression. It might look weird at first, but it has some interesting use cases. Let’s explore what it is, how it works, and when to use it.

What is an IIFE?

An IIFE is a function that runs immediately after it’s defined. The main idea is to create a new scope without polluting the global one.

Here’s how it looks:
(function () { console.log('This runs immediately!'); })();
Or, with arrow function syntax:
(() => { console.log('Arrow IIFE runs immediately!'); })();

Why Does This Work?

In JavaScript, when you define a function like:
function sayHi() {}
…it’s just a declaration, and it won’t run until you call it.

But to make the function run immediately, you need to turn it into an expression. That’s why we wrap it in parentheses:

The first () turns the function into a function expression.
The second () calls it.

Common Use Cases

Avoiding Global Scope Pollution IIFEs help keep variables inside their own scope so they don’t interfere with other parts of your code.

(function () { const secret = 'I stay local'; console.log(secret); // Works here })();

console.log(secret); // Error: secret is not defined

Running Setup Code Once If you want to run some initialization logic right away (like setting up configs), IIFE can be a clean solution.

const app = (() => { const config = { env: 'production' }; console.log('App is starting...'); return { getConfig: () => config }; })();

Using await in Non-Async Environments (Async IIFE) In environments where you can't use top-level await (like older Node.js or CommonJS modules), an async IIFE allows you to run asynchronous code with await.

(async () => { const response = await fetch('https://api.example.com/data'); const data = await response.json(); console.log(data); })();

This is super useful for running async logic without needing to define and then manually call a separate async function.

IIFEs are a handy JavaScript pattern that allow you to execute functions immediately while keeping variables scoped locally. While not as common in ES6+ codebases thanks to modules and let/const, they're still worth knowing — especially when you stumble across them in older code or want a quick isolated block.

Console You Later!

DEV Community: Matsu

The AI Engineering Concepts I Wish Someone Explained Simply

1. The Foundation

LLM (Large Language Model)

Models

System One Models (Jev)

Tokens

Context

Context Window

2. Anatomy of an AI Agent

Agent

Subagent

Scout

Persona

Tools

Tool Calling

Agent Harness

Orchestration

3. Engineering the Agent's Environment

Prompt Engineering

Context Engineering

Harness Engineering

RAG (Retrieval-Augmented Generation)

MCP (Model Context Protocol)

Skills

4. What Counter-Strike Can Teach Us About AI Agents 🎮

The Agent Is Your Player

The Model Is the Brain, and the Harness Is the Game System

Personas Are the Roles on Your Team

Tools Are Your Weapons and Equipment

Context Is Your Game Information

Skills Are Your Strategies and Playbooks

Subagents and Scouts Are Your Teammates

Orchestration Is Your IGL Calling the Round

So, What's the Point?

5. Tools Worth Exploring

OMP (Oh My Pi) — An Agent Harness

Herd — Multi-Agent Orchestration

Which One Should You Use?

6. Where to Start

Transactional Outbox Pattern - Improving how we deal with atomicity

Transactional Outbox Pattern: Solving the Dual-Write Problem with Atomicity

Understanding the Dual-Write Problem

What Is Atomicity?

Introducing the Transactional Outbox Pattern

But How Does the Event Reach Kafka?

Polling vs. Event-Driven Relays

What About Duplicate Events?

What About Multiple Relay Workers?

When Should We Use Transactional Outbox?

Final Thoughts

How Relational Databases Find Database: Understanding Table and Index Scans

Choosing the right scan

"The API Is Slow, Fix It!" – What I Learned About `EXPLAIN` and Indexing

What Does EXPLAIN Actually Show?

Why Not Add Indexes Everywhere?

What I Took from That Interview

Setting a Default Node Version for Your Project with .nvmrc

What is .nvmrc?

How does it work?

Why it matters

How JavaScript Gets Updated: ECMAScript, V8 and Your Runtime Explained

What is ECMAScript?

Examples of features introduced by ECMAScript versions:

But How Do We Get Those Features?

What is a JavaScript Engine?

When Do You Get New JavaScript Features?

Why Is This Important?

Example:

Final Thoughts

Closures vs Classes in JavaScript: What I Learned Solving LeetCode #2622

🔁 Closure-style cache:

Using this + Classes = Encapsulation

Private Fields in Classes

What I Learned

What happens when both try and finally return in JavaScript?

How try, catch and return Work

The flow with finally

Why Does This Happen?

ECMAScript Spec (in simple terms)

What Does `EXPLAIN` Actually Show?

What is `.nvmrc`?

Using `this` + Classes = Encapsulation

How `try`, `catch` and `return` Work

The flow with `finally`

`Object.freeze()`

`Object.seal()`