Codex Reglas y Hooks

Mediante las reglas y los hooks, puedes personalizar el comportamiento de Codex para que se adapte mejor a tu flujo de trabajo. Esta sección detalla ambas funciones.


Reglas

Las reglas te permiten definir pautas de comportamiento personalizadas para Codex, aplicadas a todas las conversaciones.

Ubicación de los archivos de reglas

Codex carga las reglas desde las siguientes ubicaciones:

  • ~/.codex/rules/- Reglas a nivel de usuario
  • {项目}/.codex/rules/- Reglas a nivel de proyecto

Formato de los archivos de reglas

Crear un archivo de reglas

# Mis reglas de codificación

## Estilo de código
- Usar sangría de 4 espacios
- Máximo 100 caracteres por línea
- Usar siempre const/let, no usar var

## Normas de comentarios
- Las funciones públicas deben incluir comentarios JSDoc
- Agregar comentarios en línea para lógica compleja
- Eliminar todos los console.log de depuración

## Requisitos de pruebas
- Todas las funciones nuevas deben incluir casos de prueba
- Nombres de archivos de prueba: *.test.js o *.spec.js

## Confirmaciones de Git
- Los mensajes de confirmación usan el formato Conventional Commits
- Ejecutar lint y pruebas antes de confirmar

Habilitar reglas

Habilitar reglas en la configuración

[features]
codex_hooks = true
Las reglas se inyectan en el aviso del sistema de cada conversación, asegurando que Codex siga siempre tus normas de codificación.

Hooks

Los hooks te permiten ejecutar acciones personalizadas cuando ocurren eventos específicos.

Ubicación de los archivos de hooks

Los hooks~/.codex/hooks.jsonse configuran en:

Crear configuración de hooks

{
  "hooks": [
    {
      "event": "on_tool_call",
      "match": "shell",
      "action": "allow"
    },
    {
      "event": "on_task_complete",
      "action": "notify",
      "command": "echo 'Task completed'"
    }
  ]
}

Eventos disponibles

EventoDescripción
on_tool_callSe activa antes de la llamada a una herramienta
on_task_startSe activa al inicio de la tarea
on_task_completeSe activa al completar la tarea
on_errorSe activa cuando ocurre un error
on_messageSe activa al recibir un mensaje

Acciones de hooks

AcciónDescripción
allowPermitir que la operación continúe
denyBloquear la operación
notifyEnviar notificación
logRegistrar logs
customEjecutar script personalizado
Para habilitar los hooks, se debe configurar[features].codex_hooks = true

Ejemplos prácticos

Ejemplo 1: Ejecutar pruebas automáticamente

Ejecutar pruebas automáticamente después de cada modificación de archivos por Codex:

Hook de pruebas automáticas

{
  "hooks": [
    {
      "event": "on_tool_call",
      "match": "edit_file",
      "action": "custom",
      "command": "npm test",
      "timeout": 60
    }
  ]
}

Ejemplo 2: Forzar revisión de código

Forzar una revisión de código antes de confirmar:

Hook de revisión de código

{
  "hooks": [
    {
      "event": "on_tool_call",
      "match": "git_commit",
      "action": "custom",
      "command": "/review",
      "require_approval": true
    }
  ]
}

Ejemplo 3: Registrar logs

Registrar todas las ejecuciones de comandos:

Hook de registro

{
  "hooks": [
    {
      "event": "on_tool_call",
      "match": "shell",
      "action": "log",
      "log_file": "/tmp/codex-commands.log"
    }
  ]
}

Diferencias entre reglas y hooks

CaracterísticaReglasHooks
Momento de aplicaciónAl inicio de la conversaciónCuando se activa un evento
Uso principalDefinir normas de codificaciónAutomatizar acciones
Ubicación de configuraciónDirectorio rules/hooks.json
Las reglas y los hooks se pueden combinar: las reglas definen "cómo hacerlo", los hooks definen "cuándo hacerlo".

Mejores prácticas

Mejores prácticas para reglas

  • Mantén las reglas concisas y claras
  • Evita restricciones demasiado estrictas
  • Ajusta las reglas según las necesidades del proyecto

Mejores prácticas para hooks

  • Evita hooks de larga duración
  • Establece tiempos de espera razonables
  • Prueba el comportamiento de los hooks
El uso excesivo de hooks puede afectar el rendimiento de Codex; agrega solo los hooks que realmente necesites.

Preguntas frecuentes

P: ¿Las reglas no tienen efecto?

Asegúrate de que el archivo de reglas esté en la ubicación correcta y de que la característicacodex_hooksesté habilitada.

P: ¿Un fallo en la ejecución de un hook bloqueará la operación?

Depende de la configuración del hook; algunos fallos de hooks pueden bloquear operaciones posteriores.

P: ¿Se pueden habilitar/deshabilitar reglas dinámicamente?

Sí, se puede controlar mediante archivos de configuración o variables de entorno.

Otras extensiones