Humanizar Salida
Crear trabajo que sea útil en su entorno real, no simplemente con forma de respuesta pulida. Tratar el "olor a IA" como un problema de calidad de salida: contexto faltante, evidencia débil, estructura genérica, lenguaje ornamental o decisiones poco prácticas. Nunca afirmar que el estilo demuestra autoría de IA.
Principios fundamentales
- Contexto sobre plantilla: ajustarse al lector, tarea, repositorio, medio y restricciones antes de elegir una estructura.
- Claridad sobre sofisticación: preferir el lenguaje más preciso que la audiencia pueda entender.
- Sustancia sobre volumen: eliminar contenido que no ayude a alguien a decidir, actuar, implementar o verificar.
- Evidencia sobre afirmación: fundamentar, calificar o etiquetar las afirmaciones; no inventar hechos, métricas, citas, APIs o capacidades.
- Propósito sobre convención: usar encabezados, tablas, tarjetas, patrones y abstracciones solo cuando ayuden a la tarea.
- Juicio humano sobre automatización: tratar los hallazgos del linter como indicaciones de revisión, no como veredictos automáticos.
Elegir un modo
Usar el modo Generación por defecto. Aplicar estos principios mientras se produce el artefacto solicitado, luego ejecutar una verificación de entrega breve antes de responder.
Usar el modo Revisión cuando el usuario proporcione un artefacto existente, solicite explícitamente crítica/revisión, o la tarea sea de alto riesgo. Diagnosticar los problemas importantes, revisar el artefacto directamente cuando esté autorizado y validar el resultado.
Flujo de trabajo
- Establecer el contrato de salida a partir del contexto disponible:
- audiencia y propósito práctico;
- medio y formato solicitados;
- convenciones y restricciones del proyecto;
- evidencia o verificación esperada;
- qué significa "listo para usar". Preguntar solo cuando una respuesta faltante cambiaría materialmente el resultado. En caso contrario, hacer la suposición segura más pequeña y declararla brevemente si es relevante.
- Seleccionar el dominio dominante y leer solo su archivo de referencia. Agregar un segundo dominio solo para un artefacto genuinamente mixto.
- Producir o inspeccionar el artefacto según cinco preguntas:
- ¿Responde a la solicitud real en lugar de una versión genérica?
- ¿Cada afirmación importante está fundamentada, calificada o marcada para verificación?
- ¿La estructura refleja prioridad y flujo de trabajo en lugar de una plantilla estándar?
- ¿El lenguaje, la profundidad técnica y el diseño son apropiados para la audiencia?
- ¿Se puede usar o verificar el resultado sin llenar vacíos obvios?
- Revisar eliminando ruido antes de agregar contenido. Preservar la terminología precisa, la estructura útil, la voz del autor y las convenciones del proyecto.
- Ejecutar la verificación de entrega y devolver el artefacto solicitado. No agregar un ensayo de revisión a menos que ayude al usuario o lo haya solicitado.
Enrutamiento por dominio
| Artefacto | Leer |
|---|---|
| Issue de GitLab/GitHub, tarea, requisito, criterios de aceptación | references/issue.md |
| README, guía de API, documentación técnica o general | references/documentation.md |
| Propuesta de arquitectura, ADR, diseño de sistema, elección tecnológica | references/architecture.md |
| Código, comentarios, nomenclatura, abstracciones, plan de implementación | references/code.md |
| UI/UX, consola de administración, panel, especificación de componente o página | references/ui-ux.md |
| Diapositivas, informe técnico, revisión de proyecto, esquema de presentación | references/presentation.md |
| Respuesta de chat, explicación, recomendación, preguntas frecuentes | references/conversation.md |
Para síntomas a nivel de lenguaje en todos los dominios, consultar también references/language.md cuando la redacción en sí sea un problema central. No cargar todas las referencias por defecto.
Gravedad de revisión
- P0 — Bloqueante: error factual, evidencia o cita inventada, problema de seguridad/protección, o flujo central roto. Corregir antes de la entrega.
- P1 — Mayor: instrucciones inutilizables, decisión central sin respaldo, contexto crítico faltante o requisito principal poco claro. Corregir antes de la entrega.
- P2 — Calidad: redacción genérica, repetición, abstracción innecesaria, diseño decorativo o residuo visible de patrón de IA que debilita el artefacto. Normalmente corregir.
- P3 — Preferencia: elección estilística opcional sin efecto significativo. No forzar un cambio.
En modo Revisión, informar solo hallazgos relevantes. Usar esta forma compacta cuando un informe sea útil:
### P1 — [problema específico]
- Evidencia: [cita o decisión visible]
- Impacto: [por qué impide que el artefacto cumpla su función]
- Corrección: [cambio concreto]
- Revisión: [texto de reemplazo o dirección de implementación, cuando sea útil]
Juicio de lenguaje
No convertir la humanización en un ejercicio de palabras prohibidas. Términos como "gating", "convergence", "orchestration" o sus equivalentes en español pueden ser precisos en el campo correcto. Mantener un término cuando sea estándar para el lector previsto y más preciso que un sustituto en lenguaje sencillo.
Adaptar el lenguaje del entregable solicitado. Para salida en español, preferir el orden de información natural del español y el uso técnico establecido; no preservar la estructura de la oración en inglés solo porque sea gramaticalmente traducible. Leer references/language.md para verificaciones específicas del español cuando la redacción sea una preocupación central. Mantener abreviaturas estándar como API, ADR, SSO y UI/UX cuando sean más claras para los lectores previstos que traducciones forzadas.
Observar grupos en lugar de tokens aislados: marcos vacíos, traduccionés, afirmaciones teatrales, conclusiones repetidas, encabezados excesivos, listas uniformes de tres partes y verbos inflados pueden combinarse en una voz genérica. Reescribir el pensamiento subyacente, no solo la palabra marcada.
El linter opcional usa data/zh-output-smells.json para identificar candidatos (actualmente configurado principalmente para chino). Incluye reglas léxicas y sintácticas en chino, reescrituras sugeridas, gravedad y exenciones de contexto para uso técnico legítimo:
python scripts/humanize_lint.py <file> [<file> ...]
python scripts/humanize_lint.py --list
python scripts/humanize_lint.py <file> --format json --fail-on P2
El umbral de salida predeterminado es P1. Usar --fail-on P2 solo cuando un proyecto trate deliberadamente la salida genérica como una puerta de entrega; usar --fail-on none para escaneos de asesoramiento. Los bloques de código y el código en línea se omiten a menos que se proporcione --include-code.
Inspeccionar cada hallazgo en contexto. Leer su context_note antes de cambiar términos técnicos como "门控", "收敛", "原语" o "心智模型". Nunca reescribir solo para que el linter pase.
Verificación de entrega
Antes de devolver el resultado:
- Confirmar que se cumplan el formato y alcance solicitados.
- Eliminar afirmaciones sin respaldo, detalles inventados, marcadores de posición, conclusiones repetidas y secciones de plantilla no utilizadas.
- Confirmar que los ejemplos, comandos, APIs, diseños o recomendaciones sean plausibles en el entorno indicado; probarlos cuando la tarea lo permita.
- Verificar que la apertura llegue al punto útil y el cierre proporcione la decisión, acción o resultado necesarios.
- Preferir el artefacto en sí mismo sobre comentarios acerca de lo bien que fue escrito.
Ver examples/before-after.md para ejemplos de Issue, arquitectura y UI. Usarlos como ejemplos de razonamiento, no como plantillas.