Artigo Técnico

Instruções para agentes de IA sobre criação, revisão e análise de artigos técnicos usando linguagem formal, estrutura coerente, terminologia precisa, exemplos práticos e referências verificáveis.

1. Benefícios
2. Princípios
- 2.1. Linguagem
- 2.2. Integridade do Conteúdo
3. Estrutura
4. Fluxo de Trabalho
5. Guia de Estilo
6. Portões de Qualidade
7. Recursos
8. Referências

1. Benefícios

Consistência

Uma gramática de artigo estável torna o conteúdo técnico previsível entre tópicos e permite que os leitores localizem definições, categorias, princípios, exemplos e referências sem reaprender a estrutura do documento.
Legibilidade

Parágrafos de definição concisos, cabeçalhos explícitos e listas de termo-definição reduzem a carga cognitiva enquanto preservam a precisão técnica.
Navegabilidade

Um sumário hierárquico mantido manualmente e cabeçalhos numerados expõem a hierarquia conceitual e fornecem navegação direta para artigos longos.
Reutilização

Taxonomias, listas de terminologia, exemplos práticos e referências qualificadas tornam cada artigo útil tanto como introdução quanto como referência de engenharia durável.
Revisabilidade

Regras determinísticas de formatação e evidência permitem que os revisores separem defeitos estruturais, defeitos de linguagem e imprecisões técnicas.

2. Princípios

2.1. Linguagem

Formal

Use inglês neutro adequado para engenheiros de software, engenheiros de sistemas, profissionais de segurança e tomadores de decisão técnica.
Enciclopédico

Defina o assunto antes de prescrever práticas. Explique o que é um conceito, como ele é categorizado e onde é aplicado antes de apresentar recomendações.
Preciso

Prefira substantivos e verbos específicos do domínio em vez de palavras genéricas ou promocionais. Diferencie padrões, especificações, protocolos, ferramentas, frameworks, práticas, métricas e padrões arquiteturais.
Impessoal

Prefira construções em terceira pessoa ou impessoais. Evite narração em primeira pessoa, endereçamento direto em segunda pessoa, perguntas retóricas e preenchimento conversacional.
Declarativo

Declare definições, relacionamentos, restrições e resultados diretamente. Use verbos modais apenas ao expressar um requisito real, recomendação, possibilidade ou incerteza.

2.2. Integridade do Conteúdo

Evidência

Apoie alegações verificáveis externamente com fontes confiáveis. Prefira organismos de padronização, documentação oficial, pesquisa primária e repositórios canônicos.
Atualidade

Verifique fatos sensíveis ao tempo, comportamento específico de versão, limites de desempenho, requisitos legais e capacidades de produto antes de incluí-los.
Escopo

Mantenha cada artigo centrado em um assunto técnico. Vincule a artigos adjacentes em vez de duplicar material de base substancial.
Coerência Taxonômica

Agrupe conceitos por uma dimensão de classificação explícita por vez. Não misture ferramentas, práticas, resultados e propriedades como pares, a menos que a seção explique o relacionamento.
Exemplos

Use exemplos que sejam sintaticamente válidos, tecnicamente plausíveis e diretamente conectados à explicação anterior.

3. Estrutura

3.1. Arquivo e Título

Nome do Arquivo

Use um nome de arquivo em kebab-case minúsculo que identifique o assunto, por exemplo technical-debt.md, feature-flags.md ou file-systems.md.
Frontmatter

Não adicione frontmatter YAML aos arquivos de artigo, a menos que o repositório de destino exija explicitamente.
Título H1

Comece com exatamente um cabeçalho H1 contendo o nome canônico do assunto em título.
```
# Feature Flags
```

3.2. Introdução

Coloque um ou dois parágrafos concisos imediatamente após o cabeçalho H1.

Definição

Defina o assunto na primeira frase. Expanda uma sigla no primeiro uso quando não for universalmente autoexplicativa no domínio do artigo.
Contexto

Explique o propósito do assunto, papel operacional ou relação com a engenharia de software. Não introduza taxonomia detalhada antes do sumário.

Exemplo:

# Feature Flags

Feature flags são controles em tempo de execução que permitem ativar ou desativar o comportamento de uma aplicação sem exigir uma nova implantação. Eles desacoplam a implantação de código do lançamento de funcionalidades e suportam rollout controlado, experimentação e mitigação operacional.

3.3. Índice

Insira um sumário em Markdown mantido manualmente após a introdução e antes da primeira seção H2.

Hierarquia

Espelhe cada cabeçalho H2, H3 e H4 material numerado usando indentação de dois espaços por nível.
Rótulos

Inclua o prefixo numérico completo e o texto do cabeçalho.
Âncoras

Use âncoras minúsculas compatíveis com GitHub. Remova pontuação de acordo com as regras de cabeçalho do GitHub, preservando hífens entre palavras.
Completude

Adicione, remova ou renomeie entradas do sumário sempre que os cabeçalhos mudarem.

Exemplo:

- [1. Categoria](#1-categoria)
  - [1.1. Estratégias de Implantação](#11-estratégias-de-implantação)
    - [1.1.1. Implantação Blue-Green](#111-implantação-blue-green)
    - [1.1.2. Implantação Canário](#112-implantação-canário)
- [2. Princípio](#2-princípio)
- [3. Melhores Práticas](#3-melhores-práticas)
- [4. Terminologia](#4-terminologia)
- [5. Referências](#5-referências)

3.4. Seções Numeradas

Use numeração decimal arábica em todos os cabeçalhos de artigo abaixo de H1.

H2

Use ## 1. <Seção> para seções de nível superior.
H3

Use ### 1.1. <Subseção> para seções de segundo nível.
H4

Use #### 1.1.1. <Tópico> apenas quando uma subseção contiver uma taxonomia substancial que exija mais um nível.
Profundidade

Prefira no máximo quatro níveis de cabeçalho, incluindo H1. Substitua profundidade excessiva de cabeçalho por listas de termo-definição ou tabelas.
Seções Canônicas

Selecione apenas seções que contribuam para o assunto. Rótulos comuns compatíveis com o corpus incluem Benefícios, Categoria, Princípio, Princípios, Melhores Práticas, Terminologia e Referências.
Ordem

Comece com conceitos e categorias fundamentais, continue com princípios ou práticas, depois conclua com terminologia e referências.

3.5. Taxonomias e Definições

Use prosa para transições conceituais e listas de termo-definição para conteúdo técnico escaneável.

Liderança de Seção

Abra uma seção principal com um ou dois parágrafos que expliquem a dimensão de classificação ou o propósito da seção.

Padrão Termo-Definição

Apresente um rótulo técnico como um marcador e sua explicação como uma citação em bloco indentada.

- Atomicidade
  > Atomicidade garante que uma transação seja concluída como uma unidade ou revertida sem reter um resultado parcial.

Padrão Agrupado

Use um item de lista ordenada como cabeçalho de grupo local quando uma subseção contiver várias visões distintas, como convenções, exemplos ou ferramentas.
Capitalização de Rótulos

Use título para rótulos conceituais e maiúsculo inicial para descrições.
Qualidade da Descrição

Comece as descrições pelo papel, comportamento ou propriedade definidora do termo. Evite definições circulares que repitam o rótulo sem adicionar significado.

3.6. Exemplos e Dados

Exemplos Independentes

Introduza exemplos independentes em nível de prosa com Exemplo:. Dentro de subseções agrupadas como Exemplos e Explicações, use um rótulo de exemplo descritivo.
Exemplos de Código

Use um bloco de código cercado com o identificador de linguagem mais preciso.
Sintaxe Inline

Use crases para comandos, caminhos de arquivo, chaves de configuração, identificadores, literais e fragmentos curtos de sintaxe.
Tabelas

Use tabelas Markdown para comparações compactas, matrizes, métricas, comandos ou dados de referência enumerados. Mantenha o conteúdo das células paralelo e evite parágrafos de prosa dentro das células.
Diagramas

Use diagramas baseados em texto como Mermaid quando relacionamentos ou fluxos não puderem ser explicados eficientemente com prosa ou tabela.
Advertências

Use advertências do GitHub com moderação para restrições, ressalvas, links cruzados ou informações que alterem materialmente a interpretação.
```
> [!NOTE]
> O limite da métrica depende do período de relatório citado e deve ser verificado antes da publicação.
```

3.7. Referências

Termine cada artigo com uma seção Referências numerada.

Referências Internas

Use links relativos ao repositório para artigos relacionados do Sentenz.
```
- Sentenz artigo [Versionamento](../articles/versioning.md).
```

Referências Externas

Nomeie a organização ou editor antes do título vinculado e identifique o tipo de fonte após o link.

- NIST publicação [Secure Software Development Framework (SSDF) Version 1.1](https://csrc.nist.gov/pubs/sp/800/218/final).
- Kubernetes documentação [Documentation](https://kubernetes.io/docs/).
- GitHub repositório [DORA Four Keys](https://github.com/dora-team/fourkeys).

Tipos de Fonte

Use um qualificador preciso como artigo, documentação, página, publicação, repositório, relatório, especificação ou padrão.
Relevância

Inclua apenas fontes citadas ou materialmente usadas no artigo. Não crie uma lista de leitura geral não relacionada às alegações do artigo.

4. Fluxo de Trabalho

4.1. Criar

Inspecionar

Leia arquivos vizinhos no diretório de artigo de destino. Registre o vocabulário de cabeçalho local, estilo de link, convenções de bloco de código e artigos internos relacionados.
Escopo

Defina o assunto do artigo, profundidade pretendida e dimensão de classificação primária. Separe assuntos adjacentes em artigos com links cruzados.
Pesquisar

Colete fontes primárias confiáveis. Verifique terminologia, padrões, métricas, comportamento do produto e detalhes sensíveis ao tempo.
Esboço

Selecione as seções canônicas necessárias e construa uma hierarquia de cabeçalhos numerados antes de redigir a prosa.
Carregar Modelo

Carregue assets/technical-article-template.md ao criar um novo artigo. Remova seções que não contribuam para o assunto.
Redigir Introdução

Escreva o título H1 e um ou dois parágrafos de definição. Estabeleça o assunto e o contexto de engenharia sem antecipar detalhes de implementação.
Construir Índice

Espelhe a hierarquia de cabeçalhos planejada e gere âncoras exatas compatíveis com GitHub.
Escrever Seções

Adicione lideranças de seção, listas de termo-definição, exemplos, tabelas, diagramas e advertências apenas onde melhorarem a compreensão.
Adicionar Referências

Adicione links relativos internos e referências externas qualificadas por fonte. Garanta que toda alegação externa material tenha uma fonte confiável apropriada.
Validar

Aplique todos os Portões de Qualidade antes de retornar ou commitar o artigo.

4.2. Revisar

Preservar Intenção

Identifique o assunto, escopo e taxonomia do artigo existente antes de alterar a estrutura.
Carregar Modelo

Carregue assets/technical-article-template.md antes de revisar o artigo. Use-o como linha de base estrutural, remova seções de modelo inaplicáveis e preserve seções específicas do artigo válidas.
Diagnosticar

Separe defeitos em precisão técnica, taxonomia, organização, linguagem, formatação, links, exemplos e referências.
Normalizar

Alinhe o título, introdução, índice, numeração, níveis de cabeçalho, listas, citações em bloco, blocos de código e referências com esta skill.
Refinar Linguagem

Substitua palavras vagas, repetitivas, conversacionais ou promocionais por definições técnicas diretas e verbos apropriados ao domínio.
Reconciliar Navegação

Atualize âncoras, links cruzados e referências após cada alteração de cabeçalho ou nome de arquivo.
Validar

Reexecute todos os portões de qualidade e confirme que a revisão não removeu informações tecnicamente relevantes sem uma razão explícita.

4.3. Analisar

Carregar Modelo

Carregue assets/technical-article-template.md antes de analisar um artigo. Use-o como linha de base estrutural e não relate seções opcionais omitidas como defeitos, a menos que sua ausência crie um problema de completude ou coerência.
Avaliar

Analise o artigo na seguinte ordem:
1. Correção Técnica
2. Escopo e Coerência Taxonômica
3. Conformidade Estrutural
4. Terminologia e Siglas
5. Exemplos, Tabelas e Diagramas
6. Links e Referências
7. Gramática, Pontuação e Legibilidade
Relatar Achados

Relate achados com o cabeçalho ou linha afetada, o defeito, sua consequência técnica e uma correção concreta. Priorize erros factuais e inconsistências estruturais sobre preferências estilísticas.

5. Guia de Estilo

5.1. Voz e Tom

Presente

Use presente para definições, capacidades e práticas atuais.
Passado

Use passado apenas para eventos históricos ou comportamento obsoleto.
Voz Ativa

Prefira voz ativa quando o ator ou mecanismo for importante.
Voz Passiva

Use voz passiva quando o processo ou resultado for o foco e o ator for irrelevante.
Perspectiva Impessoal

Evite pronomes em primeira e segunda pessoa.
Cortesia e Inclusão

Não use masculino genérico quando o contexto não exigir gênero. Use "o usuário", "a pessoa" ou reformule a frase.
Tom Decisivo

Prefira declarações diretas. Evite advérbios de dúvida desnecessários, como "talvez", "possivelmente" ou "potencialmente", a menos que a incerteza seja o ponto central.

5.2. Terminologia

Primeiro Uso

Defina ou vincule à definição de qualquer termo técnico não trivial no primeiro uso.
Linguagem do Domínio

Use a terminologia estabelecida pelos padrões, especificações ou comunidades do domínio. Não invente novos termos quando alternativas padrão existirem.
Siglas e Símbolos

Expanda uma sigla na primeira ocorrência em cada artigo. Use o símbolo sozinho depois disso.
Consistência de Ortografia

Use a mesma ortografia e maiúsculas em todo o artigo. Para grafias em disputa, siga a fonte escolhida ou um guia de estilo do domínio.
Evitar Jargão

Não use jargão informal, gíria ou analogias não técnicas como substitutos para definições precisas.

5.3. Frases e Parágrafos

Comprimento da Frase

Prefira frases de 15–25 palavras. Em uma frase longa, quebre-a após o verbo principal ou um modificador-chave.
Comprimento do Parágrafo

Mantenha parágrafos de prosa entre 3–7 frases. Use parágrafos mais curtos para aberturas de seção ou transições.
Ideia Única

Cada parágrafo deve desenvolver uma única ideia ou uma etapa de um argumento sequencial.
Conectividade

Abra parágrafos com um tópico definido ou uma frase de conexão que relacione a nova ideia ao parágrafo anterior.
Modificadores

Coloque modificadores próximos ao elemento que modificam. Evite modificadores pendentes no início ou final da frase.

5.4. Listas e Citações em Bloco

Listas Ordenadas

Use listas ordenadas para sequências, prioridades, classificações ou dependências ordenadas.
Listas Não Ordenadas

Use listas não ordenadas para categorias paralelas, opções ou conjuntos sem ordenação intrínseca.
Estrutura Paralela

Use a mesma estrutura gramatical para todos os itens em uma lista. Comece cada item com um substantivo, um verbo no infinitivo ou uma frase completa, mas não misture.
Pontuação

Use ponto final no final de itens de lista que sejam frases completas; omita a pontuação final para fragmentos curtos.
Citações em Bloco

Use citações em bloco para definições, citações de fontes externas e explicações multi-linha de um único termo. Não use citações em bloco para ênfase ou como uma segunda forma de marcador.

5.5. Links e Citações

Texto do Link

Use texto de link descritivo que nomeie o destino ou seu propósito. Evite "clique aqui", "este link" ou URLs nuas.
Citações no Texto

Ao citar uma fonte externa, identifique nome, título e ano suficiente para localização em uma referência.
Citações Literais

Inclua citações literais curtas entre crases ou aspas duplas para passagens em prosa. Para código ou saída, use um bloco de código inline.
Citações Nacionais ou Regionais

Se um artigo se aplicar a jurisdições específicas, cite variações regionais quando afetarem a conformidade ou implementação.

5.6. Código, Tabelas e Advertências

Blocos de Código

Use blocos de código cercados para blocos de código multi-linha. Use crases para tokens inline.
Identificadores de Linguagem

Declare o idioma do bloco de código após a abertura das crases para acionar o realce de sintaxe: markdown`, python, ````bash, yaml`, json, ````text.
Nomes de Tabela

Preceda cada tabela com uma frase de introdução ou cabeçalho de frase que explique o que a tabela contém.
Alinhamento de Tabela

Alinhe colunas de tabela para legibilidade. Use :--- (esquerda), :---: (centro) e ---: (direita) conforme necessário.
Limite de Células

Mantenha as células da tabela com menos de 60 caracteres. Converta células longas em listas, blocos de código ou subseções separadas.
Advertências do GitHub

Use > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING] e > [!CAUTION] para informações que quebram o fluxo normal de prosa. Coloque-os imediatamente antes do material que qualificam.

6. Portões de Qualidade

Aplique todas as verificações a seguir antes de retornar ou commitar um artigo.

6.1. Integridade Estrutural

Existe exatamente um cabeçalho H1 no topo.
A introdução começa com uma definição do assunto e segue com contexto.
Um sumário manual segue a introdução e cada cabeçalho subsequente, incluindo H4 materiais.
A numeração do cabeçalho usa arábico decimal, começa em 1 e não tem lacunas.
As âncoras do sumário correspondem ao id do HTML gerado.
O artigo termina com uma seção Referências.

6.2. Precisão Técnica

Os fatos reivindicados podem ser verificados a partir das referências citadas.
As métricas e limites de desempenho são atuais e atribuídos.
A terminologia da versão do produto corresponde à versão documentada.
Exemplos são sintaticamente válidos para a linguagem ou ferramenta mostrada.

6.3. Qualidade da Linguagem

A linguagem é formal e impessoal; sem narração em primeira pessoa ou perguntas retóricas.
A terminologia é consistente em todo o artigo e definida no primeiro uso.
As definições começam com papéis ou propriedades, não com repetições do termo.
As frases têm em média 15–25 palavras; parágrafos 3–7 frases.

6.4. Exatidão de Links e Referências

Todos os links internos são relativos ao repositório e funcionais.
Todos os links externos apontam para URIs válidos e específicos.
As referências listam a organização, título, tipo de fonte e URL.
Nenhuma fonte é listada, a menos que citada materialmente no conteúdo.

6.5. Consistência de Formatação

Cabeçalhos usam título, não maiúsculas espalhadas.
Blocos de código cercados têm um identificador de linguagem.
Tabelas têm largura de coluna consistente e alinhamento adequado.
Advertências usam a sintaxe correta do GitHub.

6.6. Portão Final

O artigo foi lido em voz alta ou processado por conversão de texto em fala para detectar ritmo estranho.
Um revisor diferente do autor examinou a correção técnica e a coerência.

7. Recursos

Modelo de artigo técnico: Para criar um novo artigo, abra assets/technical-article-template.md. Para revisar ou analisar, use o mesmo modelo como linha de base estrutural.
Artigos de exemplo: Consulte artigos existentes no diretório articles/ para padrões de estrutura, estilo de link e convenções de taxonomia.

8. Referências

Complemento para ambiente de desenvolvimento baseado em Markdown. Mantenha este guia acessível para agentes de IA em cada interação de sessão que envolva criação de artigos.
Consulte GitHub Flavored Markdown Spec para regras de sintaxe de âncora de título e formatação de tabelas.
Consulte o repositório Sentenz Skill para habilidades de agente que tocam documentação, revisão de código e classificação técnica.

Perguntar na sua IA favorita

Documentação