xz1220/feishu-doc-style

O que feishu-doc-style faz?

Normas a seguir ao escrever documentos no Feishu, aplicáveis a propostas técnicas, PRDs, retrospectivas, notas explicativas e afins. O objetivo é um só: fazer com que alguém entenda o conteúdo em uma única leitura.

Quando usar

Sempre que estiver escrevendo, editando, revisando ou refinando um documento do Feishu ou documento técnico, aplique estas normas por padrão, sem necessidade de solicitação explícita.

Quando o usuário digitar explicitamente /feishu-doc-style, ou perguntar "Isso está claro?" ou "Como posso tornar este trecho mais compreensível?", utilize os "Princípios Centrais" e a "Checklist Pré-entrega" para sugerir alterações.

Ao ajudar alguém a revisar um texto, percorra primeiro a checklist item por item, destaque as violações, forneça a versão corrigida e explique o que foi alterado.

Princípios Centrais

1. Deixe apenas a conclusão, omita o raciocínio. Elimine explicações como "por que escolhemos isso" ou "como foi feita a ponderação". Vá direto ao ponto. O leitor quer a resposta, não o seu processo de pensamento.

2. Parágrafos de no máximo duas ou três linhas. Não empilhe várias frases em um bloco longo. Parágrafos extensos cansam a leitura.

3. Use diagramas para processos, não texto. Sequências, fluxos de dados, mudanças de estado: represente com diagramas, não com longas descrições textuais. Um diagrama de sequência vale por um bloco de texto.

4. Setas só aparecem em diagramas. No corpo do texto e em tabelas, é proibido usar cadeias de setas como "A → B; C → D". Isso força o leitor a fazer associações mentais, transferindo o custo da interpretação para ele.

5. Fale como gente, sem jargões. Termos internos que o leitor não conhece devem ser substituídos por linguagem simples ou explicados em uma frase na primeira ocorrência. Consulte a tabela de jargões em references/jargon.md.

6. Células de tabela devem conter frases completas e curtas. Não use apenas siglas técnicas; escreva "quem fez o quê e qual foi o resultado".

7. Evite emojis decorativos e caixas de destaque coloridas. Emojis como 📌 ⭐ 🔒 💡 ✅ 🚧 e caixas de callout coloridas poluem visualmente a página. Para ênfase, use "subtítulo em negrito. seguido do texto normal"; para notas ou avisos de status no nível do documento, use blocos de citação >. Um documento completo não deve conter nenhum emoji decorativo ou caixa de destaque.

8. Use negrito com moderação. No máximo uma ou duas ocorrências por seção, aplicado apenas a conclusões globais ou cabeçalhos de princípios. Nomes de listas, nomes de campos, palavras de direção (esquerda/centro/direita) nunca devem estar em negrito — a hierarquia deve ser expressa pela estrutura das frases e tabelas, não por negrito no texto.

9. Não use caracteres que não podem ser digitados no teclado. Códigos circulares ①②③④⑤, emojis de estado ✓ ◐ ◑ ● ○, ! usado como ícone, ícones funcionais ⚡ ⌘ — tudo isso parece cópia literal da interface. Para listas, use listas ordenadas normais "1. 2. 3." ou "primeiro, segundo"; para estados, escreva diretamente "Concluído / Em andamento"; para numeração de etapas, use números comuns (Etapa 1 / PASSO 1).

10. Títulos devem descrever o conteúdo, não a estrutura. O título deve dizer diretamente sobre o que é a seção ("Metas e principais meios para este ano", "Trabalhos em andamento e progresso"), sem incluir lógica organizacional ou andaimes de escrita. Evite prefixos como "Visão geral:", "Detalhamento:", "Parte 1:" — a relação geral-específico, paralela ou sequencial deve ser naturalmente indicada pela ordem do conteúdo e hierarquia dos títulos. Também não coloque metainformações no título (explicações como "(IA atualiza diariamente)" devem ir no corpo do texto ou em blocos de citação >). Evite colocar o conteúdo em um molde inadequado — por exemplo, forçar uma lista de "várias tarefas por direção" dentro de um invólucro temporal como "Progresso no primeiro semestre"; primeiro, pense na real dimensão organizacional do conteúdo (o estado atual segue a direção; o fluxo segue o tempo). Autoverificação: leia o título em voz alta; soa como um nome que uma pessoa normal daria? "Visão geral: Metas deste ano" não soa natural; "Metas deste ano" sim.

Como escrever tabelas

Os nomes das colunas devem ser em linguagem simples, de preferência no formato de pergunta. Por exemplo: "O que o usuário faz / O que o sistema faz internamente / É necessário aguardar online?", em vez de "Entrada de sincronização / Cadeia assíncrona e persistência no banco".

As células devem conter frases completas e curtas, explicando em uma frase quem fez o quê e qual foi o resultado.

Detalhes técnicos devem ficar no corpo do texto; a tabela serve apenas para facilitar a compreensão. Instruções completas de criação de tabelas, definições de interfaces, etc., devem ser colocadas em seções específicas do texto, não na tabela.

Ilustrações: qual tipo usar para cada situação

Processos que podem ser representados graficamente não devem ser descritos com texto. Escolha o tipo de diagrama de acordo com o que deseja expressar:

O que expressar	Qual tipo de diagrama usar
Fluxo lógico, sequência, como os dados fluem passo a passo	Diagrama de sequência (mermaid sequenceDiagram), com pistas por papel
Como os módulos são divididos em camadas, quem depende de quem	Diagrama de arquitetura (nós em formato de cartão: ícone + título + descrição curta, com cores por camada)
Como o estado muda (ex.: rascunho → publicado → removido)	Fluxograma ou diagrama de estados (mermaid flowchart)

Como inserir esses diagramas no Feishu (usando o quadro Mermaid, lark-whiteboard, lark-cli) consulte references/feishu-tooling.md.

Checklist pré-entrega

Antes de entregar, percorra esta lista item por item. Se algum item falhar, volte e corrija:

• Não há cadeias de setas (A → B) no corpo do texto ou em tabelas? Setas só aparecem em diagramas?
• Cada parágrafo tem no máximo duas ou três linhas?
• Não há jargões não explicados? O primeiro uso de um termo técnico vem acompanhado de uma explicação simples?
• Conteúdos processuais são representados com diagramas, e não com texto?
• As células da tabela são frases completas? Os nomes das colunas estão em linguagem simples?
• Foram removidas longas justificativas do tipo "por que escolhemos isso", deixando apenas a conclusão?
• Não há emojis decorativos, nem caixas de destaque coloridas (callouts)? Ênfase usa subtítulos em negrito, notas usam blocos de citação?
• Não há códigos circulares ①②③, emojis de estado ✓ ◐, ou outros caracteres que não podem ser digitados no teclado?
• O uso de negrito é moderado — no máximo uma ou duas ocorrências por seção para conclusões globais, sem negrito em listas de nomes / palavras de direção?
• Títulos e tabelas não usam palavras em inglês como sujeito sem contexto? Se houver mockups em inglês, inclua uma legenda em português entre parênteses?
• Os títulos nomeiam diretamente o conteúdo, sem prefixos como "Visão geral:/Detalhamento:/Parte 1:" ou metainformações? O conteúdo não foi forçado dentro de um invólucro temporal inadequado?

Referências complementares

• references/jargon.md: Tabela de jargões — substitua sempre as palavras da esquerda pela linguagem simples da direita; será atualizada continuamente.
• references/feishu-tooling.md: Anotações sobre como inserir diagramas no Feishu (quadro Mermaid, lark-whiteboard, lark-cli).

Este skill também segue estas regras

O SKILL.md, README e references deste skill foram escritos seguindo as normas acima. Ao modificá-lo, primeiro utilize a "Checklist pré-entrega" como autoavaliação: sem emojis decorativos, sem cadeias de setas, parágrafos curtos, títulos descritivos. Se as regras mudarem, atualize o SKILL.md e o README simultaneamente para não gerar inconsistências.