> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codewarden.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Referencia de .codewarden.yml

> Cada clave del archivo que un repositorio usa para decirle a CodeWarden sus propias reglas: tipo, valor por defecto y un ejemplo.

`.codewarden.yml` es un archivo opcional en la raíz de un repositorio. Indica cómo quiere ese repositorio que lo revisen: qué rutas omitir, qué reglas aplican en qué rutas, qué datos suele equivocar el modelo y qué pull requests no revisar en absoluto.

Sin archivo, un repositorio recibe todos los valores por defecto de esta página. Todas las claves son opcionales.

## De dónde se lee

CodeWarden lee `.codewarden.yml` desde la **base branch** del pull request, en su punta actual. Nunca lee la copia que está en el pull request que se revisa, ni siquiera cuando el pull request es el que agrega o edita el archivo.

Esto es a propósito. Si se leyera la copia editada, cualquiera que pueda abrir un pull request podría reescribir las instrucciones del revisor, o desactivar la revisión, en el mismo commit que oculta un defecto. Un cambio en `.codewarden.yml` surte efecto en los pull requests hacia una base branch una vez que se hace merge en esa base branch.

## Un archivo malo nunca hace fallar una revisión

| Situación | Qué pasa |
| - | - |
| No hay archivo | Valores por defecto. |
| GitHub no entrega el archivo | Valores por defecto, y la revisión se ejecuta. |
| No es YAML válido, o no es un mapeo | Valores por defecto, y la revisión se ejecuta. |
| Una clave tiene la forma equivocada | Esa clave usa su valor por defecto. Todas las demás claves siguen aplicando. |
| Una entrada de una lista está mal formada | Esa entrada se descarta. El resto de la lista aplica. |
| Una clave que CodeWarden no conoce | Se ignora. Es seguro escribir una clave de una versión más nueva. |
| Texto que excede un límite de longitud | Ese elemento se descarta. |

Lo que estaba vigente en cada revisión, y cualquier cosa que se descartó, se muestra en la página de la revisión en la [consola](https://docs.codewarden.co/es/console/review-history.md) bajo **Qué estaba vigente**. La lista de verificación de configuración de la página de inicio de la consola también dice si el archivo se encontró y se pudo usar.

## Un ejemplo completo

```yaml .codewarden.yml theme={null}
language: en
profile: balanced
tone: "Be direct. Skip the preamble."

ignore:
  - "legacy/**"
  - "priv/static/**"
unignore:
  - "docs/architecture.md"

instructions:
  - path: "lib/**/workers/**"
    text: |
      These run in a job queue with retries. Flag anything that is not safe
      to run twice on the same input.

errata:
  - "URI.parse/1 fills in the scheme's default port, so .port is 443 for https, never nil."

skip:
  labels: ["no-review"]
  authors: ["dependabot[bot]", "renovate[bot]"]
  base_branches: []

jira:
  projects: ["PROJ"]
  public_repositories: false

sentry:
  projects: ["widgets-api"]
  public_repositories: false

accepted:
  - path: lib/widgets/clicks.ex
    problem: "read-modify-write on the click counter"
    category: bug
    code: |
      |> Ecto.Changeset.change(clicks: link.clicks + 1)
    reason: "the counter is advisory and the nightly job recomputes it"
```

## Lo que CodeWarden escribe

### language

**language** `string` (default: en)

El idioma del resumen y de los comentarios, como un código ISO tal como `en`, `es` o `pt-BR` (de 2 a 8 caracteres).

Con `en` o `es` (también `es-CO`, `es-MX`), las palabras que CodeWarden agrega alrededor de un hallazgo también salen en ese idioma: la etiqueta de gravedad, "Prompt para LLM", el pie del comentario, el marco del resumen, el resultado del check y el aviso de que empezó a revisar. Con cualquier otro código el modelo sigue escribiendo en ese idioma, y esas palabras agregadas quedan en inglés. Los avisos de que falta un plan o de que se agotó el cupo, y la oferta de copiar una regla a este archivo, quedan en inglés.

### profile

**profile** `quiet | balanced | strict` (default: balanced)

La mayor cantidad de comentarios que puede llevar una revisión: `quiet` son 4, `balanced` son 8, `strict` son 15.

Eso es todo lo que define. Los hallazgos se ordenan de peor a mejor, así que un tope menor conserva los más graves. No filtra por gravedad, y no existe un ajuste de confianza mínima: consulta [Cómo funciona una revisión](https://docs.codewarden.co/es/how-a-review-works.md#what-decides-which-comments-are-published).

### tone

**tone** `string` (default: none)

Una o dos frases sobre la voz de los comentarios, de hasta 200 caracteres. El texto más largo se descarta.

```yaml theme={null}
tone: "Be direct. Skip the preamble."
```

## Lo que CodeWarden lee

### ignore

**ignore** `list of globs` (default: \[])

Rutas que nunca se revisan, además de la [lista incorporada](https://docs.codewarden.co/es/how-a-review-works.md#which-files-are-read).

```yaml theme={null}
ignore:
  - "legacy/**"
  - "**/*_generated.ex"
```

### unignore

**unignore** `list of globs` (default: \[])

Rutas que se revisan aunque la lista incorporada o `ignore` las omitirían. `unignore` gana sobre ambas.

No puede rescatar un archivo sin diff, ni uno con más de 1.500 líneas modificadas.

```yaml theme={null}
unignore:
  - "docs/architecture.md"
```

### Globs

Los globs coinciden con la ruta completa desde la raíz del repositorio, distinguiendo mayúsculas de minúsculas. `**` cruza los límites de directorio; `*` y `?` no. `lib/**` coincide con archivos bajo `lib/` y no con `vendor/lib/x.ex`. Un patrón que no coincide con nada no es un error.

## Lo que CodeWarden sabe

### instructions

**instructions** `list of \{ path, text \}` (default: \[])

Reglas para rutas concretas. El texto se agrega a la revisión solo para los archivos cuya ruta coincide con `path`, así que un controlador puede someterse a reglas que un módulo auxiliar no tiene.

Úsalo para decir qué cuenta como defecto ahí: una regla que tu equipo decidió en un documento de diseño, en una especificación o en la cabeza de alguien, y que el revisor no puede ver de otro modo.

Cada `text` está limitado a 2.000 caracteres; una entrada con `path` o `text` vacío, o que exceda el límite, se descarta. Las instrucciones que coinciden con los archivos de una revisión comparten 8.000 caracteres, para que un repositorio no desplace su propio código fuera de la revisión. Cuando no caben todas, van primero las que coinciden con más archivos.

```yaml theme={null}
instructions:
  - path: "lib/**_web/live/**"
    text: |
      Every handle_event must load records through the caller's scope.
      A record loaded by id alone is an authorization hole, not a style issue.
```

`instructions` no puede:

* hacer que CodeWarden comente en una línea que el pull request no agregó;
* activar comentarios sobre estilo, nombres, formato, orden de imports, pruebas faltantes, documentación faltante, ni nada formulado como "considera";
* llegar a un archivo que el pull request no tocó, ni a uno que los filtros omitieron;
* reemplazar las reglas que recibe el revisor. Solo agrega a ellas.

### errata

**errata** `list of strings` (default: \[])

Datos sobre tus bibliotecas que el modelo se equivoca. Una frase cada uno, que diga lo que es verdad, de hasta 300 caracteres. Se conservan en el orden en que los escribes.

Agrega uno el día en que CodeWarden publique una afirmación errónea con total seguridad sobre una biblioteca que usas.

```yaml theme={null}
errata:
  - "An Oban {:snooze, n} does not spend an attempt; Oban raises max_attempts with it."
```

## Qué pull requests revisar

### skip

**skip** `mapping`

Pull requests que CodeWarden no debe revisar. Un pull request omitido no cuesta ningún turno de IA, no publica nada y aparece en la consola con el estado `skipped` y el motivo.

**claves de skip**

**drafts** `boolean` (default: true)

Omitir los pull requests en borrador. Con el valor por defecto, un borrador se revisa una vez, cuando se marca como listo para revisión, y sus pushes anteriores no cuestan nada y no dejan ninguna entrada en la consola. Defínelo en `false` para revisar los borradores como cualquier otro pull request: cuando se abre uno y en cada push. Marcar como listo un borrador ya revisado revisa entonces solo lo nuevo desde entonces.

**labels** `list of strings` (default: \[])

Omitir un pull request que lleve cualquiera de estas etiquetas.

**authors** `list of strings` (default: \[])

Omitir los pull requests abiertos por estas cuentas de GitHub, por ejemplo `dependabot[bot]`.

**base\_branches** `list of strings` (default: \[] (every branch))

Revisar solo los pull requests hacia estas branches. Vacío significa todas las branches.

```yaml theme={null}
skip:
  labels: ["dependencies", "no-review"]
  authors: ["dependabot[bot]", "renovate[bot]"]
  base_branches: ["main"]
```

Para dejar de revisar un repositorio completo, desactívalo en la consola. Consulta [Interruptores de repositorio](https://docs.codewarden.co/es/configure/repositories.md).

## Integraciones

### jira

**jira** `mapping`

De qué proyectos de Jira puede un pull request enlazar un ticket. Sin esta clave, nunca se lee ningún ticket. Consulta [Jira](https://docs.codewarden.co/es/integrations/jira.md).

**claves de jira**

**projects** `list of project keys` (default: \[])

Claves de proyecto en mayúsculas, como `PROJ` en `PROJ-123`.

**public\_repositories** `boolean` (default: false)

En un repositorio público, no se lee ningún ticket a menos que esto sea `true`, para que un ticket privado no se cite en una revisión pública.

**ticket\_coverage** `boolean` (default: true)

Si el resumen de la revisión lista los requisitos del ticket, cada uno marcado como visto, no visto o contradicho. `false` quita la lista; las contradicciones se siguen reportando como comentarios. Consulta [Qué muestra el resumen](https://docs.codewarden.co/es/integrations/jira.md#what-the-summary-shows).

### sentry

**sentry** `mapping`

De qué proyectos de Sentry puede un pull request enlazar un issue. Sin esta clave, nunca se lee ningún issue. Consulta [Sentry](https://docs.codewarden.co/es/integrations/sentry.md).

**claves de sentry**

**projects** `list of project slugs` (default: \[])

Slugs de proyectos de Sentry en minúsculas, como `widgets-api`.

**public\_repositories** `boolean` (default: false)

En un repositorio público, no se lee ningún issue a menos que esto sea `true`.

## Hallazgos ya decididos

### accepted

**accepted** `list of \{ path, code, problem, category, reason \}` (default: \[])

Hallazgos que tu equipo revisó y decidió que aquí no son defectos. Un hallazgo que coincide con uno no se publica. Rara vez los escribes a mano: CodeWarden propone las líneas exactas cuando cede en una conversación. Consulta [Hallazgos aceptados](https://docs.codewarden.co/es/configure/accepted-findings.md).

`path` y `code` son obligatorios, y `code` (hasta 2.000 caracteres) debe ser texto que realmente esté en el archivo. `problem`, `category` y `reason` son opcionales.

## Lo que el archivo deliberadamente no puede hacer

* **Ejecutar herramientas.** No hay una sección `tools` para linters ni analizadores estáticos. Ejecutarlos significa ejecutar código del repositorio, y la configuración de un linter es código.
* **Elegir el modelo ni su costo.** Qué modelo revisa un pull request es responsabilidad de CodeWarden.
* **Fijar una confianza mínima.** Se midió, y no cambió lo que se publica.
* **Desactivar la revisión incremental.** Consulta [Revisión incremental](https://docs.codewarden.co/es/how-a-review-works.md#incremental-review).
* **Reemplazar el prompt de revisión.** Todo lo del archivo se suma a las reglas; nada las reemplaza.

La consola tampoco guarda reglas de revisión. Viven en este archivo, en tu repositorio, donde se revisan como cualquier otro cambio.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.