DEV Community

Cover image for Criei uma pipeline de planejamento no OpenCode e olha no que deu
Clinton Rocha
Clinton Rocha

Posted on

Criei uma pipeline de planejamento no OpenCode e olha no que deu

#ai #braziliandevs #opensource

Você é como eu e vem buscando formas de otimizar o uso de ferramentas como o OpenCode? Talvez este conteúdo te ajude a ter novas ideias e até mesmo entender alguns fluxos dessa e de outras ferramentas.

Enquanto eu estudava a documentação do OpenCode, encontrei a aba de plugins feitos pela comunidade. Ali, encontrei três plugins que, na minha visão, se complementam bem. Na verdade, um deles eu já utilizava: o Plannotator.

A partir disso, comecei a estudar como funcionava os comandos, agentes e como eu poderia fazer um fluxo que fizesse sentido e principalmente que funcionasse, calma que já te explico oq cada um dos plugins fazem e qual a ideia final da integração.

A partir disso, comecei a estudar como funcionam os comandos, os agentes e como eu poderia montar um fluxo que realmente fizesse sentido e principalmente que funcionasse. Calma que já te explico o que cada um desses plugins faz e como fica o fluxo entre eles.

Table of Contents

Como eu estava usando o OpenCode

Após começar a utilizar o OpenCode, notei o quão importante é o uso do módulo de planejamento e, principalmente, não apenas o planejamento em si, mas também as perguntas que são feitas durante esse processo. O resultado dessas duas novas abordagens (planejamento e perguntas) melhora bastante não só o código produzido, mas também a minha compreensão sobre a regra de negócio, além de comportamentos e fluxos do sistema.

Mesmo com todas essas descobertas que trouxeram otimizações para o processo, eu ainda sentia que dava para melhorar mais.

O fluxo de uso do OpenCode era basicamente o seguinte: eu enviava o prompt, a ferramenta vasculhava o código para obter contexto, depois vinham algumas perguntas e, em seguida, ela ia para a parte de build, ou seja, para colocar em prática o que tinha sido planejado.

Objetivo da integração

A ideia vai ser conseguir extrair o máximo de contexto com o Octto, usar o subtask2 para orquestrar os comandos e visualizar o plano final com Plannotator.

+---------------------------------------------------------------+
|                                                               |
|  IDEIA -> CONTEXTO -> PLANO -> REFINAMENTO -> REVISAO -> OK   |
|                                                               |
+---------------------------------------------------------------+
Enter fullscreen mode Exit fullscreen mode

O resultado é um único comando que orquestra todo o processo:

/generate-plan "descrição do objetivo"
Enter fullscreen mode Exit fullscreen mode

Plannotator: Revisão visual

O primeiro plugin chegou até mim por recomendação de uma amiga da comunidade (He4rtDevs), a Cherry, e o plugin era o Plannotator.

Esse plugin basicamente faz com que, ao final de um planejamento, seja aberta uma página no navegador contendo todo o plano gerado. Isso facilita muito a visualização em comparação com o terminal. Na interface do navegador, você consegue selecionar trechos do planejamento e dar feedback, que retorna para o processo de planejamento. Também é possível aprovar o plano e seguir diretamente para a etapa de build, ou seja, aplicar o que foi planejado.

Octto: Coleta estruturada de contexto

O Octto quando você envia o primeiro prompt, ele abre uma página no navegador com perguntas relacionadas ao que você pediu inicialmente. Essa página funciona como uma interface interativa de brainstorming. Conforme você responde às perguntas, o sistema utiliza essas respostas para gerar novas perguntas dentro da mesma sessão, aprofundando o entendimento do problema e ajudando a estruturar melhor o contexto antes de seguir para as próximas etapas, ao final ele gera um arquivo .md no diretório /docs/plnas dentro do projeto.

A unica configuração que adicionei a ele foi uma que faz com que a primeira pergunta seja um campo de texto livre onde o usuário consiga descreve o contexto com maior liberdade (colocar uma task completa, por exemplo).

Fluxo de Funcionamento 

+----------------------+
|       ask_text       |  <-- Primeira ação obrigatória
+----------+-----------+
           |
           | Campo de texto no browser:
           | "Descreva com detalhes o que
           | você quer planejar..."
           v
+----------------------+
|   create_brainstorm  |  <-- Agente inicia sessão
+----------+-----------+      com contexto coletado
           |
           | Define branches de exploração
           v
+--------------------------------------------------------------+
|                    BRANCHES DE EXPLORAÇÃO                    |
|                                                              |
|  +----------------+  +-------------------+  +---------------+|
|  | Motivação &    |  | Requisitos &      |  | Riscos &      ||
|  | Objetivos      |  | Restrições        |  | Dependências  ||
|  +--------+-------+  +---------+---------+  +-------+-------+|
|           |                    |                    |        |
+-----------+--------------------+--------------------+--------+
            |
            v
+----------------------+
|      BROWSER UI      |
|                      |
|  [ Pergunta 1 ]      |
|  [ Pergunta 2 ]      |
|  [ Pergunta N ]      |
|                      |
|      [Responder]     |
+----------+-----------+
           |
           | Usuário responde
           v
+----------------------+
| await_brainstorm_    |
| complete             |  <-- Agente aguarda respostas
+----------+-----------+
           |
           | Sintetiza respostas
           v
+----------------------+
|      docs/plans/     |
| 2026-03-08-objetivo  |  <-- Arquivo gerado
|        .md           |
+----------------------+
Enter fullscreen mode Exit fullscreen mode

Configuração via Fragments

O comportamento do Octto é customizado através de fragments instruções adicionadas ao prompt dos agentes internos:

{
    "fragments": {
        "octto": [
            "Sempre pergunte a motivação e o 'porquê' das mudanças",
            "Gere nomes de arquivo no formato: YYYY-MM-DD-slug.md",
            "Salve os planos em docs/plans/"
        ],
        "probe": [
            "Priorize perguntas sobre motivações e restrições",
            "Inclua perguntas sobre requisitos não-funcionais"
        ],
        "bootstrapper": [
            "Crie branches focados em: requisitos, arquitetura, riscos"
        ]
    }
}
Enter fullscreen mode Exit fullscreen mode

Função de cada agente interno:

  • bootstrapper: cria a estrutura inicial de branches
  • probe : gera perguntas de aprofundamento
  • octto: define o comportamento geral da coleta de contexto

Subtask2: Orquestração de pipeline

O Subtask2 permite encadear comandos de forma sequencial. Quando um comando termina, o próximo da cadeia é executado automaticamente.

Nesse meu contexto só vou usar a funcionalidade de return, mas esse plugin tem muitas outras interessantes como:

  • loop de subtarefas até que a condição do usuário seja atendida
  • paralela de subtarefas simultaneamente - PR pendente.
  • $TURN[n] passa turnos da sessão (mensagens do usuário/assistente).
  • {as:name} + $RESULT[name] captura e referencia as saídas das subtarefas.

Sintaxe de Return Chain 

---
subtask: true
return:
- /comando-1
- /comando-2
- /comando-3
---
Enter fullscreen mode Exit fullscreen mode

Comandos

Com o subtask2, consigo adicionar comandos ao fluxo, e isso abre muitas possibilidades. Mas, por enquanto, estou com os pés no chão e vou fazer um fluxo simples com alguns novos comandos.

Eu criei esses comandos com o único intuito de usar na pipeline.

Comando Principal

O comando que vai dar inicio a todo o fluxo, vai ser o /generate-plan ao executar, ele da inicio a pipeline de planejamento.

Você é livre para escolher qualquer nome para o comando, para escolher o nome desse aqui eu só segui as vozes da minha cabeça.

Caso queira saber mais sobre como criar e configurar comandos no opencode, a doc é legalzinha.

/generate-plan refatorar sistema de autenticação
/generate-plan "adicionar suporte a múltiplos gateways de pagamento"
Enter fullscreen mode Exit fullscreen mode

As aspas são opcionais: tudo após o comando é passado como $ARGUMENTS.

---
description: Pipeline completo de planejamento 
agent: octto
subtask: true
return:
- /refine-plan
- /review-plan
---

prompt aqui, e lembre de usar o $ARGUMENTS
Enter fullscreen mode Exit fullscreen mode

Caso você queira ver como deixei o meu prompt usado no comando generate-plan é só ir no gist.

Todos os comandos podem ser usados individualmente/isolado no OpenCode, a unica diferença ao usar um comando com o subtask é que ele vai ser executado em um contexto diferente.

Refinamento Técnico

O /refine-plan tem como objetivo expandir um plano existente com detalhes arquiteturais.

/refine-plan # usa plano mais recente
/refine-plan docs/plans/meu-plano.md # plano específico
Enter fullscreen mode Exit fullscreen mode

refine-plan:

---
description: Expande e refina tecnicamente um plano existente com arquitetura e diagramas
subtask: true
---

Mesma coisa que o anterior, aqui você consegue adicionar a instrução que você quiser.
Enter fullscreen mode Exit fullscreen mode

No meu caso, o prompt que estou sando tá no gist 'refine-plan.md'.

Revisão Visual

Por ultimo vem o comando /review-plan com o objetivo de mandar o plano para revisão interativa via Plannotator.

/review-plan # usa plano mais recente
/review-plan docs/plans/meu-plano.md # plano específico
Enter fullscreen mode Exit fullscreen mode

Importante: Este comando não usa subtask: true. Ele roda na sessão primária para que a ferramenta submit_plan possa abrir a interface do Plannotator no browser corretamente. Comandos rodando como subtarefa não conseguem inicializar a UI do browser.

Fluxo Completo de Execução:

diagrama contendo todo o fluxo

Considerações

O mais importante de tudo: funcionou? Sim. É uma bazuca? Sim, hahahaha. Esse projeto acabou saindo porque entrei em hiperfoco ao me fazer a pergunta “será que funciona?”. No fim, tive minha resposta.

Olhando para a usabilidade no dia a dia, acredito que os melhores momentos para utilizar algo assim são em novas features, refatoração de projeto e até mesmo para estruturar estudos, quem sabe. Só não use para algo como “quero trocar a cor de um botão”, aí você acaba complicando.

O ponto que mais curti foi o Octto, com as perguntas geradas de forma dinâmica. Aquilo ali, ao meu ver, auxilia na contextualização de uma baita maneira. Fora que é possível dar instruções para as branches dele, especificar qual tipo de input você quer ou não quer, entre outras coisas (vale ler a documentação).

Já o subtask2 abre portas para muita coisa. Como eu tinha dito antes, acabei indo pelo simples, mas alguém com a mente mais aberta provavelmente vai conseguir extrair o melhor da ferramenta.

Eu pretendo criar novos comandos, refinar mais os prompts e ver o que acontece. É isso, obrigado por ler até aqui e tente brincar com isso ai.

Como meu Tech Lead fala:

Faça codigo inútil e quebre alguma coisa.

Referências

Top comments (0)