Pular para o conteúdo
Triadeflow Docs

Como contribuir

Toda mudanca em arquitetura, agentes ou processos da Triadeflow passa por este repositorio. Este guia descreve como contribuir.

Fluxo de contribuicao

  1. Crie branch a partir de main:

    Terminal window
    git checkout -b feat/nome-descritivo

  2. Faca alteracoes nos .md relevantes em .claude/

  3. Atualize CHANGELOG.md se for mudanca arquitetural

  4. Execute o sync para atualizar o site:

    Terminal window
    python scripts/sync-docs.py

  5. Teste localmente o site:

    Terminal window
    cd site && npm run dev

  6. Abra Pull Request com:

    • Titulo no padrao Conventional Commits (docs:, feat:, etc)
    • Descricao do que muda e por que
    • Screenshots se afeta layout do site

  7. Apos merge na main, Cloudflare Pages atualiza automaticamente em triadeflow.dev

Padroes de escrita

Linguagem

  • Portugues brasileiro em todo conteudo visivel
  • Ingles apenas em codigo, comentarios de codigo e nomes de variaveis
  • Tom direto - sem rodeios, sem clichês
  • Sem emojis - preferencia forte do Alex

Formatacao

  • Cabecalho H1 unico por arquivo, no topo
  • H2 para secoes principais
  • H3 para subsecoes
  • Listas com - (nunca com *)
  • Codigo inline com backticks
  • Blocos de codigo com linguagem especificada (```python, ```yaml)
  • Tabelas markdown padrao para comparativos

Estrutura recomendada por tipo de arquivo

Workflows (.claude/workflows/):

  1. Quando usar
  2. Pre-requisitos
  3. Passos numerados
  4. Saida esperada
  5. Erros comuns
  6. Versao e relacionados

Agentes (.claude/agents/):

  1. ICP (para quem e)
  2. Casos de uso
  3. Tools necessarias
  4. Flows do LangGraph
  5. System prompt template
  6. Default config.yaml
  7. KPIs
  8. Eval inicial
  9. Pricing

Integracoes (.claude/integrations/):

  1. Quando usar
  2. Setup do tenant
  3. Operacoes comuns no codigo
  4. Erros comuns
  5. Referencias

Playbooks de nicho (.claude/playbooks/):

  1. Tom e linguagem
  2. Qualificacao especifica
  3. Compliance e LGPD
  4. Integracoes tipicas
  5. Pricing tipico

Quando criar ADR

Crie nova entrada em .claude/reference/decisoes.md quando:

  • Adicionar novo componente arquitetural relevante
  • Mudar tecnologia em uso (DB, framework, etc)
  • Mudar padrao operacional (ex: criar cliente, deploy)
  • Tomar decisao com impacto em multiplos repositorios

Use o formato Michael Nygard:

## ADR-XXX: Titulo curto


**Status**: Proposto | Aceito | Rejeitado | Substituido por ADR-YYY
**Data**: YYYY-MM-DD


### Contexto
{descricao do problema}


### Alternativas consideradas
1. **Opcao A**: ...
2. **Opcao B**: ...


### Decisao
**Opcao escolhida**: ...
{justificativa}


### Consequencias
**Positivas**: ...
**Negativas**: ...

Quando atualizar CHANGELOG

  • Sempre que adicionar agente novo (minor bump)
  • Sempre que adicionar integracao nova (minor bump)
  • Quando mudar workflow significativamente (patch bump)
  • Quando ADR for criada (referenciar no CHANGELOG)

Nao precisa atualizar para:

  • Correcoes de typo
  • Reescrita de paragrafos
  • Reorganizacao sem mudanca de conteudo

Como testar localmente

Terminal window
# Sincronizar conteudo de .claude/ -> site/
python scripts/sync-docs.py


# Servir site local
cd site
npm install  # primeira vez
npm run dev
# abre http://localhost:4321

Erros comuns

Esquecer de rodar sync

Se editou .claude/conventions.md mas o site nao atualiza, voce esqueceu o sync-docs.py. Em prod isso roda automaticamente, mas em dev precisa rodar manual.

Conflitos de slug

Dois arquivos nao podem virar mesmo slug no site. Se acontecer, ajuste o mapeamento em scripts/sync-docs.py.

Frontmatter quebrado

Starlight e estrito com YAML do frontmatter. Aspas dentro de aspas precisam ser escapadas. O script sync-docs.py ja faz isso, mas se editar frontmatter manualmente, valide.

Use sempre links relativos a partir da raiz do site (/agentes/sdr/ em vez de ../agents/sdr.md). Starlight resolve corretamente.