Como usar o Claude Code — 4 coisas para fazer depois do tutorial introdutório

Há muitos artigos que explicam como usar o Claude Code, mas a maioria termina em “instale e execute a primeira vez”. Os problemas reais começam depois — escrever as mesmas instruções todas as vezes, lidar com diálogos de confirmação demais e atingir o limite de uso de 5 horas no meio do trabalho. Esta página começa onde os artigos introdutórios terminam e resolve esses 3 pontos em sequência.

Para começar, o Claude Code não é uma “ferramenta para colar código no chat”, mas um agente que vive no repositório pelo terminal. Ele lê e modifica arquivos, executa testes e até faz commits. Por isso, a primeira coisa a fazer não é aprender a usá-lo, mas transmitir as regras do projeto.

Os 3 primeiros passos — iniciar, /init, solicitação específica

Logo após a instalação, só vale a pena fazer estes 3 passos. Em especial, se você pular o segundo, /init, terá de repetir a mesma explicação em todas as sessões seguintes.

# 1. プロジェクトのディレクトリで起動する（ここが全ての前提）
cd ~/work/my-app
claude

# 2. 最初の一手は /init — リポジトリを読んで CLAUDE.md を書き出す
> /init

# 3. 以降は普通の日本語で頼む。ファイル名を添えるほど精度が上がる
> src/api/user.ts のバリデーションを zod に置き換えて、テストも直して

/init lê o repositório e gera CLAUDE.md. O conteúdo gerado é um rascunho, portanto não o deixe como está: sempre faça ajustes manualmente. A próxima seção explica o que escrever nele.

CLAUDE.md — escreva uma vez o que você explica todas as vezes

CLAUDE.md é um arquivo Markdown colocado na raiz do projeto e carregado automaticamente a cada sessão. O que deve ser escrito nele é apenas “o que não dá para entender lendo o código”.

# CLAUDE.md — プロジェクトのルート、git にコミットする

## コマンド
- テスト: npm test（1 ファイルだけなら npm test -- path/to/file）
- 型チェック: npx tsc --noEmit
- Lint: npm run lint

## 決めごと
- 日付は必ず date-fns。moment は使わない。
- API ハンドラは app/api/**/route.ts のみ。lib に書かない。
- コミットメッセージは日本語、prefix は feat / fix / docs。

## 触ってはいけない場所
- db/migrations/ — 生成物。手で編集しない。

Também é claro o que é melhor não escrever. Estruturas de diretórios e explicações de funções são desnecessárias porque podem ser entendidas lendo o código. CLAUDE.md é incluído em todas as solicitações, portanto ficará certamente caro se for longo — mantenha-o curto e registre apenas as regras. Fazer commit no git aplica as mesmas regras a toda a equipe.

Permissões — reduza as confirmações, mas não ignore demais

Há uma confirmação a cada alteração de arquivo ou execução de comando. Isso é um mecanismo de segurança; na prática, a solução é “permitir apenas comandos de leitura e verificação”, em vez de eliminar tudo. Selecione “permitir sempre” durante a sessão para que seja lembrado; escreva .claude/settings.json para fixá-lo no nível do projeto.

Também existem flags que ignoram todas as confirmações, mas elas eliminam a confirmação até para exclusões e push para repositórios remotos. Use-as apenas dentro de contêineres descartáveis ou árvores de trabalho que possam ser abandonadas se forem danificadas. Os critérios e o uso seguro estão reunidos em quando usar --dangerously-skip-permissions.

Comandos personalizados — não escreva a mesma solicitação todas as vezes

Tarefas que exigem quase sempre a mesma solicitação, como revisão, verificação antes do lançamento e formatação de mensagens de commit, podem virar comandos. Basta colocar Markdown em .claude/commands/.

# .claude/commands/review.md — 置くだけで /review として使える
指定されたファイルをレビューして、次の 3 点だけ指摘してください。

1. 実際に落ちる条件があるバグ（再現手順を添える）
2. 既存のユーティリティで置き換えられる重複
3. テストが無い分岐

スタイルの好みは指摘しないでください。

Assim, ao digitar /review src/api/user.ts, você recebe uma revisão com os mesmos critérios. Fazer commit no git permite compartilhar com a equipe e manter os próprios critérios de revisão no repositório. Os formatos de comandos eficazes no trabalho estão detalhados em inglês em Claude Code workflows.

Como continuar quando a janela de 5 horas se fecha

A cota da assinatura é gerenciada em uma janela móvel de 5 horas e pode se fechar à tarde, quando o trabalho está avançando. Mesmo mudar para um plano superior não a abre naquele instante. Na prática, existem 3 opções.

A terceira opção pode ser feita sem cancelar a assinatura. Enquanto as 2 linhas seguintes estiverem configuradas, a cobrança será conforme o uso; remova as variáveis para voltar à assinatura original.

# 5 時間ウィンドウが閉じても作業を続けるための 2 行。
# この変数が設定されている間だけ従量課金になり、消せば元のサブスクに戻る。
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Claude Code の既定モデルと opus エイリアスは最新の Opus を、sonnet エイリアスは
# Kunavo が提供していない Sonnet 5.5 を指す。/model sonnet や opusplan の実行
# フェーズ、sonnet 指定のサブエージェントが 404 にならないようモデルを固定する。
# opus は Opus 5.5 に固定（Claude Code v2.1.280 以降が必要。古ければ claude update）。
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5

# 補助的な処理を一番安いモデルに逃がす 1 行（毎セッション効く）
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

As tarifas são carregadas diretamente do catálogo: Claude Sonnet 5 custa $1.40 / $7.00 por 1M de tokens, e Claude Haiku 4.5 custa $0.70 / $3.50. Como o valor é descontado do saldo pré-pago, a cobrança nos meses em que você não usar nada é 0. Calculamos qual é mais barato entre assinatura e cobrança conforme o uso, o custo real por etapa e o ponto de equilíbrio em preço do Claude Code. O funcionamento da janela está em limites do Claude Pro, e a escolha do modelo padrão está em diferenças entre Opus e Sonnet.

Como fazer solicitações que aumentam ou reduzem a precisão

Por fim, esta é a parte em que a habilidade de uso mais aparece. Acrescentar o nome e o caminho do arquivo reduz os tokens usados na exploração e torna o resultado mais rápido e preciso — “corrija a validação” é menos eficaz que “substitua a validação de src/api/user.ts por zod”.

E não envie uma solicitação grande de uma só vez. Divida-a em alteração → teste → próxima alteração para deixar claro onde voltar mesmo se algo falhar. O diagnóstico de erros está reunido em páginas específicas, como erro 401 do Claude Code.

Se você quiser experimentar o mesmo fluxo com o agente do lado da OpenAI, reunimos em como usar o Codex as instruções para executá-lo com uma chave de API, sem um plano do ChatGPT.

Perguntas frequentes