@farm-investimentos/claude-workflow

CLI para setup e manutenção do workflow Claude Code da FarmTech.

Instala e gerencia: vault Obsidian, modos cognitivos, templates, hooks de formatação, integração Jira/GitHub e configuração do Claude Code — tudo cross-platform (macOS, Linux e Windows).

Instalação

npm install -g @farm-investimentos/claude-workflow

Requer Node.js 18+.

Se o registry não for encontrado automaticamente:

npm install -g @farm-investimentos/claude-workflow --registry https://registry.npmjs.org

Para configurar o scope permanentemente:

npm config set @farm-investimentos:registry https://registry.npmjs.org

Setup inicial

farmtech-claude init

Wizard interativo em 9 etapas:

1. Dados pessoais (nome, email)
2. Jira (URL, email, API token)
3. Credenciais opcionais (MySQL, AWS)
4. Path do vault pessoal
5. Vault compartilhado (clona o repo Git da equipe)
6. Instalação do CLAUDE.md e settings.json
7. Vault + hooks + credenciais
8. RTK — instala automaticamente o RTK (token optimizer)
9. Integração com shell (zsh/bash/PowerShell)

Comandos

Para ver todos os comandos disponíveis:

farmtech-claude --help

Para ver detalhes de um comando específico:

farmtech-claude <comando> --help

Setup e manutenção

| Comando | Descrição | |---------|-----------| | farmtech-claude init | Setup completo (wizard interativo) | | farmtech-claude doctor | Verifica saúde da instalação | | farmtech-claude update | Atualiza assets (modos, templates, hooks) | | farmtech-claude update --only vault | Atualiza apenas o vault |

Projetos

farmtech-claude project init ./meu-projeto

Detecta automaticamente stack, arquitetura, banco, porta, dependências e gera:

• Projetos/<nome>/overview.md no vault
• <projeto>/.claude/CLAUDE.md com build/run/test

Stacks suportadas: Spring Boot, NestJS, Node.js, Python, Rust, Go.

Jira

| Comando | Descrição | |---------|-----------| | farmtech-claude jira fetch SC-1234 | Busca ticket e retorna em Markdown | | farmtech-claude jira create-subtask SC-1234 "Implementar X" | Cria subtask | | farmtech-claude jira update SC-1234 descricao.json | Atualiza descrição (ADF) | | farmtech-claude jira config | Reconfigura credenciais do Jira |

GitHub

| Comando | Descrição | |---------|-----------| | farmtech-claude github apply-suggestions | Aplica sugestões do PR atual | | farmtech-claude github apply-suggestions 42 | PR específico | | farmtech-claude github apply-suggestions --dry-run | Preview sem aplicar | | farmtech-claude github apply-suggestions --user ana | Filtrar por autor |

Vault compartilhado

O vault compartilhado é um repo Git (Farm-Investimentos/vault-shared) clonado em ~/dev/vault-shared/. Ele armazena o conhecimento coletivo da equipe: aprendizados cross-project e decisões arquiteturais por projeto.

Arquitetura dual-vault:

| Vault | Path | Conteúdo | Sync | |-------|------|----------|------| | Pessoal | ~/dev/vault-claude/ | Sessões, overview, bugs, queries, specs | Local only | | Compartilhado | ~/dev/vault-shared/ | Aprendizados, decisões por projeto | Git (push/pull) |

O que o Claude faz automaticamente:

• No início da sessão: faz git pull silencioso no vault compartilhado e lê decisões + aprendizados relevantes
• Durante a sessão: escreve decisões arquiteturais e aprendizados cross-project no vault compartilhado
• No final da sessão: avisa se há contribuições pendentes para publicar

O que o dev faz manualmente:

farmtech-claude sync pull                           # Atualizar do remote
farmtech-claude sync push                           # Publicar mudanças locais
farmtech-claude sync status                         # Ver o que mudou
farmtech-claude share Aprendizados/minha-nota.md    # Promover nota pessoal para o shared

Estrutura do vault compartilhado:

vault-shared/
├── Aprendizados/
│   ├── 2026-05-11-queries-contagem-divergentes.md
│   ├── 2026-05-11-inner-join-relatorios-silencioso.md
│   └── ...
└── Projetos/
    ├── received-invoices-spring-api/
    │   └── decisoes.md
    └── operacao-elegibilidade-api/
        └── decisoes.md

Convenções:

• Naming de aprendizados: YYYY-MM-DD-<titulo-kebab>.md
• Decisões: mais recente no topo do arquivo
• Notas em português, tags Obsidian no final
• Sem credenciais, sem dados pessoais

Para quem já tem v1 instalado:

npm install -g @farm-investimentos/claude-workflow@latest
farmtech-claude init

O wizard detecta a instalação existente e pede apenas os dados do vault compartilhado. Regenera o ~/.claude/CLAUDE.md com o protocolo dual-vault.

Exemplos de prompts

Depois do setup, abra o Claude Code em qualquer projeto onboardado e use os modos cognitivos:

Bug fix (Modo DEBUG)

Modo: DEBUG
A API /api/invoices retorna 500 quando o campo dueDate é null.
Ticket: GI-4521

Feature nova (Modo PLANNING)

Modo: PLANNING
Preciso adicionar filtro por data no endpoint GET /api/transactions.
Ticket: SC-2891

Implementação (Modo CODING)

Modo: CODING
Implementar o plano em specs/2026-05-10-SC-2891-plano-implementacao.md

Refatoração (Modo REFACTOR)

Modo: REFACTOR
O service TransactionService tem 3 métodos que fazem queries muito parecidas.
Consolidar sem mudar comportamento.

Revisão de PR (Modo REVIEW)

Modo: REVIEW
Revisar o PR #142 — adiciona endpoint de elegibilidade.

Decisão arquitetural (Modo ARCHITECTURE)

Modo: ARCHITECTURE
Precisamos escolher entre SQS e Kafka para eventos de pagamento.
Volume: ~50k msgs/dia, precisa de ordering por conta.

Visão sistêmica (Modo TECH LEAD)

Modo: TECH LEAD
Qual o impacto de migrar o received-invoices de MySQL para PostgreSQL?
Quais serviços downstream seriam afetados?

Sem modo explícito

Quando nenhum modo é especificado, o Claude detecta automaticamente pelo contexto:

O consumer SQS está processando mensagens duplicadas no ambiente de UAT.

→ Ativa Modo DEBUG (bug implícito)

Cria um endpoint POST /api/reports/export que gera CSV assíncrono.

→ Ativa Modo PLANNING (feature nova sem código existente)

O que é instalado

| Componente | Destino | Descrição | |-----------|---------|-----------| | CLAUDE.md | ~/.claude/CLAUDE.md | Instruções globais do Claude Code | | RTK.md | ~/.claude/RTK.md | RTK — proxy CLI que reduz 60-90% do consumo de tokens em operações dev (git, npm, etc.) | | settings.json | ~/.claude/settings.json | Configuração com hook de formatação | | Vault | ~/dev/vault-claude/ | Memória persistente entre sessões | | Modos | vault/Modos/ | 7 modos cognitivos com framework de raciocínio e checklists dinâmicos | | Templates | vault/Templates/ | 5 templates Obsidian (sessão, decisão, aprendizado, spec, retrospectiva) | | Aprendizados INDEX | vault/Aprendizados/INDEX.md | Índice de aprendizados por trigger e severidade | | Format hook | ~/.config/claude/format-hook.js | Formatação automática (Java, TS/JS, Python, Rust, Go, Kotlin) | | Credenciais | ~/.config/claude/env | Variáveis de ambiente (chmod 600) | | Jira config | ~/.config/jira/config | Configuração Jira (chmod 600) | | Vault compartilhado | ~/dev/vault-shared/ | Aprendizados e decisões da equipe (Git sync) |

No Windows, as credenciais ficam em %APPDATA%\jira\config e %APPDATA%\claude\env.

Atualização

npm install -g @farm-investimentos/claude-workflow@latest
farmtech-claude update

O update compara versões do manifest.json com o estado local e atualiza apenas o que mudou, sem sobrescrever configs pessoais.

Troubleshooting

| Problema | Solução | |----------|---------| | Token do Jira errado | farmtech-claude jira config | | Registry não encontrado | npm config set @farm-investimentos:registry https://registry.npmjs.org | | Verificar instalação | farmtech-claude doctor | | Refazer setup completo | farmtech-claude init (pergunta antes de sobrescrever) |

Changelog

v2.1.0 (2026-05-12)

Modos cognitivos — Condensação e pragmatismo

Reescrita dos 7 modos baseada em análise de 11 bugs reais e sessões de debug. Foco em tornar os modos frameworks de pensamento, não manuais de operação.

Mudança principal: tabela "O que eu faço vs O que peço ao dev"

Todos os 7 modos agora separam explicitamente o que o Claude pode fazer sozinho (ler código, comparar queries, avaliar blast radius) do que depende do dev (rodar testes, validar dados no banco, confirmar regras de negócio). Isso resolve o problema de o Claude tentar fazer coisas que não consegue ou não pedir ajuda quando precisa.

| Modo | Antes | Depois | |------|-------|--------| | DEBUG | 5 steps sequenciais (manual) | 3 blocos (antes/durante/depois), schema inspection, correlação de bugs, heurística de escalação | | CODING | Listas genéricas de regras | Tabela durante implementação, heurísticas concretas | | PLANNING | Formato do plano duplicado | Tabela antes do plano, formato unificado | | REVIEW | Classificação em 3 blocos de texto | Tabela única severidade/quando/exemplo | | ARCHITECTURE | 7 critérios de avaliação | 6 critérios, tabela eu faço vs peço ao dev | | TECH LEAD | Lista de bullet points | Tabela de impacto com 4 colunas | | REFACTOR | Sem framework de raciocínio | Framework completo + priorização de melhorias |

DEBUG — reescrito com base em dados

Análise de 11 bugs no received-invoices-spring-api (64% first-try fix rate) revelou 7 lacunas:

• Não inspecionava schema do banco (SC-2443: campo certo, tipo errado)
• Não correlacionava com bugs anteriores (4 bugs de query divergente tratados isoladamente)
• Não exigia teste de regressão (SC-2243 reverteu fix sem ninguém perceber)
• Não considerava ambiente de reprodução (prod-only vs sempre)
• Não usava git history (git blame, git log)
• Ignorava dependências externas (SQS, APIs)
• Sem critério de quando parar e escalar

Redução de verbosidade

Total: -63 linhas nos 7 modos (-11%). Regras em prosa convertidas para tabelas. Redundâncias removidas.

v2.0.0 (2026-05-12)

Modos cognitivos — Framework de raciocínio

Todos os 7 modos agora incluem uma seção "Framework de raciocínio" com heurísticas de pensamento:

| Modo | Framework | |------|-----------| | DEBUG | Eliminação por camada (entrada→transformação→persistência→saída), priorização por custo de validação | | ARCHITECTURE | Matriz de decisão com critérios ponderados, heurística "bom o suficiente", red flags | | REVIEW | Profundidade risk-based por arquivo, heurística de classificação blocker/importante/sugestão | | CODING | Checklist antes/durante/depois de implementar | | PLANNING | Investigação obrigatória antes do plano, tabela de granularidade de tasks | | TECH LEAD | Avaliação de blast radius, priorização de dívida técnica | | REFACTOR | (modo já era prescritivo, adicionado checklist dinâmico) |

Checklists dinâmicos

Todos os 7 modos agora têm seção "Checklist dinâmico" alimentada por Aprendizados. A lista cresce conforme novos padrões são descobertos, garantindo que aprendizados apareçam no momento em que são relevantes.

Aprendizados — base de conhecimento

• Aprendizados/INDEX.md — índice por trigger ("consultar quando: paginação, JOIN, timezone") e por severidade (crítico, importante, referência)
• Template evoluído: +Trigger, +Severidade, +Validade, +Anti-padrões

Sessões com métricas

• Template de sessão agora inclui: modo ativado, métricas quantitativas, aprendizados aplicados/gerados, retrospectiva rápida
• Protocolo FINAL expandido para 8 passos com feedback loop

Retrospectiva mensal

• Novo template Templates/retrospectiva.md para análise mensal
• Protocolo RETROSPECTIVA: primeira sessão do mês analisa sessões anteriores, identifica aprendizados não utilizados e bugs recorrentes

Protocolo de sessão

• INÍCIO passo 4: consulta sistemática por triggers no INDEX.md (substitui "leia se relevante")
• DURANTE: novo evento para propagar aprendizados para INDEX + checklists dinâmicos

Desenvolvimento

git clone [email protected]:Farm-Investimentos/farmtech-claude-workflow.git
npm install
npm run dev    # watch mode
npm run build  # compilar
npm run lint   # type check

Estrutura do projeto

src/
├── cli.ts                  # Entry point (commander)
├── types.ts                # Tipos compartilhados
├── commands/
│   ├── init.ts             # Wizard de setup
│   ├── doctor.ts           # Health check
│   ├── update.ts           # Atualização de assets
│   ├── project-init.ts     # Onboarding de projeto
│   ├── jira-cmd.ts         # Comandos Jira
│   ├── github-cmd.ts       # Comandos GitHub
│   ├── sync-cmd.ts         # Sync pull/push/status
│   └── share-cmd.ts        # Promover notas para shared
├── modules/
│   ├── claude-config.ts    # CLAUDE.md, RTK.md, settings.json
│   ├── vault.ts            # Estrutura do vault
│   ├── hooks.ts            # Format hook
│   ├── credentials.ts      # Env files + Jira config
│   ├── shell-integration.ts # Profile do shell
│   ├── jira.ts             # API Jira (fetch, create, update)
│   ├── github.ts           # Apply suggestions
│   ├── rtk.ts              # Auto-install RTK binary
│   ├── project-detect.ts   # Detecção de stack
│   └── sync.ts             # Git operations para vault shared
└── utils/
    ├── platform.ts         # OS, paths, shell detection
    ├── fs.ts               # Operações de arquivo
    └── template.ts         # Handlebars wrapper