Inglês Simplificado
Visão Geral
A Regra 1 das regras de Jarrett: saída de chat, documentação gerada, comentários de código e mensagens de commit usam inglês técnico simplificado. O estilo baseia-se nos princípios do ASD-STE100. Leitores encontram fatos mais rápido. Leitores cujo primeiro idioma não é o inglês entendem mais.
Esta habilidade é nosso próprio resumo. Não é o padrão ASD-STE100 e não inclui seu dicionário.
Quando Usar
- Você escreve ou edita uma especificação, plano, ADR, README, entrada de vocabulário ou outro documento.
- Você escreve um comentário de código ou uma mensagem de commit.
- Você revisa texto para a regra 1.
Não aplicar a identificadores de código, saída citada (erros, logs, saída de comandos), arquivos de habilidade ou texto que o usuário escreveu.
Processo
Escreva o texto. Em seguida, verifique-o em relação a cada regra.
| # | Regra | Não assim | Assim |
|---|---|---|---|
| 1 | Um tópico por frase. | O hook lê o arquivo e, se estiver faltando, imprime um aviso, que o usuário vê. | O hook lê o arquivo. Se o arquivo estiver faltando, o hook imprime um aviso. O usuário vê o aviso. |
| 2 | Instruções: 20 palavras ou menos. Descrições: 25 palavras ou menos. | Certifique-se de que, antes de prosseguir e enviar o branch, você executou a suíte completa de testes e verificou a saída. | Execute ./scripts/test.sh. Em seguida, envie o branch. |
| 3 | Use a voz ativa. | As regras são carregadas pelo hook. | O hook carrega as regras. |
| 4 | Instruções usam o imperativo. | O teste deve ser executado antes do commit. | Execute o teste antes do commit. |
| 5 | Uma palavra tem um significado. Use os termos em .claude-work/docs/VOCABULARY.md. | Avisar, depois "sinalizar", "alertar" ou "notificar" para a mesma ação. | Avisar, toda vez. |
| 6 | Use tempos simples: presente, passado, futuro. | O hook estaria verificando a entrada. | O hook verifica a entrada. |
| 7 | Use um único verbo, não um verbo frasal ou expressão idiomática. | Inicie a build. Descubra a causa. | Inicie a build. Encontre a causa. |
| 8 | Mantenha "o" e "um". | Execute script, verifique saída. | Execute o script. Verifique a saída. |
| 9 | Uma instrução por etapa. | 1. Abra o arquivo e altere a versão. | 1. Abra o arquivo. 2. Altere a versão. |
| 10 | Parágrafos: 6 frases ou menos. | Um bloco de dez frases. | Dois parágrafos curtos, ou uma lista. |
Mais regras:
- Escreva um aviso ou cuidado antes da etapa à qual se aplica. Comece com o perigo: "Aviso: isso exclui o branch."
- Use números, não palavras, para valores: "72 caracteres", não "setenta e dois caracteres".
- Use uma lista ou uma tabela quando fornecer três ou mais itens.
- Não use sinônimos para variar o texto. Repita o mesmo termo.
- Não use "ele" ou "isso" quando o substantivo não estiver claro. Nomeie o substantivo novamente.
- Quando um termo não estiver no vocabulário e o significado não estiver claro, pergunte ao usuário. Em seguida, adicione o termo ao vocabulário.
Justificativas Comuns
| Justificativa | Realidade |
|---|---|
| "Frases curtas soam robóticas." | Frases curtas são rápidas de ler e difíceis de interpretar mal. A velocidade do leitor importa mais que o estilo. |
| "Um sinônimo torna o texto menos repetitivo." | Um sinônimo faz o leitor perguntar se é uma coisa diferente. |
| "Este comentário é pequeno demais para as regras." | Comentários e mensagens de commit estão no escopo. Texto pequeno é fácil de corrigir. |
| "A voz passiva é mais formal." | A voz passiva esconde quem faz a ação. Nomeie o ator. |
Bandeiras Vermelhas
- Frases com "e", "que" ou "para que" que unem dois tópicos.
- "Deveria", "poderia" ou "talvez" em uma instrução.
- A mesma coisa tem dois nomes em um documento.
- Uma etapa com duas ações.
- Um aviso após a etapa à qual se aplica.
Verificação
- Cada frase tem um tópico.
- Nenhuma instrução tem mais de 20 palavras. Nenhuma descrição tem mais de 25 palavras.
- Todas as instruções usam o imperativo e a voz ativa.
- Todos os termos correspondem ao vocabulário.
- Cada etapa da lista tem uma instrução.
- Nenhum parágrafo tem mais de 6 frases.