DEV Community: Indiorlei de Oliveira

Como transformei tarefas repetitivas de Git em agentes de IA com o Kiro CLI

Indiorlei de Oliveira — Sun, 11 Oct 2026 13:41:17 +0000

Toda equipe tem aquele conjunto de tarefas chatas que ninguém gosta de fazer, mas que precisam ser feitas sempre do mesmo jeito: abrir PR com o título no padrão, nomear a branch certo, montar o changelog, linkar o work item. São tarefas de baixo valor intelectual e alto custo de atenção — e, pior, qualquer desvio do padrão vira ruído na revisão.

Resolvi atacar isso de uma forma diferente: em vez de escrever mais um script bash gigante, montei agentes de IA especializados que encapsulam esses fluxos. Neste artigo mostro como estruturei esse setup usando o Kiro CLI, com um padrão que separa claramente configuração, conhecimento e regras de segurança.

Vou usar meus próprios agentes como exemplo — abstraindo nomes internos — mas o padrão serve para qualquer time.

O problema

No meu dia a dia eu repetia, várias vezes por dia, dois fluxos:

Abrir um Pull Request: criar a branch no padrão, commitar com a convenção certa, inferir a branch de destino, abrir o PR com título e descrição padronizados e linkar o work item.
Fechar um pacote de release: buscar os PRs já concluídos de uma demanda, gerar o changelog, commitar e abrir um PR de release para a branch certa.

Nenhum desses passos é difícil. O problema é que todos eles têm detalhes — e detalhe esquecido é retrabalho. Automatizar com um script puro seria frágil, porque boa parte das decisões depende de contexto (qual branch, qual título, qual destino).

Agente de IA é bom justamente nessa zona cinzenta: segue regras, mas interpreta contexto.

A ideia central: separar configuração, conhecimento e regras

O que mais me ajudou foi não jogar tudo em um prompt gigante. Em vez disso, dividi cada agente em quatro camadas, cada uma em um arquivo próprio:

.kiro/
├── agents/        # Configuração: quais ferramentas o agente pode usar
├── prompts/       # Identidade: quem o agente é e seu contexto fixo
├── steering/      # Guardrails: o que ele NUNCA pode fazer
├── skills/        # Conhecimento: o passo a passo de cada tarefa
└── settings/      # Integração com ferramentas externas (via MCP)

A sacada é que cada camada tem uma responsabilidade única:

Agent = o contrato (ferramentas permitidas, atalho, mensagem de boas-vindas)
Prompt = a identidade (contexto que nunca muda)
Steering = os limites (proibições inegociáveis)
Skill = o manual (como executar cada passo, com exemplos)

Separar assim traz um benefício enorme: as skills viram reutilizáveis entre agentes. A skill de "criar commit" é a mesma para o agente que abre PR e para o que fecha release.

Camada 1 — O agente (configuração)

O arquivo de configuração do agente é enxuto. Ele diz o que o agente pode fazer, não como. Veja um exemplo (abstraído):

{
  "name": "open-pr",
  "description": "Agente que abre Pull Requests: cria branch, commita, abre o PR e linka o work item.",
  "prompt": "file://./prompts/open-pr.md",
  "includeMcpJson": true,
  "tools": ["shell", "read", "write", "grep", "glob", "@git-provider"],
  "allowedTools": [
    "shell",
    "read",
    "write",
    "@git-provider/create_pull_request",
    "@git-provider/create_branch",
    "@git-provider/link_work_item"
  ],
  "resources": [
    "skill://.kiro/skills/commit/SKILL.md",
    "skill://.kiro/skills/create-branch/SKILL.md",
    "skill://.kiro/skills/open-pr/SKILL.md"
  ],
  "keyboardShortcut": "ctrl+shift+p",
  "welcomeMessage": "Me diga o ID da demanda ou descreva a feature. Eu cuido do resto."
}

Dois pontos importantes aqui:

allowedTools é uma allowlist explícita. O agente só consegue chamar exatamente as ferramentas que eu listei. Isso é segurança por design: ele não vai, por engano, chamar uma ferramenta destrutiva que eu nunca autorizei.
resources injeta as skills. O agente carrega as instruções detalhadas sob demanda, em vez de carregar tudo o tempo todo.

Camada 2 — O prompt (identidade e contexto fixo)

O prompt define quem o agente é e qual contexto nunca muda. É aqui que eu "ancoro" o agente para ele não ficar perguntando o óbvio toda vez.

Você é um agente especializado em abrir Pull Requests para o
repositório da equipe.

## Contexto Fixo
- Provedor de git: <configurado via MCP>
- Projeto / repositório: <fixos, injetados pela configuração>
- Branch de origem padrão: `main`

## Regras de Operação
- SEMPRE usar o projeto e repositório fixos — NUNCA perguntar ao usuário
- Inferir a branch de destino a partir do contexto da demanda
- Seguir as convenções de branch e commit definidas nas skills

## O que NÃO fazer
- NÃO perguntar projeto ou repositório — são fixos
- NÃO fazer push direto para branches protegidas

Repare no padrão "Regras" + "O que NÃO fazer". Dizer ao agente o que não fazer é tão importante quanto dizer o que fazer. Isso reduz muito o comportamento imprevisível.

Dica: dados que não devem vazar (IDs internos, GUIDs, URLs) ficam fora do artigo/documentação pública e são injetados via configuração ou MCP. Nunca coloque isso no corpo de uma skill que vai pro repositório aberto.

Camada 3 — Steering (guardrails inegociáveis)

Essa é a camada que me deixa dormir tranquilo. O steering lista proibições absolutas, independentes de qualquer instrução que o agente receba.

# Open PR — Guardrails

## Proibições
- NUNCA fazer force push
- NUNCA push direto em branches protegidas
- NUNCA criar PR sem pelo menos 1 commit na branch
- NUNCA prosseguir se o git mostrar conflitos não resolvidos

## Confirmações Obrigatórias
- SEMPRE mostrar o resumo (branch, commits, destino, título) antes de abrir o PR
- SEMPRE confirmar se houver dúvida sobre a branch de destino

## Comportamento em Falha
- Se o push falhar → mostrar o erro e sugerir ação (nunca forçar)
- Se a branch de destino não existir → perguntar ao usuário

A diferença entre prompt e steering é intencional: o prompt é a personalidade (pode ter nuance), o steering é a lei (não tem exceção). Mesmo que o usuário peça "faz um force push aí", o guardrail segura.

Camada 4 — Skills (o conhecimento reutilizável)

As skills são o coração do setup. Cada uma é um documento curto que ensina um procedimento, com formato e exemplos. A skill de commit, por exemplo, define a convenção completa:

# Responsabilidade
Criar commits padronizados.

## Formato
<type>(<scope>): <emoji> <descrição curta>

## Procedimento
1. Rodar `git status --short`
2. Analisar os caminhos para determinar tipo e escopo
3. Agrupar em commits lógicos
4. Fazer staging seletivo (nunca `git add .`)
5. Commitar com a mensagem formatada

## Exemplos
feat(module-a): ✨ add product tag component
fix(module-b): 🐛 correct price display
refactor(shared): 🔨 simplify item props

O ponto forte: a mesma skill de commit é usada pelo agente de PR e pelo agente de release. Escrevi uma vez, reaproveitei em todos. Quando a convenção muda, altero um arquivo só.

Meu segundo agente — o de fechar release — é basicamente uma orquestração de skills:

Recebe o ID da demanda
  → busca os PRs já concluídos
  → troca para a branch certa
  → gera o changelog
  → usa a skill de commit
  → usa a skill de open-pr para abrir o PR de release
  → linka o work item

Ou seja: um agente complexo nasce da composição de skills simples. Isso é muito mais fácil de manter do que um prompt monolítico.

Camada 5 — Integração via MCP

Para o agente conseguir realmente abrir PRs e buscar demandas, ele precisa falar com o provedor de git. Eu faço isso via MCP (Model Context Protocol), que expõe as operações externas como ferramentas que o agente pode chamar.

{
  "mcpServers": {
    "git-provider": {
      "command": "npx",
      "args": ["-y", "<pacote-mcp-do-provedor>", "--arg", "valor"],
      "env": {
        "PROVIDER_ORG_URL": "<url-da-organizacao>",
        "PROVIDER_DEFAULT_PROJECT": "<projeto>",
        "PROVIDER_DEFAULT_REPOSITORY": "<repo>"
      }
    }
  }
}

O MCP é o que conecta o "cérebro" (o agente) às "mãos" (as operações no provedor de git). E, combinado com a allowlist lá do agente, eu controlo exatamente quais dessas operações ficam disponíveis.

Camada 6 — Docs de onboarding

Por último, mantenho um doc curto por agente explicando o que ele é e como invocar. É o que eu passo pra qualquer pessoa nova do time:

# Agente `open-pr`

## Como invocar
- Atalho: Ctrl+Shift+P
- Ou: "Abre um PR para a demanda 123" / "Commita e abre PR"

## Fluxo
Usuário informa demanda → busca contexto → cria branch →
commit → push → abre PR → linka work item → retorna o link

## Onde vivem as regras
| Assunto              | Arquivo                     |
|----------------------|-----------------------------|
| Convenção de branch  | skills/create-branch        |
| Convenção de commit  | skills/commit               |
| Regras de PR         | skills/open-pr              |
| Guardrails           | steering/open-pr            |

O resultado na prática

Depois que esse setup entrou no fluxo, abrir um PR virou uma frase: "abre um PR pra demanda X". O agente infere a branch, commita no padrão, abre o PR com título e descrição corretos e linka o work item — sempre do mesmo jeito, sem eu precisar lembrar de cada detalhe.

E, olhando o histórico de commits do repositório, dá pra ver a convenção sendo seguida de forma consistente: tipo, escopo, emoji e descrição curta em inglês, commit após commit. Essa consistência é exatamente o que eu queria — e ela não depende mais da minha memória num dia cansado.

O que eu levaria pra qualquer projeto

Se eu fosse resumir o aprendizado em princípios reaproveitáveis:

Separe configuração de conhecimento. O agente diz o que pode; a skill diz como fazer.
Guardrails são uma camada à parte. Proibições não deveriam estar misturadas com instruções normais.
Skills pequenas e reutilizáveis. Um agente complexo é composição de skills simples.
Allowlist de ferramentas sempre. Segurança por design, não por confiança.
Diga o que NÃO fazer. Isso reduz comportamento imprevisível mais do que qualquer instrução positiva.
Mantenha dados sensíveis fora das skills. Injete por configuração/MCP, nunca no texto versionado.

No fim, não automatizei só tarefas — padronizei decisões. E isso, mais do que o tempo economizado, foi o que mudou meu fluxo de trabalho.

Se você também vive repetindo os mesmos passos de Git, vale experimentar esse padrão. Comece com uma skill só, como a de commit, e vá compondo a partir daí.

🇺🇸 English version: How I turned repetitive Git chores into AI agents with the Kiro CLI

How I turned repetitive Git chores into AI agents with the Kiro CLI

Indiorlei de Oliveira — Sun, 11 Oct 2026 13:41:02 +0000

Every team has that set of boring tasks nobody enjoys but everybody has to do the exact same way every time: open a PR with the right title format, name the branch correctly, build the changelog, link the work item. These are low-intellectual-value, high-attention-cost chores — and worse, any deviation from the standard becomes noise during review.

I decided to tackle this differently: instead of writing yet another giant bash script, I built specialized AI agents that encapsulate these workflows. In this article I'll show how I structured that setup using the Kiro CLI, with a pattern that cleanly separates configuration, knowledge, and safety rules.

I'll use my own agents as the example — with internal names abstracted away — but the pattern works for any team.

The problem

In my day-to-day, I repeated two workflows several times a day:

Opening a Pull Request: create the branch in the right format, commit with the correct convention, infer the target branch, open the PR with a standardized title and description, and link the work item.
Closing a release package: find the already-completed PRs for a work item, generate the changelog, commit it, and open a release PR against the right branch.

None of these steps is hard. The problem is that every one of them has details — and a forgotten detail means rework. Automating with a pure script would be fragile, because many of the decisions depend on context (which branch, which title, which target).

AI agents are great precisely in that gray zone: they follow rules, but they interpret context.

The core idea: separate configuration, knowledge, and rules

What helped me the most was not throwing everything into one giant prompt. Instead, I split each agent into four layers, each in its own file:

.kiro/
├── agents/        # Configuration: which tools the agent is allowed to use
├── prompts/       # Identity: who the agent is and its fixed context
├── steering/      # Guardrails: what it must NEVER do
├── skills/        # Knowledge: the step-by-step for each task
└── settings/      # Integration with external tools (via MCP)

The key insight is that each layer has a single responsibility:

Agent = the contract (allowed tools, shortcut, welcome message)
Prompt = the identity (context that never changes)
Steering = the limits (non-negotiable prohibitions)
Skill = the manual (how to execute each step, with examples)

Splitting it this way brings a huge benefit: skills become reusable across agents. The "create commit" skill is the same for the agent that opens PRs and the one that closes releases.

Layer 1 — The agent (configuration)

The agent's config file is lean. It states what the agent can do, not how. Here's an example (abstracted):

{
  "name": "open-pr",
  "description": "Agent that opens Pull Requests: creates a branch, commits, opens the PR and links the work item.",
  "prompt": "file://./prompts/open-pr.md",
  "includeMcpJson": true,
  "tools": ["shell", "read", "write", "grep", "glob", "@git-provider"],
  "allowedTools": [
    "shell",
    "read",
    "write",
    "@git-provider/create_pull_request",
    "@git-provider/create_branch",
    "@git-provider/link_work_item"
  ],
  "resources": [
    "skill://.kiro/skills/commit/SKILL.md",
    "skill://.kiro/skills/create-branch/SKILL.md",
    "skill://.kiro/skills/open-pr/SKILL.md"
  ],
  "keyboardShortcut": "ctrl+shift+p",
  "welcomeMessage": "Give me the work item ID or describe the feature. I'll handle the rest."
}

Two important points here:

allowedTools is an explicit allowlist. The agent can only call exactly the tools I listed. That's security by design: it won't accidentally call a destructive tool I never authorized.
resources injects the skills. The agent loads detailed instructions on demand instead of carrying everything all the time.

Layer 2 — The prompt (identity and fixed context)

The prompt defines who the agent is and which context never changes. This is where I "anchor" the agent so it doesn't keep asking the obvious every time.

You are an agent specialized in opening Pull Requests for the
team's repository.

## Fixed Context
- Git provider: <configured via MCP>
- Project / repository: <fixed, injected by configuration>
- Default source branch: `main`

## Operating Rules
- ALWAYS use the fixed project and repository — NEVER ask the user
- Infer the target branch from the work item context
- Follow the branch and commit conventions defined in the skills

## What NOT to do
- Do NOT ask for project or repository — they are fixed
- Do NOT push directly to protected branches

Notice the "Rules" + "What NOT to do" pattern. Telling the agent what not to do is just as important as telling it what to do. It dramatically reduces unpredictable behavior.

Tip: data that must not leak (internal IDs, GUIDs, URLs) stays out of public articles/docs and is injected via configuration or MCP. Never put that in the body of a skill that lands in an open repository.

Layer 3 — Steering (non-negotiable guardrails)

This is the layer that lets me sleep at night. Steering lists absolute prohibitions, independent of any instruction the agent receives.

# Open PR — Guardrails

## Prohibitions
- NEVER force push
- NEVER push directly to protected branches
- NEVER create a PR without at least 1 commit on the branch
- NEVER proceed if git shows unresolved conflicts

## Mandatory Confirmations
- ALWAYS show the summary (branch, commits, target, title) before opening the PR
- ALWAYS confirm if there's any doubt about the target branch

## Failure Behavior
- If the push fails → show the error and suggest an action (never force)
- If the target branch doesn't exist → ask the user

The distinction between prompt and steering is intentional: the prompt is the personality (it can have nuance), the steering is the law (no exceptions). Even if the user says "just force push it," the guardrail holds.

Layer 4 — Skills (reusable knowledge)

Skills are the heart of the setup. Each one is a short document that teaches one procedure, with a format and examples. The commit skill, for instance, defines the full convention:

# Responsibility
Create standardized commits.

## Format
<type>(<scope>): <emoji> <short description>

## Procedure
1. Run `git status --short`
2. Analyze the paths to determine type and scope
3. Group into logical commits
4. Stage selectively (never `git add .`)
5. Commit with the formatted message

## Examples
feat(module-a): ✨ add product tag component
fix(module-b): 🐛 correct price display
refactor(shared): 🔨 simplify item props

The strong point: the same commit skill is used by both the PR agent and the release agent. I wrote it once and reused it everywhere. When the convention changes, I edit a single file.

My second agent — the release closer — is basically skill orchestration:

Receives the work item ID
  → finds the already-completed PRs
  → switches to the right branch
  → generates the changelog
  → uses the commit skill
  → uses the open-pr skill to open the release PR
  → links the work item

In other words: a complex agent emerges from composing simple skills. That's far easier to maintain than a monolithic prompt.

Layer 5 — Integration via MCP

For the agent to actually open PRs and fetch work items, it needs to talk to the git provider. I do this via MCP (Model Context Protocol), which exposes external operations as tools the agent can call.

{
  "mcpServers": {
    "git-provider": {
      "command": "npx",
      "args": ["-y", "<provider-mcp-package>", "--arg", "value"],
      "env": {
        "PROVIDER_ORG_URL": "<org-url>",
        "PROVIDER_DEFAULT_PROJECT": "<project>",
        "PROVIDER_DEFAULT_REPOSITORY": "<repo>"
      }
    }
  }
}

MCP is what connects the "brain" (the agent) to the "hands" (the operations on the git provider). And combined with the agent's allowlist, I control exactly which of those operations are available.

Layer 6 — Onboarding docs

Finally, I keep a short doc per agent explaining what it is and how to invoke it. It's what I hand to anyone new on the team:

# `open-pr` Agent

## How to invoke
- Shortcut: Ctrl+Shift+P
- Or: "Open a PR for work item 123" / "Commit and open a PR"

## Flow
User provides a work item → fetch context → create branch →
commit → push → open PR → link work item → return the link

## Where the rules live
| Topic               | File                        |
|---------------------|-----------------------------|
| Branch convention   | skills/create-branch        |
| Commit convention   | skills/commit               |
| PR rules            | skills/open-pr              |
| Guardrails          | steering/open-pr            |

The result in practice

Once this setup entered my workflow, opening a PR became a single sentence: "open a PR for work item X." The agent infers the branch, commits in the right format, opens the PR with the correct title and description, and links the work item — always the same way, without me having to remember each detail.

And looking at the repository's commit history, you can see the convention being followed consistently: type, scope, emoji, and a short English description, commit after commit. That consistency is exactly what I wanted — and it no longer depends on my memory on a tired day.

What I'd take to any project

If I had to boil the lessons down into reusable principles:

Separate configuration from knowledge. The agent says what it can do; the skill says how to do it.
Guardrails are their own layer. Prohibitions shouldn't be mixed with normal instructions.
Small, reusable skills. A complex agent is a composition of simple skills.
Always allowlist tools. Security by design, not by trust.
Say what NOT to do. It reduces unpredictable behavior more than any positive instruction.
Keep sensitive data out of skills. Inject it via configuration/MCP, never in versioned text.

In the end, I didn't just automate tasks — I standardized decisions. And that, more than the time saved, is what actually changed my workflow.

If you also find yourself repeating the same Git steps over and over, this pattern is worth a try. Start with a single skill, like the commit one, and compose from there.

🇧🇷 Versão em português: Como transformei tarefas repetitivas de Git em agentes de IA com o Kiro CLI

Como criei um tema para VS Code e terminal como projeto de estudo

Indiorlei de Oliveira — Wed, 09 Sep 2026 00:48:15 +0000

Temas parecem um projeto pequeno: escolher algumas cores e trocar o arquivo de configuração do editor. Foi exatamente com essa expectativa que comecei o Underground, um tema escuro para VS Code e Kiro IDE. No caminho, descobri que um tema bom não é uma coleção de cores bonitas; é um pequeno sistema de design aplicado a muitos contextos.

O Underground nasceu como projeto de estudo. A proposta era simples: uma interface escura, discreta, com contraste confortável e um verde quente como ponto de atenção. Depois, o projeto cresceu para incluir o terminal integrado do editor, o Windows Terminal e o Terminal.app do macOS — todos orientados pela mesma paleta.

Neste artigo, compartilho o processo, as decisões e os problemas que encontrei. O repositório está disponível em GitHub.

Comecei pela intenção, não pelas cores

Antes de escrever JSON, defini a sensação que queria criar:

fundo escuro sem ser preto absoluto;
pouca competição visual entre as áreas da interface;
cores de sintaxe que ajudem a escanear o código;
cores semânticas previsíveis para erro, aviso, Git e conflitos;
terminal e editor com a mesma identidade.

Essa primeira etapa evitou uma armadilha comum: atribuir cores isoladamente à medida que os elementos aparecem. Em vez disso, cada escolha deveria responder a uma função. O verde, por exemplo, não existe apenas porque eu gosto dele; ele marca elementos ativos e também palavras-chave, parâmetros e tags. Ele é uma cor de atenção moderada, não uma cor usada em todo lugar.

Uma paleta pequena, com papéis claros

O núcleo do tema é composto por poucos tons:

Papel	Cor	Uso principal
Fundo	`#222222`	editor, barra lateral e painéis
Superfície elevada	`#272727`	abas ativas, inputs e status bar
Texto principal	`#ffffffde`	conteúdo de maior prioridade
Texto secundário	`#ffffff99`	descrições e informações auxiliares
Acento verde	`#9bd4b2`	atividade, parâmetros e Git modificado
Azul	`#90aed3`	strings, funções e números
Roxo	`#ceb0d3`	tipos, interfaces e atributos
Comentários	`#8a8a8a`	conteúdo propositalmente secundário

Um detalhe importante é o de em #ffffffde. Em temas do VS Code, também podemos usar hex com canal alfa. Assim, em vez de inventar muitos cinzas diferentes, usei branco com transparências distintas para criar uma escala de hierarquia: texto principal, secundário e sutil.

Essa abordagem deixou as decisões mais fáceis de manter. Quando percebi que comentários estavam apagados demais, por exemplo, não precisei redesenhar o tema inteiro: subi seu tom de #6a6a6a para #8a8a8a, preservando seu papel visual e melhorando a legibilidade.

A estrutura mínima de uma extensão de tema

Uma extensão de tema do VS Code pode ser surpreendentemente pequena. No caso do Underground, os dois arquivos essenciais são:

editors/vscode/
├── package.json
└── themes/
    └── underground-color-theme.json

O package.json registra o tema na seção contributes:

{
  "contributes": {
    "themes": [
      {
        "label": "Underground",
        "uiTheme": "vs-dark",
        "path": "./themes/underground-color-theme.json"
      }
    ]
  }
}

O arquivo de tema contém duas partes que vale separar mentalmente:

colors: a interface do VS Code — editor, abas, listas, widgets, terminal e estado do Git.
tokenColors e semanticTokenColors: a aparência do código.

Essa separação parece óbvia, mas foi uma boa forma de organizar o trabalho. Primeiro deixei o ambiente confortável para navegar; depois cuidei da leitura do código.

Tokens de sintaxe: cor é uma ferramenta de leitura

Para a primeira camada de sintaxe, associei grupos de scopes a papéis visuais. Uma versão reduzida da configuração é esta:

{
  "scope": ["keyword", "storage", "variable.parameter", "entity.name.tag"],
  "settings": { "foreground": "#9bd4b2" }
},
{
  "scope": ["string", "support.function", "constant.numeric"],
  "settings": { "foreground": "#90aed3" }
},
{
  "scope": ["entity.name.type", "entity.other.attribute-name"],
  "settings": { "foreground": "#ceb0d3" }
}

O ponto não é decorar scopes, e sim testar em linguagens diferentes. A mesma categoria pode receber scopes diferentes em TypeScript, HTML, JSON ou Markdown. Por isso mantive uma amostra de código para abrir no editor enquanto ajustava o tema.

Também adicionei semanticTokenColors. Essa camada moderna permite ao editor informar significados como type, function, parameter e variable.readonly, especialmente útil em TypeScript e JavaScript. O resultado é mais consistente do que depender exclusivamente da gramática textual.

A parte que quase sempre fica esquecida: a interface inteira

Colorir strings e palavras-chave é só o começo. Um tema realmente utilizável precisa lidar com estados menos frequentes: busca, sugestões, mensagens de validação, diff, merge conflict, Peek Definition, foco por teclado e decoração de Git.

Esses casos revelam problemas que uma captura de tela comum não mostra. No Underground, encontrei dois exemplos marcantes:

os números de linha tinham contraste insuficiente e praticamente desapareciam;
o widget de Peek Definition não tinha cores próprias e usava um fundo claro inesperado.

Corrigi o primeiro caso elevando o tom dos números inativos e mantendo o número ativo em branco. Para o segundo, foi preciso definir as chaves peekView*, usando o fundo elevado e a seleção já existentes na paleta.

Essa experiência mudou meu critério de pronto: um tema não está pronto quando o arquivo de exemplo está bonito. Ele está pronto depois de passar por fluxos reais de edição, busca, autocomplete, Git e resolução de conflitos.

Diferenças e conflitos também comunicam significado

Para diffs, evitei blocos muito saturados. Linhas adicionadas usam verde com baixa opacidade; removidas usam vermelho com baixa opacidade. As palavras alteradas recebem uma opacidade um pouco maior que a linha inteira, para criar hierarquia.

Nos conflitos de merge, mantive uma convenção semântica:

versão atual: verde;
versão recebida: azul;
base comum: cinza;
conflito ainda não resolvido: borda amarela.

É uma decisão pequena, mas útil: as cores deixam de ser decoração e passam a explicar o estado da informação.

Um tema, mais de um ambiente

Eu queria que abrir o terminal não parecesse mudar de aplicação. Por isso, documentei a paleta em PALETTE.md e usei o tema do VS Code como fonte canônica. A partir dos valores terminal.ansi*, criei:

um esquema JSON para o Windows Terminal;
um perfil .terminal para o Terminal.app do macOS.

Há uma sutileza aqui: o fundo do editor é #222222, mas o preto ANSI é #1a1a1a. Isso preserva a convenção de cores do terminal sem transformar toda a interface em preto absoluto.

Ter uma fonte de verdade reduz divergências. Se eu alterar o amarelo de aviso, sei que preciso revisar o amarelo ANSI e a documentação da paleta. Esse cuidado é mais simples do que tentar descobrir, meses depois, por que o editor e o terminal usam cores quase iguais.

O que eu faria desde o início em um próximo tema

Se fosse começar novamente, eu adotaria estes hábitos desde o primeiro commit:

Criar uma paleta com nomes de papel, não apenas uma lista de hexadecimais.
Preparar arquivos de exemplo com várias linguagens e estados de interface.
Testar acessibilidade e contraste antes de considerar uma cor definitiva.
Documentar a relação entre editor e terminal desde cedo.
Registrar mudanças visuais no changelog, incluindo o motivo da alteração.

Também vale testar o tema localmente por meio de um link simbólico na pasta de extensões do VS Code. Esse ciclo curto — editar, recarregar a janela, observar — tornou os ajustes muito mais rápidos.

Conclusão

Criar o Underground foi uma forma excelente de estudar ferramentas de desenvolvimento por outro ângulo. Um tema não altera a lógica do programa, mas influencia diretamente a experiência de ler, navegar e depurar código por horas.

A maior lição foi esta: consistência é mais valiosa do que quantidade de cores. Quando fundo, contraste, estados e semântica contam a mesma história, o resultado é mais calmo e mais útil.

Se você quiser explorar a implementação, contribuir ou adaptar a paleta, o código está no repositório do Underground, sob licença MIT.