Claude Code: planeje antes de editar e amplie funções com o modo plan

01Defina primeiro o escopo, mesmo em mudanças que parecem pequenas

Atualmente, summarize.py lê expenses.csv e exibe a soma mensal de amount. Desta vez, ampliaremos o programa para que, sem remover a função existente, ele também mostre os totais de cada category por mês somente quando a opção `--by-category` for usada. Mesmo ao adicionar uma única função, se o arquivo for editado imediatamente, a IA pode decidir por conta própria detalhes como o formato de saída, a manutenção do comportamento atual ou a ordem de classificação. Por isso, primeiro definimos o que deve permanecer igual e o que deve mudar.

Aqui, o critério para evitar regressões é mais importante do que a nova função. Mesmo com a opção adicionada, a saída existente de `python summarize.py expenses.csv` não deve mudar. Não basta verificar o resultado da nova opção: também é necessário testar novamente a execução anterior.

02Comece no modo plan para ainda impedir alterações

O Claude Code pode ser iniciado no modo plan com `claude --permission-mode plan`. Esse modo é usado para analisar o código e o escopo do trabalho principalmente por leitura e para revisar o plano. Para iniciantes, costuma ser mais fácil entender a mudança recebendo primeiro um plano, em vez de ampliar imediatamente as permissões de edição sobre um código existente.

cd vibe-expenses
claude --permission-mode plan

Quando a sessão começar, peça primeiro que ele leia summarize.py e expenses.csv e explique quais partes pretende alterar. Nesta etapa, indique explicitamente que ainda não deve modificar nada. Se o plano não estiver adequado, você pode corrigir os requisitos antes de tocar nos arquivos.

Leia summarize.py e explique primeiro o comportamento atual.
Depois, escreva apenas um plano de mudanças para adicionar a opção `--by-category`. Ainda não modifique nenhum arquivo.
A saída da execução básica `python summarize.py expenses.csv` deve permanecer exatamente igual.
Na execução com opção `python summarize.py expenses.csv --by-category`, adicione os totais por category de cada mês.
Use apenas a biblioteca padrão do Python e não modifique expenses.csv.
Os totais esperados por categoria para 2026-09 são food 20500, transport 2900 e supplies 3200.

03Procure primeiro condições ausentes, não detalhes de implementação

Ao receber o plano, verifique primeiro se todos os requisitos foram incorporados, não se a solução parece elegante. Em especial, confirme a manutenção da saída existente, o comportamento sem a opção, a ordenação de category, o tratamento de opções inválidas e se algum pacote externo será adicionado. Se o plano estiver ambíguo, faça outra pergunta antes da implementação.

[Exemplo editorial · não é uma resposta real]
1. A estrutura atual de leitura do CSV e cálculo dos totais mensais é mantida.
2. É adicionada uma estrutura de dados para acumular também os totais de category por mês.
3. O segundo argumento é verificado para saber se é `--by-category` e decidir se a opção será ativada.
4. Na execução básica, apenas os totais mensais existentes são exibidos.
5. Na execução com a opção, o nome e o total de cada category são exibidos em ordem abaixo do total mensal.
6. Após a implementação, a execução básica e a execução com opção são realizadas separadamente para comparar os valores esperados.

• A saída da execução básica existente permanece exatamente igual?
• Os resultados por categoria são adicionados somente quando a opção está presente?
• Nenhum novo pacote externo precisa ser instalado?
• expenses.csv não é modificado nem convertido para outro formato?
• O plano inclui os comandos de execução para comparar com os valores esperados?

O plano acima é um exemplo editorial para explicar o processo e não uma resposta real do Claude Code. Em uma sessão real, o modelo pode sugerir outra ordem de implementação; portanto, em vez de memorizar as frases como resposta correta, verifique se o plano atende aos seus requisitos.

04Implemente depois de revisar o plano e confira o código final

Depois de confirmar que o plano corresponde aos requisitos, prossiga com a implementação. No Claude Code, a alteração real de arquivos e a execução de comandos podem exigir aprovação dependendo do ambiente e das configurações de permissão. O código abaixo é o exemplo completo usado para verificar os resultados deste artigo. Ele não foi copiado de uma resposta real do Claude Code: foi escrito de acordo com os requisitos do artigo e executado separadamente no ambiente Python do chat do GPT.

import csv
import sys
from collections import defaultdict

def read_totals(path):
    monthly = defaultdict(int)
    by_category = defaultdict(lambda: defaultdict(int))

    with open(path, newline="", encoding="utf-8") as f:
        reader = csv.DictReader(f)
        for row in reader:
            month = row["date"][:7]
            amount = int(row["amount"])
            monthly[month] += amount
            by_category[month][row["category"]] += amount

    return monthly, by_category

def main():
    if len(sys.argv) not in (2, 3):
        print("Usage: python summarize.py expenses.csv [--by-category]")
        raise SystemExit(2)

    if len(sys.argv) == 3 and sys.argv[2] != "--by-category":
        print("Usage: python summarize.py expenses.csv [--by-category]")
        raise SystemExit(2)

    monthly, by_category = read_totals(sys.argv[1])
    show_category = len(sys.argv) == 3

    for month in sorted(monthly):
        print(f"{month} = {monthly[month]}")
        if show_category:
            for category in sorted(by_category[month]):
                print(f"  {category} = {by_category[month][category]}")

if __name__ == "__main__":
    main()

Este código usa apenas o módulo csv e collections.defaultdict. Na execução básica, exibe somente os totais mensais; quando `--by-category` aparece exatamente como segundo argumento, mostra abaixo de cada total mensal os totais por category em ordem. Se outra opção ou uma quantidade diferente de argumentos for fornecida, exibe o uso correto e encerra.

05Verifique novamente tanto a nova função quanto a execução existente

Depois de adicionar a função, verifique os dois casos. Primeiro execute sem a opção para confirmar que o resultado anterior foi mantido; depois, adicione `--by-category` para testar a nova função. O código Python deste artigo foi realmente executado com a ferramenta Python do chat do GPT e coincidiu exatamente com a saída esperada mostrada abaixo.

python summarize.py expenses.csv
python summarize.py expenses.csv --by-category

Saída esperada da execução básica:
2026-09 = 26600
2026-10 = 9800

Saída esperada com --by-category:
2026-09 = 26600
  food = 20500
  supplies = 3200
  transport = 2900
2026-10 = 9800
  food = 9800

Em setembro, as category são exibidas em ordem alfabética: food, supplies, transport. Os totais coincidem com os valores de referência definidos no primeiro artigo da série: food 20500, transport 2900 e supplies 3200. Em outubro existe apenas food, portanto é exibido 9800.

06Lista curta antes de aprovar a implementação

O objetivo do modo plan não é receber um plano longo da IA, mas criar pontos concretos de decisão antes da edição. Se o plano responder claramente a algumas perguntas como as seguintes, você pode aprovar a implementação; se alguma resposta estiver ambígua, corrija primeiro o plano.

No próximo artigo, registraremos com git o estado antes e depois desse tipo de mudança. Mesmo que o Claude Code tenha checkpoints, git é um sistema de controle de versão separado; ao aprender a revisar os arquivos alterados e o diff, você consegue acompanhar com mais clareza o que a IA mudou.

O que conferir por conta própria

Execução real no ambiente Python da ferramenta Python do chat do GPT após salvar como arquivos o expenses.csv fictício e o summarize.py do artigo · Claude Code não foi realmente executado

• Confirmar que a execução básica exibe exatamente 2026-09 = 26600 e 2026-10 = 9800
• Confirmar que a execução com `--by-category` exibe exatamente 2026-09 food = 20500, supplies = 3200 e transport = 2900
• Confirmar que a execução com `--by-category` exibe 2026-10 food = 9800
• Confirmar que as duas execuções terminam com código de saída 0
• Confirmar que o código usa apenas a biblioteca padrão do Python e não modifica expenses.csv
• Confirmar que o exemplo de resposta de planejamento do Claude Code está marcado com '[Exemplo editorial · não é uma resposta real]'