Guia prático completo do Claude Code: solução completa para instalação, configuração de modelos domésticos e prática avançada.

As ferramentas de programação de IA estão evoluindo de "remendadores" de código passivos para "parceiros de desenvolvimento" ativos. Elas são capazes de entender requisitos complexos, planejar tarefas e participar diretamente de todo o processo de desenvolvimento. Neste artigo, daremos uma olhada detalhada em uma ferramenta de programação de IA de linha de comando que representa essa tendência - uma ferramenta que chamamos de Claude Codee fornece um guia detalhado e completo para seu uso.

Ideias para uma nova geração de assistentes de programação de IA

Diferentemente dos plug-ins de IDE conhecidos, oClaude Code Essas ferramentas escolhem uma interface mais próxima do fluxo de trabalho principal do desenvolvedor: a linha de comando (CLI).

A interface de linha de comando é simples e eficiente

Esse design não é por acaso. Para os desenvolvedores, a linha de comando é leve, pode ser programada e se integra perfeitamente a ferramentas como o Git. A injeção de recursos de IA nessa área central torna-a parte do fluxo de trabalho e não um recurso isolado. As ferramentas da mesma categoria incluem o Ali's Qwen Code e do Google Gemini CLI.

 
Interfaces de ferramentas de programação de IA CLI semelhantes

Modelos avançados e ecossistema de API

Claude Code A capacidade de fazer isso decorre dos grandes modelos de linguagem de primeira linha por trás dele, como os desenvolvidos pelo Antrópica Empresa desenvolvida Claude 3 OpuseClaude 3.5 Sonnet Fundada por Dario Amodei, ex-membro do núcleo da OpenAI, os modelos da Anthropic são líderes permanentes do setor em programação e raciocínio.

mesmo que Claude Code O modelo Anthropic oficial é usado por padrão, mas seu alto custo limita seu uso por desenvolvedores individuais. Felizmente, podemos configurá-lo para se conectar a modelos caseiros mais econômicos, como o Wisdom Spectrum's GLM-4.5 ou o lado escuro da lua Kimi K2.

Um detalhe técnico importante é o formato da API. Embora a maioria dos grandes modelos seja compatível com o formato de chamada da OpenAI, o Anthropic tem seu próprio conjunto de especificações.Claude Code O formato Anthropic é usado, portanto, os provedores de serviços de modelo que também suportam esse formato são suportados nativamente. Os modelos que suportam apenas o formato OpenAI precisam ser conectados por meio de uma ferramenta de conversão.

Além disso.Claude Code É uma inteligência bem projetada por si só, com prompts de sistema incorporados que são profundamente otimizados para os recursos do próprio modelo do Anthropic. Ao substituí-lo por um modelo de terceiros, pode haver cerca de 5% até que 20% a perda de eficácia. Entretanto, para a grande maioria dos cenários de desenvolvimento, esse impacto está dentro dos limites aceitáveis, desde que os requisitos sejam claramente descritos.

De "assistentes" a "parceiros"

Os plug-ins tradicionais de programação de IA, como o antigo Tongyi Linguistic Code, são limitados pelos recursos do modelo e pela extensão do contexto e servem principalmente como "pranchetas" e ferramentas de diálogo único.Claude Code Essa nova geração de ferramentas é capaz de entender toda a pasta do projeto, com planejamento autônomo e recursos multitarefa para tarefas complexas.

Em vez de apenas gerar trechos de código, ele pode editar arquivos diretamente, executar testes, executar comandos de compilação e até mesmo lidar com confirmações do Git. A função do desenvolvedor deixa de ser a de um "executor" de tarefas e passa a ser a de um "delegador" de projetos complexos, entrando no chamado "mundo do trabalho". VibeCoding(Ambient Programming) - definindo requisitos, projetando a arquitetura e, em seguida, supervisionando a IA por meio de tarefas específicas de codificação.

Guia completo de instalação e configuração

Este tutorial usa o macOS como exemplo, mas o procedimento é semelhante no Windows.

Etapa 1: Instalação rápida

Certifique-se de que o Node.js esteja instalado em seu sistema (versão >= 18) e, em seguida, execute o seguinte comando para instalá-lo globalmente:

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

Após a conclusão da instalação, execute em qualquer diretório do projeto claude para iniciá-lo.

# 进入你的项目目录
cd your-awesome-project
# 启动 Claude Code
claude
# 首次使用时，可能会提示登录

Etapa 2: Tratamento de restrições regionais e configuração de modelos domésticos

Se você encontrar uma mensagem informando que uma região não está disponível na primeira execução, poderá configurar variáveis de ambiente para fazer o proxy da solicitação para um provedor de serviços de modelo doméstico compatível com o formato da API Anthropic.

Problemas com restrições regionais que podem ser encontrados durante a execução inicial

Abra o arquivo de configuração do terminal (o padrão do macOS é .zshrc), adicione as duas linhas a seguir:

# 使用 vi 编辑配置文件。新手提示：打开后按 i 进入插入模式，
# 粘贴内容后按 ESC，然后输入 :wq 回车即可保存退出。
vi ~/.zshrc

Adicione o seguinte ao arquivo:

export ANTHROPIC_BASE_URL=你的模型调用地址
export ANTHROPIC_API_KEY=你的API密钥

Depois de salvar e sair, certifique-se de executar o comando source ~/.zshrc para que a configuração tenha efeito imediato.

Exemplo de configuração 1: Modelo Smart Spectrum GLM-4.5

1. Registro e obtenção de uma chave de API: AcessoPlataforma aberta de IA Smart SpectrumRegistre-se comPágina de gerenciamento de chaves de APICriar uma nova chave.
   
2. Pacotes opcionais (opcional)O Smart Spectrum oferece aos desenvolvedores uma solução econômicaPacotes de programaçãoO custo do serviço é de cerca de US$ 20 no primeiro mês, com muitas chamadas.
   
3. Configuração de variáveis de ambienteO endereço compatível com a antropologia do Smart Spectrum é https://open.bigmodel.cn/api/anthropic.

   export ANTHROPIC_BASE_URL=https://open.bigmodel.cn/api/anthropic
   export ANTHROPIC_API_KEY=粘贴你的智谱API密钥
   

4. Configuração em vigor e reinicialização: Implementação source ~/.zshrc Depois disso, execute novamente o claude Comando.

Exemplo de configuração 2: modelo Dark Side of the Moon Kimi K2

1. Registro e recarga: AcessoPlataforma de desenvolvedores do Dark Side of the MoonRegistro. Para garantir a taxa de chamada, é recomendável fazer uma recarga de US$ 50 ou mais.
   
2. Obter chave de APICrie uma nova chave de API no sistema de gerenciamento de back-end.
   
3. Configuração de variáveis de ambienteO endereço compatível com a Antropologia de Kimi é https://api.moonshot.cn/anthropic/.

   export ANTHROPIC_BASE_URL=https://api.moonshot.cn/anthropic/
   export ANTHROPIC_API_KEY=粘贴你的KimiAPI密钥
   

4. Configuração em vigor e reinicialização: Implementação source ~/.zshrc Depois disso, execute novamente o claude Comando.

Etapa 3: rotear para qualquer modelo de formato OpenAI

Para usar um modelo que seja compatível apenas com o formato OpenAI (por exemplo, Tongyi Qianqian), você pode usar a opção ClaudeCodeRouter middleware para realizar a conversão.

1. Instalação do roteador::

   npm install -g @musistudio/claude-code-router
   

   Seus principais recursos incluem roteamento de modelos, suporte a vários provedores e transformação de solicitação/resposta.

2. Início da interface de configuração::

   ccr ui
   

   Na página que se abre, adicione o provedor de modelo, selecione o modelo e preencha a chave de API e o nome do modelo.
   
   

3. Configuração de roteamento::
   Na seção de roteamento à direita, aponte diferentes tarefas (por exemplo, pensar, contexto longo) para o modelo que acabou de adicionar, depois salve e reinicie.
   
4. ativar (um plano) Claude Code::
   fazer uso de ccr code é iniciado, o modelo configurado pode ser usado por meio dessa rota.
   

Etapa 4: Integração ao IDE

Claude Code São fornecidos plug-ins aprimorados para o VS Code e para a família de IDEs da JetBrains (IntelliJ IDEA, WebStorm etc.), que podem ser iniciados com um clique no IDE para facilitar a interação.

Instalação de plug-ins no IDE

Início com um toque, integração perfeita

Dicas de uso principais em detalhes

Interação básica

• @ notaçãoReferência a um arquivo ou diretório a ser adicionado ao contexto.
• # notaçãoDefinem memórias ou regras que a IA seguirá nas interações subsequentes.
• ! notaçãoModo bash: Alterna temporariamente para o modo bash para executar comandos do shell.
• ESC pino de ligaçãoInterrupção da tarefa em execução no momento: interrompe a tarefa em execução no momento.
• entrada de várias linhas: Uso Shift+Enter talvez Option+Enter (macOS) Digite um texto com várias linhas. Você pode executar /terminal-setup montagem Shift+Enter Atalhos.

Lista completa de comandos

importação / O menu de comandos pode ser acessado, e a seguir há uma lista completa de comandos:

/add-dir                  添加一个新的工作目录
/agents                   管理代理配置
/bashes                   列出和管理后台任务
/clear (reset, new)       清除对话历史并释放上下文
/compact                  清除对话历史，但在上下文中保留摘要。可选：/compact [摘要说明]
/config (theme)           打开配置面板
/context                  将当前上下文使用情况可视化为彩色网格
/cost                     显示当前会话的总成本和持续时间
/doctor                   诊断并验证您的 Claude Code 安装和设置
/exit (quit)              退出 REPL
/export                   导出当前对话到文件或剪贴板
/feedback (bug)           提交关于 Claude Code 的反馈
/help                     显示帮助和可用命令
/hooks                    管理工具事件的钩子配置
/ide                      管理 IDE 集成并显示状态
/init                     使用代码库文档初始化一个新的 CLAUDE.md 文件
/install-github-app       为代码仓库设置 Claude GitHub Actions
/login                    使用您的 Anthropic 帐户登录
/logout                   从您的 Anthropic 帐户注销
/mcp                      管理 MCP 服务器
/memory                   编辑 Claude 内存文件
/migrate-installer        从全局 npm 安装迁移到本地安装
/model                    设置 Claude Code 的 AI 模型
/output-style             直接或从选择菜单设置输出样式
/output-style:new         创建一个自定义输出样式
/permissions              管理允许和拒绝工具的权限规则
/pr-comments              从 GitHub 拉取请求中获取评论
/release-notes            查看发行说明
/resume                   继续一个对话
/review                   审查一个拉取请求
/security-review          完成对当前分支上待定更改的安全审查
/status                   显示 Claude Code 状态
/statusline               设置 Claude Code 的状态行用户界面
/terminal-setup           安装 Shift+Enter 换行快捷键
/todos                    列出当前的待办事项
/upgrade                  升级到 Max 以获得更高的速率限制
/vim                      在 Vim 和普通编辑模式之间切换

Análise aprofundada de comandos comuns

• /init:: Geração de projetos de digitalização CLAUDE.mdcontendo resumos da pilha de tecnologia, arquitetura, etc., para ajudar a IA a entender rapidamente o projeto.
• /compactoResumir longos históricos de diálogo para preservar informações importantes, conservar o token e manter o foco da IA.
• /limparDiálogo: Esvazie completamente o diálogo atual e abra um novo.
• /resumo:: Restaura o histórico de diálogos recentes e continua as tarefas anteriores.
• /memóriaEdição: Edite uma série de arquivos Markdown para definir preferências comportamentais de longo prazo (por exemplo, estilo de codificação, personalidade) para a IA. Esses arquivos estão localizados na pasta ~/.claude dividido em nível global e de projeto. Por exemplo.rules.md O arquivo pode conter os seguintes princípios de programação:

  你的任务是：**审查、理解并迭代式地改进/推进一个[项目类型，例如：现有代码库 / 软件项目 / 技术流程]。**
  在整个工作流程中，你必须内化并严格遵循以下核心编程原则，确保你的每次输出和建议都体现这些理念：
  - **简单至上 (KISS):** 追求代码和设计的极致简洁与直观，避免不必要的复杂性。
  - **精益求精 (YAGNI):** 仅实现当前明确所需的功能，抵制过度设计和不必要的未来特性预留。
  - **坚实基础 (SOLID):**
  - **S (单一职责):** 各组件、类、函数只承担一项明确职责。
  - **O (开放/封闭):** 功能扩展无需修改现有代码。
  - **L (里氏替换):** 子类型可无缝替换其基类型。
  - **I (接口隔离):** 接口应专一，避免"胖接口"。
  - **D (依赖倒置):** 依赖抽象而非具体实现。
  - **杜绝重复 (DRY):** 识别并消除代码或逻辑中的重复模式，提升复用性。
  - **文档同步 (Doc Sync):** 代码变更必须同步更新相关文档，保持一致性。
  **请严格遵循以下工作流程和输出要求：**
  1.  **深入理解与初步分析（理解阶段）：**
      - 详细审阅提供的[资料/代码/项目描述]，全面掌握其当前架构、核心组件、业务逻辑及痛点。
      - 在理解的基础上，初步识别项目中潜在的**KISS, YAGNI, DRY, SOLID**原则应用点或违背现象。
  2.  **明确目标与迭代规划（规划阶段）：**
      - 基于用户需求和对现有项目的理解，清晰定义本次迭代的具体任务范围和可衡量的预期成果。
      - 在规划解决方案时，优先考虑如何通过应用上述原则，实现更简洁、高效和可扩展的改进，而非盲目增加功能。
  

Recursos avançados: personalização e automação

Comandos personalizados

Encapsule tarefas complexas comuns em comandos personalizados. Basta escrever um arquivo Markdown contendo o prompt (o nome do arquivo é o nome do comando, por exemplo add-changelog.md), insira o ~/.claude/commands/ reinicie para passar o diretório /add-changelog Chamada. Sites da comunidade https://www.buildwithclaude.com/ Um grande número de comandos predefinidos é fornecido para download.

Sistema de subagentes

Crie várias "subinteligências" dedicadas (por exemplo, especialistas em front-end, designers de UX), e a inteligência principal pode dividir e atribuir tarefas automaticamente com base em requisitos complexos, permitindo a colaboração paralela entre várias funções.

aprovar (um projeto de lei ou inspeção etc.) /agents Gerenciamento de comandos com a opção de fazer com que a IA ajude a criar novos agentes ou importar predefinições da comunidade.

Criação de subagentes assistida por IA

Ao lidar com uma tarefa que inclui o design da interface do usuário, o corpo inteligente principal chamará primeiro o designer de UX e, em seguida, o código após a confirmação do design. A IA gerará uma lista de tarefas ao executar a tarefa e a concluirá item por item, com um fluxo de trabalho altamente transparente.

Sistema de ganchos

Aciona comandos automaticamente quando ocorre um evento específico (por exemplo, após a edição de um arquivo). Os comandos são acionados automaticamente pela função /hooks Gerenciamento de instruções para processos automatizados, como formatação automática e controle de permissões.

Exemplo: Formatação automática com o Prettier após a edição de um arquivo TS

{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|MultiEdit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
}
]
}
]
}
}

Ferramentas comunitárias claudecode-rule2hook Suporte para gerar configurações de hooks em linguagem natural.

Configuração do servidor MCP

O MCP (Machine-to-Claude Protocol) é um protocolo que permite que ferramentas e serviços externos se comuniquem com o Claude Code para comunicação, que podem ser estendidos com recursos como a conexão com o Jira, o Notion e assim por diante.

• Adição de um servidor MCP Stdio local:

  claude mcp add airtable --env AIRTABLE_API_KEY=YOUR_KEY -- npx -y airtable-mcp-server
  

• Adicionar servidor MCP SSE:

  claude mcp add --transport sse linear https://mcp.linear.app/sse
  

• Gerenciamento do servidor MCP:

  # 列出所有服务器
  claude mcp list
  # 删除服务器
  claude mcp remove github
  

Dicas de palavras-chave e padrões de trabalho

Dicas de estruturação de tags XML

O uso de tags XML para agrupar instruções, contexto e exemplos ajuda o Claude a entender sua intenção com mais precisão.

<instruction>
你希望 Claude 执行的主要任务或目标
</instruction>
<context>
任务的背景信息，比如涉及的框架、业务逻辑、团队规范等
</context>
<code_example>
可以参考的代码片段、接口规范或已有实现
</code_example>

Comutação de três modos operacionais

fazer uso de Shift+Tab Troca de ciclo:

1. modo normalModo padrão: No modo padrão, é necessária a aprovação do usuário antes de realizar operações como a edição de arquivos.
2. Modo de aceitação automáticaTodas as operações são aprovadas por padrão e a IA tem controle total.
3. modo de planejamentoA IA apenas planeja e gera uma lista de tarefas sem executar nenhuma operação real.

Outras ferramentas e recursos úteis

• histórico de regressão: clique duas vezes ESC Os nós de diálogo podem ser revertidos. Para reversões de alterações de código, use a ferramenta da comunidade ccundo (npm install -g ccundo).
• Código operacional da ferramenta de configuração visual:: Site https://opcode.sh/ Oferece uma interface da Web avançada para o gerenciamento de visualizações Claude Code Todas as configurações, incluindo comandos personalizados, ganchos, permissões, etc., do
  
  
• Guia Oficial Chinês Claude: documento oficial Fornece a introdução mais abrangente e autorizada às funções e instruções de uso.
  

Uma nova geração de ferramentas de programação de IA está remodelando os fluxos de trabalho de desenvolvimento, liberando os desenvolvedores da tediosa execução de códigos para que se concentrem mais no projeto arquitetônico e na inovação comercial. Dominar essas ferramentas é adotar o paradigma de desenvolvimento do futuro.