Configuración del proyecto

Haz que los flujos de trabajo planifiquen los cambios como quieras con unas pocas líneas en config.yaml.

openspec/config.yaml indica a los flujos de trabajo cómo quieres que se planifiquen los cambios.

Por ejemplo, la siguiente configuración actualiza las reglas de creación del artefacto tasks.md:

rules:
  tasks:
    - End every task with a commit

Cuando el agente se ejecuta, toma estas reglas y garantiza que cada tarea termine con un paso de commit.

Mantén las reglas breves. Todo lo que hay aquí llega al contexto del agente, y las reglas extensas pueden empeorar la salida.

Cómo funciona

config.yaml contiene las instrucciones que recibe el agente cuando crea artefactos o ejecuta el flujo de trabajo.

Esto es lo que sucede en cada ejecución:

1. Ejecutas un flujo de trabajo (p. ej., /openspec-propose).
2. El agente llama al comando openspec instructions.
3. El comando lee tu contexto y tus reglas de config.yaml.
4. Las instrucciones integradas de OpenSpec y tus personalizaciones se combinan en un único prompt para el agente.
5. El agente sigue ese prompt para escribir el artefacto.

Por ejemplo, con un campo context y la regla del inicio de esta página, esto es lo que devuelve openspec instructions para tasks.md (recortado y anotado):

<artifact id="tasks" change="add-dark-mode" schema="spec-driven">

  <!-- De tu config.yaml: context -->
  <project_context>
    Designs and tasks must cover Windows, macOS, and Linux
    Write all artifacts in Spanish
  </project_context>

  <!-- De tu config.yaml: reglas para tasks -->
  <rules>
    - End every task with a commit
  </rules>

  <!-- De OpenSpec: la guía integrada -->
  <instruction>
    ...how to write a good tasks.md...
  </instruction>

  <template>
    ...the tasks.md structure to fill in...
  </template>

</artifact>

Tu configuración llega primero, luego la instrucción y la plantilla integradas de OpenSpec. Las reglas se suman a las integradas y nunca las reemplazan. Las ediciones en config.yaml llegan al agente en la siguiente ejecución.

Los campos

Tres campos determinan lo que recibe el agente. El contrato exacto de cada campo (tipos, límites, validación) está en Configuración del proyecto (config.yaml).

Campo	Qué hace	Se inyecta en
context	Instrucciones que el agente recibe siempre	Todo: cada artefacto, apply, archive
rules	Instrucciones adicionales para un artefacto	Solo la creación de ese artefacto
operations	Guía sobre cómo se lleva a cabo un paso del flujo de trabajo	Solo apply y archive

Los demás campos de config.yaml (schema, store, references) seleccionan qué esquema y qué raíz de OpenSpec usa un proyecto. La página del contrato los cubre.

La última columna es exacta, por lo que un campo llega solo a los pasos indicados allí. En particular, verify nunca recibe rules. Comprueba la implementación frente a los artefactos tal como se escribieron.

context

context es información de contexto que el agente recibe cuando crea un artefacto, aplica tareas o archiva un cambio.

context: |
  We ship cross-platform. Designs and tasks must cover Windows, macOS, and Linux
  Write all artifacts in Spanish

Usa context para hechos y restricciones que deban orientar la salida del flujo de trabajo. Mantén la documentación permanente del proyecto en los archivos de documentación del proyecto y deja fuera todo lo que el agente pueda aprender leyendo el código.

Otro idioma: como el contexto llega a cada artefacto, puedes añadir Write all artifacts in Spanish. para indicar al agente que escriba los artefactos de propuesta, especificación, diseño y tareas en español.

rules

rules se asocian a un artefacto, usando el id del artefacto como clave. Cada línea se añade a la guía integrada de ese artefacto:

rules:
  proposal:
    - Keep proposals under 500 words
  tasks:
    - Every UI task includes a Playwright test

Ahora las propuestas se mantienen breves y tasks.md siempre planifica pruebas de navegador. Los demás artefactos no se modifican.

operations

operations orienta cómo lleva a cabo el agente apply y archive, en lugar de lo que dicen los artefactos:

operations:
  apply:
    guidance:
      - Run the linter before marking a task complete
  archive:
    guidance:
      - Summarize what shipped before archiving

Durante apply, el agente ejecuta el linter a medida que completa las tareas. Durante archive, cierra con un resumen.

Cuando config.yaml no es suficiente

La configuración añade instrucciones al flujo de trabajo estándar, pero no puede cambiar qué artefactos existen ni cómo están estructurados. Cuando quieras ese nivel de control, o las reglas no estén orientando el comportamiento de forma consistente, crea un fork de un esquema.