Inglés Simplificado
Resumen
Regla 1 de las reglas de Jarrett: la salida del chat, los documentos generados, los comentarios de código y los mensajes de commit usan inglés técnico simplificado. El estilo se basa en los principios de ASD-STE100. Los lectores encuentran los hechos más rápido. Los lectores cuyo primer idioma no es el inglés entienden más.
Esta habilidad es nuestro propio resumen. No es el estándar ASD-STE100 y no incluye su diccionario.
Cuándo Usarlo
- Escribes o editas una especificación, plan, ADR, README, entrada de vocabulario u otro documento.
- Escribes un comentario de código o un mensaje de commit.
- Revisas texto para la regla 1.
No lo apliques a identificadores de código, salida citada (errores, registros, salida de comandos), archivos de habilidades o texto que el usuario escribió.
Proceso
Escribe el texto. Luego verifícalo contra cada regla.
| # | Regla | No así | Así |
|---|---|---|---|
| 1 | Un tema por oración. | El hook lee el archivo y, si falta, imprime una advertencia, que el usuario ve. | El hook lee el archivo. Si el archivo falta, el hook imprime una advertencia. El usuario ve la advertencia. |
| 2 | Instrucciones: 20 palabras o menos. Descripciones: 25 palabras o menos. | Asegúrate de que antes de continuar y empujar la rama hayas ejecutado la suite de pruebas completa y verificado la salida. | Ejecuta ./scripts/test.sh. Luego empuja la rama. |
| 3 | Usa la voz activa. | Las reglas son cargadas por el hook. | El hook carga las reglas. |
| 4 | Las instrucciones usan el imperativo. | La prueba debería ejecutarse antes del commit. | Ejecuta la prueba antes del commit. |
| 5 | Una palabra tiene un significado. Usa los términos en .claude-work/docs/VOCABULARY.md. | Advertir, luego después "marcar", "alertar" o "notificar" para la misma acción. | Advertir, cada vez. |
| 6 | Usa tiempos simples: presente, pasado, futuro. | El hook habría estado verificando la entrada. | El hook verifica la entrada. |
| 7 | Usa un verbo simple, no un verbo frasal o modismo. | Inicia la compilación. Averigua la causa. | Inicia la compilación. Encuentra la causa. |
| 8 | Mantén "el" y "un". | Ejecuta script, verifica salida. | Ejecuta el script. Verifica la salida. |
| 9 | Una instrucción por paso. | 1. Abre el archivo y cambia la versión. | 1. Abre el archivo. 2. Cambia la versión. |
| 10 | Párrafos: 6 oraciones o menos. | Un bloque de diez oraciones. | Dos párrafos cortos, o una lista. |
Más reglas:
- Escribe una advertencia o precaución antes del paso al que aplica. Comienza con el peligro: "Advertencia: esto elimina la rama."
- Usa números, no palabras, para los valores: "72 caracteres", no "setenta y dos caracteres".
- Usa una lista o una tabla cuando des tres o más elementos.
- No uses sinónimos para variar el texto. Repite el mismo término.
- No uses "ello" o "esto" cuando el sustantivo no esté claro. Nombra el sustantivo nuevamente.
- Cuando un término no esté en el vocabulario y el significado no esté claro, pregúntale al usuario. Luego agrega el término al vocabulario.
Racionalizaciones Comunes
| Racionalización | Realidad |
|---|---|
| "Las oraciones cortas suenan robóticas." | Las oraciones cortas son rápidas de leer y difíciles de malinterpretar. La velocidad del lector importa más que el estilo. |
| "Un sinónimo hace que el texto sea menos repetitivo." | Un sinónimo hace que el lector pregunte si es algo diferente. |
| "Este comentario es demasiado pequeño para las reglas." | Los comentarios y los mensajes de commit están incluidos. El texto pequeño es fácil de corregir. |
| "La voz pasiva es más formal." | La voz pasiva oculta quién realiza la acción. Nombra al actor. |
Banderas Rojas
- Oraciones con "y", "que" o "así que" que unen dos temas.
- "Debería", "podría" o "pudiera" en una instrucción.
- La misma cosa tiene dos nombres en un documento.
- Un paso con dos acciones.
- Una advertencia después del paso al que aplica.
Verificación
- Cada oración tiene un tema.
- Ninguna instrucción tiene más de 20 palabras. Ninguna descripción tiene más de 25 palabras.
- Todas las instrucciones usan el imperativo y la voz activa.
- Todos los términos coinciden con el vocabulario.
- Cada paso de lista tiene una instrucción.
- Ningún párrafo tiene más de 6 oraciones.