São 14h de uma quarta-feira. Você abre um .prw de 2008 — 1.200 linhas, comentários em portunhol, variáveis tipo cVar1, três níveis de IF aninhado e um RecLock sem MsUnlock escondido na linha 847. Aperta Ctrl+F9. Console do TDS-VSCode cospe: ERROR: 'EXEMPLO' is not declared. Linha errada, mensagem genérica, zero contexto. Você já está na quarta xícara de café.

Esse é o ponto onde o TOTVS Developer Studio for VSCode termina e o Claude AI começa. Um resolve a parte mecânica do desenvolvimento Protheus — compila, debuga, conecta no AppServer, gera patch. O outro resolve a parte cognitiva — entende o que o erro quer dizer, aponta o lock perdido na linha 847 antes de você compilar, e refatora o monstro pra algo legível em 30 segundos. Os dois juntos no mesmo workspace mudam o jogo.

O que o TDS-VSCode já entrega

A extensão oficial da TOTVS (github.com/totvs/tds-vscode) é uma suíte completa de desenvolvimento Protheus baseada em LSP (Language Server Protocol) e DAP (Debug Adapter Protocol). Ela faz o trabalho pesado: compilação remota via AppServer (atalho Ctrl+F9), debug com SmartClient integrado ao tipo de launch totvs_language_debug, geração de patches, manutenção de RPO, monitor de servidor, web service client, replay de execução. Encoding fixo cp1252 (Windows1252) pra preservar acentos no fonte. Suporta AdvPL, TLPP e 4GL nativamente.

O que ela não faz é entender o seu código. Ela compila — mas não te diz que aquele RecLock nunca é fechado. Ela mostra o erro — mas em inglês cru, sem explicar a causa. Ela permite refatorar — mas você quem digita.

Onde a extensão para e o Claude começa

TarefaTDS-VSCodeClaude AI
Compilar fonteSim (Ctrl+F9, AppServer)Não compila
Debug step-by-stepSim (SmartClient)Não acessa runtime
Conectar no AppServerSim (LSP nativo)Não
Detectar lock sem unlockNão (linter sintático)Sim (semântico)
Explicar erro de compilação em pt-BRNãoSim
Refatorar legado preservando comportamentoNãoSim
Gerar doc no estilo TDNNãoSim
Detectar SQL sem D_E_L_E_T_NãoSim
Sugerir boilerplate de MSExecAutoNãoSim

O ponto não é substituir o TDS-VSCode — é parar de pedir pra ele fazer o que ele nunca foi feito pra fazer. Compilação, conexão, debug seguem com a extensão. Tudo que envolve entender o código vai pro Claude.

Setup combinado

As duas extensões convivem no mesmo workspace sem brigar. O TDS-VSCode mantém o cache dele em .vscode/.advpl/ (arquivos _binary_class.prw e _binary_functions.prw com índice de classes/funções pra autocomplete) e .vscode/.linter/. O Claude Code lê os .prw e .tlpp direto da pasta do projeto.

Pequeno detalhe técnico: o TDS-VSCode salva fonte em cp1252 por exigência do AppServer. O Claude Code lê em UTF-8 por default — se aparecer caractere estranho ao colar fonte no chat, é encoding. Solução: salvar uma cópia temporária em UTF-8, ou pedir pro Claude ignorar acentos do header.

launch.json típico de quem usa as duas:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "totvs_language_debug",
      "request": "launch",
      "name": "TOTVS Language Debug",
      "program": "${command:AskForProgramName}",
      "smartclientBin": "../totvs/bin/smartclient/smartclient.exe",
      "isMultiSession": true,
      "enableTableSync": true
    }
  ]
}

Workflow 1: Code review antes de Ctrl+F9

Antes de mandar pro AppServer compilar, peça revisão semântica. Prompt copy-paste:

revisa esse fonte AdvPL antes de eu compilar.
foco em: 
 - RecLock sem MsUnlock
 - SQL sem D_E_L_E_T_ = ' '
 - variáveis nao declaradas (LOCAL/PRIVATE/PUBLIC)
 - User Function sem prefixo do projeto
 - alocacao de recurso sem free

[cole o fonte aqui]

Resposta típica do Claude num fonte real:

3 problemas:
1. Linha 47: RecLock("SE1", .F.) abre lock mas o MsUnlock() só está dentro do bloco If — se cair no Else, o registro fica travado. Mover pra fora do EndIf.
2. Linha 89: TCQuery sem filtro D_E_L_E_T_ = ' ' — vai retornar registros logicamente deletados como se estivessem ativos.
3. Linha 12: cAux usada sem declaração — vira PUBLIC implícito, contamina escopo do chamador.

O TDS-VSCode nunca aponta isso — não é trabalho dele. O linter sintático dele acha typo, função inexistente, parêntese faltando. Padrão semântico é outra liga.

Workflow 2: Diagnosticar erro de compilação

Compilou e bateu erro. Em vez de googlar, copia a mensagem do Output do TDS-VSCode e pergunta direto:

esse erro veio do TDS-VSCode ao compilar:

Error: ERROR LINE 47: 'EXEMPLO' is not declared

fonte:
[cola as 50 linhas em volta]

o que pode ser?

Resposta típica:

Causa provável: você está chamando EXEMPLO() mas a função não está definida no escopo. 3 hipóteses por ordem de probabilidade:
1. Esqueceu o prefixo U_ — se for User Function, a chamada deve ser U_EXEMPLO().
2. Falta #INCLUDE do header .ch que declara EXEMPLO como #XCOMMAND ou #TRANSLATE.
3. Função existe em outro .prw mas não foi incluída no RPO da compilação.

Você não precisa abrir 4 abas do TDN nem perguntar no grupo do WhatsApp — vem em 5 segundos.

Workflow 3: Refatorar fonte legado

Função de 2008 com 5 níveis de aninhamento e variáveis cVar1/nVar2:

refatora pra AdvPL moderno:
 - nomes claros (cClienteCod ao invés de cVar1)
 - early-return ao invés de if aninhado
 - extrai validações em funções pequenas
 - mantém comportamento idêntico
 - preserva o header de copyright

[cola fonte legado]

Claude entrega versão refatorada lado a lado. Cuidado importante: rode os testes de regressão antes de subir. IA refatora bem, mas em fluxo financeiro/fiscal qualquer mudança sutil de comportamento pode estourar conciliação.

Workflow 4: Gerar documentação no estilo TDN

Função sem comentário? Cola o corpo e peça:

gera o header de documentacao no estilo TDN para essa funcao.
formato: bloco de comentarios com Funcao, Descricao, 
Uso, Parametros, Retorno, Historico (data + autor + alteracao).
semana atual: 06/05/2026, autor: Mayco.

Saída pronta pra colar antes da função:

/*/{Protheus.doc} ATSaldoReal
Retorna o saldo real de um título considerando 
baixas, abatimentos e juros vinculados.

@type Function
@author Mayco
@since 06/05/2026
@version 1.0

@param cPrefixo, character, prefixo do título
@param cNum,     character, numero do título
@param cParcela, character, parcela
@param cTipo,    character, tipo do título

@return numeric, saldo real, ou -1 se nao encontrado
/*/

Workflow 5: Boilerplate de User Function

Pra começar uma rotina nova sem ficar caçando exemplo no Slack:

gera boilerplate de User Function que faz inclusao de produto via
MSExecAuto chamando MATA010, com:
 - PRIVATE lMsErroAuto e lMsHelpAuto
 - Begin Transaction com DisarmTransaction em erro
 - GetAutoGrLog pra captura
 - GetArea/RestArea
 - retorno {lOk, cMsg}

O Claude entrega o esqueleto pronto. Você ajusta os 3-4 campos específicos do seu caso e está livre pra focar no que importa: a regra de negócio.

O que NÃO delegar pro Claude

Tem coisa que IA não faz. Pra você não cair em armadilha:

  • Não compila. Compilação só rola via TDS-VSCode + AppServer. Claude não tem RPO, não conhece sua versão do Protheus, não roda .prw.
  • Não vê estado de runtime. Variáveis em memória, conteúdo da SE1, MV_PARs no ambiente atual — invisíveis. Pra debug ao vivo, é TDS-VSCode com breakpoint.
  • Pode alucinar nomes de função. Especialmente em TLPP recente (versão 12.1.NN), Claude pode citar uma FwSomething() que não existe na sua build. Sempre cruze com o TDN.
  • Não substitui code review humano em mudança crítica. Sempre que tocar em fluxo fiscal, contábil, financeiro: olho humano experiente, mais teste de regressão, mais ambiente de homologação. Claude é primeiro filtro, não único.

8 prompts prontos para o seu dia

TarefaPrompt resumido
Review pré-compilerevisa fonte AdvPL: locks, SQL sem D_E_L_E_T_, vars nao declaradas
Explicar erroesse erro do TDS-VSCode + fonte em volta. o que pode ser?
Refatorar legadorefatora pra AdvPL moderno: nomes claros, early-return, mantem comportamento
Gerar header TDNgera Protheus.doc dessa funcao com Funcao/Descricao/Param/Return/Historico
Boilerplate ExecAutoboilerplate User Function MSExecAuto MATA010 com tratamento de erro
Validar SQLauditar essa TCQuery: filial, D_E_L_E_T_, performance, indices
AdvPL → TLPPtraduz essa funcao AdvPL para TLPP moderno com tipagem e namespace
Auditar performanceidentifica gargalos nesse loop: SaldoTit/Posicione/SQL em loop

O fluxo de dev com IA

flowchart TD Start[Editar .prw] --> Review[Pedir review
ao Claude AI] Review --> Issues{Achou
problema?} Issues -->|Sim| Fix[Aplicar fix sugerido] Fix --> Compile Issues -->|Nao| Compile[Ctrl+F9 no TDS-VSCode] Compile --> ErrComp{Erro de
compilacao?} ErrComp -->|Sim| Diag[Colar erro no Claude
pra diagnostico] Diag --> Fix ErrComp -->|Nao| Debug[Debug no SmartClient
via TDS-VSCode] Debug --> RunErr{Erro em
runtime?} RunErr -->|Sim| Inspect[Inspecionar variaveis
no debugger TDS] Inspect --> AskAI[Perguntar Claude
com contexto coletado] AskAI --> Fix RunErr -->|Nao| Done[Subir pra homologacao]

O caminho daqui

O TDS-VSCode expõe uma API pública com métodos como generatePPO, createProtheusServer e apiTlppTools — em tese, dá pra construir uma extensão que orquestra Claude e TDS-VSCode juntos: revisão automática antes de cada Ctrl+F9, diagnóstico de erro injetado direto no Problems do VSCode, geração de doc disparada pelo menu de contexto. Hoje é manual (você cola o fonte, pergunta, aplica). Amanhã pode ser plug-in.

Por enquanto, o ganho já está em parar de tratar a IA como gimmick. Use como ferramenta de pensamento técnico — review, diagnóstico, refatoração, doc — e mantenha TDS-VSCode pro que ele faz bem: compilar, debugar, conectar. Os dois juntos cortam ciclos de minutos pra segundos. Pra dev Protheus em 2026, esse é o stack mínimo viável.

Topa testar a skill?

A claude-advpl-skill v0.2.0 esta liberada — open source, MIT, sem trava. Baixar ZIP v0.2.0 (64 KB) →

Instalacao em 30 segundos
unzip claude-advpl-skill-v0.2.0.zip
cd claude-advpl-skill
bash install.sh    # Linux/Mac/Git Bash
# ou
.install.ps1     # Windows nativo

Depois disso, em qualquer sessao Claude Code:

  • /advpl-setup — instala e valida ambiente (1x apenas)
  • /advpl-validate arquivo.prw — pre-compile local, sem AppServer
  • /advpl-servers — lista AppServers configurados na sua extensao TDS-VSCode
  • /advpl-compile arquivo.prw — compila no AppServer remoto (auto-detecta servers do TDS-VSCode)

Lancamento v0.2.0: nova skill /advpl-find-issues faz analise estatica profunda de fontes AdvPL/TLPP com 9 regras (RecLock sem MsUnlock, SQL sem D_E_L_E_T_, Function nua, For sem Local, MemoWrite esquecido, e mais). Aceita arquivo ou pasta recursiva. Total: 7 skills + 11 templates + parser AdvPL. Open source, MIT.

Feedback, bug ou ideia pra v0.2? comercial@archtecgroup.com.br