Guia prático completo do Claude Code: da configuração introdutória aos fluxos de trabalho de automação avançados

Código Claude: Agentes de desenvolvimento inteligente em terminais

Antrópica Lançamento de ferramentas de linha de comando Claude Code Não é apenas mais uma janela de bate-papo ou um plug-in de IDE, mas um agente de desenvolvimento integrado de forma nativa ao ambiente de terminal. Ele compreende a estrutura do projeto, lê e grava arquivos, executa comandos e até mesmo coordena vários subagentes para concluir tarefas complexas, projetadas para levar a IA mais profundamente ao fluxo de trabalho principal dos desenvolvedores.

Para os desenvolvedores que estão acostumados a operar em terminais, oClaude Code Oferece uma alternativa ao GitHub Copilot e outras ferramentas com diferentes modos de interação.Copilot Os pontos fortes do IDE são a integração perfeita com o IDE e a conclusão rápida de código em nível de linha - é mais como um "programador de pares" que otimiza a parte de "escrita" do processo. Por outro lado, o Claude Code É mais um "gerente de projeto", com uma posição na Shell, concentrando-se no planejamento e na execução de tarefas de nível superior e especializando-se em problemas complexos que exigem compreensão e refatoração entre documentos.

Principais recursos

• Integração de terminais nativosGeração de código, depuração e execução de comandos podem ser feitas sem sair do terminal. Essa filosofia de design é atraente para os desenvolvedores que dependem de fluxos de trabalho de automação de scripts e linhas de comando.
• Comandos de barra personalizadosEncapsulamento de fluxos de trabalho comuns em comandos de um clique para um alto grau de automação.
• Colaboração de subagentesAgente mestre: suporta a criação de subagentes dedicados com diferentes responsabilidades e permissões, que são coordenados pelo agente mestre e são adequados para lidar com tarefas de vários estágios, como revisão de código e geração de testes.
• Forte controle de projetosPor meio de lista branca de comandos, configuração de proxy (Proxy), mecanismo de plug-in de ganchos (Hooks) e protocolo de contexto de modelo (MCP) que fornece granularidade de controle preciso.
• SDK e integração de sistemas: Fornecido TypeScript responder cantando Python SDK que suporta chamadas não interativas e personalização profunda.

Usado em ambientes domésticos

começar a usar Claude Code Assegure-se de que o ambiente tenha o Node.js 18 anos ou mais, seguido por npm Instalação global:

npm install -g @anthropic-ai/claude-code

Após a instalação, digite no terminal claude pode ser iniciado. Na primeira vez em que é executado, o usuário é solicitado a passar o /login para fazer login e se inscrever.

devido a Claude Existem barreiras ao processo de registro e pagamento no país, e os usuários podem considerar as duas alternativas a seguir para configurar e usar o Claude Code.

1. usando a API Kimi (Dark Side of the Moon)

O lado escuro da lua (Moonshot AI) Compatibilidade de API Claude Code de formatos de entrada e saída. Os usuários podem se inscrever em sua plataforma aberta API Keye configurando variáveis de ambiente para especificar API endpoints e tokens de autenticação:

export ANTHROPIC_BASE_URL="https://api.moonshot.cn/anthropic" && export ANTHROPIC_AUTH_TOKEN="sk-******"

Após a conclusão da configuração, oClaude Code Pronto para usar.

2. configuração de serviços de proxy local

claude-code-proxy é um software de código aberto Python que leva tudo o que tem a ver com o projeto OpenAI As APIs compatíveis são convertidas para Claude Code Interfaces disponíveis.

Etapas de operação e configuração locais::

1. Faça o download do projeto e instale as dependências:uv sync
2. Criar e modificar arquivos de configuração:cp .env.example .env. Em .env Preencher o arquivo OpenAI compatível API Key responder cantando Base URLe especificar os modelos correspondentes para diferentes complexidades de tarefas.

   OPENAI_API_KEY="sk-your-openai-key"
   OPENAI_BASE_URL="https://api.openai.com/v1"
   BIG_MODEL="gpt-4o"          # 对应 'claude-3-opus'
   MIDDLE_MODEL="gpt-4o"       # 对应 'claude-sonnet-4'
   SMALL_MODEL="gpt-4o-mini"   # 对应 'claude-3.5-haiku'
   

3. Inicie o serviço local:uv run claude-code-proxyO serviço é executado na porta 8082 por padrão.
4. Configure as variáveis de ambiente definindo a variável Claude Code para o proxy local.AUTH_TOKEN Pode ser definido como qualquer caractere para ignorar o prompt de login.

   export ANTHROPIC_BASE_URL="http://localhost:8082" 
   export ANTHROPIC_AUTH_TOKEN="anything"
   

5. Execute-o em um terminal claude Pronto para começar.

Funções principais em detalhes

Claude Code como um AgentPlanejamento autônomo de tarefas, invocando ferramentas e coordenação Sub-Agent A capacidade de fazer isso. Ele lerá os arquivos relevantes e criará o contexto necessário para concluir a tarefa, conforme exigido pela tarefa e com a autorização do usuário.

Configuração de permissões e considerações de segurança

O objetivo da configuração de privilégios é encontrar um equilíbrio entre a eficiência da automação e a segurança do sistema.Claude Code Permitir que comandos arbitrários do shell sejam executados significa que a IA descontrolada pode levar à perda de dados, à corrupção do sistema e até mesmo a violações de dados.

Um risco notável éInjeção imediata. Os invasores podem ocultar instruções mal-intencionadas em comentários de código, documentos ou até mesmo no conteúdo de páginas da Web. Quando Claude Code Ao ler essas informações externas, comandos maliciosos podem ser executados, induzindo-os a divulgar informações confidenciais ou a realizar operações perigosas.

Para controlar o risco.Claude Code É fornecido um mecanismo de gerenciamento de direitos com granularidade fina. Os usuários podem editar manualmente o nível do item .claude/settings.json ou nível de usuário ~/.claude.json para configurar as permissões:

{
"skipPermissions": false,
"allowedTools": ["read", "write"],
"allowCommands": ["node ./scripts/setup.js"],
"denyCommands": ["rm -rf /", "curl http://*"]
}

• skipPermissionsSe deseja ignorar a confirmação manual em cada etapa.
• allowedTools: Permitido Claude Lista de permissões das ferramentas usadas.
• allowCommands/denyCommandsLista branca e lista negra mais granulares em nível de comando.

Para restauração lint Erros como esses são tarefas em lote de baixo risco que podem ser executadas usando o --dangerously-skip-permissions ignora todas as verificações de permissão. No entanto, é altamente recomendável que, em ambientes de contêineres sem acesso à rede (por exemplo, o Docker Dev Containers) em que esse modo é usado para isolar riscos potenciais.

Além disso, é possível usar a interface de interação /permissions ajusta dinamicamente as permissões da sessão atual.

Gerenciamento de memória

Por meio de um arquivo chamado CLAUDE.md os arquivos de memória doClaude Code A memória para informações como contexto do projeto, especificações de codificação, preferências pessoais etc. pode ser mantida entre as sessões. Os arquivos de memória são categorizados em nível de empresa, usuário e projeto e são sobrepostos uns sobre os outros para formar um contexto completo quando carregados.

Na janela interativa, digite # A criação de memória pode ser acionada. Use o botão /init comando.Claude Code Pode examinar automaticamente a base de código e gerar uma visão geral do projeto com um CLAUDE.md Documentação. Por meio da /memory para editar e visualizar a memória.

CLAUDE.md A documentação apóia o uso de @path/to/file A sintaxe importa o conteúdo de outros arquivos para facilitar a referência README ou informações pré-existentes, como arquivos de configuração.

Comandos de barra personalizados

Os comandos de barra são atalhos para prompts de engenharia comumente usados (Prompts). Os usuários podem escrever instruções de tarefas como arquivos Markdown em um diretório específico.Claude Code Ele é automaticamente reconhecido como um comando que pode ser chamado.

• local de armazenamento:
  • Nível do projeto. .claude/commands/ (Chamado. /project:命令名)
  • Nível do usuário. ~/.claude/commands/ (Chamado. /user:命令名)
• entrada de parâmetros:
  • fazer uso de $ARGUMENTS O espaço reservado recebe todos os argumentos após o comando.

Uma criação Hugo Comandos de amostra para o artigo (.claude/commands/posts/new.md):

---
description: 创建一篇新的 Hugo 文章
argument-hint: [title]
model: haiku
---
创建一篇文章，标题为 $ARGUMENTS：
# 文章要求
1.  生成 kebab-case 格式的文件名 (格式: YYYY-MM-DD-标题.md)。
2.  使用 Hugo 命令创建新文件: `hugo new content`。
3.  更新文件的 Front Matter，包含标题、日期和描述。
4.  告诉我预览网站的命令。
# 偏好设置：
文章风格需风趣幽默、通俗易懂。

Chamando o /project:posts:new 介绍 GPT-5(matemática) gênero介绍 GPT-5 Essa peça é então substituída $ARGUMENTSMotorista Claude Executar o fluxo de tarefas definido.

Subagentes personalizados

Sub-Agents são subagentes dedicados, cada um com prompts de sistema separados, janelas de contexto e permissões de ferramentas para tarefas específicas do domínio. Esse design permite que tarefas complexas sejam decompostas, permitindo que o diálogo principal se concentre em metas de alto nível e, ao mesmo tempo, delegue detalhes específicos de execução a subagentes especializados.

Sub-Agents O arquivo de configuração também está no formato Markdown e é armazenado no diretório .claude/agents/ (nível de projeto) ou ~/.claude/agents/ (nível de usuário). Os usuários podem acessar o diretório por meio do comando /agents Criação de subagentes orientada por comando, definindo seus nomes, descrições, ferramentas e modelos disponíveis.

O perfil de subagente gerado (.claude/agents/product-prd-expert.md) Exemplo:

---
name: product-prd-expert
description: 当需要根据用户规格创建专业的产品需求文档 (PRD) 时使用此代理。
tools: Grep, LS, Edit, Write
model: sonnet
color: red
---
You are a senior product manager with 10+ years of experience...

Quando as necessidades do usuário são diferentes das description Quando os campos coincidem, oClaude Code invocará automaticamente esse subagente. O usuário também pode chamar o subagente por meio do comando 使用 product-prd-expert 来生成产品需求 essa diretriz para chamá-la explicitamente.

comando básico

Claude Code Uma série de comandos é fornecida para simplificar as operações diárias:

Ganchos personalizados

Hooks são comandos do Shell definidos pelo usuário que são usados no Claude Code execução em pontos de eventos específicos no ciclo de vida, fornecendo um meio de Claude A maneira pela qual o comportamento é controlado de forma determinística.

• cenário do aplicativo:
  • notificações: Em Claude Alerta os usuários por meio de notificações do sistema quando estiverem aguardando entrada ou solicitando permissões.
  • reformatarExecuta automaticamente após cada edição de arquivo Prettier talvez gofmt.
  • Registro e auditoriaRegistro de todos os comandos executados para verificação de conformidade.

aprovar (um projeto de lei ou inspeção etc.) /hooks pode ser usado para diferentes eventos (por exemplo, o comando PreToolUseePostToolUseeNotification) ganchos de registro. Por exemplo, registre um gancho para o Notification cria um evento macOS Notificação pop-up:

1. estar em movimento /hooks e selecione Notification Eventos.
2. Digite o comando Shell. msg=$(jq -r '.message'); osascript -e "display alert \"Claude Code 通知\" message \"$msg\"". Este é o lugar para usar o jq ferramentas de Claude transmitido JSON Extração da entrada padrão message Campos.
3. Selecione o escopo do gancho (por exemplo local), a configuração é salva no arquivo .claude/settings.local.json Médio.
4. reabrir Claude Code Torne o gancho eficaz.

Ferramenta Hook MCP

Claude Code Os ganchos funcionam perfeitamente com a ferramenta MCP (Model Context Protocol), que segue o protocolo mcp__<server>__<tool> O padrão de nomenclatura do gancho pode ser passado no gancho por meio da função matcher para corresponder.

Exemplo de configuração:

{
"hooks": {
"PreToolUse": [
{
"matcher": "mcp__memory__.*",
"hooks": [
{
"type": "command",
"command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
}
]
},
{
"matcher": "mcp__.*__write.*",
"hooks": [
{
"type": "command",
"command": "/home/user/scripts/validate-mcp-write.py"
}
]
}
]
}
}

Usando a ferramenta MCP

Por meio do protocolo de contexto de modelo (Modelo de protocolo de contextoMCP).Claude Code Pode se conectar a ferramentas e fontes de dados externas, como AirtableeNotioneGitHub etc.

Adição de um servidor stdio local

# 基本语法
claude mcp add <name> <command> [args...]
# 实际示例：添加 Airtable 服务器
claude mcp add airtable --env AIRTABLE_API_KEY=YOUR_KEY \
-- npx -y airtable-mcp-server

-- (traço Claude sinalizadores e comandos próprios passados para o servidor MCP.

Adição de um servidor SSE remoto

# 基本语法
claude mcp add --transport sse <name> <url>
# 实际示例：连接到 Linear
claude mcp add --transport sse linear https://mcp.linear.app/sse

Adição de um servidor HTTP remoto

# 基本语法
claude mcp add --transport http <name> <url>
# 实际示例：连接到 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

Gerenciamento de serviços MCP

# 列出所有配置的服务器
claude mcp list
# 获取特定服务器的详细信息
claude mcp get github
# 删除服务器
claude mcp remove github

Faixa de instalação

fazer uso de --scope pode especificar onde a configuração é armazenada:local (padrão, somente o projeto atual),project (por meio de .mcp.json compartilhado com a equipe),user (disponível em todos os projetos).

Integração do SDK do Claude Code

Para cenários não interativos, oClaude Code ofertas TypeScript responder cantando Python O SDK é essencialmente um invólucro em torno de sua funcionalidade de linha de comando, permitindo que os desenvolvedores chamem o Claude Code A capacidade do

seguintes Python Exemplos básicos de uso do SDK:

import asyncio
from claude_code_sdk import (
AssistantMessage,
ClaudeCodeOptions,
ClaudeSDKClient,
UserMessage,
)
async def interact_with_claude():
# 配置客户端选项
options = ClaudeCodeOptions(
model="claude-3-5-sonnet-20241022",
system_prompt="你是一个专业的软件开发助手",
allowed_tools=["Bash", "Read", "Edit"],
permission_mode="acceptEdits" # 自动接受文件编辑权限
)
# 创建客户端实例
async with ClaudeSDKClient(options=options) as client:
# 发送消息
await client.query("帮我检查项目中的潜在 bug")
# 接收和处理响应
async for message in client.receive_messages():
if isinstance(message, AssistantMessage):
print(f"Claude: {message.content}")
if __name__ == "__main__":
asyncio.run(interact_with_claude())

consulta

1. Documentação oficial do Claude Code - https://docs.anthropic.com/en/docs/claude-code/
2. Guia completo de Siddharth Bharath sobre o código Claude - https://www.siddharthbharath.com/claude-code-the-complete-guide/
3. Guia de Configuração do Código Claude da Fuszti - https://fuszti.com/claude-code-setup-guide-2025/
4. Fluxos de trabalho comuns do Claude Code - https://docs.anthropic.com/en/docs/claude-code/common-workflows
5. Documentação do Claude Code SDK - https://docs.anthropic.com/en/docs/claude-code/sdk
6. Configuração de agência corporativa - https://docs.anthropic.com/en/docs/claude-code/corporate-proxy