Forem: Rodrigo Sicarelli

Claude Code 101: Demystifying Language Models

Rodrigo Sicarelli — Thu, 09 Apr 2026 11:34:24 +0000

What is a token

The context window

How models generate text

The attention mechanism

How the model picks between options

Model families

What models can't do

How much it costs

Final thoughts

🇧🇷 Leia em português

In the previous article, we built the entire factory: the evolution from manual production to autonomous machines, the ecosystem of agentic tools, the three pillars (prompt, context, and harness engineering). You know what the factory does, who works in it, and even how much revenue it pulls in.

But the machines in the factory build things. And to understand how they build, the best analogy I know is LEGO. Standardized pieces that snap together one at a time, following (or ignoring) a manual, on a desk with limited space.

This is the second article in the Claude Code 101 series, and here we take that mechanic apart. What tokens are, how the context window works, why models generate text the way they do, and why they sometimes get things wrong with unsettling confidence.

What is a token

Computers don't understand text. They understand numbers. Before a language model processes anything you wrote, every word, space, and punctuation mark has to become a sequence of integers. Those integers are tokens: the standardized pieces the model works with.

A token isn't necessarily a word. It can be a whole word ("hello" becomes 1 token), a chunk of a word ("tokenization" becomes several tokens), an isolated character, or even a single byte. The rule of thumb for English: 1 token is roughly 4 characters, or about 3/4 of a word. For Portuguese, it's closer to 1 token per 2.7 to 3 characters.

How the vocabulary is built

Most LLMs use an algorithm called BPE (Byte Pair Encoding) to build their vocabulary. The logic is straightforward: start with the 256 possible byte values, scan billions of training texts, find the most frequent byte pair, merge it into a new token, repeat. The result is a vocabulary ranging from ~100K to ~260K tokens, depending on the model.

The detail that matters: this training corpus is dominated by English. Words like "the," "and," "great" become single tokens, whole pieces. Words in Portuguese get fragmented into smaller chunks, as if the kit came with pieces cut in half. Compare:

The character "o" with an accent becomes a separate token because accented characters are rare in the training data. This isn't an irrelevant technical detail. It directly affects your wallet and the model's effective capacity when you work in Portuguese.

The linguistic tax on Portuguese

A study by Petrov et al. presented at NeurIPS 2023 measured what they called the "tokenization premium" across languages [1]. The numbers:

Tokenizer	How much more Portuguese consumes vs English
GPT-2 (`r50k_base`)	1.94x (nearly double)
GPT-4 (`cl100k_base`)	1.48x (~50% more)
GPT-4o (`o200k_base`)	~1.3-1.4x (improved) *

The GPT-2 and GPT-4 numbers come directly from Petrov et al. [1]. The GPT-4o estimate reflects the improvement trend with larger vocabularies, confirmed by subsequent studies.

The good news: each generation of tokenizer narrows this gap. The news that actually matters: even in the best case, Portuguese still consumes at least 30% more pieces than English to build the same thing. This "tax" will come back when we talk about context windows and cost, because it compounds with every interaction.

The context window

If tokens are the pieces, the context window is the desk where you build. Fixed size. Everything has to fit on it: the instructions you sent, the conversation history, reference files, and the response the model is constructing. When the desk fills up, that's it. The model doesn't "remember" anything left off the surface.

The desks of 2026

The market has converged on 1 million tokens (1M) as the standard for frontier models [2]. In the table below, "K" means thousand and "M" means million:

Model	Desk size	Max response
Claude Opus 4.6	1M tokens	128K tokens
Claude Sonnet 4.6	1M tokens	64K tokens
Claude Haiku 4.5	200K tokens	64K tokens
GPT-5.4	1.05M tokens	128K tokens
GPT-4.1	1M tokens	32K tokens
Gemini 2.5 Pro	1M tokens	65K tokens
Llama 4 Scout	10M tokens	varies

The desk is shared. Everything you send to the model (your question, files, conversation history) and everything it replies with must fit together on the same surface. A desk of 1 million tokens sounds enormous, but the response already reserves a chunk of it, and the rest is the maximum you can send.

For a sense of scale: 1 million tokens is roughly 750,000 words in English, about 8 to 10 books. For Portuguese, because of the tokenization tax, that drops to around 500,000 words. About 7 books.

Advertised size vs. actual size

Here's a point that rarely comes up. Having a desk of 1 million tokens doesn't mean the model uses all of that surface well.

Recent research shows that the model's ability to pay attention (attention, a concept we'll dig into right below) drops as context grows, especially for information positioned in the middle of the text [3]. The phenomenon even has a name: "lost in the middle." In practice, the model's effective attention span is significantly smaller than the advertised window. The NoLiMa benchmark (ICML 2025) showed that most LLMs fail more than half the time when they need to locate specific information in contexts beyond 32K tokens [9].

And the linguistic tax shows up again here. If the effective window of a model with 200K tokens is already significantly smaller than advertised, for content that's 100% in Portuguese, plan with a generous safety margin. The usable space can drop to roughly 80K-90K tokens of English-equivalent content. Larger pieces take up more room on the same surface.

How models generate text

You already know what the pieces are (tokens) and the size of the desk (context window). Now comes the assembly process itself.

The mechanic is surprisingly simple. The model looks at everything already on the desk, calculates a probability distribution over the entire vocabulary (between ~100K and ~260K possible pieces) to decide which one fits best in the sequence, places one, and repeats. One at a time, from beginning to end of the response. There's no master plan. This is called autoregressive generation [4], and it's the core mechanic of the Transformer architecture published in 2017 by Vaswani et al.

Example: the model receives "The sky is" and needs to continue.

Result: "The sky is blue today."

Each piece placed depends on all the ones before it: both the original input and what the model has already built. That's why responses sometimes start well and derail halfway through. The model doesn't know where it will end up when it starts generating.

If you read the previous article, you might recognize this mechanism. Remember autocomplete, phase 1 of the evolution? The code completion that suggested the next line in the editor? The underlying mechanism is the same: next-token prediction. The difference is scale. Models like GPT-2 (2019) had 1.5 billion parameters and a tiny desk. Claude Opus 4.6 operates at a completely different scale, with a context window a thousand times larger. The assembly process is the same. The ability to build complex things is what changed.

The attention mechanism

The assembly process explains that the model places one piece at a time. But we still need to understand how it decides the probabilities. If the input is "I need to check the bank by the river," how does the model know whether "bank" means the riverbank or a financial institution?

The answer is the attention mechanism (self-attention), introduced in the paper "Attention Is All You Need" [4]. It's the heart of the Transformer architecture that powers every modern LLM.

How the model sees context

Imagine that the building manual doesn't just show the next step. For each new piece, it highlights which parts of the construction matter for this decision: the foundation lights up bright (supports everything), the nearby towers glow (they define the pattern), the garden on the other side stays dim (irrelevant right now). The attention mechanism does exactly this: for each token, it "lights up" the preceding ones that carry the most weight and "dims" the ones that don't matter.

Before Transformers, it was like building LEGO with someone dictating instructions: one piece at a time, no repeating, no going back. Missed step 12? Tough luck. The Transformer is like having the entire manual open on the desk, all pages visible at once. This ability to process everything in parallel was the leap that made it feasible to train models at today's scale.

Disambiguation in practice

Go back to the example: "I need to check the bank by the river." The attention mechanism makes the token "bank" pay close attention to "river," and little attention to "need" and "to." It's like a build where a blue piece could be sky or ocean depending on what's around it. Context resolves the ambiguity.

This mechanism has a price. For every piece on the desk, the model looks at all the others before deciding on the fit [4]. On a desk with 10 pieces, no problem. On a desk with 10,000, every decision requires looking at 10,000 pieces. Doubling the desk size doesn't double the work; it quadruples it.

On top of that, building costs more than looking. When you send a question, the model reads everything at once, like scanning a full page of the manual at once. But when it constructs the response, it's one piece at a time, each one requiring a glance at the entire desk. That's why the price per output token is 3x to 5x higher than input.

What this means for you

If attention works by weighing the relevance of each token against the others, clear and well-structured prompts make the model's job easier. Ambiguity in the input produces "confusion" in the attention: the model has to distribute weight across competing interpretations. A precise prompt is like clean code: the intent is obvious and the attention mechanism focuses on what matters. The more organized the desk, the more precise the next piece.

This isn't abstract. It's the technical foundation for why prompt engineering works, something we'll explore in depth in Part 6 of this series.

How the model picks between options

You now understand how the model weighs its options. But when several tokens have similar probabilities, what decides which one gets picked?

The difference is between following the manual to the letter and improvising.

Temperature

You're building a blue wall and need the next piece. In the box, the pieces are sorted: on top are the blue ones that fit perfectly, in the middle are some green ones that could work as an accent, and way at the bottom there's a red wheel that makes no sense at all.

Temperature controls how deep the model reaches into the box. At zero, it always grabs the piece on top: same choice, every time, no surprises. At 0.7, it sometimes fishes out a green one nobody expected, and it adds a nice touch to the build. Above 1.0, it pulls the red wheel and snaps it onto the wall anyway.

Temperature	Completing "The recipe calls for..."	Behavior
0.0	"flour, sugar, and cocoa."	Always the same answer
0.3	"whole wheat flour, coconut oil, and cocoa."	Minor variations
0.7	"exotic spices and a hint of Sicilian lemon."	Creative
1.5	"melted dreams in dragon caramel."	Incoherent

Top-p

Temperature isn't the only control. Top-p works differently: instead of changing how deep the model reaches into the box, it removes pieces from the box before the model chooses. With top-p at 0.9, the bottom 10% most improbable pieces aren't even available. The effect is similar to temperature, and the recommendation from providers is to adjust one or the other, not both at the same time.

What this means in practice

When you start using agentic tools to write code (from Part 5 of this series), these values come pre-calibrated. But understanding that they exist helps explain why the model sometimes surprises you with an unexpected response: someone let it dig deeper into the box.

For what we care about in this series, the rule is simple: for code, the model works best in predictable mode. Right piece, right place, no improvisation.

Model families

Not every piece works for every build. LEGO Duplo (big pieces, simple) is perfect for getting started, but you can't build a working motor with it. LEGO Technic (gears, axles, complexity) enables sophisticated builds, but costs more and takes more time. The same logic applies to language models.

Reasoning models

The Technic kits: they "think before answering," spending internal tokens on step-by-step reasoning (extended thinking) before producing the final response. They're the most capable, slowest, and most expensive. The prices below are in dollars per MTok (1 million tokens): the first value is the input cost (what you send), the second is the output cost (what the model generates).

Claude Opus 4.6 (Anthropic) reaches 80.8% on SWE-bench Verified [5]. $5/$25 per MTok.
o3 / o3-pro (OpenAI) are dedicated reasoning models. o3-pro costs $20/$80 per MTok.
Gemini 2.5 Pro (Google) lets you configure the "thinking budget." $1.25/$10 per MTok.

Fast models

The Duplo kits: bigger pieces, quick assembly, immediate results. Built for low latency and high volume.

Claude Haiku 4.5 (Anthropic): $1/$5 per MTok.
GPT-4o-mini (OpenAI): $0.15/$0.60 per MTok.
Gemini 2.5 Flash (Google): $0.30/$2.50 per MTok.

Code models

Kits optimized for specific builds. Like the Creator Expert line, where each set is designed for a particular result.

GPT-4.1 (OpenAI): 1M context, $2/$8 per MTok. Explicitly optimized for code.
Claude Code (Anthropic): uses Opus/Sonnet under the hood, but with an entire harness of tools to read, edit, execute, and commit.

Open-weight models

Kits with all the pieces exposed: you build, take apart, and adapt however you want.

Llama 4 Scout (Meta): 10M context, open-weight [6].
Llama 4 Maverick (Meta): 1M context, 17B active parameters out of 400B total.
DeepSeek R1: open-source (MIT), 671B parameters, strong reasoning.

Choosing the right kit

Using Opus to classify tweet sentiment is like buying a 4,000-piece Technic set to build a cube. The difference between Haiku ($1/$5 per MTok) and Opus ($5/$25 per MTok) is 5x on input and 5x on output. Plenty of tasks that seem to "need" a large model work perfectly well with a smaller one.

The rule of thumb: always start with the cheapest model that could work. Test with Haiku, Flash, or mini. If quality falls short, move up. Opus and o3-pro are reserved for when you truly need them.

But regardless of which kit you choose, they all share the same fundamental limitations.

What models can't do

The build might look perfect. Visually flawless, every piece in place. But push the wall and it falls over. The model doesn't "know" whether what it built actually works. It snaps pieces where they seem to fit, following statistical patterns, and the result often holds up. But not always.

Hallucinations aren't bugs

When a model generates information that looks correct but is factually false, we call it a hallucination. It's tempting to treat this as a defect, something that will be "fixed" in a future version. But hallucinations are a direct consequence of the design: the model snaps pieces where they seem to fit statistically, without checking whether the build makes sense in the real world [4].

If the statistical pattern of "X wrote the book Y" is strong enough in the training data, the model will assert it even if it's false. It has no internal fact-checker. It doesn't distinguish between generating "Paris is the capital of France" and "Paris is the capital of Italy." Both are plausible token sequences; one is true, the other isn't, and the model doesn't know the difference.

The concrete limitations

The model's manual was printed on a specific date. Everything that happened after that doesn't exist for it. And worse: at the end of every build, the desk is wiped clean. The next conversation starts from zero, with no pieces from the previous one. If you need the model to remember something, you have to put it back on the desk yourself.

The good news: with context engineering and harness engineering techniques (topics in Parts 7 and 8 of this series), you can automate what goes on the desk for each conversation. But for now, the important thing is knowing that the model on its own doesn't remember anything.

Math remains a weak spot. The model can assemble a calculation that looks right but gets the result wrong. For computations that demand precision, it's safer to ask the model to write code that does the math rather than trusting the direct answer.

And in the context of code, Veracode tests showed that 45% of AI-generated code contains security flaws, across evaluations of more than 100 LLMs [7]. The model builds fast, but if nobody checks the construction, poorly fitted pieces end up in the final product.

What's getting better

But the community isn't standing still. Improvements are coming from multiple fronts at the same time: models that "think step by step" before building, reducing errors on complex tasks. Systems that automatically populate the desk with the right pieces for your project, instead of you placing everything by hand. Agents that remember previous builds and learn from them. And infrastructure that gets faster and cheaper with every generation.

Each of these fronts will show up in the upcoming articles of this series. For now, the takeaway is: the limitations are real, but they're shrinking.

Even with these limitations, models are being used at scale. And scale has a cost.

How much it costs

Every piece costs money. LLMs are billed per token processed, split into two categories: input tokens (everything you send) and output tokens (what the model generates). Building something new (output) always costs more than reading what already exists (input), typically 3x to 5x the price [8]. This makes sense: generating each token requires a full forward pass through the model.

Price table (April 2026)

Prices in USD per 1 million tokens (MTok):

Model	Input / MTok	Output / MTok	Cache read / MTok
Claude Opus 4.6	$5.00	$25.00	$0.50
Claude Sonnet 4.6	$3.00	$15.00	$0.30
Claude Haiku 4.5	$1.00	$5.00	$0.10
GPT-5.4	$2.50	$15.00	$0.25
GPT-4.1	$2.00	$8.00	$0.50
Gemini 2.5 Pro	$1.25	$10.00	$0.125
Gemini 2.5 Flash	$0.30	$2.50	$0.03

Notice the "Cache read" column. It'll be important in a moment.

The linguistic tax comes full circle

Remember the tokenization cost for Portuguese? It translates directly into money. For the same content, Portuguese applications cost between 30% and 50% more in input tokens than the same application in English, depending on the tokenizer. On a $5,000/month bill, that's an extra $1,150 to $1,650 just because of the language.

Throughout this article, one thread runs through three sections: Portuguese consumes more pieces to build the same thing (section 1), that takes up more room on the desk (section 2), and now it costs more (here). These aren't three problems. It's the same problem, in three layers.

How to optimize

The good news: there are concrete ways to bring this cost down.

Prompt caching is the most impactful. All major providers offer cache reads at roughly 10% of the input price [8]. If your system prompt or reference context repeats across calls, caching can cut input costs by up to 90%. This significantly mitigates the Portuguese linguistic tax.

Batch API offers a 50% discount in exchange for asynchronous processing (24-hour window). For tasks that aren't real-time (document analysis, bulk classification), it's easy savings.

Model selection is the third lever. Many tasks running on Opus would work just as well on Haiku, at a fraction of the cost. Testing with the cheapest model first isn't premature optimization. It's responsible engineering.

Combining batch + caching on Anthropic, the discount can reach 95% in ideal scenarios [8].

This topic will be central in Part 4, when we talk about context engineering. Managing what goes on the desk is, in practice, managing money.

Final thoughts

Tokens, desk, attention, temperature, limitations, cost. It might seem like a lot, but everything connects. And none of this is technical trivia. It's the foundation of every decision you'll make with these tools: why one prompt works and another doesn't, why the response cut off midway, why the bill came in higher than expected.

But there's a gap. Knowing how the pieces work doesn't explain how typing a paragraph into a terminal results in 50 edited files, passing tests, and a ready commit. Something is taking those pieces, arranging them on the desk, building, checking, tearing down what fails, and trying again. Something is turning a next-token engine into a system that actually builds software.

That something is what tools like Claude Code, Codex CLI, and OpenCode do. They wrap the model, give it tools to act, and orchestrate the cycle of building, checking, and correcting. In the next article, we crack one of them open, piece by piece.

🤖 This article was written with assistance from Claude (Anthropic).

Content researched, verified, and edited by a human.

Found an error or a missing credit? Send me a message!

References

Claude Code 101: Desmistificando os Modelos de Linguagem

Rodrigo Sicarelli — Thu, 09 Apr 2026 10:50:29 +0000

O que é um token

A janela de contexto

Como o modelo gera texto

O mecanismo de atenção

Como o modelo escolhe entre as opções

As famílias de modelos

O que modelos não conseguem fazer

Quanto custa

Considerações finais

🌐 Read in English

No artigo anterior, montamos a fábrica inteira: a evolução de produção manual pra máquinas autônomas, o ecossistema de ferramentas agênticas, os três pilares (prompt, context e harness engineering). Você sabe o que a fábrica faz, quem trabalha nela e até quanto fatura.

Mas as máquinas da fábrica constroem coisas. E pra entender como elas constroem, a melhor analogia que eu conheço é LEGO. Peças padronizadas que se encaixam uma por vez, seguindo (ou não) um manual, numa mesa com espaço limitado.

Este é o segundo artigo da série Claude Code 101, e aqui a gente desmonta essa mecânica. O que são tokens, como funciona a context window, por que modelos geram texto do jeito que geram, e por que eles às vezes erram com uma confiança desconcertante.

O que é um token

Computadores não entendem texto. Entendem números. Antes que um modelo de linguagem processe qualquer coisa que você escreveu, cada palavra, espaço e pontuação precisa virar uma sequência de inteiros. Esses inteiros são os tokens: as peças padronizadas com as quais o modelo trabalha.

Um token não é necessariamente uma palavra. Pode ser uma palavra inteira ("hello" vira 1 token), um pedaço de palavra ("tokenização" vira vários tokens), um caractere isolado ou até um byte. A regra prática pro inglês: 1 token corresponde a mais ou menos 4 caracteres, ou cerca de 3/4 de uma palavra. Pro português, fica mais perto de 1 token pra cada 2.7 a 3 caracteres.

Como o vocabulário é construído

A maioria dos LLMs usa um algoritmo chamado BPE (Byte Pair Encoding) pra montar seu vocabulário. A lógica é simples: começa com os 256 valores possíveis de um byte, percorre os bilhões de textos usados pra treinar o modelo, encontra o par de bytes mais frequente, junta num token novo, e repete. O resultado é um vocabulário que varia entre ~100 mil e ~260 mil tokens, dependendo do modelo.

O detalhe que importa: essa massa de textos é dominada por inglês. Palavras como "the", "and", "great" viram tokens únicos, peças inteiras. Palavras em português são fragmentadas em pedaços menores, como se o kit viesse com peças cortadas ao meio. Compare:

O caractere "ó" sozinho já vira um token separado porque acentos aparecem pouco nos textos de treinamento. Não é detalhe técnico irrelevante. Afeta diretamente o seu bolso e a capacidade efetiva do modelo quando você trabalha em português.

O imposto linguístico do português

Um estudo de Petrov et al. apresentado no NeurIPS 2023 mediu o que eles chamaram de "prêmio de tokenização" entre idiomas [1]. Os números:

Tokenizer	Quanto a mais o português consome vs inglês
GPT-2 (`r50k_base`)	1.94x (quase o dobro)
GPT-4 (`cl100k_base`)	1.48x (~50% a mais)
GPT-4o (`o200k_base`)	~1.3-1.4x (melhorou) *

Os números do GPT-2 e GPT-4 vêm diretamente do estudo de Petrov et al. [1]. A estimativa pro GPT-4o reflete a tendência de melhoria com vocabulários maiores, confirmada por estudos posteriores.

A boa notícia: cada geração de tokenizer melhora essa disparidade. A notícia que importa: mesmo no melhor caso, português ainda consome pelo menos 30% mais peças que inglês pra construir a mesma coisa. Esse "imposto" vai reaparecer quando falarmos de context window e de custo, porque ele se acumula em cada interação.

A janela de contexto

Se tokens são as peças, a context window é a mesa onde você monta. Tamanho fixo. Tudo precisa caber ali: as instruções que você mandou, o histórico da conversa, os arquivos de referência e a resposta que o modelo está construindo. Quando a mesa enche, acabou. O modelo não "lembra" de nada que ficou de fora.

As mesas de 2026

O mercado convergiu pra 1 milhão de tokens (1M) como padrão nos modelos frontier [2]. Na tabela abaixo, "K" significa mil e "M" significa milhão:

Modelo	Tamanho da mesa	Resposta máxima
Claude Opus 4.6	1M tokens	128K tokens
Claude Sonnet 4.6	1M tokens	64K tokens
Claude Haiku 4.5	200K tokens	64K tokens
GPT-5.4	1.05M tokens	128K tokens
GPT-4.1	1M tokens	32K tokens
Gemini 2.5 Pro	1M tokens	65K tokens
Llama 4 Scout	10M tokens	varia

A mesa é compartilhada. Tudo que você manda pro modelo (sua pergunta, arquivos, histórico de conversa) e tudo que ele responde precisam caber juntos na mesma superfície. Uma mesa de 1 milhão de tokens parece enorme, mas o espaço da resposta já reserva uma parte, e o resto é o máximo que você pode mandar.

Pra ter noção de escala: 1 milhão de tokens equivale a mais ou menos 750 mil palavras em inglês, algo como 8 a 10 livros. Pro português, por conta do imposto de tokenização, cai pra cerca de 500 mil palavras. Uns 7 livros.

O tamanho anunciado vs. o tamanho real

Aqui entra um ponto que pouca gente discute. Ter uma mesa de 1 milhão de tokens não significa que o modelo usa bem toda essa superfície.

Pesquisas recentes mostram que a capacidade do modelo de prestar atenção (attention, um conceito que vamos explorar logo abaixo) cai conforme o contexto cresce, especialmente pra informações posicionadas no meio do texto [3]. O fenômeno tem até nome: "lost in the middle". Na prática, a atenção efetiva do modelo é significativamente menor que a janela anunciada. O benchmark NoLiMa (ICML 2025) mostrou que a maioria dos LLMs erra mais da metade das vezes quando precisa encontrar uma informação específica em contextos a partir de 32K tokens [9].

E aqui o imposto linguístico aparece de novo. Se a janela efetiva de um modelo com 200K tokens já é significativamente menor que o anunciado, pra conteúdo 100% em português, planeje com uma margem generosa de desconto. O espaço útil pode cair pra algo entre 80K e 90K tokens de conteúdo equivalente ao inglês. Peças maiores ocupam mais espaço na mesma superfície.

Como o modelo gera texto

Você já sabe quais são as peças (tokens) e o tamanho da mesa (context window). Agora vem o processo de montagem em si.

A mecânica é surpreendentemente simples. O modelo olha pra tudo que já está na mesa, calcula uma distribuição de probabilidade sobre todo o vocabulário (entre ~100K e ~260K peças possíveis) pra decidir qual encaixa melhor na sequência, coloca uma, e repete. Uma de cada vez, do começo ao fim da resposta. Não existe um plano mestre. Isso se chama geração autorregressiva [4], e é a mecânica central da arquitetura Transformer publicada em 2017 por Vaswani et al.

Exemplo: o modelo recebe "O céu está" e precisa continuar.

Resultado: "O céu está azul hoje."

Cada peça colocada depende de todas as anteriores: tanto o input original quanto o que o modelo já construiu. Por isso respostas às vezes começam bem e descarrilham no meio. O modelo não sabe onde vai terminar quando começa a gerar.

Se você leu o artigo anterior, pode reconhecer esse mecanismo. Lembra do autocomplete, a fase 1 da evolução? O code completion que sugeria a próxima linha no editor? O mecanismo por baixo é o mesmo: next-token prediction. A diferença é a escala. Modelos como o GPT-2 (2019) tinham 1,5 bilhão de parâmetros e uma mesa minúscula. O Claude Opus 4.6 opera numa escala completamente diferente, com uma janela de contexto mil vezes maior. O processo de montagem é o mesmo. A capacidade de construir coisas complexas é que mudou.

O mecanismo de atenção

O processo de montagem explica que o modelo coloca uma peça por vez. Mas falta entender como ele decide as probabilidades. Se a entrada é "O banco está na margem do rio", como o modelo sabe que "banco" aqui é uma formação de areia e não uma instituição financeira?

A resposta é o mecanismo de atenção (self-attention), introduzido no paper "Attention Is All You Need" [4]. É o coração da arquitetura Transformer que sustenta todos os LLMs modernos.

Como o modelo enxerga o contexto

Imagine que o manual de montagem não mostra só o próximo passo. Pra cada peça nova, ele destaca quais partes da construção importam pra essa decisão: a base brilha forte (sustenta tudo), as torres ao redor acendem (definem o padrão), o jardim do outro lado fica apagado (irrelevante agora). O mecanismo de atenção faz exatamente isso: pra cada token, ele "acende" os anteriores que mais pesam e "apaga" os que não importam.

Antes dos Transformers, era como montar LEGO com alguém ditando as instruções: uma peça por vez, sem repetir, sem voltar atrás. Perdeu o passo 12? Já era. O Transformer é ter o manual inteiro aberto na mesa, todas as páginas visíveis ao mesmo tempo. Essa capacidade de processar tudo em paralelo foi o salto que viabilizou treinar modelos na escala atual.

Desambiguação na prática

Volte pro exemplo: "O banco está na margem do rio." O mecanismo de atenção faz com que o token "banco" preste muita atenção nos tokens "margem" e "rio", e pouca atenção em "está" e "na". É como numa montagem onde uma peça azul pode ser céu ou mar dependendo do que está ao redor. O contexto resolve a ambiguidade.

Esse mecanismo tem um preço. Pra cada peça na mesa, o modelo olha pra todas as outras antes de decidir o encaixe [4]. Numa mesa com 10 peças, tranquilo. Numa mesa com 10 mil, cada decisão exige olhar pra 10 mil peças. Dobrar o tamanho da mesa não dobra o trabalho, quadruplica.

Além disso, montar custa mais que olhar. Quando você manda uma pergunta, o modelo lê tudo de uma vez, como abrir o manual numa página. Mas quando ele constrói a resposta, é uma peça por vez, cada uma exigindo uma olhada na mesa inteira. Por isso o preço por token de resposta é 3x a 5x maior que o de entrada.

O que isso significa pra você

Se a atenção funciona ponderando a relevância de cada token em relação aos outros, prompts claros e bem estruturados facilitam o trabalho do modelo. Ambiguidade no input produz "confusão" na atenção: o modelo precisa distribuir pesos entre interpretações concorrentes. Um prompt preciso é como código limpo: a intenção fica óbvia e o mecanismo de atenção foca no que importa. Quanto mais organizada a mesa, mais precisa a próxima peça.

Isso não é abstração. É a base técnica de por que prompt engineering funciona, algo que vamos explorar a fundo na Parte 6 desta série.

Como o modelo escolhe entre as opções

Você já entende como o modelo pesa as opções. Mas quando vários tokens têm probabilidades próximas, quem decide qual é escolhido?

A diferença está entre seguir o manual ao pé da letra ou improvisar.

Temperatura

Você tá montando uma parede azul e precisa da próxima peça. Na caixa, as peças estão organizadas: no topo ficam as azuis que encaixam perfeitamente, no meio aparecem umas verdes que até funcionariam como detalhe, e lá no fundo tem uma roda vermelha que não faz sentido nenhum.

A temperatura controla o quão fundo o modelo enfia a mão na caixa. No zero, sempre pega a peça do topo: mesma escolha, toda vez, sem surpresa. No 0.7, às vezes pesca uma verde que ninguém esperava, mas que dá um charme na construção. Acima de 1.0, puxa a roda vermelha e encaixa na parede mesmo assim.

Temperatura	Completando "A receita leva..."	Comportamento
0.0	"farinha, açúcar e cacau."	Sempre a mesma resposta
0.3	"farinha de trigo, óleo de coco e cacau."	Pequenas variações
0.7	"especiarias exóticas e um toque de limão siciliano."	Criativo
1.5	"sonhos derretidos em caramelo de dragão."	Incoerente

Top-p

Temperatura não é o único controle. O top-p funciona diferente: em vez de mudar o quão fundo o modelo vai na caixa, ele tira peças da caixa antes da escolha. Com top-p de 0.9, as 10% mais improváveis nem ficam disponíveis. O efeito é parecido com temperatura, e a recomendação dos providers é ajustar um ou outro, não os dois ao mesmo tempo.

O que isso significa na prática

Quando você começar a usar ferramentas agênticas pra escrever código (a partir da Parte 5 desta série), esses valores já vêm calibrados. Mas entender que eles existem ajuda a entender por que o modelo às vezes surpreende com uma resposta inesperada: alguém deixou a mão mais funda na caixa.

Pro que nos interessa nesta série, a regra é simples: pra código, o modelo trabalha melhor no modo previsível. Peça certa no lugar certo, sem improviso.

As famílias de modelos

Nem toda peça serve pra toda construção. LEGO Duplo (peças grandes, simples) é perfeito pra quem está começando, mas não dá pra construir um motor funcional com ele. LEGO Technic (engrenagens, eixos, complexidade) permite construções sofisticadas, mas é mais caro e exige mais tempo. A mesma lógica vale pra modelos de linguagem.

Modelos de raciocínio

Os kits Technic: "pensam antes de responder", gastando tokens internos em raciocínio passo a passo (extended thinking) antes de produzir a resposta final. São os mais capazes, mais lentos e mais caros. Os preços abaixo estão em dólares por MTok (1 milhão de tokens): o primeiro valor é o custo de entrada (o que você manda), o segundo é o de resposta (o que o modelo gera).

Claude Opus 4.6 (Anthropic) alcança 80.8% no SWE-bench Verified [5]. $5/$25 por MTok.
o3 / o3-pro (OpenAI) são modelos de raciocínio dedicados. O o3-pro custa $20/$80 por MTok.
Gemini 2.5 Pro (Google) permite configurar o "orçamento de raciocínio". $1.25/$10 por MTok.

Modelos rápidos

Os kits Duplo: peças maiores, encaixe rápido, resultado imediato. Projetados pra latência baixa e alto volume.

Claude Haiku 4.5 (Anthropic): $1/$5 por MTok.
GPT-4o-mini (OpenAI): $0.15/$0.60 por MTok.
Gemini 2.5 Flash (Google): $0.30/$2.50 por MTok.

Modelos de código

Kits otimizados pra construções específicas. Como a linha Creator Expert, onde cada set é projetado pra um resultado particular.

GPT-4.1 (OpenAI): 1M de contexto, $2/$8 por MTok. Explicitamente otimizado pra código.
Claude Code (Anthropic): usa Opus/Sonnet por baixo, mas com um harness inteiro de ferramentas pra ler, editar, executar e fazer commit.

Modelos open-weight

Kits com todas as peças expostas: você monta, desmonta e adapta como quiser.

Llama 4 Scout (Meta): 10M de contexto, open-weight [6].
Llama 4 Maverick (Meta): 1M de contexto, 17B parâmetros ativos de 400B total.
DeepSeek R1: open-source (MIT), 671B parâmetros, raciocínio forte.

Escolhendo o kit certo

Usar Opus pra classificar sentimento de tweets é como comprar um Technic de 4 mil peças pra construir um cubo. A diferença entre Haiku ($1/$5 por MTok) e Opus ($5/$25 por MTok) é 5x no input e 5x no output. Muita tarefa que parece "precisar" de um modelo grande funciona perfeitamente com um modelo menor.

A regra prática: comece sempre pelo modelo mais barato que pode funcionar. Teste com Haiku, Flash ou mini. Se a qualidade não for suficiente, suba. Opus e o3-pro ficam reservados pra quando realmente necessário.

Mas independente do kit que você escolher, todos compartilham as mesmas limitações fundamentais.

O que modelos não conseguem fazer

A construção pode parecer perfeita. Visualmente impecável, cada peça no lugar. Mas empurre a parede e ela cai. O modelo não "sabe" se o que construiu funciona. Ele encaixa peças onde elas parecem caber, seguindo padrões estatísticos, e o resultado frequentemente se sustenta. Mas nem sempre.

Alucinações não são bugs

Quando um modelo gera informação que parece correta mas é factualmente falsa, chamamos de alucinação (hallucination). É tentador tratar isso como defeito, algo que será "consertado" numa versão futura. Mas alucinações são uma consequência direta do design: o modelo encaixa peças onde elas parecem caber estatisticamente, sem checar se a construção faz sentido no mundo real [4].

Se o padrão estatístico de "X escreveu o livro Y" é forte o bastante nos dados de treinamento, o modelo vai afirmar isso mesmo se for falso. Ele não tem um verificador de fatos interno. Não distingue entre gerar "Paris é a capital da França" e "Paris é a capital da Itália". Ambas são sequências de tokens plausíveis; uma é verdade, a outra não, e o modelo não sabe a diferença.

As limitações concretas

O manual do modelo foi impresso numa data específica. Tudo que aconteceu depois não existe pra ele. E pior: no final de cada montagem, a mesa é limpa. A próxima conversa começa do zero, sem nenhuma peça da anterior. Se você precisa que o modelo lembre de algo, você mesmo precisa colocar de volta na mesa.

A boa notícia: com técnicas de Context Engineering e Harness Engineering (temas das Partes 7 e 8 desta série), dá pra automatizar o que vai na mesa a cada conversa. Mas por enquanto, o importante é saber que o modelo sozinho não lembra de nada.

Matemática continua sendo um ponto fraco. O modelo pode montar uma conta que parece certa mas erra o resultado. Pra cálculos que exigem precisão, é mais seguro pedir pro modelo escrever código que faça a conta do que confiar na resposta direta.

E no contexto de código, testes da Veracode mostraram que 45% do código gerado por IA contém falhas de segurança, em avaliações com mais de 100 LLMs [7]. O modelo monta rápido, mas se ninguém confere a construção, peças mal encaixadas vão parar no produto final.

O que está melhorando

Mas a comunidade não tá parada. As melhorias estão vindo de várias frentes ao mesmo tempo: modelos que "pensam passo a passo" antes de montar, reduzindo erros em tarefas complexas. Sistemas que preenchem a mesa automaticamente com as peças certas pro seu projeto, em vez de você colocar tudo na mão. Agentes que lembram das montagens anteriores e aprendem com elas. E uma infraestrutura que fica mais rápida e mais barata a cada geração.

Cada uma dessas frentes vai aparecer nos próximos artigos da série. Por enquanto, o importante é saber: as limitações são reais, mas estão encolhendo.

Mesmo com essas limitações, os modelos estão sendo usados em escala. E escala tem um custo.

Quanto custa

Cada peça custa dinheiro. LLMs são cobrados por token processado, dividido em duas categorias: input tokens (tudo que você envia) e output tokens (o que o modelo gera). Construir algo novo (output) sempre custa mais que consultar o que já existe (input), geralmente entre 3x e 5x o preço [8]. Faz sentido: gerar cada token exige um forward pass completo pelo modelo.

Tabela de preços (abril 2026)

Preços em USD por 1 milhão de tokens (MTok):

Modelo	Input / MTok	Output / MTok	Cache read / MTok
Claude Opus 4.6	$5.00	$25.00	$0.50
Claude Sonnet 4.6	$3.00	$15.00	$0.30
Claude Haiku 4.5	$1.00	$5.00	$0.10
GPT-5.4	$2.50	$15.00	$0.25
GPT-4.1	$2.00	$8.00	$0.50
Gemini 2.5 Pro	$1.25	$10.00	$0.125
Gemini 2.5 Flash	$0.30	$2.50	$0.03

Repare na coluna "Cache read". Ela vai ser importante daqui a pouco.

O imposto linguístico fecha o ciclo

Lembra do custo de tokenização do português? Ele se traduz diretamente em dinheiro. Pro mesmo conteúdo, aplicações em português custam entre 30% e 50% a mais em tokens de input do que a mesma aplicação em inglês, dependendo do tokenizer. Numa conta de $5.000/mês, isso representa entre $1.150 e $1.650 extras só por causa do idioma.

Ao longo deste artigo, um fio conecta três seções: o português consome mais peças pra construir a mesma coisa (seção 1), isso ocupa mais espaço na mesa (seção 2), e agora cobra mais caro (aqui). Não são três problemas. É o mesmo problema, em três camadas.

Como otimizar

A boa notícia: existem formas concretas de reduzir esse custo.

Prompt caching é a mais impactante. Todos os grandes providers oferecem cache reads a cerca de 10% do preço de input [8]. Se o seu system prompt ou contexto de referência se repete entre chamadas, caching pode reduzir o custo de input em até 90%. Isso mitiga significativamente o imposto linguístico do português.

Batch API oferece 50% de desconto em troca de processamento assíncrono (janela de 24h). Pra tarefas que não são real-time (análise de documentos, classificação em massa), é dinheiro fácil de economizar.

Seleção de modelo é a terceira alavanca. Muitas tarefas que rodam em Opus funcionariam tão bem em Haiku, a uma fração do custo. Testar com o modelo mais barato primeiro não é otimização prematura. É engenharia responsável.

Combinando batch + caching na Anthropic, o desconto pode chegar a 95% em cenários ideais [8].

Esse tema vai ser central na Part 4, quando falarmos de context engineering. Gerenciar o que vai na mesa é, na prática, gerenciar dinheiro.

Considerações finais

Tokens, mesa, atenção, temperatura, limitações, custo. Pode parecer muita coisa, mas tudo se conecta. E nada disso é trivia técnica. É a base de cada decisão que você vai tomar com essas ferramentas: por que um prompt funciona e outro não, por que a resposta travou no meio, por que a conta veio mais cara do que o esperado.

Mas tem um gap. Saber como as peças funcionam não explica como digitar um parágrafo no terminal resulta em 50 arquivos editados, testes passando e um commit pronto. Alguma coisa tá pegando essas peças, organizando na mesa, montando, conferindo, desmontando quando erra e tentando de novo. Alguma coisa tá transformando um motor de próximo-token em um sistema que realmente constrói software.

Essa alguma coisa é o que ferramentas como Claude Code, Codex CLI e OpenCode fazem. São elas que envolvem o modelo, dão ferramentas pra ele agir, e orquestram o ciclo de montar, conferir e corrigir. No próximo artigo, a gente abre uma delas por dentro, peça por peça.

🤖 Este artigo foi escrito com assistência do Claude (Anthropic).

Conteúdo pesquisado, verificado e editado por um humano.

Encontrou algum erro ou crédito faltando? Me manda uma mensagem!

Referências

Claude Code 101: Introduction to Agentic Programming

Rodrigo Sicarelli — Mon, 06 Apr 2026 10:00:39 +0000

Software development as we know it

The era of AI assistance

From assistant to agent

The agentic tooling ecosystem

Agentic programming: the paradigm shift

Final thoughts

🇧🇷 Leia em português

September 2025. I was leading a critical dependency upgrade on a mobile app with millions of users. The kind of change that breaks tests in a cascade. The deadline was October: if it wasn't ready, the app wouldn't ship to the store.

The problem: nearly 10,000 tests needed to be adapted for the new version. Code owned by over 20 teams, spread across hundreds of modules.

I thought "what if I give these AI tools everyone keeps talking about a real shot?" After watching a few videos and reading the docs, I spun up four terminals running Claude Code in parallel, each one migrating a slice of the tests. One week later: 2,000+ files changed, 50,000 lines of code, 85% migrated on the first pass. The following week, I cleaned up the rest.

When I merged everything with the owning teams' approval, one thing was clear: I never could have done that alone. Not in two weeks, maybe not even in two months. It was cognitively impossible.

That's when I understood something had genuinely changed: my role had shifted, and I needed to understand how this works under the hood.

This is the first article in the Claude Code 101 series. Throughout it, we'll break down what's behind agentic programming: where it came from, how it works, what tools exist, and what you need to learn to use this for real. Together we'll build a mental model (the factory analogy) and meet the three pillars that hold everything up: prompt engineering, context engineering, and harness engineering.

Software development as we know it

The flow every dev knows: read requirements, design a solution, write code, run tests, fix bugs, deploy. Nothing happens unless you're actively involved. You're the one reading the docs, the one searching the (late) Stack Overflow, the one keeping the project's context in your head, the one typing every character.

Software only moves forward when you're sitting in front of the screen, working on it. Every line of code is a product assembled by hand, and the pace of production depends on how fast your fingers move and how much your memory can hold.

We are the bottleneck

Cognitive science has some uncomfortable data for us. Our working memory holds roughly 7 items at a time [1]. After an interruption (that tap on the shoulder, that Slack message) it takes an average of 23 minutes to regain focus [2]. And if you actually measure it, you'll find that you spend only about 30% of your time effectively writing code. The rest is reading, navigating, debugging, and meetings.

The bottleneck isn't just the compiler. It's not CI. It's not the server. The bottleneck is us.

For decades, we accepted this as the natural cost of building software. The factory produces at the speed of whoever operates it. Period. Until artificial intelligence started changing that equation.

The era of AI assistance

Intelligent autocomplete (2021-2022)

In June 2021, GitHub launched the technical preview of Copilot, which suggested lines of code in real time inside the editor [3]. Along with TabNine and similar tools, the code completion paradigm was born: single- or multi-line suggestions based on the current file's context.

Did it change things? Sure. Less typing, boilerplate filled in automatically, suggestions that often nailed what you were about to write. But the role of the developer didn't change one bit. You still decide what to write, where to write it, when to run tests, how to fix errors. The AI suggests; you execute.

Think of the factory: the production line got a conveyor belt to move parts faster. Useful? Absolutely. But you're still assembling everything by hand.

The chat paradigm (2022-2023)

November 2022: ChatGPT launches and changes how devs seek help [4]. The pattern quickly became familiar: copy a code snippet, paste it into the chat, describe the problem, get a suggestion, copy it back to the editor. LangChain, launched a month earlier, was already experimenting with connecting LLMs to external tools. A precursor of what was to come.

Chat was more versatile than autocomplete: it explained concepts, suggested refactors, generated tests. But the limitations were fundamental. No access to project files, no awareness of the folder structure, no ability to run commands. You became a messenger between the AI and your code.

It's like having a really good consultant sitting next to you. Someone who reads any manual in seconds and has an answer for almost anything. Except this consultant can't touch the machines. The manual work is still on you.

Why assistance wasn't enough

At the end of the day, both paradigms hit the same wall: the AI is not agentic (meaning it can't act on its own). It doesn't read your project. It doesn't run commands. It doesn't execute tests. It doesn't iterate on errors.

The conveyor belt and the consultant help, but nobody operates the machines for you. When you leave, production stops.

In 2024, the natural question came: what if AI could do more than suggest?

From Assistant to Agent

Looking back, the evolution of AI tools for code follows four distinct phases. Each phase is like an upgrade to the factory: first comes the conveyor belt, then the consultant, then better machines, until you reach ones that operate on their own.

We've already covered phases 1 and 2. The real leap starts at phase 3.

Phase 3: Multi-file editing (2024)

In 2024, Cursor (an editor built as a VS Code fork) popularized a new category: multi-file editing via natural language. You describe what you want; the AI proposes coordinated changes across multiple files at once.

The growth speaks for itself: from $1 million in annual revenue in January 2024 to over $1 billion by November 2025 [5]. Devs wanted more than line-by-line suggestions.

But the fundamental model didn't change: the human orchestrates, the AI executes. You say what to change, the AI changes it, you verify. The machines got more sophisticated, yes, but you're still operating every control panel, step by step.

Phase 4: Agentic coding (2024-present)

This is where the paradigm flips. Instead of you orchestrating the AI, you set the goal and the AI orchestrates itself.

This shift didn't happen out of nowhere. A sequence of advances made it possible:

Function calling (OpenAI, June 2023). For the first time, models could invoke external tools. This is the technical prerequisite for any agentic behavior [6].
Andrew Ng coins "agentic" (late 2023). He chose an adjective on purpose, not a noun: "Unlike the noun 'agent,' the adjective 'agentic' lets us think of systems as being more or less agent-like, in varying degrees." [7]
Model Context Protocol (Anthropic, November 2024). The open standard for connecting agents to external tools, rapidly adopted across the industry [8].
"Building Effective Agents" (Anthropic, December 2024). The paper that became the most cited reference in the field, distinguishing workflows (predefined paths) from agents (dynamic, self-directed processes) [9].

What makes something "agentic"? Five things:

Autonomy: decides what to do without step-by-step guidance
Tool use: reads and writes files, executes commands, runs tests
Planning: breaks goals into subtasks
Loop reasoning: iterates, doesn't just respond once
Self-correction: makes mistakes, notices, adjusts, and tries again

This is where the factory analogy changes completely. You're no longer on the production line tightening bolts and moving parts. Now you design the factory. You program the machines, set up quality controls, oversee production. The agents execute, report problems, and self-correct. Your productivity is no longer limited by the speed of your hands; it depends on the quality of your instructions.

As Anthropic put it: development shifts "from 'write code, run tests, read errors, fix, repeat' to 'set goal, review changes, approve implementation.'"

The full timeline

Five years, accelerating dramatically in 2024-2025:

2021: GitHub Copilot (preview) — code completion with AI is born
2022: LangChain (October), ChatGPT (November) — chat is born
2023: Function calling (June), AutoGPT goes viral, Andrew Ng coins "agentic"
2024: Devin AI jumps the SWE-bench from 1.96% to 13.86%. MCP is launched. "Building Effective Agents" is published
2025: Claude Code, Copilot Agent Mode, Codex CLI. Agents solve over 80% of SWE-bench, up from 13.86% just 18 months earlier [10]

"Vibe coding" vs. the real deal

An important distinction here. Typing vague prompts without checking the output (what the community calls "vibe coding") is not agentic programming. It's just... laziness with a nice interface. It's the difference between turning on a machine without reading the manual and configuring everything properly before pressing the button.

Professional agentic programming, as Tweag's engineering blog defines it, involves "qualified professionals who write prompts intentionally, validate rigorously, and guide the output within clear architectural boundaries" [11].

That's the approach this series teaches. And to use it properly, it helps to know the ecosystem of available tools.

The agentic tooling ecosystem

There's no shortage of tools in this space. In 2025, AI coding tools generated $7.37 billion in revenue, accounting for 55% of all enterprise AI investment [12]. Google already attributes 50% of its code to agents [13]. And 84% of devs say they use or plan to use AI tools [14].

The tools fall into three categories: CLI (terminal: Claude Code, Codex CLI, Cursor CLI, Aider, OpenCode), IDE (editor with built-in AI: Cursor, Windsurf), and hybrid (plugin + cloud: GitHub Copilot).

Here are the main ones:

Claude Code operates in the terminal: reads the entire codebase, edits files, runs commands, creates commits, opens PRs. The extensions and plugins are open source on GitHub (108K+ stars). It reached $2.5 billion in annual revenue in nine months, the fastest growth in enterprise software history [15]. It runs exclusively on Anthropic models (Opus, Sonnet, Haiku).

Cursor started as a VS Code fork rebuilt around AI, and now also has a CLI for those who prefer the terminal. It supports Claude, GPT, and Gemini simultaneously. It went from $1M to $1B+ in annual revenue in under two years, with over 1 million daily active users [5].

GitHub Copilot is the most widely adopted: 20 million users, 90% of Fortune 100 companies. Its Coding Agent generates around 1.2 million PRs per month [16].

OpenCode (MIT) became the most-starred code agent on GitHub, with ~129K stars. It runs in the terminal, supports 75+ LLM providers, and has native LSP integration. Completely free (you only pay for the model's API) [18].

On the open source side, two more stand out. Aider (Apache 2.0) works with any LLM and is free. Fun fact: Aider writes 70–88% of its own code in each release [17]. Codex CLI from OpenAI (Apache 2.0) has 2M+ weekly users [19].

Tool	Interface	Models	Open Source	Price	Approx. Users
Claude Code	CLI + extensions	Anthropic	Source-available	$20/mo	108K+ stars
Cursor	IDE + CLI	Multi-model	No	$20/mo	1M+ DAU
GitHub Copilot	IDE plugin + cloud	Multi-model	Partial	$10/mo	20M+
OpenCode	CLI/TUI	75+ providers	Yes (MIT)	Free (bring your API key)	129K stars
Codex CLI	CLI	OpenAI	Yes (Apache 2.0)	$20/mo	2M+ weekly
Aider	CLI	Any LLM	Yes (Apache 2.0)	Free (bring your API key)	42.5K stars

What stands out: these are machines from different manufacturers, but they ultimately do the same thing. Multi-file editing, terminal execution, extensibility via MCP, and an iterative loop. What truly differentiates each one is how the agentic behavior is implemented and orchestrated under the hood: the tool system, the way context is managed, the planning and self-correction loop. Beyond that, what matters is the delivery model (CLI vs IDE vs cloud), the ecosystem, and the price. And the open source alternatives prove that the agentic paradigm doesn't require expensive tools. Just a capable LLM.

But tools are only half the story. The other half is how you work with them.

Agentic programming: the paradigm shift

In traditional development, you are simultaneously the brain and the hands of the operation. You think through the solution, type the code, run the tests, read the errors, fix, repeat. Your productivity has a physical ceiling: typing speed, memory capacity, how many hours you can stay focused.

In agentic programming, the role changes. You define the goal, provide context, configure the environment. The agent executes. You're at the beginning (definition) and at the end (review). The middle cycle is autonomous.

I know what you might be thinking: "so the AI does the work and I just... do what?"

The better question might be: do what differently. When the compiler came along, nobody needed to write Assembly by hand anymore. Programmers didn't lose their purpose. They moved up a level of abstraction. They started thinking about business logic instead of memory registers. They became more productive, more strategic, more valuable.

The same thing is happening now: you're not being replaced, you're leveling up. Whoever designs the factory isn't less important than whoever operates it — quite the opposite — but the skills are different.

So what are those skills?

The three pillars

If the new role is orchestrating agents, three skills become essential. I call them the three pillars of agentic engineering, and each one will get a dedicated article in this series.

The first is prompt engineering. It's how you communicate intent to the agent. Not just "write a good prompt," but structured communication: clear goals, explicit constraints, examples of what you want and what you don't. Back to the factory: these are the instructions you hand to the machine operator. The more precise they are, the better the output.

The second is context engineering. It's the discipline of curating what the agent knows. Which files are relevant? What documentation should be accessible? How do you structure project rules in the CLAUDE.md file? Context is the most precious resource in an agentic system, and it's limited and expensive. Think of the documentation you hand to someone new on the team: without quality information, even the best machine produces junk.

The third is harness engineering: the configuration of everything that surrounds and orchestrates the agent. Automation hooks, MCP servers to connect external services, permissions, custom tools. In the factory, it's the infrastructure: the conveyor belts, the sensors, the safety systems. The factory that produces the most isn't the one with the best workforce; it's the one with the best structure around it.

The numbers: good and bad

It's worth looking at the data honestly, because the landscape has real contradictions.

On one hand, the growth is undeniable: $7.37 billion in revenue in 2025, 84% of devs adopting, SWE-bench jumping from 1.96% to over 80% in 18 months. GitHub Copilot generates 1.2 million PRs per month. In LLM API calls for coding, Claude leads with a 54% share [20].

On the other hand, independent data is more sobering. The METR study (a rigorous randomized trial with 16 experienced devs) found that AI tools made the team 19% slower, even though participants perceived themselves as 20% faster [21]. AI-generated code carries 2.74x more vulnerabilities according to Veracode [22]. And Gartner predicts that 40% of agentic AI projects will be canceled before reaching production by 2027 [23].

The most honest take I've read on this came from the DORA 2025 report: "AI amplifies the strengths of high-performing organizations and the dysfunctions of those that are struggling." [24]

The automated factory produces more, but without quality control, it produces defects faster too. The outcome depends on who configures and oversees it. That's exactly what the three pillars address.

Final thoughts

You now know what agentic programming is, where it came from, and what tools exist. You know that the role has shifted: from the one who writes every line to the one who designs, guides, and oversees. And you know that three pillars (prompt engineering, context engineering, and harness engineering) separate those who use AI haphazardly from those who use it with consistency.

But knowing the what isn't enough. To actually use this, you need to understand the how. And the how starts with a question few people stop to ask: how does this technology work under the hood?

What are tokens? What is a context window? Why do models hallucinate with such conviction? Understanding this completely changes how you interact with any agentic tool.

That's exactly what we'll break down in the next article: Demystifying Language Models.

🤖 This article was written with assistance from Claude (Anthropic).

Content researched, verified, and edited by a human.

Found an error or a missing credit? Send me a message!

References

Miller, G.A. — "The Magical Number Seven, Plus or Minus Two" (1956)
Mark, G. et al. — "The Cost of Interrupted Work: More Speed and Stress" (2008) — ACM CHI 2008
GitHub Copilot — documentation
ChatGPT — OpenAI launch announcement (November 2022)
Cursor / Anysphere — CNBC (November 2025) — $1B+ ARR, $29.3B valuation
OpenAI Function Calling — API update (June 2023)
Andrew Ng — "Agentic Design Patterns" (2024) — The Batch newsletter; Sequoia AI Ascent talk
Model Context Protocol (MCP) — Anthropic (November 2024)
Building Effective Agents — Anthropic (December 2024)
SWE-bench — Princeton NLP (ICLR 2024)
Tweag — "Introduction to Agentic Coding" (2025); Agentic Coding Handbook
Mordor Intelligence — AI Code Tools Market Report (2025) — US$ 7.37B market size
Alphabet Q4 2025 Earnings Call (February 2026) — CFO Anat Ashkenazi: "about 50% of our code is written by coding agents"
Stack Overflow Developer Survey 2025
Claude Code — Anthropic documentation
GitHub Blog — "Copilot: Faster, smarter, and built for how you work now" (October 2025) — 20M+ users, 1.2M PRs/month
Aider — GitHub repository
OpenCode — GitHub repository
OpenAI Codex CLI — GitHub repository
Menlo Ventures — "2025: The State of Generative AI in the Enterprise" (December 2025) — Claude: 54% coding market share
METR — "Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity" (2025); arXiv
Veracode — "GenAI and Code Security: What You Need to Know" (2025)
Gartner — "Over 40% of Agentic AI Projects Will Be Canceled by End of 2027" (June 2025)
DORA State of DevOps Report 2025 — Google

Claude Code 101: Introdução à Programação Agêntica

Rodrigo Sicarelli — Sat, 04 Apr 2026 20:07:58 +0000

O desenvolvimento de software como conhecemos

A era da assistência por IA

De assistente a agente

O ecossistema de ferramentas agênticas

Programação agêntica — a mudança de paradigma

Considerações finais

🌐 Read in English

Setembro de 2025. Eu estava tocando a atualização de uma dependência crítica num app mobile com milhões de usuários. O tipo de mudança que quebra testes em cascata. O prazo era Outubro: se não ficasse pronto, o app não subia pra loja.

O problema: quase 10.000 testes precisavam ser adaptados pra nova versão. Código de mais de 20 times, espalhado por centenas de módulos.

Pensei "e se eu der uma chance pra essas ferramentas de IA que todo mundo fala?" Depois de alguns vídeos e documentação, coloquei quatro terminais rodando em paralelo com Claude Code, cada um migrando uma fatia dos testes. Em uma semana: 2.000+ arquivos alterados, 50 mil linhas de código, 85% migrado de primeira. Na semana seguinte, pente fino no restante.

Quando mergiei tudo com aprovação dos times responsáveis, uma coisa ficou clara: eu nunca teria feito aquilo sozinho. Não em duas semanas, talvez nem em dois meses. Era cognitivamente impossível.

Foi aí que eu entendi que alguma coisa tinha mudado de verdade: meu papel tinha mudado, e eu precisava entender como isso funciona por dentro.

Este é o primeiro artigo da série Claude Code 101. Ao longo dela, vamos desmontar o que está por trás da programação agêntica: de onde veio, como funciona, quais ferramentas existem e o que você precisa aprender pra usar isso de verdade. Vamos construir juntos um modelo mental (a analogia da fábrica) e conhecer os três pilares que sustentam tudo: prompt engineering, context engineering e harness engineering.

O desenvolvimento de software como conhecemos

O fluxo que todo dev conhece: ler requisito, projetar solução, escrever código, rodar testes, corrigir bugs, fazer deploy. Nada acontece sem que você esteja ativamente envolvido. É você quem lê a documentação, quem busca no (finado 😅) Stack Overflow, quem mantém o contexto do projeto na cabeça, quem digita cada letra.

O software só avança quando você está sentado na frente da tela, trabalhando nele. Cada linha de código é um produto montado à mão, e o ritmo de produção depende da velocidade dos seus dedos e da capacidade da sua memória.

O gargalo somos nós

A ciência cognitiva tem dados desconfortáveis pra gente. Nossa memória de trabalho retém, em média, 7 itens ao mesmo tempo [1]. Depois de uma interrupção (aquele tapinha no ombro, aquela mensagem no Slack) levamos em média 23 minutos pra retomar o foco [2]. E se você parar pra medir, vai perceber que passa apenas uns 30% do tempo efetivamente escrevendo código. O resto é leitura, navegação, debugging e reuniões.

O gargalo não é só o compilador. Não é o CI. Não é o servidor. O gargalo é a gente.

Por décadas, aceitamos isso como o custo natural de construir software. A fábrica produz na velocidade de quem opera. E ponto. Até que a inteligência artificial começou a mudar essa equação.

A era da assistência por IA

Autocomplete Inteligente (2021-2022)

Em junho de 2021, o GitHub lançou a preview técnica do Copilot, que sugeria linhas de código em tempo real dentro do editor [3]. Junto com o TabNine e outras ferramentas similares, nascia o paradigma do code completion: sugestões de uma ou mais linhas baseadas no contexto do arquivo atual.

Mudou algo? Claro. Menos digitação, boilerplate preenchido automaticamente, sugestões que muitas vezes acertavam o que você ia escrever. Mas o papel de quem desenvolve não mudou em nada. Você ainda decide o quê escrever, onde escrever, quando rodar testes, como corrigir erros. A IA sugere; você executa.

Pense na fábrica: a linha de produção ganhou uma esteira pra mover peças mais rápido. Útil? Sem dúvida. Mas você continua montando tudo à mão.

O paradigma do chat (2022-2023)

Novembro de 2022: ChatGPT é lançado e muda a forma como devs buscam ajuda [4]. O padrão se tornou familiar pra qualquer um: copiar um trecho de código, colar no chat, descrever o problema, receber uma sugestão, copiar de volta pro editor. O LangChain, lançado um mês antes, já ensaiava conectar LLMs a ferramentas externas. Um precursor do que viria depois.

O chat era mais versátil que o autocomplete: explicava conceitos, sugeria refatorações, gerava testes. Mas as limitações eram fundamentais. Sem acesso aos arquivos do projeto, sem contexto da estrutura de pastas, sem capacidade de executar comandos. Você virava um mensageiro entre a IA e o código.

É como ter um consultor muito bom sentado ao seu lado. Alguém que lê qualquer manual em segundos e tem resposta pra quase tudo. Só que esse consultor não pode tocar nas máquinas. O trabalho manual continua sendo seu.

Por que assistência não bastava

No fim das contas, os dois paradigmas esbarram no mesmo problema: a IA não é agêntica (ou seja, não tem capacidade de agir por conta própria). Não lê seu projeto. Não roda comandos. Não executa testes. Não itera sobre erros.

A esteira e o consultor ajudam, mas ninguém opera as máquinas por você. Quando você vai embora, a produção para.

Em 2024, a pergunta natural veio: e se a IA pudesse fazer mais do que sugerir?

De Assistente a Agente

Olhando pra trás, a evolução das ferramentas de IA para código segue quatro fases bem definidas. Cada fase é como um upgrade na fábrica: primeiro vem a esteira, depois o consultor, depois máquinas melhores, até chegar nas que operam sozinhas.

As fases 1 e 2 já vimos. O salto real começa na fase 3.

Fase 3 — Edição multi-arquivo (2024)

Em 2024, o Cursor (um editor construído como fork do VS Code) popularizou uma nova categoria: edição multi-arquivo via linguagem natural. Você descreve o que quer, a IA propõe mudanças coordenadas em vários arquivos de uma vez.

O crescimento fala por si: de US$ 1 milhão de receita anual em janeiro de 2024 para mais de US$ 1 bilhão em novembro de 2025 [5]. Devs queriam mais do que sugestões linha a linha.

Mas o modelo fundamental não mudou: o humano orquestra, a IA executa. Você diz o que mudar, a IA muda, você confere. As máquinas ficaram mais sofisticadas, sim — mas você ainda opera cada painel de controle, passo a passo.

Fase 4 — A codificação agêntica (2024-presente)

Aqui o paradigma inverte. Em vez de você orquestrar a IA, você define o objetivo e a IA se orquestra sozinha.

Essa virada não aconteceu do nada. Teve uma sequência de avanços que a tornaram possível:

Function calling (OpenAI, junho de 2023). Pela primeira vez, modelos podiam invocar ferramentas externas. É o pré-requisito técnico pra qualquer comportamento agêntico [6].
Andrew Ng cunha "agentic" (final de 2023). Ele escolheu um adjetivo de propósito, não um substantivo: "Diferente do substantivo 'agent', o adjetivo 'agentic' nos permite pensar em sistemas como sendo mais ou menos parecidos com agentes, em diferentes graus." [7]
Model Context Protocol (Anthropic, novembro de 2024). O padrão aberto pra conectar agentes a ferramentas externas, adotado rapidamente por toda a indústria [8].
"Building Effective Agents" (Anthropic, dezembro de 2024). O paper que virou a referência mais citada do campo, diferenciando workflows (caminhos predefinidos) de agents (processos dinâmicos, autodirigidos) [9].

O que faz algo ser "agêntico"? Cinco coisas:

Autonomia: decide o que fazer sem guia passo a passo
Tool use: lê e escreve arquivos, executa comandos, roda testes
Planejamento: quebra objetivos em subtarefas
Raciocínio em loop: itera, não responde uma vez só
Autocorreção: erra, percebe, ajusta e tenta de novo

Aqui é onde a analogia da fábrica muda completamente. Você não está mais na linha de produção apertando parafuso e movendo peça. Agora você projeta a fábrica. Programa as máquinas, configura os controles de qualidade, supervisiona a produção. Os agentes executam, reportam problemas e se autocorrigem. Sua produtividade deixa de ser limitada pela velocidade das suas mãos e passa a depender da qualidade das suas instruções.

Como a Anthropic resumiu: o desenvolvimento vai "de 'escrever código, rodar testes, ler erros, corrigir, repetir' para 'definir objetivo, revisar mudanças, aprovar implementação.'"

A linha do tempo completa

Cinco anos, acelerando absurdamente em 2024-2025:

2021: GitHub Copilot (preview) — nasce o code completion com IA
2022: LangChain (outubro), ChatGPT (novembro) — nasce o chat
2023: Function calling (junho), AutoGPT viraliza, Andrew Ng cunha "agentic"
2024: Devin AI salta o SWE-bench de 1,96% pra 13,86%. MCP é lançado. "Building Effective Agents" é publicado
2025: Claude Code, Copilot Agent Mode, Codex CLI. Agentes resolvem mais de 80% do SWE-bench — contra 13,86% apenas 18 meses antes [10]

"Vibe coding" vs. o negócio sério

Vale uma distinção importante aqui. Digitar prompts vagos sem conferir o resultado (o que a comunidade chama de "vibe coding") não é programação agêntica. É só... preguiça com interface bonita. É a diferença entre ligar a máquina sem ler o manual e configurar tudo direitinho antes de apertar o botão.

Programação agêntica profissional, como o blog de engenharia da Tweag define, envolve "profissionais qualificados que escrevem prompts intencionalmente, validam rigorosamente e guiam a saída dentro de limites arquiteturais claros" [11].

É essa abordagem que esta série ensina. E pra usá-la direito, vale conhecer o ecossistema de ferramentas disponíveis.

O ecossistema de ferramentas agênticas

Não falta ferramenta nesse espaço. Em 2025, ferramentas de IA pra código geraram US$ 7,37 bilhões em receita, o equivalente a 55% de todo o investimento empresarial em IA [12]. O Google já atribui 50% do seu código a agentes [13]. E 84% de devs dizem que usam ou planejam usar ferramentas de IA [14].

As ferramentas se dividem em três categorias: CLI (terminal: Claude Code, Codex CLI, Cursor CLI, Aider, OpenCode), IDE (editor com IA integrada: Cursor, Windsurf) e híbrido (plugin + nuvem: GitHub Copilot).

Eis as principais:

Claude Code opera no terminal: lê o codebase inteiro, edita arquivos, roda comandos, cria commits, abre PRs. As extensões e plugins são open source no GitHub (108K+ stars). Atingiu US$ 2,5 bilhões de receita anual em nove meses, o crescimento mais rápido da história de software empresarial [15]. Roda exclusivamente com modelos da Anthropic (Opus, Sonnet, Haiku).

Cursor começou como um fork do VS Code reconstruído em torno de IA e hoje também tem uma CLI pra quem prefere o terminal. Suporta Claude, GPT e Gemini ao mesmo tempo. Passou de US$ 1M pra US$ 1B+ de receita anual em menos de dois anos, com mais de 1 milhão de usuários ativos por dia [5].

GitHub Copilot é o mais amplamente adotado: 20 milhões de usuários, 90% das empresas Fortune 100. Seu Coding Agent gera cerca de 1,2 milhão de PRs por mês [16].

OpenCode (MIT) virou o agente de código mais estrelado do GitHub com ~129K stars. Roda no terminal, suporta 75+ provedores de LLM e tem integração nativa de LSP. Totalmente gratuito (você só paga a API do modelo) [18].

No lado open source, mais dois se destacam. Aider (Apache 2.0) funciona com qualquer LLM e é gratuito. Detalhe curioso: o Aider escreve 70-88% do seu próprio código em cada release [17]. Codex CLI da OpenAI (Apache 2.0) tem 2M+ de usuários semanais [19].

Ferramenta	Interface	Modelos	Open Source	Preço	Usuários aprox.
Claude Code	CLI + extensões	Anthropic	Source-available	$20/mês	108K+ stars
Cursor	IDE + CLI	Multi-modelo	Não	$20/mês	1M+ DAU
GitHub Copilot	Plugin IDE + cloud	Multi-modelo	Parcial	$10/mês	20M+
OpenCode	CLI/TUI	75+ provedores	Sim (MIT)	Grátis (usa sua API key)	129K stars
Codex CLI	CLI	OpenAI	Sim (Apache 2.0)	$20/mês	2M+ semanais
Aider	CLI	Qualquer LLM	Sim (Apache 2.0)	Grátis (usa sua API key)	42.5K stars

O que chama atenção: são máquinas de fabricantes diferentes, mas no fim fazem a mesma coisa. Edição multi-arquivo, execução no terminal, extensibilidade via MCP e loop iterativo. O que realmente diferencia cada uma é como o comportamento agêntico é implementado e orquestrado por baixo dos panos: o sistema de tools, a forma de gerenciar contexto, o loop de planejamento e autocorreção. Fora isso, pesam o modelo de entrega (CLI vs IDE vs nuvem), o ecossistema e o preço. E as alternativas open source provam que o paradigma agêntico não exige ferramenta cara. Só um LLM capaz.

Mas ferramentas são só metade da história. A outra metade é como você trabalha com elas.

Programação Agêntica — a mudança de paradigma

No desenvolvimento tradicional, você é simultaneamente o cérebro e as mãos da operação. Pensa na solução, digita o código, roda os testes, lê os erros, corrige, repete. Sua produtividade tem um teto físico: velocidade de digitação, capacidade de memória, quantas horas consegue manter o foco.

Na programação agêntica, o papel muda. Você define o objetivo, fornece contexto, configura o ambiente. O agente executa. Você está no início (definição) e no fim (revisão). O ciclo do meio é autônomo.

Eu sei o que você pode estar pensando: "então a IA faz o trabalho e eu fico... fazendo o quê?"

A pergunta melhor talvez seja: fazendo o quê de diferente. Quando surgiu o compilador, ninguém mais precisou escrever Assembly na mão. Quem programava não ficou sem função. Subiu um nível de abstração. Passou a pensar em lógica de negócio em vez de registradores de memória. Ficou mais produtivo, mais estratégico, mais valioso.

A mesma coisa está acontecendo agora: você não está sendo substituído, está subindo de nível. Quem projeta a fábrica não é menos importante que quem opera, pelo contrário, mas as habilidades são outras.

E quais são essas habilidades?

Os três pilares

Se o novo papel é orquestrar agentes, três habilidades se tornam essenciais. Eu chamo de os três pilares da engenharia agêntica, e cada um vai ganhar um artigo dedicado nesta série.

O primeiro é prompt engineering. É como você comunica intenção ao agente. Não só "escreva um bom prompt", mas comunicação estruturada: objetivos claros, restrições explícitas, exemplos do que você quer e do que não quer. Voltando à fábrica, são as instruções que você passa pro operador da máquina. Quanto mais precisas, melhor o resultado.

O segundo é context engineering. É a disciplina de curar o que o agente sabe. Quais arquivos são relevantes? Qual documentação deve estar acessível? Como estruturar as regras do projeto no arquivo CLAUDE.md? Contexto é o recurso mais precioso num sistema agêntico, e é limitado e caro. Pense na documentação que você entrega pra alguém novo na equipe: sem informação de qualidade, até a melhor máquina produz lixo.

O terceiro é harness engineering, a configuração de tudo que envolve e orquestra o agente: hooks de automação, MCP servers pra conectar serviços externos, permissões, ferramentas customizadas. Na fábrica, é a infraestrutura: as esteiras, os sensores, o sistema de segurança. A fábrica que mais produz não é a que tem a melhor mão de obra, é a que tem a melhor estrutura ao redor.

Os números — bons e ruins

Vale olhar pros dados com honestidade, porque o cenário tem contradições reais.

Por um lado, o crescimento é inegável: US$ 7,37 bilhões de receita em 2025, 84% dos devs adotando, o SWE-bench saltando de 1,96% pra mais de 80% em 18 meses. O GitHub Copilot gera 1,2 milhão de PRs por mês. Em chamadas de API de LLM pra código, o Claude lidera com 54% [20].

Por outro, os dados independentes são mais sóbrios. O estudo METR (um ensaio randomizado rigoroso com 16 devs experientes) encontrou que ferramentas de IA deixaram o time 19% mais lento, embora a percepção fosse de estar 20% mais rápido [21]. Código gerado por IA carrega 2,74× mais vulnerabilidades segundo a Veracode [22]. E o Gartner prevê que 40% dos projetos agênticos serão cancelados antes de chegar a produção até 2027 [23].

A frase mais honesta que li sobre o assunto veio do relatório DORA 2025: "A IA amplifica as forças de organizações de alto desempenho e as disfunções das que estão em dificuldade." [24]

A fábrica automatizada produz mais, mas sem controle de qualidade, produz defeito mais rápido também. O resultado depende de quem configura e supervisiona. É exatamente isso que os três pilares endereçam.

Considerações finais

Você agora sabe o que é programação agêntica, de onde veio e quais ferramentas existem. Sabe que o papel mudou: de quem escreve cada linha pra quem projeta, orienta e supervisiona. E sabe que três pilares (prompt engineering, context engineering e harness engineering) separam quem usa IA de qualquer jeito de quem usa com consistência.

Só que saber o que não é suficiente. Pra usar isso de verdade, você precisa entender o como. E o como começa por uma pergunta que pouca gente para pra fazer: como essa tecnologia funciona por dentro?

O que são tokens? O que é uma context window? Por que modelos erram com tanta convicção? Entender isso muda completamente a forma como você interage com qualquer ferramenta agêntica.

É exatamente o que vamos desmontar no próximo artigo: Desmistificando os Modelos de Linguagem.

🤖 Este artigo foi escrito com assistência do Claude (Anthropic).

Conteúdo pesquisado, verificado e editado por um humano.

Encontrou algum erro ou crédito faltando? Me manda uma mensagem!

Referências

Miller, G.A. — "The Magical Number Seven, Plus or Minus Two" (1956)
Mark, G. et al. — "The Cost of Interrupted Work: More Speed and Stress" (2008) — ACM CHI 2008
GitHub Copilot — documentation
ChatGPT — OpenAI launch announcement (November 2022)
Cursor / Anysphere — CNBC (November 2025) — $1B+ ARR, $29.3B valuation
OpenAI Function Calling — API update (June 2023)
Andrew Ng — "Agentic Design Patterns" (2024) — The Batch newsletter; Sequoia AI Ascent talk
Model Context Protocol (MCP) — Anthropic (November 2024)
Building Effective Agents — Anthropic (December 2024)
SWE-bench — Princeton NLP (ICLR 2024)
Tweag — "Introduction to Agentic Coding" (2025); Agentic Coding Handbook
Mordor Intelligence — AI Code Tools Market Report (2025) — US$ 7.37B market size
Alphabet Q4 2025 Earnings Call (February 2026) — CFO Anat Ashkenazi: "about 50% of our code is written by coding agents"
Stack Overflow Developer Survey 2025
Claude Code — Anthropic documentation
GitHub Blog — "Copilot: Faster, smarter, and built for how you work now" (October 2025) — 20M+ users, 1.2M PRs/month
Aider — GitHub repository
OpenCode — GitHub repository
OpenAI Codex CLI — GitHub repository
Menlo Ventures — "2025: The State of Generative AI in the Enterprise" (December 2025) — Claude: 54% coding market share
METR — "Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity" (2025); arXiv
Veracode — "GenAI and Code Security: What You Need to Know" (2025)
Gartner — "Over 40% of Agentic AI Projects Will Be Canceled by End of 2027" (June 2025)
DORA State of DevOps Report 2025 — Google

Fakt: Automating the Fake-over-mock pattern

Rodrigo Sicarelli — Wed, 25 Feb 2026 12:40:19 +0000

Kotlin testing has a problem that gets worse the more successful your project becomes.

Manual test fakes don't scale—each interface requires 60-80 lines of boilerplate that silently drifts from reality during refactoring. Runtime mocking frameworks (MockK, Mockito) solve the boilerplate but introduce severe performance penalties and don't work on Kotlin/Native or WebAssembly. KSP-based tools promised compile-time generation, but Kotlin 2.0 broke them all.

Fakt is a compiler plugin that generates production-quality fakes through deep integration with Kotlin's FIR and IR compilation phases—the same extension points used by Metro, a production DI framework from Zac Sweers.

What Fakt Does

https://github.com/rsicarelli/fakt

Fakt reduces fake boilerplate to an annotation:

@Fake
interface AnalyticsService {
    fun track(event: String)
    suspend fun flush(): Result<Unit>
}

At compile time, Fakt generates a complete fake implementation. You use it through a type-safe factory:

val fake = fakeAnalyticsService {
    track { event -> println("Tracked: $event") }
    flush { Result.success(Unit) }
}

// Use in tests
fake.track("user_signup")
fake.flush()

// Verify interactions (thread-safe StateFlow)
assertEquals(1, fake.trackCalls.value.size)
assertEquals(1, fake.flushCalls.value.size)

That's it ✨

The Testing Problem

Consider a simple interface:

interface AnalyticsService {
    fun track(event: String)
    suspend fun flush(): Result<Unit>
}

A proper, production-quality fake requires ~40-60 lines of boilerplate:

// Typical handwritten fake — error-prone, tedious
class FakeAnalyticsService(
    private val trackBehavior: ((String) -> Unit)? = null
    private val flushBehavior: (suspend () -> Result<Unit>)? = null
) : AnalyticsService {

    private var _trackCalls = mutableListOf<Unit>()
    val trackCalls: List<Unit> get() = _trackCalls

    private var _flushCalls = mutableListOf<Unit>()
    val flushCalls: List<Unit> get() = _flushCalls

    // Interface implementation
    override fun track(event: String) {
        _trackCalls.add(Unit)
        trackBehavior?.invoke(event) ?: Unit
    }

    override suspend fun flush(): Result<Unit> {
        _flushCalls.add(Unit)
        return flushBehavior?.invoke() ?: Result.success(Unit)
    }
}

The problems: N methods require ~10N lines. Interface changes don't break unused fakes—they silently drift. For 50 interfaces, this means thousands of lines of brittle boilerplate.

The Mock Tax

Runtime mocking frameworks solve the boilerplate but pay a different cost. Kotlin classes are final by default, so MockK and Mockito resort to bytecode instrumentation. Independent benchmarks¹ quantify the penalty:

Mocking Pattern	Framework	Comparison	Verified Penalty
`mockkObject` (Singletons)	MockK	vs. Dependency Injection	1,391x slower
`mockkStatic` (Top-level functions)	MockK	vs. Interface-based DI	146x slower
`verify { ... }` (Interaction verification)	MockK	vs. State-based testing	47x slower
`relaxed` mocks (Unstubbed calls)	MockK	vs. Strict mocks	3.7x slower
`mock-maker-inline`	Mockito	vs. `all-open` plugin	2.7-3x slower²³

A production test suite with 2,668 tests experienced a 2.7x slowdown (7.3s → 20.0s) when using mock-maker-inline³. For large projects, the mock tax accumulates to 40% slower test suites¹.

The KMP Dead End

Runtime mocking relies on JVM-specific features: reflection, bytecode instrumentation, dynamic proxies. Kotlin/Native and Kotlin/Wasm compile to machine code. There is no JVM. MockK and Mockito cannot run in commonTest source sets targeting Native or Wasm⁴⁵.

The community attempted KSP-based solutions, but Kotlin 2.0's K2 compiler broke them. The StreetComplete app (10,000+ tests) was forced to migrate mid-project⁶.

Why Compiler Plugins Work

KSP-based tools (Mockative, MocKMP) operated at the symbol level—after type resolution, with limited access to the type system. When K2 landed, they broke. Compiler plugins operate during compilation, with full access to FIR and IR. They survive Kotlin version updates.

Aspect	KSP	Compiler Plugin
Access	After type resolution	During compilation
Type System	Read-only symbols	Full manipulation

Fakt uses a two-phase FIR → IR architecture:

┌──────────────────────────────────────────────────────┐
│  PHASE 1: FIR (Frontend IR)                          │
│  • Detects @Fake annotations                         │
│  • Validates interface structure                     │
│  • Full type system access                           │
└──────────────────────────────────────────────────────┘
                         ↓
┌──────────────────────────────────────────────────────┐
│  PHASE 2: IR (Intermediate Representation)           │
│  • Analyzes interface methods and properties         │
│  • Generates readable .kt source files               │
│  • Thread-safe StateFlow call history                │
└──────────────────────────────────────────────────────┘

This is the same pattern used by Metro, Zac Sweers' DI compiler plugin. Metro's architecture has proven stable across Kotlin 1.9, 2.0, and 2.1.

Why Fakes Over Mocks

Beyond performance, fakes represent a different testing philosophy. Martin Fowler's "Mocks Aren't Stubs"⁷ describes two schools: state-based testing (verify outcomes) and interaction-based testing (verify method calls).

The problem with interaction-based tests: they couple to implementation details⁸. Refactor a method signature without changing behavior, and mock-based tests break. Google's Testing Blog defines resilience as a critical test quality—"a test shouldn't fail if the code under test isn't defective"⁹. Mock-based tests often violate this.

Google's "Now in Android" app makes this explicit¹⁰:

"Don't use mocking frameworks. Instead, use fakes."

The goal: "less brittle tests that may exercise more production code, instead of just verifying specific calls against mocks"¹¹.

Kotlin's async testing stack—runTest, TestDispatcher, Turbine¹²—is inherently state-based. Turbine's awaitItem() verifies emitted values, not method calls. The natural data source for this stack is a fake with MutableStateFlow backing. Fakt automates this pattern.

Practical Guidance

Fakes vs. Mocks: Quick Comparison

Feature	MockK/Mockito	Fakt
KMP Support	Limited (JVM only)	Universal (all targets)
Compile-time Safety	❌	✅
Runtime Overhead	Heavy (reflection)	Zero
Type Safety	Partial (`any()` matchers)	Complete
Learning Curve	Steep (complex DSL)	Gentle (typed functions)
Call History	Manual (`verify { }`)	Built-in (StateFlow)
Thread Safety	Not guaranteed	StateFlow-based
Debuggability	Reflection (opaque)	Generated `.kt` files

Choosing the Right Tool

Fakt and mocking libraries solve overlapping but distinct problems. Choosing between them depends on your constraints and testing needs.

Fakt works best when:

You've already chosen fakes over mocks. If you understand the state-based testing philosophy and prefer testing outcomes over verifying interactions, Fakt automates what you'd otherwise write by hand.
You only use mocks for convenience. Many developers reach for mocking frameworks not for verify { } features, but simply because writing manual fakes is tedious. Fakt gives you the factory convenience without the mock overhead—generated fakes are plain Kotlin classes.
You're building for Kotlin Multiplatform. Fakt generates plain Kotlin that compiles on JVM, Native, and WebAssembly—no reflection required. This applies to any source set, not just commonTest.
You value exercising production code in tests. Fakt-generated fakes are real implementations your tests compile against, catching interface drift at build time rather than runtime.
Tests run concurrently. Fakt tracks call history with StateFlow, which is thread-safe by design. Manual fakes with var count = 0 break under parallel execution.

Mocking libraries (Mokkery, MockK) work best when:

You need spy behavior. Partial mocking of real implementations—calling real methods while intercepting others—is something only mocking frameworks can do. Fakt generates new implementations, it doesn't wrap existing ones.
You're mocking third-party classes without interfaces. If a library exposes final classes with no interface to program against, mocking frameworks can instrument the bytecode. Fakt requires an interface to annotate.

Neither tool replaces contract testing. For third-party HTTP APIs, use WireMock or Pact. Hand-written fakes for external services drift from reality without contract validation—they create dangerous illusions of fidelity that break in production.

Works Cited

Benchmarking Mockk — Avoid these patterns for fast unit tests. Kevin Block. https://medium.com/@_kevinb/benchmarking-mockk-avoid-these-patterns-for-fast-unit-tests-220fc225da55 ↩
Effective migration to Kotlin on Android. Aris Papadopoulos. https://medium.com/android-news/effective-migration-to-kotlin-on-android-cfb92bfaa49b ↩
Mocking Kotlin classes with Mockito — the fast way. Brais Gabín Moreira. https://medium.com/21buttons-tech/mocking-kotlin-classes-with-mockito-the-fast-way-631824edd5ba ↩
Did someone try to use Mockk on KMM project. Kotlin Slack. https://slack-chats.kotlinlang.org/t/10131532/did-someone-try-to-use-mockk-on-kmm-project ↩
Mock common tests in kotlin using multiplatform. Stack Overflow. https://stackoverflow.com/questions/65491916/mock-common-tests-in-kotlin-using-multiplatform ↩
Mocking in Kotlin Multiplatform: KSP vs Compiler Plugins. Martin Hristev. https://medium.com/@mhristev/mocking-in-kotlin-multiplatform-ksp-vs-compiler-plugins-4424751b83d7 ↩
Mocks Aren't Stubs. Martin Fowler. https://martinfowler.com/articles/mocksArentStubs.html ↩
Unit Testing — Why must you mock me? Craig Walker. https://medium.com/@walkercp/unit-testing-why-must-you-mock-me-69293508dd13 ↩
Testing on the Toilet: Effective Testing. Google Testing Blog. https://testing.googleblog.com/2014/05/testing-on-toilet-effective-testing.html ↩
Testing strategy and how to test. Now in Android Wiki. https://github.com/android/nowinandroid/wiki/Testing-strategy-and-how-to-test ↩
android/nowinandroid: A fully functional Android app built entirely with Kotlin and Jetpack Compose. GitHub. https://github.com/android/nowinandroid ↩
Flow testing with Turbine. Cash App Code Blog. https://code.cash.app/flow-testing-with-turbine ↩

The Hidden Cost of Default Hierarchy Template in Kotlin Multiplatform

Rodrigo Sicarelli — Sun, 02 Nov 2025 18:43:50 +0000

Introduction

The Default Hierarchy Template in KMP projects is a great way to reduce boilerplate code and start working quickly. However, it came with an unexpected cost in our large-scale codebase. A project with 70+ KMP modules targeting Android, iOS, and JVM saw sync times balloon from 15 minutes to over an hour. More critically, an enterprise project with 180+ modules became completely unusable, crashing after 10+ hours of attempting to sync.

This wasn't a misconfiguration or a rogue plugin. The culprit? A single, seemingly innocent line of code introduced with Kotlin 1.9.20:

applyDefaultHierarchyTemplate()

Before we dive into the solution, let's understand what's happening under the hood. What are hierarchy templates, and why does the default one create such a performance bottleneck?

What Are Hierarchy Templates in Kotlin Multiplatform?

At its core, Kotlin Multiplatform is built on a elegant but complex system of source sets—logical collections of code that share common dependencies and compilation settings.

When you create a KMP project, you declare targets (the platforms you're compiling for) and source sets (where your code lives):

kotlin {
    androidTarget()
    jvm()
    iosArm64()
    iosX64()
    iosSimulatorArm64()
}

Each target automatically gets its own source set (androidMain, jvmMain, iosArm64Main), where you can write platform-specific code with access to platform APIs. But the real power of KMP lies in commonMain—code written here is shared across all your targets.

The dependsOn Relationship: Connecting the Dots

Source sets form a hierarchy through the dependsOn relationship. When iosArm64Main depends on commonMain, it can access all the code written in the common source set. This relationship creates a directed graph that determines:

Code visibility - Which declarations are accessible where
Dependency propagation - Libraries added to commonMain flow down to all dependent source sets
API safety - The compiler ensures you only use APIs available on all platforms a source set compiles to

Intermediate Source Sets: The Middle Ground

Here's where it gets interesting. What if you want to share code between some platforms, but not all?

Imagine you have iOS-specific logic that works across all iOS variants (arm64 for devices, x64 for Intel simulators, simulatorArm64 for Apple Silicon simulators). You don't want to duplicate this code in three places, but you also can't put it in commonMain because it uses iOS-specific APIs.

Enter intermediate source sets. An iosMain source set sits between commonMain and your platform-specific iOS source sets, allowing you to:

Access iOS-specific APIs (like Foundation framework)
Share that code across all iOS targets
Keep it separate from Android and JVM code

This hierarchy might look like:

commonMain
├── androidMain
├── jvmMain
└── iosMain (intermediate)
    ├── iosArm64Main
    ├── iosX64Main
    └── iosSimulatorArm64Main

What Hierarchy Templates Do

Manually creating intermediate source sets and wiring up all the dependsOn relationships was tedious and error-prone. You'd write something like:

val iosMain by creating {
    dependsOn(commonMain.get())
}
val iosArm64Main by getting {
    dependsOn(iosMain)
}
// ... repeat for each iOS target

Hierarchy templates automate this boilerplate. They're predefined blueprints that analyze your declared targets and automatically create the appropriate intermediate source sets with the correct dependency relationships.

Starting with Kotlin 1.9.20, the default hierarchy template became active automatically, eliminating the need to manually configure iOS source sets. Sounds great, right?

It is—until it isn't.

The Default Hierarchy Template in Action

To understand the performance problem, we need to see what the default template actually does.

When you call applyDefaultHierarchyTemplate() (or let it apply automatically), the Kotlin Gradle Plugin analyzes your targets and creates intermediate source sets based on a comprehensive, predefined structure designed to support all possible Kotlin Multiplatform targets.

Let's consider a common real-world scenario. Your project targets:

kotlin {
    applyDefaultHierarchyTemplate()

    androidTarget()
    jvm()
    iosArm64()
    iosX64()
    iosSimulatorArm64()
}

You might expect a simple hierarchy:

commonMain
├── androidMain
├── jvmMain
└── iosMain
    ├── iosArm64Main
    ├── iosX64Main
    └── iosSimulatorArm64Main

But here's what the default template actually creates:

commonMain
├── androidMain
├── jvmMain
├── nativeMain (shared by ALL native targets)
    └── appleMain (shared by ALL Apple targets)
        └── iosMain (shared by iOS targets)
            ├── iosArm64Main
            ├── iosX64Main
            └── iosSimulatorArm64Main

Notice the extra layers: nativeMain and appleMain. The template creates these intermediate source sets (and their corresponding src/nativeMain and src/appleMain directories) to enable code sharing in scenarios like:

nativeMain: Share code across all Kotlin/Native targets (iOS, macOS, Linux, Windows Native, watchOS, tvOS, etc.)
appleMain: Share code across all Apple platforms (iOS, macOS, watchOS, tvOS)

The design philosophy is sound. The default template optimizes for the most comprehensive code-sharing scenario. If you later add macosArm64() to your targets, it will automatically slot into the existing hierarchy under appleMain, and any code you've written there will just work.

This is "convention over configuration" at its finest—the template handles the complexity for you.

But here's the critical question: What if you're never going to target macOS, Linux, or tvOS? What if your "native" targets are only iOS?

In an iOS-only project, you likely have no code in nativeMain or appleMain—these directories sit empty in your project structure. Yet they still generate build tasks and configuration overhead.

The Hidden Cost: A Task Explosion

Source sets aren't just a conceptual model—they have real, tangible consequences in your build system. Every source set in your hierarchy triggers the creation of multiple Gradle tasks.

When the Kotlin Gradle Plugin processes your source set hierarchy, it generates tasks for each source set. The pattern is predictable and measurable.

The results were striking:

Optimized template: 158 tasks per module
Default template: 166 tasks per module
Difference: 8 extra tasks per module

Extrapolate to our production codebase with 70 modules, and you're looking at 560 wasteful tasks. In our enterprise codebase with 180+ modules we have "only" 1440 wasteful tasks 🫣.

For every intermediate source set (nativeMain, appleMain), Gradle creates a family of tasks:

compile<SourceSet>KotlinMetadata - Compiles the source set into platform-agnostic Kotlin IR (Intermediate Representation) stored in a .klib file
metadata<SourceSet>Classes - Assembles compilation outputs
metadata<SourceSet>ProcessResources - Processes resources for the source set
transform<SourceSet>DependenciesMetadata - Generates serialized dependency metadata for IDE tooling

Task Deep Dive: The Metadata Compilation Tasks

compileNativeMainKotlinMetadata and compileAppleMainKotlinMetadata are responsible for compiling the (conceptual) nativeMain and appleMain source sets into Kotlin metadata.

Here's the problem: These source sets have no code. The src/nativeMain/kotlin and src/appleMain/kotlin directories exist but sit empty because we're not sharing any code at those levels. Yet the Kotlin compiler still runs, processing an empty source set, generating an (essentially empty) .klib file.

The source sets exist in the dependency graph because the template created them. The iosArm64Main compilation needs to know what APIs are available from appleMain, which needs to know what's available from nativeMain. Even if those source sets are empty, the metadata must be compiled to satisfy the dependency chain.

Think of it like compiling an empty .kt file—the compiler still has to initialize, parse (nothing), run analysis passes, and write output. The overhead isn't zero.

Task Deep Dive: The IDE Transform Tasks

transformNativeMainCInteropDependenciesMetadataForIde and transformAppleMainCInteropDependenciesMetadataForIde are even more insidious.

If you have tests under iosTest you will get an extra transformNativeTestCInteropDependenciesMetadataForIde and transformAppleTestCInteropDependenciesMetadataForIde as well.

These tasks exist specifically for IDE support. When you sync your project in Android Studio or IntelliJ IDEA, these tasks run to process C-interop dependencies (Kotlin/Native bindings to C/Objective-C libraries) and make them understandable to the IDE's code analysis engine.

The irony? Our project has no C-interop dependencies in nativeMain or appleMain because those source sets don't exist in our codebase. We're transforming... nothing.

But the task still runs. It still needs to:

Resolve the dependency graph for the source set
Check for C-interop .klib files
Process (empty) results
Write metadata for the IDE

These tasks created real bottlenecks in our workflow. The 70-module project went from 15-minute syncs to over an hour and twenty minutes. The 180-module project became completely unusable, with syncs crashing consistently after 10+ hours.

After implementing the fix, we couldn't reproduce the exact conditions to capture detailed metrics—Gradle's caching and environmental factors made this difficult. But the aggregate impact was consistent across our entire team, and the theoretical analysis aligned with reality: eliminating 1,440 wasteful tasks restored functionality to the broken project.

The Solution: Custom Optimized Hierarchy

Once we understood the problem, the solution became clear: build exactly the hierarchy we need, no more, no less.

Kotlin provides the applyHierarchyTemplate() DSL for precisely this purpose—defining custom hierarchies that match your project's actual structure.

The Optimized Hierarchy

Instead of the default template's deep, general-purpose hierarchy, we created a minimal, flat structure:

kotlin {
    applyHierarchyTemplate {
        common {
            withAndroidTarget()
            withJvm()
            group("ios") {
                withIosArm64()
                withIosX64()
                withIosSimulatorArm64()
            }
        }
    }

    androidTarget()
    jvm()
    iosArm64()
    iosX64()
    iosSimulatorArm64()
}

This creates the hierarchy:

commonMain
├── androidMain
├── jvmMain
└── iosMain
    ├── iosArm64Main
    ├── iosX64Main
    └── iosSimulatorArm64Main

Notice what's missing: nativeMain and appleMain. We've collapsed the hierarchy to only include the intermediate source sets we actually use.

This configuration change transformed our development experience. The 70-module project saw sync times improve from roughly an hour and twenty minutes to about 14 minutes. The 180-module project went from completely broken to functional. The improvement was universal across our team ✨.

By eliminating unused intermediate source sets, we removed the overhead that had been silently compounding across our codebase.

A Note on Reproducing This Issue

After implementing the fix, I attempted to reproduce the original problem to capture more detailed metrics. Surprisingly, the severe degradation didn't reoccur—likely due to Gradle's aggressive caching and configuration state.

If you're considering this optimization: You may not see dramatic improvements immediately after switching, especially if Gradle has already cached artifacts from your current configuration. The benefits become most apparent on clean syncs or when onboarding new team members. The task count reduction is objective—whether it becomes a bottleneck depends on your specific project context and scale.

When to Use Default vs Custom Hierarchy

The default hierarchy template isn't inherently bad—it's solving for a different use case than ours. Understanding when to use each approach is critical.

If your project genuinely targets macOS, Linux, Windows, iOS, and watchOS, the nativeMain source set becomes valuable. You want to share native-specific code across all these platforms, so the Default Hierarchy is gold here.

On the other hand, if you're starting a new project and not sure if you'll add macOS support in six months, the default template provides a stable foundation that scales as you add targets.

However, if "native" means exclusively iOS in your project, nativeMain and appleMain are dead weight. The task multiplication effect becomes severe at scale, as it adds 8-10 tasks per module.

So, when to use Default Hierarchy Template? Sorry, but "it depends" 🫠.

Conclusion

The default hierarchy template in Kotlin Multiplatform is a powerful tool that embodies the "convention over configuration" philosophy. For many projects, it's the right choice—it simplifies setup, reduces boilerplate, and scales effortlessly as you add targets.

But as our experience demonstrates, the default optimizes for maximum flexibility, not maximum performance. When you know your platform constraints (iOS-only native targets) and operate at scale (70+ modules), that flexibility becomes a liability. You're paying the build-time cost of supporting platforms you'll never target.

The transformation we experienced—from unusable to functional, from frustrating to manageable—came from a simple realization: we don't need a hierarchy designed for the entire Kotlin Multiplatform universe. We need one designed for our project. The applyHierarchyTemplate() DSL gave us the precision to define exactly that, eliminating hundreds of wasteful tasks and restoring our development velocity.

That's it! ✌️ Hope you can apply to our project today and give your day a performance boost!

KMP-102 - Modularização no KMP

Rodrigo Sicarelli — Fri, 07 Mar 2025 14:07:13 +0000

No último artigo, entramos em detalhes e aprendemos sobre as peculiaridades do código exportado nos headers do Objective-C, assim como as boas práticas quanto ao que exportar.

Neste artigo, vamos entender melhor o comportamento da modularização em projetos KMP, e como isso pode ser feito de forma eficiente e organizada.

O que é modularização?
Modularização no KMP
Pavimentando flexibilidade da UI
Exportando para o XCFramework
- Cenário 1: "backend" KMP compartilhado, "frontend" flexível
- Cenário 2: Híbrido, migrando para Compose Multiplatform
- Cenário 3: 100% Compose Multiplatform
Explorando os benefícios da modularização no KMP
Conclusão

O que é modularização?

Não irei me alongar muito neste tópico, pois já abordamos esse assunto no Android Plataforma - Parte 1: Modularização. Se você não tem certeza do que é modularização em projetos Gradle, recomendo uma pausa para a leitura do artigo.

Em resumo, modularização é a prática de dividir um projeto em módulos menores e independentes, que podem ser desenvolvidos, testados e mantidos separadamente.

Essa prática é crucial para escalar projetos KMP, já que a modularização impacta diretamente na autonomia e independência dos times, evitando que um time dependa do outro para realizar suas tarefas.

Modularização no KMP

No KMP, a modularização é feita por meio de módulos compartilhados, que são responsáveis por compartilhar código entre as plataformas.

Vamos elaborar uma estrutura de módulos que respeite a separação de responsabilidades e possibilite a reutilização de código de forma eficiente entre módulos. Nosso contexto aqui considera uma aplicação que irá escalar, no sentido de ter mais features e mais plataformas:

Essa estrutura segue algumas ideias do Domain Driven Design (DDD), em que cada módulo representa um domínio independente e isolado da aplicação. Não irei entrar em muitos detalhes sobre o DDD, mas recomendo a leitura do livro Domain-Driven Design: Tackling Complexity in the Heart of Software para entender melhor sobre o assunto.

Com essa estrutura, conseguimos:

Permitir escalar de forma eficiente sem duplicação de código. Ao criar uma nova feature, basta criar um novo módulo e adicionar as dependências necessárias.
Ter granularidade no que será exportado para as outras plataformas, especialmente para o XCFramework.
Ter independência de domínio para times específicos, evitando conflitos de código e responsabilidades. Por exemplo, times podem criar um CODEOWNER para um módulo específico, e serem responsáveis por manter e evoluir esse módulo.

Pavimentando flexibilidade da UI

Um dos superpoderes do KMP é permitir compartilhar muito ou pouco código. Essa habilidade implica que podemos escolher qual UI iremos utilizar em cada plataforma. Dependendo da sua estratégia de construção de UI, você precisará de uma abordagem específica de módulos para criar essa flexibilidade.

Vamos pensar que cada feature pode ser separada em um "frontend" e "backend". Seguindo o padrão de arquitetura MVVM, o "frontend" seria a nossa UI (Compose, SwiftUI) e o "backend" seria a nossa lógica de negócio (ViewModel/UiModel + Domain + Data). Ou seja, partes da camada de apresentação podem ser compartilhadas, mas damos a liberdade para cada plataforma de escolher a sua UI.

Com isso em mente, uma abordagem que pode ser utilizada é a seguinte:

Aqui, nós separamos cada feature que possui uma tela em 3 módulos:

common, nosso "backend" que contém a lógica de negócio da feature.
android-ui, nosso "frontend" apenas em Android, que contém a UI da feature.
common-ui, nosso "frontend" multiplataforma, que contém a UI da feature compartilhada entre as plataformas.

Com essa abordagem, é possível:

Iniciar migrações de telas em SwiftUI de forma gradual, sem a necessidade de migrar toda a feature de uma vez.
Ter flexibilidade para migrar features Jetpack Compose (apenas Android) enquanto se compartilha o "backend" com outras plataformas.
Ter flexibilidade para iniciar telas em Compose Multiplatform (Android, iOS, Desktop, ...) enquanto se compartilha o "backend" com outras plataformas.

Exportando para o XCFramework

Agora que exploramos um modelo de modularização que permite flexibilidade na escolha da UI, podemos avançar e exportar nosso código Kotlin para o XCFramework.

Para utilizar nosso código Kotlin no iOS, precisamos de um módulo que represente nosso XCFramework. Esse é um módulo "cola", ou seja, um módulo que agrega vários módulos que serão exportados para o XCFramework.

Esse módulo não será utilizado diretamente pelo app Android ou outras plataformas, mas representará nossa exportação para o iOS. Esse módulo é comumente chamado de ios-interop.

Para exemplificar o poder da modularização e a flexibilidade do KMP, vamos explorar alguns cenários de compartilhamento:

Cenário 1: "backend" KMP compartilhado, "frontend" flexível

Neste cenário, temos um módulo common que contém a lógica de negócio da feature. O módulo android-ui contém a UI da feature apenas para Android e é utilizado pelo app Android.

Características desse modelo:

A lógica de negócio é compartilhada entre as plataformas
A UI é específica para Android usando Jetpack Compose
A UI não é compartilhada entre as plataformas
No iOS, a lógica de negócio é utilizada, mas a UI é específica para iOS com SwiftUI
Modelo ideal para projetos que buscam migrar para Compose gradualmente ou que pretendem manter a UI específica por plataforma

Cenário 2: Híbrido, migrando para Compose Multiplatform

Neste cenário, temos um módulo common que contém a lógica de negócio da feature. O módulo common-ui contém a UI da feature compartilhada entre as plataformas.

Aqui, inicia-se a migração para Compose Multiplatform, enquanto mantemos a feature android-ui específica para Android.

Características desse modelo:

Lógica de negócio compartilhada entre as plataformas
Parte da UI compartilhada entre as plataformas
No android-ui, componentes de UI específicos para Android usando Jetpack Compose
No common-ui, componentes de UI compartilhados usando Compose Multiplatform
Modelo ideal para iniciar migração para Compose Multiplatform com migração gradual da UI

Cenário 3: 100% Compose Multiplatform

Neste cenário, temos um módulo common que contém a lógica de negócio da feature. O módulo common-ui contém a UI da feature compartilhada entre as plataformas.

Aqui, não há distinção por plataforma - toda a UI é compartilhada usando Compose Multiplatform.

Características desse modelo:

Lógica de negócio compartilhada entre as plataformas
UI totalmente compartilhada por meio do Compose Multiplatform
Modelo ideal para projetos com UI unificada entre todas as plataformas

Explorando os benefícios da modularização no KMP

Como vocês puderam ver, a modularização no KMP é uma prática essencial para escalar projetos de forma eficiente e organizada.

Mas há um ponto crucial que quero destacar: a modularização ajuda a ter granularidade no que queremos exportar para o XCFramework, mais especificamente, para os headers do Objective-C.

Como vimos no último post, KMP-102 - Otimizando a Exportação do Kotlin para o Obj-c/Swift, ser seletivo com o código que exportamos para os headers do Objective-C está diretamente ligado à eficiência do tempo de build (ou seja, compilações do XCFramework mais eficientes).

Por exemplo:

No Modelo 1, garantimos que apenas o login:common seja exposto nos headers do Objective-C, enquanto evitamos que qualquer parte do android-ui seja exposta.
No Modelo 3, garantimos que nada do "backend" da jornada seja exposto nos headers, apenas o "frontend" multiplataforma.

Essa estratégia é fundamental para a saúde e evolução do repositório, e garante que DEVs KMP possam consumir o XCFramework de forma eficiente e sem conflitos de dependências.

Conclusão

Neste artigo, exploramos a modularização no KMP e como isso pode ser feito de forma eficiente e organizada. Aprendemos como essa prática pode ser utilizada para escalar projetos e obtivemos uma prévia de como isso impacta diretamente na autonomia e independência dos times.

Geralmente, em exemplos KMP básicos, temos apenas um módulo shared. Porém, em cenários reais - onde projetos precisam escalar e adotar estratégias de UI flexíveis - a complexidade é muito maior.

A modularização é uma peça-chave para o sucesso de projetos KMP, e é crucial que seja implementada de forma estruturada e organizada!

No próximo artigo, vamos explorar estratégias de construção do XCFramework em projetos existentes, garantindo autonomia e independência para os times.

Até a próxima!

KMP-102 - Otimizando o Kotlin para o Obj-c/Swift

Rodrigo Sicarelli — Sat, 18 Jan 2025 11:37:03 +0000

No último post, aprendemos como utilizar código Kotlin no Swift.
Aprendemos sobre algumas técnicas para melhorar o codigo exportado para o Swift,
e como as anotações como @HiddenFromObjC e @HidesFromObjC controlam a visibilidade do código no Swift.

Nesse post, vamos aprofundar sobre como essa exportação funciona e o impacto no nosso código gerado.

Como o Kotlin/Native exporta código para o Swift
Recapitulando a exportação de código
- 💡 Resumindo
Como o Kotlin/Native resolve os tipos Kotlin para Objective-C?
Controlando o que é exportado para os Headers
- 🤔 Mas por que eu devo me preocupar com isso?
- Recomendação de paragidma de exportação
- Formas de esconder código Kotlin do Objective-C
  - 1. Utilizando o modificador internal
  - 2. Utilizando as anotações @HiddenFromObjC e @HidesFromObjC
  - 2.1 @HiddenFromObjC
  - 2.2 @HidesFromObjC
Impacto do uso do internal, @HiddenFromObjC e @HidesFromObjC no codebase
Conclusão

Recapitulando a exportação de código

Ao compilar um .framework com o Kotlin/Native, o compilador gera uma série de arquivos, sendo eles:

Headers/KotlinShared.h: Interface gerada pelo KMP que expõe as funções e classes Kotlin para o Objective-C/Swift.
KotlinShared.c (ou sem extensão): Arquivo binário compilado que contém as implementações nativas do código Kotlin, traduzido para LLVM IR.
Outros componentes (como .plist e bundles): Informações adicionais necessárias para o funcionamento do framework no iOS.

💡 Resumindo

KotlinShared.h: é o que está visível para utilizar no Obj-c/Swift
KotlinShared.c: é a compilação interna, que não está exposto.

Como o Kotlin/Native resolve os tipos Kotlin para Objective-C?

Ao compilar código com o Kotlin/Native, o compilador segue uma série de etapas para traduzir tipos e estruturas Kotlin para algo compreensível pelo Objective-C (e, consequentemente, pelo Swift). O resultado dessa tradução é o arquivo KotlinShared.h, que mapeia os tipos Kotlin para seus equivalentes nativos.

Por exemplo, uma String no Kotlin é transformado em NSString, enquanto coleções como List e Map são traduzidas para NSArray e NSDictionary. Além disso, o compilador preserva informações importantes, como nullability, garantindo que valores nullable e non-nullable sejam representados corretamente no Objective-C.

Aqui, a classe Kotlin Person foi mapeada diretamente para uma classe Objective-C, com propriedades como name traduzidas para NSString e parents para NSArray<Person *>.

class Person(
    val name: String,
    val age: Int,
    val parents: List<Person>
)

#import <Foundation/Foundation.h>

NS_SWIFT_NAME(Person)
@interface Person : NSObject

@property (readonly) NSString * _Nonnull name;
@property (readonly) NSInteger age;
@property (readonly) NSArray<Person *> * _Nonnull parents;

- (instancetype _Nonnull)initWithName:(NSString * _Nonnull)name 
                                  age:(NSInteger)age 
                              parents:(NSArray<Person *> * _Nonnull)parents;

@end

Controlando o que é exportado para os Headers

Esse conceito é crucial, especialmente se você busca escalar o KMP no seu projeto.

Por padrão, tudo que é público no Kotlin é exportado para o Objective-C, o que não é ideal em projetos grandes. À medida que o código cresce, o arquivo KotlinShared.h pode se tornar extenso, impactando o desempenho da compilação e dificultando a manutenção.

🤔 Mas por que eu devo me preocupar com isso?

A medida que seu projeto cresce, você terá mais e mais código Kotlin sendo processado e exportado para os Headers.

Isso pode (e vai) resultar em um arquivo KotlinShared.h gigante, com centenas de linhas de código.

Com um KotlinShared.h grande, a compilação do seu XCFramework irá ficar mais lenta, pois o compilador precisa processar todas as declarações do Kotlin para gerar os Headers.

Além disso, um KotlinShared.h grande pode resultar em mais erros de compilação no Xcode, pois o compilador do Swift precisa processar todas as declarações do Kotlin para gerar o binário final.

Por último, a experiência de desenvolvimento é deteriodada, já que toda vez que você precisa checar o KotlinShared.h no Xcode, você terá que lidar com um arquivo gigante e difícil de navegar, além de uma demora maior para abrir o arquivo no Xcode.

💡 Resumindo

Se seu time quer escalar o KMP, é importante controlar o que é exportado para o Objective-C.
Isso garante que o KotlinShared.h seja enxuto e fácil de navegar, acelerando a compilação do XCFramework e melhorando a experiência de desenvolvimento (vamos nos aprofundar nisso em um post futuro).
É extremamente recomendado que seu time propague a cultura de controlar o que é exportado para o Objective-C desde o começo, para evitar problemas de escalabilidade no futuro.
Esconder código Kotlin do Objective-C é considerada boa prática. O famoso "combinado não sai caro" se aplica muito bem aqui 😅.

Recomendação de paragidma de exportação

Aqui temos muito o que aprender com bibliotecas open source. Ao consumir uma biblioteca open source, é comum você ter acesso apenas a uma interface bem definida, com poucos detalhes de implementação.

Isso ajuda a gente (que consome a biblioteca) a entender o que a biblioteca faz, sem precisar entender como ela faz. Isso é o que chamamos de encapsulamento. Além do mais, a experiência na IDE é elevada, já que o auto-complete e a navegação entre arquivos é mais rápida e precisa.

Com isso em mente, a recomendação é esconder o máximo possível do código Kotlin do Objective-C. Isso significa que você deve exportar apenas o que é necessário para o Swift consumir, e esconder o resto.

A mentalidade é a seguinte:

✅ Esconder por padrão.

⚠️ Expor apenas o necessário.

Formas de esconder código Kotlin do Objective-C

Existem 3 formas de esconder código Kotlin do Objective-C:

1. Utilizando o modificador `internal`

Essa abordargem é a mais recomendada, pois gera um impacto positivo no seu código Kotlin consumido em outros source sets (Android, Desktop, Common, etc).

Por padrão, o modificador internal faz com que a declaração seja visível apenas no módulo em que foi declarada. Isso significa que o código Kotlin marcado como internal não será exportado para o Objective-C.

internal data class Person(
    val name: String,
    val age: Int,
    val parents: List<Person>
)

2. Utilizando as anotações `@HiddenFromObjC` e `@HidesFromObjC`

As anotações @HiddenFromObjC e @HidesFromObjC são específicas do Kotlin/Native e têm como objetivo controlar a visibilidade de métodos, propriedades ou classes na interoperabilidade com Objective-C/Swift. Elas influenciam como os elementos Kotlin são expostos ao framework gerado pelo Kotlin/Native para uso em projetos iOS.

2.1 @HiddenFromObjC

Essa anotação é usada para ocultar completamente um elemento Kotlin da API exposta para Objective-C/Swift. Qualquer método, propriedade ou classe anotada com @HiddenFromObjC não será gerado no framework resultante e, portanto, não será visível em projetos Swift/Objective-C.

@HiddenFromObjC
fun internalUtilityFunction() {
    // Esta função não será exposta para Objective-C/Swift
}
@HiddenFromObjC
class InternalHelper {
    fun doSomething() {
        // Esta classe inteira será invisível no framework gerado
    }
}

2.2 @HidesFromObjC

É uma meta-anotação, ou seja, ela é usada para marcar outras anotações que serão aplicadas a elementos do código Kotlin.

Quando uma anotação é marcada com @HidesFromObjC, qualquer elemento que for anotado com essa anotação será automaticamente removido da API Objective-C pública gerada.

@HidesFromObjC permite uma maior flexibilidade, já que você pode criar suas próprias anotações com essa funcionalidade.

Exemplos de uso incluem criar anotações personalizadas que escondem partes do código da API Objective-C, enquanto ainda permitem que o elemento permaneça disponível no Kotlin.

Aqui, a anotação personalizada @InternalUseOnly utiliza @HidesFromObjC, o que automaticamente remove qualquer função ou classe anotada com ela da API Objective-C.

@HidesFromObjC
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
annotation class InternalUseOnly

@InternalUseOnly
fun internalFunction() {
    println("Esta função não será exposta ao Objective-C")
}

Impacto do uso do `internal`, `@HiddenFromObjC` e `@HidesFromObjC` no codebase

Ao controlar o que é exportado:
• Você reduz a superfície da API pública, evitando confusões e erros.
• O tamanho do framework gerado diminui, melhorando o desempenho do build.
• A segurança aumenta, já que classes ou métodos internos não ficam acessíveis no iOS.
• A manutenção se torna mais simples, com uma API mais limpa e focada.

Conclusão

Controlar o que é exportado para o Objective-C é uma prática essencial para manter a qualidade e a escalabilidade do seu projeto KMP.

Ao esconder código Kotlin do Objective-C, você garante que apenas o necessário é exposto para o Swift, mantendo a API enxuta e fácil de navegar.

Além disso, você evita problemas de performance, segurança e manutenção, garantindo que seu projeto KMP seja escalável e fácil de manter.

👍 É de suma importância que você e seu time adotem essa prática desde o início do projeto, para evitar problemas de escalabilidade no futuro.

Com esse conceito bem fixado, podemos avançar no próximo post onde iremos explorar uma estratégia que irá desbloquear a escala do KMP no seu projeto (spoiler: utilizando .klibs).

Nos vemos na próxima ✌️

KMP-102 - Utilizando Código Kotlin no Swift

Rodrigo Sicarelli — Fri, 11 Oct 2024 11:20:34 +0000

No último post, aprendemos a criar um XCFramework a partir de código Kotlin e exploramos algumas características dos tipos de build gerados.

Com isso, podemos avançar e aprender como o código Kotlin compilado para Objective-C funciona e como consumi-lo no iOS.

Exportando um 'Olá mundo' em Kotlin para iOS
- O que está acontecendo aqui?
Compreendendo o código gerado pelo Kotlin/Native
Melhorando a interoperabilidade com Swift
- E a anotação @HiddenFromObjC?
Outras maneiras de melhorar a interoperabilidade
- Utilizando o SKIE para melhorar a interoperabilidade
- Considerações sobre o SKIE
  - Reduzindo o tempo de build do SKIE utilizando anotações
Conclusões finais

Exportando um 'Olá mundo' em Kotlin para iOS

Para começar, vamos entender alguns pontos importantes sobre como o código Kotlin é convertido para Objective-C e, consequentemente, como utilizá-lo no iOS.

Vamos criar um simples HelloWorld em Kotlin:

//HelloWorld.kt commonMain
expect fun helloWorld(): String

//HelloWorld.apple.kt appleMain
actual fun helloWorld(): String = "Olá mundo Apple Main"

Agora precisamos compilar um XCFramework e integra-lo no Xcode. Existem diversos tutoriais na internet sobre como realizar essa tarefa; para esta demonstração, segui o guia "How to Integrate Kotlin Multiplatform (KMP) into Your iOS Project".

Os passos básicos são:

Compilar o XCFramework com ./gradlew assembleKotlinSharedXCFramework. NOTA: substitua "KotlinShared" pelo nome do seu XCFramework. Explicamos isso nos artigos anteriores.
Configurar o projeto Xcode para consumir o XCFramework gerado.
Utilizar o código Kotlin no iOS.

Depois que toda a configuração for realizada, conseguimos avançar e criar uma tela bem simples em SwiftUI para consumir o código Kotlin:

import SwiftUI
import KotlinShared

struct ContentView: View {
    @State private var showText = false

    var body: some View {
        Button("Show Text") { showText.toggle() }
        if showText { Text(HelloWorld_appleKt.helloWorld()) }
    }
}

Como resultado, teremos:

O que está acontecendo aqui?

Vamos entender o que está acontecendo nos bastidores:

O código Kotlin é compilado para Objective-C e empacotado em um XCFramework.
O XCFramework é integrado no projeto Xcode.
Com o XCFramework integrado, podemos importar o código Kotlin no iOS usando import KotlinShared.
Dentro de KotlinShared (o nome do XCFramework), temos acesso ao código Kotlin compilado para Objective-C.
A classe HelloWorld_appleKt é gerada automaticamente pelo Kotlin/Native, permitindo o acesso ao método helloWorld().
Assim, podemos utilizar o código Kotlin no iOS!

import KotlinShared

let helloWorld = HelloWorld_appleKt.helloWorld()

Mas se notarmos, a sintaxe para acessar o código Kotlin no iOS é bem estranha. HelloWorld_appleKt.helloWorld() é uma sintaxe nada idiomática para o Swift.

Vamos entender melhor esse ponto.

Compreendendo o código gerado pelo Kotlin/Native

A maior limitação hoje no Kotlin/Native é a interoperabilidade com Objective-C. O Kotlin/Native não consegue gerar um código que seja 100% compatível com o Swift.

Isso porque o Kotlin/Native é um compilador que gera código Objective-C, e não Swift. O código gerado é compatível com Objective-C, e não Swift.

Ou seja, temos várias funcionalidades em Kotlin traduzidas diretamente para Swift (como high order functions, enums, etc), mas não temos uma tradução direta de Kotlin --> Objective-c.

Para investigar como o código Kotlin é traduzido para Objective-C, podemos acessar o código gerado pelo Kotlin/Native. Para isso, basta dar um cmd + click na nossa classe HelloWorld_appleKt:

Para melhorar a experiência de uso do código Kotlin no iOS, podemos codificar nosso código Kotlin de uma forma diferente, para ser mais idiomático ao Swift.

Melhorando a interoperabilidade com Swift

Observamos que não podemos simplesmente escrever código Kotlin e esperar que ele seja idiomático ao Swift devida a característica do Kotlin/Native somente gerar código Objective-C.

Para isso, temos que escrever nosso código Kotlin de uma forma que seja mais amigável ao Swift. Vamos refatorar o código HelloWorld para ser mais idiomático ao Swift:

// HelloWorld.apple.kt appleMain
package br.com.rsicarelli.example

@HiddenFromObjC
actual fun helloWorld(): String = "Olá mundo Apple Main"

object HelloWorld

fun HelloWorld.get(): String = helloWorld()

Agora, realizamos o mesmo passo a passo para utilizar no Xcode:

Compilar o XCFramework com ./gradlew assembleKotlinSharedXCFramework.
No Xcode, Products > Build for ... > Running, ou simplesmente cmd + shift + r

Logo após o build, notamos que a nossa classe anterior HelloWorld_appleKt não está mais disponível.

Antes de entender o porquê, vamos integrar nosso código KMP utilizando a nova abordagem:

import KotlinShared

struct ContentView: View {
    @State private var showText = false

    var body: some View {
        Button("Show Text") { showText.toggle() }
        if showText { Text(HelloWorld.shared.get()) }
    }
}

Sucesso! Esse código é mais idiomático ao Swift, e conseguimos utilizar o código Kotlin no iOS de uma forma mais amigável.

Se abrirmos o código Objective-C gerado pelo Kotlin/Native, notamos algumas diferenças:

Interessante observar que, agora, nossa classe HelloWorld é gerada como um Singleton, e o método get é gerado como uma extensão!

E a anotação `@HiddenFromObjC`?

A anotação @HiddenFromObjC é uma anotação do Kotlin/Native que indica que o método não deve ser exposto para Objective-C. Isso é útil para métodos que não devem ser acessados diretamente pelo Objective-C, como funções de extensão.

A lógica do uso dessa anotação nesse contexto é a seguinte: temos duas formas de acessar o método helloWorld():

Através da função de alto nível (high order function no Kotlin)
Através da extensão do objeto HelloWorld

Nesse caso, expormos as duas maneiras para o Objective-C não faz sentido, pois a função de alto nível apenas delegar para a extensão do objeto HelloWorld. Isso pode ser confuso para quem está consumindo o código Kotlin no iOS.

Para isso, utilizamos a anotação @HiddenFromObjC para esconder a função de alto nível do Objective-C, e expor apenas a extensão do objeto HelloWorld!

Notas importantes:

A anotação @HiddenFromObjC é uma anotação do Kotlin/Native, ou seja, não podemos utilizar em nenhum outro source set do KMP.
A anotação @HiddenFromObjC pode ser utilizada para funções, classes, atributos, etc.

Uma documentação completa entre a interoperabilidade entre Kotlin e Objective-C pode ser encontrada aqui Interoperability with Swift/Objective-C.

Outras maneiras de melhorar a interoperabilidade

Essa abordagem já funciona muito bem, porém, pode ser bem tedioso ter que criar uma extensão para cada função que queremos expor para o iOS.

No final, o que queremos é ter um código Kotlin que seja idiomático ao Swift, mas, ao mesmo tempo, codando Kotlin com todo seu potencial.

Para isso, temos três opções:

Utilizar o plugin SKIE (Swift Kotlin Interface Enhancer)
Atualizar para o Kotlin 2.1 e utilizar o novo sistema de interoperabilidade entre Kotlin --> Swift.
Manualmente exportar extensions para cada acesso que queremos utilizar para o iOS, utilizando Swift.

A primeira opção é a mais robusta e a mais recomendada, já que o SKIE possuí uma série de funcionalidades que facilitam a interoperabilidade entre Kotlin e Swift.

A segunda opção, exportar código Swift utilizando Kotlin 2.1, continua em fase experimental, e não é recomendada para produção.

A terceira forma é bem manual e pode ser bem tediosa, mas é uma opção válida para quem não quer utilizar o SKIE. Como DEVs KMP, queremos escrever menos código possível, então é uma abordagem custosa de se escalar.

Para esse artigo, vamos utilizar o SKIE para melhorar a interoperabilidade entre Kotlin e Swift!

Utilizando o SKIE para melhorar a interoperabilidade

Integrar o SKIE em um módulo KMP é bem tranquilo e o projeto fornece uma documentação detalhada sobre a integração, SKIE > Installation

Mas de forma resumida:

Aplicar o plugin co.touchlab.skie no build.gradle.kts do projeto KMP
O plugin deve ser aplicado apenas no módulo que gera o XCFramework.

Basicamente é isso, aplicar o plugin e sincronizar.

Agora, vamos retornar a nossa abordagem anterior e apenas exportar a função helloWorld() (sem a anotação @HiddenFromObjC):

// HelloWorld.apple.kt appleMain

actual fun helloWorld(): String = "Olá mundo Apple Main"

Seguimos o passo a passo para utilizar no Xcode:

Compilar o XCFramework com ./gradlew assembleKotlinSharedXCFramework.
Aqui na minha máquina eu precisei de um clean build no Xcode, então Products > Clean Build Folder
No Xcode, Products > Build for ... > Running, ou simplesmente cmd + shift + r

Agora, podemos utilizar o código Kotlin no iOS de uma forma mais idiomática ao Swift:

import SwiftUI
import KotlinShared

struct ContentView: View {
    @State private var showText = false

    var body: some View {
        Button("Show Text") { showText.toggle() }
        if showText { Text(helloWorld()) }
    }
}

Analisando a função helloWorld(), observamos que o SKIE gera uma função global que é acessível diretamente no Swift. Essa função global acessa a função helloWorld() do Kotlin (na forma "feia"), e a expõe para o Swift.

Muito melhor hein? Agora, conseguimos utilizar o código Kotlin no iOS de uma forma idiomática ao Swift!

Considerações sobre o SKIE

O SKIE é extremamente poderoso e facilita muito a interoperabilidade entre Kotlin e Swift.

Porém, é importante lembrar que o SKIE é um plugin experimental, e está sujeito a mudança e depreciações.

Além disso, como é adicionado uma camada extra de conversão, a construção do XCFramework é deteriorada, e o tempo de build pode aumentar consideravelmente.

Isso porque o SKIE percorre todo o código Kotlin e cria seu par em Swift, o que pode ser um processo bem custoso. O SKIE fará isso não só com seu código Kotlin, mas também com todas as dependências que você exporta como "api" para o KotlinShared.

Reduzindo o tempo de build do SKIE utilizando anotações

Uma funcionalidade muito legal do SKIE é possibilidade de escolher quais funcionalidades do SKIE você quer utilizar.

Para isso, o SKIE fornece uma série de anotações que permitem customizar a exportação de código Kotlin para Swift. Isso nos possibilita escolher a dedo qual código queremos exportar para o Swift, e reduzir o tempo de build do SKIE.

Conclusões finais

Com esse artigo, conseguimos entender como utilizar código Kotlin no Swift, suas características e limitações, e como melhorar a interoperabilidade entre Kotlin e Swift com uma escrita alternativa de código Kotlin ou utilizando o SKIE.

O KMP é craque em exportar código Objective-C, mas estamos atualmente limitados na exportação de código Swift. Com o SKIE, conseguimos melhorar essa limitação e exportar código Kotlin de uma forma mais idiomática ao Swift. E, as próximas versões do Kotlin, a interoperabilidade entre Kotlin e Swift será ainda mais robusta e nativa.

Espero que tenham gostado do artigo! 🚀

Até a próxima 🤙

KMP-102 - Características do XCFramework no KMP

Rodrigo Sicarelli — Sun, 21 Jul 2024 11:17:30 +0000

No post anterior, aprendemos sobre como o Kotlin/Native exporta uma coleção de .frameworks no formato XCFramework.

Agora, vamos entender as características desse XCFramework.

Como utilizar um XCFramework no iOS

O pacote XCFramework irá oferecer um .framework para cada Kotlin Native target. Lá dentro, alvos como o device físico (iosArm64), simulador (iosSimulatorArm64) e simuladores para processadores intel (iosX64) estarão presentes.

Consumir um .framework varia conforme o ambiente e o codebase existente, mas de forma geral, basta criar um build phase no projeto Xcode para conseguir utilizar o import das classes exportadas pelo Kotlin/Native.

Existem diversas formas que podemos utilizar para importar no projeto.

Todos esses modelos possuem características importantes a serem exploradas.

Entendendo como o XCFramework é gerado

No KMP, o .framework é do tipo "Fat". Isso significa que ele inclui não apenas seu código, mas também todas as dependências necessárias. Isso difere de outros tipos, que podem incluir menos conteúdo:

Skinny: Contém apenas o seu código, sem nenhuma dependência externa.
Thin: Inclui seu código e suas dependências diretas.
Hollow: O oposto do Thin, contendo apenas as dependências, sem seu código.
Fat: Inclui tudo: seu código, dependências diretas e tudo o necessário para funcionar de forma independente.

Essa abordagem "Fat" tem implicações importantes para a modularização e o gerenciamento de dependências, como discutiremos a seguir.

A natureza "Fat" dos frameworks no KMP cria um desafio técnico para modularizar nossas distribuições. Isso ocorre porque todas as dependências são empacotadas juntas, forçando-nos a consolidar todo o código do KMP em uma única exportação. Esse modelo pode levar a duplicações de dependências e aumento do tamanho do pacote final, complicando a gestão do projeto, especialmente em ambientes de desenvolvimento colaborativos.

Contexto sobre aplicações Kotlin

Projetos Kotlin possuem uma natureza multi modular para reutilização de cache e desempenho de build. Modularizar projetos influenciam positivamente a experiência de desenvolvimento em projetos Kotlin que utilizam o Gradle.

Nesse artigo eu exploro um pouco mais sobre modularização em projetos Android, que também se aplicam para projetos KMP.

Projetos Kotlin costumam a ter múltiplos módulos como:

- legado
- core/design-system
- core/logging
- core/analytics
- feature1
- feature2

Esses módulos podem ser utilizados individualmente em projetos Kotlin, mas isso não significa que podemos ter um .framework para correspondente.

Quer dizer, até podemos, porém, tem uma característica a ser observada.

Considere que a feature1 e feature2 utilizam as seguintes dependências em KMP:

// feature1
kotlinx-serialization
kotlinx-coroutines

// feature2
kotlinx-serialization
kotlinx-coroutines

Ao exportar o XCFramework, as dependencias do kotlinx-serialization e kotlinx-coroutines estariam duplicadas em cada .framework, causando:

Aumento do pacote final (.ipa);
Aumento de tempo de build, considerando uma escala de módulos.

Isso acontece por uma característica imposta pelo .framework no iOS: um .framework não consegue se comunicar com o outro.

Em um cenário ideal, o kotlinx-serialization seria um .framework isolado e nosso .framework se comunicasse com esse .framework.

Então, esse modelo "fat" se torna uma característica adotada em projetos KMP, como uma forma de otimização do uso e redução do tamanho final do aplicativo.

Com isso, vamos avançar e entender melhor quais desafios esse modelo impõe.

Utilizando um "fat" KMP no iOS

Consideremos um cenário onde temos um projeto iOS existente e desejamos integrar código KMP. Para ilustrar, vamos supor que fizemos uma alteração em um módulo, como adicionar um novo parâmetro a uma função. Esta mudança, embora pareça simples, pode quebrar o código no iOS, pois o projeto iOS espera a versão anterior da função. Aqui está um exemplo passo a passo:

Primeiro, vamos assumir o seguinte build.gradle.kts:

kotlin {
    val xcFramework = XCFramework(xcFrameworkName = "KotlinShared")

    val exportedDependencies = listOf(feature1, feature2, core)

    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64()
    ).forEach { iosTarget ->
        iosTarget.binaries.framework {
            baseName = "KotlinShared"

            exportedDependencies.forEach { dependency ->
                export(dependency.get())
            }

            xcFramework.add(this)
        }
    }
}

Ao executar a task assembleKotlinSharedXCFramework, teremos um pacotão com todos os módulos exportados.

Para projetos KMP, é essencial ter um módulo central, muitas vezes chamado de ios-interop. Esse módulo funciona como um ponto de integração que agrupa e exporta todas as dependências necessárias para serem usadas no Xcode. Esse método centraliza a gestão das dependências e facilita a manutenção e atualização do projeto.

Desafios para modularizar o KMP

Como discutimos anteriormente, a natureza "fat" dos frameworks XCFramework no KMP implica que cada módulo exportado inclui todas as suas dependências. Isso resulta em duplicação de dependências comuns entre módulos e um aumento geral no tamanho do pacote final. Além disso, essa abordagem gera desafios significativos na modularização, que são especialmente evidentes em projetos que integram o SwiftUI como interface de usuário no iOS. Vejamos esses desafios mais detalhadamente.

Vamos assumir que a feature1 e feature2 expõem as seguintes classes Kotlin a serem consumidas no iOS:

class Feature1ViewModel(
    val repository: Feature1Repository
) {
    fun fetch() = Unit
}

class Feature2ViewModel(
    val repository: Feature2Repository
) {
    fun fetch() = Unit
}

Ao exportar o XCFramework, todas as classes de feature1 e feature2 estarão presentes no .framework, ou seja, conseguimos utilizar ambas Feature1ViewModel e Feature2ViewModel no iOS:

import KotlinShared

class Feature1ViewModelWrapper {
    private let viewModel: KotlinSharedFeature1ViewModel

    init(repository: Feature1Repository) {
        self.viewModel = KotlinSharedFeature1ViewModel(repository: repository)
    }

    func fetch() {
        viewModel.fetch()
    }
}

class Feature2ViewModelWrapper {
    private let viewModel: KotlinSharedFeature2ViewModel

    init(repository: Feature2Repository) {
        self.viewModel = KotlinSharedFeature2ViewModel(repository: repository)
    }

    func fetch() {
        viewModel.fetch()
    }
}

Até aqui, tudo certo. Nosso código KMP foi integrado no iOS com sucesso e vamos assumir que esse código já está até em produção. Agora, vamos adicionar um novo parâmetro no Feature1ViewModel:

class Feature1ViewModel(
    val repository: Feature1Repository,
    val repository2: Feature1Repository2
) {
    fun fetch() = Unit
    fun fetchRepository2() = Unit
}

Ao exportar o XCFramework, o código no iOS irá quebrar, pois a classe Feature1ViewModelWrapper não possui o novo parâmetro repository2:

class Feature1ViewModelWrapper {
    private let viewModel: KotlinSharedFeature1ViewModel

    init(repository: Feature1Repository) {
        //irá quebrar, `repository2` não está sendo enviado
        self.viewModel = KotlinSharedFeature1ViewModel(repository: repository) 
    }
}

Agora, vamos assumir que esse XCFramework já foi gerado e exportado, porém, ainda não foi integrado no repositório do iOS. O time responsável pela feature2 precisa de uma nova funcionalidade e também precisa realizar uma alteração na Feature2ViewModel:

class Feature2ViewModel(
    val repository: Feature2Repository,
    val repository2: Feature2Repository2,
) {
    fun fetch() = Unit
}

Ao exportar o XCFramework, o código no iOS irá quebrar, pelo mesmo motivo acima, já que a classe Feature2ViewModelWrapper não possui o novo parâmetro repository2:

class Feature2ViewModelWrapper {
    private let viewModel: KotlinSharedFeature2ViewModel

    init(repository: Feature2Repository) {
        self.viewModel = KotlinSharedFeature2ViewModel(repository: repository) //irá quebrar, `repository2` não foi passado como parametro
    }

    func fetch() {
        viewModel.fetch()
    }
}

Agregando esse cenário acima, temos a seguinte linha do tempo:

Feature1ViewModel e Feature2ViewModel são integradas ao projeto iOS.
Feature1ViewModel é atualizada para incluir um novo parâmetro, causando uma quebra no iOS.
Após o merge das alterações, uma nova versão do XCFramework é gerada e publicada através de ferramentas como Swift Package Manager, CocoaPods, controle de versão, etc.
Essa versão, contendo as mudanças em Feature1ViewModel, resulta em quebras no iOS.
Antes que essa versão seja integrada ao projeto iOS (corrigindo a quebra), o time de feature2 realiza alterações no Feature2ViewModel.
Uma versão subsequente do XCFramework é gerada e publicada, incluindo as novas alterações em Feature2ViewModel que também resultam em quebras no iOS.

Neste cenário complexo:

O time responsável por feature2 precisa esperar que o time de feature1 corrija as quebras no iOS antes de poder integrar a correção da feature2. Este processo pode criar um ciclo de espera e correção que retarda a entrega de novas funcionalidades.

Para resumir e simplificar a compreensão:

A versão 1.0.0 do XCFramework, já integrada no iOS, funciona sem problemas.
A versão 1.1.0 introduz uma mudança significativa (breaking change) em feature1, causando problemas.
A versão 1.2.0 traz uma mudança significativa em feature2.
A versão 1.2.0 só pode ser integrada ao iOS depois que as correções de feature1 na versão 1.1.0 forem integradas e validadas.

Dores do desenvolvimento KMP

Integrar código KMP em projetos iOS existentes, especialmente aqueles desenvolvidos com SwiftUI, apresenta desafios únicos devido à necessidade de uma comunicação direta entre módulos. Este desafio é menos intenso em projetos que utilizam Compose Multiplatform (CMP), onde a comunicação entre módulos ocorre de forma mais indireta e desacoplada.

O modelo "fat" de frameworks impõe várias complicações no desenvolvimento com KMP, entre elas:

Gestão de Dependências: É necessário seguir uma linha do tempo específica para incorporar mudanças no código KMP ao repositório iOS, garantindo que todas as dependências estejam sincronizadas.
Sensibilidade a Mudanças: Qualquer alteração em atributos, parâmetros ou funções pode resultar em quebras no projeto iOS, exigindo correções imediatas para manter a estabilidade do projeto.
Dependência entre times: Devs frequentemente precisam esperar que outras times corrijam quebras no iOS antes de poderem avançar com a integração de novas funcionalidades do KMP.

Impacto no ciclo de desenvolvimento diário

No dia a dia, esses desafios tornam-se ainda mais evidentes. Por exemplo, ao integrar novas funcionalidades na branch principal (main) do projeto KMP — geralmente associada ao desenvolvimento Android — e tentar testá-las no iOS, frequentemente nos deparamos com quebras devido a mudanças que ainda não foram integradas ao projeto iOS.

Para mitigar esse problema, geralmente geramos um XCFramework localmente para testes no iOS. No entanto, essa abordagem ainda sofre com o risco de quebras se a branch main contiver alterações não sincronizadas com o iOS, criando um ciclo contínuo de identificação e correção de quebras, o que atrasa significativamente o desenvolvimento.

Isso gera um gargalo enorme no dia a dia, pois temos um desafio enorme de identificar qual time responsável pela quebra e, consequentemente, aguardar a correção para então integrar o código KMP no iOS.

Em times pequenos ou projetos pessoais isso não é um problema, mas isso em escala é definitivamente o maior gargalo do desenvolvimento KMP atualmente.

Como contornar esse problema

Melhoria na Comunicação: Reforçar a comunicação entre as times de desenvolvimento para planejar e sincronizar mudanças pode reduzir a frequência de quebras inesperadas.
Automação de Testes: Implementar testes automatizados e processos de integração contínua para detectar e corrigir quebras antes que elas impactem outros desenvolvedores ou o projeto principal.

Existe uma estratégia que podemos adotar, porém, ficará para um artigo futuro. Primeiro, precisamos subir a escadinha de conhecimento em KMP em outros conceitos para conseguirmos compreender melhor essa estratégia alternativa.

Conclusão

É importante sermos realistas e encararmos os problemas reais de uma tecnologia. Às vezes, no calor do "boom" de uma nova tecnologia, deixamos passar alguns aspectos cruciais para escalarmos uma solução, e se não tratarmos esses problemas, podemos ter (teremos!) um gargalo enorme no desenvolvimento. Isso pode gerar um barulho interno no seu time, como pessoas não adotando a tecnologia devido a má experiência de desenvolvimento, e constantes quebras no código causados por outros times em outros contextos.

Entender a natureza do XCFramework é crucial para termos um projeto escalável e saudável, com uma experiência de desenvolvimento de ponta a ponta sem gargalos.

Nos próximos artigos, vamos entender melhor sobre o código que que é exportado para o iOS, algumas características e limitações do código Kotlin > Objective-C e Objective-C > Swift, como escrever nosso código Kotlin para ser idiomático em Swift, e algumas abordagens para melhorarmos a integração Kotlin <--> Swift.

Nos vemos na próxima, tchau!

Referências

https://dzone.com/articles/the-skinny-on-fat-thin-hollow-and-uber

KMP-102 - XCFramework para Devs KMP

Rodrigo Sicarelli — Wed, 29 May 2024 11:30:23 +0000

KMP102 - XCFramework para Devs Kotlin Multiplataforma

Olá! Dou as boas-vindas a série KMP-102. Vamos aprofundar os conceitos do Kotlin Multiplatform, aprendendo mais sobre como integrar nosso código Kotlin no iOS e em outras plataformas.

Como início desta série, vamos aprender mais sobre um formato de arquivo especial para compartilhar código com a família Apple: o XCFramework.

Introdução ao `.framework` da Apple

Um framework é um pacote que contém um conjunto de recursos e código-fonte destinados a serem utilizados em projetos para a família Apple. No mundo da JVM, isso é equivalente a um .jar ou, no caso do Android, a um .aar.

Trata-se de um formato pré-compilado que pode ser utilizado livremente entre projetos no Xcode. Esse formato de arquivo facilita a criação de bibliotecas para dispositivos Apple, permitindo sua distribuição e utilização por meio de gerenciadores de pacotes, como CocoaPods ou o Swift Package Manager.

Introdução ao XCFramework

O XCFramework é um tipo de pacote ou artefato que facilita a distribuição de bibliotecas para a família Apple. Basicamente, ao invés de distribuirmos vários .frameworks para cada plataforma, temos um único .xcframework contendo múltiplos .frameworks, cada um representando uma plataforma específica suportada pela biblioteca.

O Kotlin Multiplataforma, mais especificamente o Kotlin/Native, utiliza este artefato para pré-compilar código Kotlin para Objective-C, garantindo total interoperabilidade com Swift. Com isso, nosso código Kotlin é facilmente compartilhado entre todos os alvos suportados do projeto, simplificando significativamente o processo de desenvolvimento: ao invés de compilar vários .frameworks para cada alvo suportado no KMP, compilamos apenas um .xcframework para cada alvo ou arquitetura de processador.

Gerando um XCFramework no KMP

Por trás dos panos, o KGP (Kotlin Gradle Plugin) utiliza a toolchain do Xcode e nos oferece uma API que possibilita a criação de um XCFramework através dos nossos arquivos build.gradle.kts:

kotlin {
    val xcFramework = XCFramework(xcFrameworkName = "KotlinShared")

    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64()
    ).forEach { iosTarget ->
        iosTarget.binaries.framework {
            baseName = "KotlinShared"
            isStatic = true

            xcFramework.add(this)
        }
    }
}

Ao sincronizar o projeto, observamos que a task assembleKotlinSharedXCFramework foi registrada no nosso projeto. Observe que a task tem o miolo KotlinShared, que corresponde com o parâmetro xcFrameworkName da classe XCFramework:

Analisando o resultado da tarefa assemble...XCFramework

Ao executarmos a task assembleKotlinSharedXCFramework, o Kotlin/Native gera os .xcframeworks para todos os alvos que definimos no build.gradle.kts.

Este artefato é exatamente o arquivo que precisamos vincular ao projeto Xcode para consumir nosso código KMP compilado para Objective-C!

Nota: Tenha cuidado com o nome do projeto! Caracteres especiais, como "-", podem resultar em erro, apesar de o XCFramework ser gerado.

NativeBuildTypes: debug e release

Observe que temos dois frameworks gerados: a versão debug e a versão release. Esses dois tipos possuem características especiais, provenientes da classe NativeBinaryType:

Analisando esse enum, entendemos que a versão release possui a flag optimized = true e debuggable = false, enquanto a versão debug possui optimized = false e debuggable = true.

Como você pode imaginar, devemos ter cuidado ao escolher qual XCFramework utilizar no fluxo de desenvolvimento:

Para o ambiente de desenvolvimento local, a versão debug é a escolha ideal, pois permite debugar nosso código KMP.
Para o ambiente de produção, a versão release é a escolha correta, pois o binário é otimizado e evita a inclusão de informações de debug no produto final.

// kotlin/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/NativeBinaryTypes.kt

enum class NativeBuildType(
    val optimized: Boolean,
    val debuggable: Boolean
) : Named {
    RELEASE(true, false),
    DEBUG(false, true);
}

Controlando qual tipo de build gerar

A configuração para gerar os tipos de binário é proveniente da função iosTarget.binaries.framework(). Ao analisarmos a classe AbstractKotlinNativeBinaryContainer, observamos que a função framework() possui um argumento buildTypes com um valor padrão.

// kotlin/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/AbstractKotlinNativeBinaryContainer.kt

fun framework(
    namePrefix: String,
    buildTypes: Collection<NativeBuildType> = NativeBuildType.DEFAULT_BUILD_TYPES,
    configure: Framework.() -> Unit = {}
) = createBinaries(namePrefix, namePrefix, NativeOutputKind.FRAMEWORK, buildTypes, ::Framework, configure)

// kotlin/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/NativeBinaryTypes.kt
enum class NativeBuildType(...) : Named {
    ...
    companion object {
        val DEFAULT_BUILD_TYPES = setOf(DEBUG, RELEASE)
    }
}

Durante o fluxo de desenvolvimento, pode ser desejável evitar a compilação das duas versões devido ao aumento do tempo de compilação. Para isso, basta adaptar nosso build.gradle.kts:

kotlin {
    val compileOnlyDebug = true // some gradle.properties flag will help you here!

    val buildType = if (compileOnlyDebug)
        NativeBuildType.DEBUG
    else NativeBuildType.RELEASE

    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64()
    ).forEach { iosTarget ->
        iosTarget.binaries.framework(
            buildTypes = listOf(buildType)
        ) {
            baseName = "KotlinShared"
            isStatic = true

            xcFramework.add(this)
        }
    }
}

Conclusões

O XCFramework é um tema central no universo do Kotlin Multiplatform (KMP). Compreender o que é, como funciona e como gerá-lo nos proporciona um maior controle e compreensão dos bastidores do KMP.

No próximo artigo, exploraremos melhor a função framework()!

Fontes

Kotlin Koans BR: Extension functions e properties (funções e propriedades estendidas)

Rodrigo Sicarelli — Sat, 06 Apr 2024 17:18:50 +0000

🔗 Tarefa

Implemente as funções de extensão Int.r() e Pair.r() e faça com que elas convertam Int e Pair em um RationalNumber.

Introdução as extension functions no Kotlin

Em Kotlin, as extension functions são uma ferramenta poderosa que permite adicionar novas funcionalidades a uma classe sem a necessidade de modificá-la ou herdá-la: você a "estende".

Essa ferramenta nos ajuda a isolar melhor nosso código, reaproveitar, e contextualizar dependendo do uso.

Vamos supor que você possua a seguinte classe hipotética que calcula valores de frete:

class DeliveryCalculator {
    fun calculateDefaultDelivery(): String {
        val value : Double = 10.50
        return "${value * 100}%"
    }

    fun calculateFastDelivery(): String {
        val value : Double = 22.90
        return "${value * 100}%"
    }

    fun calculateScheduledDelivery(): String {
        val value : Double = 15.50
        return "${value * 100}%"
    }
}

Perceba que estamos repetindo a lógica de cálculo de porcentagem 3 vezes: "${valor * 100}%"

Para evitar a repetição do código, podemos extrair apenas esse cálculo em uma função que recebe o valor:

class DeliveryCalculator {
    fun calculateDefaultDelivery(): String {
        val value : Double = 10.50
        return formatAsPercentage(value)
    }

    fun calculateFastDelivery(): String {
        val value : Double = 22.90
        return formatAsPercentage(value)
    }

    fun calculateScheduledDelivery(): String {
        val value : Double = 15.50
        return formatAsPercentage(value)
    }

    private fun formatAsPercentage(value: Double) = "${value * 100}%"
}

Essa opção já é ótima e nos ajuda a reaproveitar nosso código. Porém, com as extension functions do Kotlin, existe uma forma mais idiomática e elegante de resolver o mesmo problema

Ao criar uma extensão, essa função atua como se fosse um membro daquela classe, mas internamente o compilador a trata como apenas uma função comum que aceita uma instância daquela classe como seu primeiro parâmetro.

class DeliveryCalculator {
    fun calculateDefaultDelivery(): String {
        val value : Double = 10.50
        return value.formatAsPercentage()
    }

    fun calculateFastDelivery(): String {
        val value : Double = 22.90
        return value.formatAsPercentage()
    }

    fun calculateScheduledDelivery(): String {
        val value : Double = 15.50
        return value.formatAsPercentage()
    }

    private fun Double.formatAsPercentage() = "${this * 100}%"
}

Ou ainda:

class DeliveryCalculator {
    fun calculateDefaultDelivery(): String = 10.50.formatAsPercentage()

    fun calculateFastDelivery(): String = 22.90.formatAsPercentage()

    fun calculateScheduledDelivery(): String = 15.50.formatAsPercentage()

    private fun Double.formatAsPercentage() = "${this * 100}%"
}

A maior vantagem é que estamos contextualizando a função e estendendo a classe Double (que é fechada), adaptando apenas para nosso contexto específico.

Também é possível declarar funcões de "high-order" e reaproveitar em todo o repositório:

class DeliveryCalculator {
    fun calculateDefaultDelivery(): String = 10.50.formatAsPercentage()

    fun calculateFastDelivery(): String = 22.90.formatAsPercentage()

    fun calculateScheduledDelivery(): String = 15.50.formatAsPercentage()
}

// Pública para todo o repositório
fun Double.formatAsPercentage() = "${this * 100}%"

Extension properties (estendendo propriedades)

No caso acima, uma função pode ser redundante, já que não há nenhum parâmetro para a função formatAsPercentage().

Para resolver isso, o Kotlin também nos possibilita estender propriedades da classe, tornando o código ainda mais limpo.

class DeliveryCalculator {
    fun calculateDefaultDelivery(): String = 10.50.asPercentage

    fun calculateFastDelivery(): String = 22.90.asPercentage

    fun calculateScheduledDelivery(): String = 15.50.asPercentage

    private val Double.asPercentage
        get() = "${this * 100}%"
}

Como elas funcionam?

Por baixo dos panos, uma extensão é apenas uma função estática que recebe o objeto que você está "expandindo" (o objeto receptor) como seu primeiro argumento.

Dessa forma, não existe uma sobrecarga de desempenho ao usar funções de extensão em comparação com funções normais.

Vantagens

Melhora a legibilidade do código: Muitas vezes, chamar um método em um objeto é mais intuitivo do que passar o objeto como um argumento para uma função.
Evita poluição do namespace: Ao invés de criar funções de utilidade genérica, você pode criar as suas próprias extensões privadas apenas no contexto onde ela é utilizada.
Evita subclasses desnecessárias: Em vez de criar uma subclasse apenas para adicionar algumas funcionalidades, você pode criar extensões

Desvantagens

Não substituem métodos originais: Se a classe original tiver um método com a mesma assinatura da função de extensão, a função original será chamado.
Acesso limitado: funções de extensão não podem acessar membros protegidos ou privados da classe.
Podem levar à confusão: O uso excessivo sem organização adequada pode tornar o código difícil de entender.

Testabilidade

Isolamento e pureza: Idealmente, as funções de extensão devem operar como funções puras, tornando os testes mais previsíveis.
Restrição de acesso: Sua incapacidade de acessar membros privados torna as funções de extensão mais fáceis de testar.
Simplicidade: funções de extensão devem ter uma única responsabilidade. Isto facilita o teste.

Pair

No exercício, nos deparamos com uma classe específica do Kotlin.

Em Kotlin, Pair é uma classe que representa um valor composto por dois elementos - uma 'dupla'. É uma maneira simples de armazenar dois valores relacionados juntos, mas sem semântica particular.

Pair é uma classe definida na stdlib:

data class Pair<out A, out B>(
    val first: A,
    val second: B
)

Conclusão

As extension functions e properties do Kotlin serão ferramentas que irão acompanhá-lo durante toda a sua trajetória como DEV Kotlin.

Elas nos ajudam a organizar e reaproveitar nosso código, contextualizando e incentivando funções puras e isoladas que facilitam a compreensão do código-fonte.