writing: el lector tiene cinco minutos; cada oración paga su parte
El fallo que este método previene: texto que dice poco con muchas palabras, en el ritmo que todo modelo produce (una apertura que anuncia, un cuerpo en tres puntos, un cierre que repite), y que por el camino cambia un número, suelta un "quizás" o inventa una fuente. El segundo fallo es la reescritura que deja el texto suave y elimina la voz del escritor.
0. El proyecto decide
Antes de escribir para un proyecto, lee CLAUDE.md / AGENTS.md y busca los
skills propios del proyecto en .claude/skills/. Las reglas y skills del proyecto
prevalecen sobre este: plantilla y puerta de PR, convención de commits, idioma
declarado, guía de voz, el sistema de diseño para el aspecto. Este skill es el
predeterminado para cuando el proyecto no tiene ninguno. El idioma, el registro y
la voz provienen del proyecto (sección 10), nunca de un proyecto o persona fijos.
Quién lo usa: cada agente del escuadrón que escribe texto para una persona (página
de aterrizaje, tarjeta, handoff, PR, informe, commit, README). El skill escribe;
el envío, la publicación y el posteo siempre pertenecen al propietario.
$WRITING es el directorio de este skill (~/.claude/skills/writing); los
scripts son de la stdlib de Python, ejecútalos con python3 -I.
1. Cinco trabajos: elige uno antes de empezar
| Trabajo | Disparador | Salida |
|---|---|---|
| Escribir (predeterminado) | Produces el texto: doc, mensaje, PR, respuesta | El texto, nada sobre el texto |
| Editar | El propietario entrega un borrador para corregir | El borrador editado y un breve Qué cambió |
| Detectar | "¿esto suena a IA?", "audita esto", "señálalo sin reescribir" | Patrones nombrados, una línea citada por cada uno, la solución en pocas palabras. Sin reescritura, sin puntuación, sin afirmación sobre quién lo escribió |
| Calibrar | Dos o más muestras: "escribe como yo", "la voz del producto" | Un perfil de voz en el formato de references/voice-profile.md, para editar y conservar |
| Comprimir | "comprime CLAUDE.md", "recorta la memoria", "menos tokens en este handoff" | El archivo más pequeño con todos los hechos, y el resultado de fidelity_check.py |
En Detectar, un patrón nombrado es evidencia que el propietario puede verificar;
un detector de IA adivina. Un perfil de voz se mantiene para cada trabajo
posterior en la sesión, va al linter como --profile y cambia solo los patrones
mecánicos, nunca un hecho o una construcción prohibida.
2. Niveles de ceremonia
El proceso sigue el riesgo. Cada nivel obedece las reglas; solo cambia la puerta.
| Nivel | Texto | Proceso |
|---|---|---|
| 0 | Respuesta de chat, estado de terminal, mensaje de commit, comentario de código, tarjeta de una línea | Las reglas de memoria. Sin script, sin informe, sin metaconentario |
| 1 | Cuerpo de PR, tarjeta de AgenFK, handoff, publicación en Slack o WhatsApp, correo electrónico, changelog, README corto | Las reglas más el barrido mecánico (sección 9) |
| 2 | Más de ~400 palabras que leerá un tercero: especificación, ADR, propuesta, informe, postmortem, documento de arquitectura | El proceso completo; ambos scripts pasan antes de que digas que está listo |
Modo ligero. Con "modo ligero", "caveman", "sé breve" o "menos tokens", el
nivel 0 se vuelve más estricto hasta "modo normal": responde primero, cero
ceremonia, artículos opcionales y negación nunca, una idea por oración de hasta
20 palabras, carga útil (código, comando, ruta, error) textual, estado de
herramientas breve, sin interpretar el modo. Vuelve a oraciones completas para
una advertencia de seguridad, una acción irreversible, un orden de pasos, un
solicitante confundido, una pregunta al usuario y todo lo que se registra fuera
del chat. Un mensaje de commit sigue la convención del repositorio (lee
git log primero); sin convención, Conventional Commits en imperativo, cuerpo
solo con el por qué. Reglas completas y la verificación antes de enviar:
references/lean.md.
El nivel 0 no es una exención: las reglas aplican a cada respuesta en la sesión,
porque después de unos turnos vuelve la cadencia predeterminada.
Auto-verificación de memoria para los niveles 0 y 1: el último bloque de
eval.md.
3. Gravedad
Los hallazgos no pesan igual, y el orden decide qué se corrige primero y qué nunca se envía. La estructura pesa más que el léxico: un documento con una lista de palabras limpia y una forma de anuncio-cuerpo-resumen sigue siendo slop, y un término preciso que está en la lista no lo es.
| Nivel | Qué | Puerta |
|---|---|---|
| Bloquea | Un hecho, nombre, número, fecha, cita o fuente inventados. Un calificador eliminado, debilitado o fortalecido. Una decisión, número o requisito cambiado. Código, tabla, enlace o frontmatter tocados. Una contradicción con la fuente | Nunca se envía. Ninguna directiva allow lo cubre. fidelity_check.py distinto de cero, o un elemento de la lista de cobertura faltante |
| Corregir | Un ERROR del linter: léxico o construcción prohibidos, encabezado genérico, emoji, lista en lugar de prosa, residuo de chatbot. Estructural: apertura vacía, cierre resumidor, párrafos del mismo molde | Corrígelo, o consérvalo con una justificación de una línea o un allow en línea. Nunca eliminando el hecho en el que se encuentra el hallazgo |
| Preferible corregir | Un WARN del linter: construcciones suaves, ritmo, densidad, transiciones, certeza, nominalización, portabilidad | Corrígelo cuando no cueste ningún hecho. De lo contrario, déjalo y continúa |
| Aviso | Un juicio de eval.md: el corte del 15%, encabezados, medio, simetría | Tú decides. Di lo que dejaste |
4. Las tres reglas por encima de todo
La fidelidad vence a la legibilidad. Nunca cambies un requisito, decisión, número, nombre, riesgo, criterio de aceptación o hecho para que la oración fluya. Si el hecho se lee mal, cambia la oración a su alrededor, no el hecho. Nunca inventes un hecho, nombre, número, fecha, cita o fuente. Mantén textual: código, comandos, diagramas, enlaces, tablas, frontmatter, identificadores técnicos.
La voz vence al pulido. Haz la edición mínima que lo resuelva. Primero nota el vocabulario, la cadencia, la franqueza, el humor, la incertidumbre y las digresiones del borrador, y consérvalos. No dejes cada párrafo igual de ordenado; una opinión fuerte, una palabrota y una admisión honesta se quedan cuando pertenecen al escritor. Abrir un texto no es simplificarlo. La personalidad encaja en una publicación y un artículo de opinión; el texto de referencia, legal y de incidentes se mantiene neutral.
La incertidumbre es un hecho. "Puede", "estimado", "inferido" y "aún no medido" dicen cuánto sabe el escritor. Cortar coberturas apiladas deja una cobertura y nombra lo que es incierto; nunca promueve la afirmación. En texto de seguridad, legal, financiero, médico y de incidentes, el calificador es el contenido y se queda incluso cuando la oración se lee mejor sin él. Lo contrario también es incorrecto: nunca cubras un hecho que la fuente establece.
5. La prueba de la oración
Cada oración entrega información, razonamiento, contexto necesario o una acción. Una oración cuyo único papel es énfasis, ceremonia o relleno: bórrala, no la reescribas.
En documentos técnicos y operativos el estándar es más alto, porque el razonamiento allí suele ser corto: cada oración lleva un hecho, número, comando, nombre, decisión o riesgo. La prosa ejecutiva y la conversación tienen espacio para la causa y el encuadre, y perder eso es un fallo diferente.
Prueba de portabilidad. Si la oración se mueve sin cambios a otra persona, empresa, país o producto, es relleno. Córtala, o reemplázala con un hecho, mecanismo, consecuencia o juicio específico del tema.
Muestra, no digas. Los hechos, acciones y consecuencias llevan el énfasis. Corta el comentario que etiqueta un punto como importante, sorprendente o sutil en lugar de mostrarlo.
Pon la medida. Un adjetivo medible sin un número es una afirmación sin
evidencia. Una clasificación técnica no lo es: endpoint público, subred privada, dependencia externa, aprobación manual, migración reversible y
etiqueta inmutable son el término preciso y se quedan.
| Palabra | Reemplázala con |
|---|---|
| robusto / robusto | lo que soporta: reintento, failover, probado en N |
| escalable / escalável | hasta cuánto: RPS, nodos, GB, inquilinos |
| significativo / significativo | el número |
| rápido / rápido | la latencia o la duración |
| varios / vários | el recuento |
| recientemente / recentemente | la fecha |
| mejor práctica / boa prática | de quién, qué documento |
6. Estructura
- Responde primero. La decisión, la solución, el número o el comando es la primera línea.
- Sin párrafo de apertura que anuncie lo que cubre el documento, sin párrafo de cierre que lo repita. Cada conclusión una vez; el lector acaba de leerla.
- Un encabezado nombra el contenido ("Rollback"), nunca hace una pregunta, y nunca es repetido por la primera oración debajo de él. Formas prohibidas: Resumen, Conclusiones clave, Reflexiones finales, Conclusión, Introducción, El camino a seguir, Resumen completo, Destacados estratégicos, Recorrido de implementación.
- Un párrafo lleva razonamiento. Una lista es para lo que realmente es un conjunto. Una tabla solo cuando el lector compara filas contra columnas.
- Varía la longitud de las oraciones y los párrafos. Nunca construyas un grupo de tres porque tres suena completo.
- Si cabe en tres líneas, son tres líneas.
El mensaje que acompaña a un archivo dice en una línea qué cambió, sin "aquí
está el documento" y sin oferta de ayuda. Formas por tipo de documento:
references/shapes.md.
7. El medio más claro
No empieces con prosa por defecto. Antes de una sección larga, nombra la
relación que el lector necesita entender y elige el medio más pequeño que
conserve el significado. Reglas completas en references/visuals.md.
| El lector necesita | Usa |
|---|---|
| Comparar 3+ elementos en 2+ atributos, o leer un mapeo exacto | Tabla |
| Seguir una secuencia, topología, jerarquía, propiedad, estado o dependencia | Diagrama |
| Reconocer una pantalla, posición, diseño, o un antes/después | Figura anotada |
| Ejecutar un procedimiento | Pasos numerados y código listo para pegar |
| Entender causa, matiz o por qué se decidió algo | Prosa |
Un visual proviene solo de material confirmado en la fuente, con una conclusión de una línea y texto alternativo, sin duplicarlo en prosa. Una imagen generada nunca sirve para topología, datos, valores o arquitectura exactos. Un diagrama grande y vacío es slop.
Un diagrama de arquitectura o nube es una afirmación sobre un sistema real:
sigue el skill cloud-diagram (inventario antes que geometría, actual o
propuesto, una fuente editable, una sonda de renderizado). Este skill se ocupa
solo de la prosa que lo rodea.
Documento renderizado (HTML, Artefacto, su PDF): el aspecto pertenece al
proyecto. Empieza desde templates/document.html y reemplaza el bloque --ds-*
al inicio con la salida de python3 -I ~/.claude/skills/design-reference/scripts/sweep.py <root> --css (sin sistema de
diseño en el proyecto, se mantiene la paleta neutral del escuadrón). Un idioma
por defecto; bilingüe solo con una audiencia bilingüe o a petición, desde
templates/document-bilingual.html con <html data-languages="en pt">. Antes
de entregar: python3 -I "$WRITING/scripts/artifact_check.py" <file>. PR,
tarjeta, commit y markdown en docs/ no toman nada de esto. Reglas:
references/rendered-document.md.
Presentación: cuando un skill de presentación esté instalado, llámalo antes de planificar las diapositivas; él posee la estructura, el diseño y el renderizado, este skill posee la prosa y la fidelidad. No conviertas un README, ADR, runbook, tarjeta o correo electrónico en diapositivas a menos que te lo pidan.
Pull request: el cuerpo sirve a un revisor con 30 segundos para decidir si
abrir el diff: qué cambia, por qué, qué se omitió, cómo se verificó, riesgo y
rollback. Sin narrar el trabajo del agente y sin repetir los commits.
Estructura: el skill pull-request (o el del proyecto); la prueba de 30
segundos en references/pull-requests.md. Solo github abre un PR, después
del SHIP del verifier.
8. Patrones y palabras que cortar
El catálogo con soluciones, los pares antes/después y las listas de palabras en
ambos idiomas están en references/patterns.md (un resumen rápido abre el
archivo). Léelo una vez por sesión. Los más frecuentes: contraste binario ("no
es solo X, es Y"), revelación de dos puntos, carraspeo ("vale la pena notar"),
falso conocimiento, anuncio ("vamos a sumergirnos"), cláusula superficial en
-ing al final, palabrería, fuente vaga, metadiscurso, actor oculto, negación
recortada al final ("sin drama"), residuo de chatbot, coberturas apiladas, una
fila de fragmentos dramáticos.
Una palabra marcada (apalancar, sin fisuras, profundizar, robusto; alavancar,
robusto, jornada, ecossistema) se elimina, no se intercambia por un
sinónimo. Algunas son la palabra precisa en contexto ("decisión estratégica" en
un documento de estrategia; gate, harness, pipeline, realm como términos
técnicos): conservarla cuesta una justificación de una línea o
<!-- writing: allow <término> -->, nunca silencio. Un adverbio vacío (solo,
realmente, simplemente; só, literalmente, na verdade) se va cuando no añade
nada y se queda cuando lleva énfasis, incertidumbre o el ritmo del escritor.
9. Barrido mecánico
En el texto final, a partir del nivel 1: sin guion largo o corto (a menos que
la muestra del escritor los use), comillas rectas, encabezados en mayúscula y
minúscula, minúscula después de dos puntos, sin emoji, negrita solo para un
término definido o una advertencia, sin lista de etiquetas en negrita, un bloque
de código para todo lo que se pegue. Lista completa en
references/process.md.
10
…
[truncado para traducción]