Como usar o Claude Code — a partir do ponto em que os guias introdutórios terminam

Há muitos textos sobre como usar o Claude Code, mas a maioria termina em “instale e receba a primeira resposta”. O que realmente trava acontece depois — você repete as mesmas explicações, as janelas de confirmação aparecem o tempo todo e a janela de uso de 5 horas fecha no meio do trabalho. Este texto começa onde os guias introdutórios terminam e organiza esses três problemas em sequência.

Vamos alinhar uma premissa. O Claude Code não é uma ferramenta para colar código em uma janela de chat, mas um agente que reside no repositório dentro do terminal. Ele lê e altera arquivos, executa testes e até faz commits. Por isso, a primeira tarefa não é memorizar como usá-lo, mas transmitir as regras do projeto.

As três primeiras etapas — executar, /init e fazer um pedido específico

Logo após a instalação, só estas três coisas valem a pena. Em especial, se você pular o segundo /init, terá de repetir as mesmas explicações em todas as sessões seguintes.

# 1. 프로젝트 디렉터리에서 실행한다 (이게 전제 조건입니다)
cd ~/work/my-app
claude

# 2. 첫 명령은 /init — 저장소를 읽고 CLAUDE.md를 만들어 줍니다
> /init

# 3. 이후엔 한국어로 그냥 부탁하면 됩니다. 파일 경로를 붙일수록 정확해집니다
> src/api/user.ts의 검증 로직을 zod로 바꾸고 테스트도 같이 고쳐줘

O /init lê o repositório e cria o CLAUDE.md. O conteúdo gerado é um rascunho, então não o deixe como está; revise-o manualmente. A próxima seção trata desse conteúdo.

CLAUDE.md — escrever uma vez o que você explicava sempre

O CLAUDE.md é um arquivo Markdown colocado na raiz do projeto e lido automaticamente em cada sessão. O que deve entrar nele é apenas “o que não pode ser descoberto pela leitura do código”.

# CLAUDE.md — 프로젝트 루트에 두고 git에 커밋합니다

## 명령어
- 테스트: npm test (파일 하나만: npm test -- path/to/file)
- 타입 검사: npx tsc --noEmit
- 린트: npm run lint

## 규칙
- 날짜는 date-fns만 사용. moment 금지.
- API 핸들러는 app/api/**/route.ts에만 둔다.
- 커밋 메시지는 한국어, prefix는 feat / fix / docs.

## 건드리면 안 되는 곳
- db/migrations/ — 생성물. 직접 수정 금지.

Também é claro o que não deve ser incluído. A estrutura de diretórios e as explicações de funções aparecem na leitura do código, portanto são desnecessárias. O CLAUDE.md é enviado junto em cada solicitação, então arquivos mais longos consomem mais tokens — mantenha-o curto e restrito às regras. Ao fazer commit no git, as mesmas regras se aplicam a toda a equipe.

Permissões — reduzir as confirmações sem desativá-las todas

Uma janela de confirmação aparece sempre que um arquivo é alterado ou um comando é executado. Como ela é uma proteção, a abordagem prática é permitir apenas operações de leitura e verificação, em vez de desativar tudo. Escolha “Sempre permitir” durante a sessão para que seja lembrado, ou registre-o em .claude/settings.json para fixá-lo no nível do projeto.

Existe uma flag que ignora todas as confirmações, mas ela também permite exclusões e push remoto sem confirmação. Use-a somente em um contêiner descartável ou em uma árvore de trabalho temporária que possa ser abandonada mesmo se for danificada. O critério está resumido em quando usar --dangerously-skip-permissions.

Comandos personalizados — não digitar o mesmo pedido toda vez

Tarefas que exigem quase sempre o mesmo tipo de solicitação, como revisão, verificação antes de um release e organização de mensagens de commit, podem virar comandos. Basta colocar um arquivo Markdown em .claude/commands/.

# .claude/commands/review.md — 파일만 두면 /review로 쓸 수 있습니다
지정된 파일을 리뷰하고 다음 세 가지만 지적하세요.

1. 실제로 실패하는 조건이 있는 버그 (재현 방법 포함)
2. 기존 유틸리티로 대체 가능한 중복
3. 테스트가 없는 분기

스타일 취향은 지적하지 마세요.

Assim, /review src/api/user.ts executa revisões sob a mesma perspectiva. Ao fazer commit no git, a equipe compartilha o comando, e os próprios critérios de revisão podem permanecer no repositório. A forma dos comandos usados na prática está descrita com mais detalhes, em inglês, em Claude Code workflows.

Como continuar quando a janela de uso fecha

O uso da assinatura é administrado em uma janela móvel de 5 horas, que pode fechar justamente à tarde, quando o trabalho se intensifica. Mudar para um plano superior também não a reabre naquele instante. As opções práticas são três.

A terceira opção funciona sem cancelar a assinatura. Enquanto as duas linhas abaixo estiverem configuradas, a cobrança será por uso; ao remover as variáveis, você volta à assinatura. Se não tiver uma chave, comece por obter uma chave de API do Claude.

# 사용량 창이 닫혀도 작업을 이어가는 두 줄.
# 이 변수가 설정된 동안에만 종량제로 청구되고, 지우면 구독으로 돌아갑니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# 클로드 코드의 기본 모델과 opus 별칭은 최신 Opus를, sonnet 별칭은 Sonnet 5.5를
# 가리킵니다. Kunavo가 제공하지 않는 모델(Sonnet 5.5, 아직 들어오지 않은 새 Opus)을
# 요청해 404가 나지 않도록 모델을 고정합니다. sonnet을 고정하지 않으면 /model sonnet,
# opusplan의 실행 단계, model: 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

# 보조 작업을 가장 싼 모델로 넘기는 한 줄 (매 세션 효과가 있습니다)
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

As tarifas são lidas diretamente do catálogo: Claude Sonnet 5 custa $1.40 / $7.00 por 1 milhão de tokens, e Claude Haiku 4.5 custa $0.70 / $3.50. O valor é descontado do saldo pré-pago, portanto não há cobrança nos meses em que você não trabalhar. A comparação entre assinatura e cobrança por uso, incluindo o cálculo do ponto de equilíbrio, está em preços do Claude Code; a solução para pagamentos bloqueados com cartões coreanos está em preços e pagamentos da Claude API; e a própria estrutura da janela de uso está em limites do Claude Pro.

Pedidos que melhoram e pedidos que pioram o resultado

Por fim, é aqui que a diferença no modo de usar a ferramenta mais aparece. Incluir o caminho do arquivo reduz os tokens gastos na exploração, tornando o resultado mais rápido e preciso — em vez de “corrija a lógica de validação”, diga “mude a lógica de validação de src/api/user.ts para zod”.

Além disso, não entregue uma tarefa grande de uma só vez. Divida-a em alteração → teste → próxima alteração para que fique claro onde voltar quando algo falhar. A distinção entre os tipos de erro está em resumo dos erros do Claude Code.

Se quiser usar o agente de programação da OpenAI da mesma forma, como usar o Codex explica como executar o Codex CLI com uma chave de API, sem um plano do ChatGPT.

Perguntas frequentes