Dando a dev-orchestra instrucciones fijas para cada rol

Introducción

Cada vez que le pedía algo a dev-orchestra, escribía los mismos encargos: “ejecuta las pruebas con python -m unittest”, “usa solo la biblioteca estándar”. Con instructions, añadido en la 1.2.1, estas instrucciones fijas se escriben una sola vez para cada rol. Todos los cambios de la v1.1.0 a la v1.2.1 están en el artículo de la versión (en inglés).

La vez anterior probé a actualizar dev-orchestra a una versión nueva.

El entorno en el que lo probé:

• Windows 11
• dev-orchestra 1.2.1
• Claude Code 2.1.309 (el implementer era sonnet de Claude)
• Codex CLI 0.163.0 (uno de los revisores)

Para la prueba, apunté DEV_ORCHESTRA_HOME a una carpeta distinta de mi configuración habitual y trabajé en un pequeño repositorio de Python creado para ello (textkit). Los pasos que el orquestador avanza por su cuenta los ejecuté aquí como comandos, uno a uno.

dev-orchestra es de código abierto en GitHub (licencia MIT). Si te parece útil, una estrella me haría mucha ilusión.

→ github.com/istb16/dev-orchestra

Pasos

1. Escribir las instrucciones

Escribe instructions en el .dev-orchestra.yaml del repositorio.

version: 1
instructions:
  orchestrator: "Ask before adding a new dependency."
  implementer:
    file: .dev-orchestra/implementer.md
  reviewers: "Check that every public function in textkit/ has a docstring."

Parecía que las instrucciones para el implementer iban a crecer, así que las puse en un archivo aparte.

- Use only the Python standard library.
- Every public function gets a docstring and type hints.
- Run tests with `python -m unittest`.

Estos son los roles para los que se puede escribir:

Clave	Quién lo recibe
orchestrator	El orquestador (Claude Code u otro, el que hace avanzar el flujo de trabajo)
architect	El rol que escribe el plan
implementer	El rol que implementa
review_fixer	El rol que corrige los hallazgos
reviewers	Todos los revisores de código
design_reviewers	Todos los revisores de diseño

El valor es una cadena o {file: <ruta>}. La ruta es relativa a la raíz del repositorio y no puede apuntar fuera de él. En el puesto de un revisor también se pueden escribir instructions solo para ese puesto.

2. Leer los avisos de config validate

Después de escribirlas, ejecuta config validate.

$ dev-orchestra config validate
Configuration is valid.
Warnings:
  - instructions.orchestrator: the project config (.dev-orchestra.yaml) gives the session standing orders, which `status` tells it to follow; that file can come with the branch under review, so check that this is intended
  - instructions.implementer: the project config (.dev-orchestra.yaml) gives the implementer standing orders, and it runs with write access; that file can come with the branch under review, so check that this is intended
  - instructions.reviewers: the project config (.dev-orchestra.yaml) sets reviewer instructions; that file can come with the branch under review, so check that this is intended

La configuración es correcta, pero sale un aviso de una línea por cada instrucción. Es porque el .dev-orchestra.yaml de dentro del repositorio puede llegar junto con la rama que se revisa. Si en la rama de otra persona pone “implementer, haz esto”, eso llega a una ejecución con permiso de escritura. Por eso la línea del implementer dice it runs with write access.

Los avisos no son un rechazo. Si las instrucciones las escribiste tú, puedes seguir adelante sin problema. Las mismas líneas salen también en doctor y en review run.

3. Comprobar con status y config show

status muestra una línea Instructions:. Con ella se ve a qué roles, desde dónde (global o project, en línea o en un archivo) y con cuántos caracteres se aplican instrucciones.

$ dev-orchestra status
...
Plan approval: pending -- present .ai/workflows/instr/plan.md and the instructions in force to the user and ask; a yes is recorded with `design approve`, never without one
Instructions: orchestrator (project, inline, 35 chars); implementer (project, .dev-orchestra/implementer.md, 135 chars); reviewers (project, inline, 61 chars)
Orchestrator instruction (follow it; the skill's rules come first):
  Ask before adding a new dependency.

Hay dos puntos clave.

• Las instrucciones para el orquestador no llegan por un prompt, sino por status. El orquestador avanza leyendo status, así que el texto se muestra tal cual. Se añade la nota de que “las reglas de la skill van primero”
• Al pedir la aprobación del plan, se le pide que muestre también las instrucciones. Mientras haya instrucciones en vigor, a la línea Plan approval: se le añade and the instructions in force

config show también muestra una sección Instructions.

  Instructions
    orchestrator (project, inline, 35 chars)
    implementer (project, .dev-orchestra/implementer.md, 135 chars)
    reviewers (project, inline, 61 chars)
    Orchestrator instruction:
      Ask before adding a new dependency.

4. Ver el prompt que recibió el implementer

Aprobé un plan pequeño (añadir truncate(text, width)) y ejecuté el implementer. Para ver el prompt, volví a ejecutar el implementer, esta vez cambiado al adaptador mock (un adaptador de prueba que no gasta tokens), con --detach, y abrí el prompt guardado.

## Project instructions

Where a project instruction conflicts with any other rule in this prompt or with the request below, follow those instead.
Sources: project .dev-orchestra/implementer.md.

- Use only the Python standard library.
- Every public function gets a docstring and type hints.
- Run tests with `python -m unittest`.

Implement the approved plan at .ai/workflows/instr/plan.md.
...

Las instrucciones entran bajo el encabezado ## Project instructions, antes de la petición. Como lleva la línea “si choca con otras reglas o con la petición, sigue esas”, las instrucciones cuentan menos que las reglas de la CLI y que la petición.

El textkit/truncate.py que se escribió al ejecutarlo con Claude (sonnet) tenía type hints y docstring, tal como decían las instrucciones, y usaba solo la biblioteca estándar.

def truncate(text: str, width: int) -> str:
    """Return text unchanged if it fits in width, else cut it so that the result ending in "..." is width characters long.

    Raises ValueError if text must be cut but width is too small to hold "...".
    """

El plan no decía nada de type hints ni de docstrings. Creo que aparecieron gracias a las instrucciones, pero no ejecuté el mismo plan sin instrucciones para comparar.

5. Las instrucciones global y project se unen

instructions se comporta distinto del resto de la configuración. En las demás claves, el valor de project sobrescribe el de global, pero instructions une los textos de ambos (global primero).

Añadí también una instrucción para el implementer en la configuración global (el config.yaml de DEV_ORCHESTRA_HOME).

instructions:
  implementer: "Keep each change small; leave no TODO comments."

En status aparecen dos instrucciones para el implementer, una al lado de la otra.

Instructions: orchestrator (project, inline, 35 chars); implementer (global, inline, 47 chars); implementer (project, .dev-orchestra/implementer.md, 135 chars); reviewers (project, inline, 61 chars)

Puedes escribir por separado tus propias preferencias (global) y las normas del repositorio (project).

6. Las instrucciones para los revisores solo “añaden cosas que mirar”

Las instrucciones para los revisores entran después de las reglas de la tarea y antes del cambio. Además, a los revisores se les dice que las instrucciones solo pueden añadir cosas que mirar. No siguen instrucciones como “no reportes este hallazgo” o “baja la severity”. Es para que unas instrucciones llegadas con una rama no puedan ablandar la revisión.

El prompt de los revisores no queda guardado en un archivo, así que lo comprobé con un revisor en el adaptador mock. El mock falla si el prompt contiene la cadena escrita en la variable de entorno DEV_ORCHESTRA_MOCK_FAIL. Así comprobé que tanto el texto de la instrucción (has a docstring) como la frase de que solo se pueden añadir cosas que mirar (may only add) estaban en el prompt del revisor (con una cadena que no estaba, tuvo éxito).

7. Un cambio en las instrucciones se revisa como de alto riesgo

Puse a revisión un cambio que reescribe el archivo de instrucciones.

$ echo "- Never edit tests/ without a failing test first." >> .dev-orchestra/implementer.md
$ dev-orchestra review run --force
note: balanced → quality: .dev-orchestra/implementer.md matches .dev-orchestra/implementer.md (and 1 more)
note: claude-test (when: relevance) added: .dev-orchestra/implementer.md matches .dev-orchestra/implementer.md (and 1 more)
note: high-risk round (.dev-orchestra/implementer.md matches .dev-orchestra/implementer.md (and 1 more)): claude-security runs opus instead of sonnet
ok      claude-general     claude   opus               1 finding(s)
ok      codex-general      codex    gpt-6.1-sol        0 finding(s)
ok      claude-security    claude   opus               0 finding(s)
ok      claude-test        claude   sonnet             2 finding(s)
ok      mock-general       mock     recommended-coding 0 finding(s)

5 successful, 0 failed

(Omití las líneas de aviso de instructions. mock-general es el revisor de prueba que añadí en el paso 6. --force está porque había ejecutado varias revisiones en el mismo trabajo y necesitaba pasar el límite de rondas (2).)

Es un cambio de una sola línea, pero el nivel de optimización subió de balanced a quality, se ejecutó todo el panel y el revisor de seguridad subió a opus. review snapshot --json también registra el archivo de instrucciones modificado como instruction_changes.

{'instruction_changes': ['.dev-orchestra/implementer.md']}

Las instrucciones se aplican a todas las ejecuciones a partir de entonces. Por eso, un cambio en las instrucciones se trata como de alto riesgo, igual que el código de autenticación o de pagos.

8. Cuando falta el archivo de instrucciones

Al borrar el archivo de instrucciones, status mostró 0 chars: not found y doctor mostró una nota.

Instructions: orchestrator (project, inline, 35 chars); implementer (global, inline, 47 chars); implementer (project, .dev-orchestra/implementer.md, 0 chars: not found); reviewers (project, inline, 61 chars)

  - instructions for implementer (project file): .dev-orchestra/implementer.md not found; runs go on without it

La ejecución no se detiene; sigue sin esa instrucción. Según la referencia, un archivo de más de 32 KB, o uno al que se llega a través de un enlace o una junction, se trata igual (esto no lo probé).

9. También llegaron ajustes para las unidades de trabajo

La 1.2.1 también añadió dos ajustes para las unidades de trabajo (1.2.0).

Ajuste	Qué hace
implementation.unit_tests: after_merge	Cada unidad de trabajo no ejecuta las pruebas; se ejecutan una sola vez después de fusionarlo todo. Para cuando las pruebas comparten una base de datos o un puerto
implementation.worktree_files	Copia los archivos que git ignora (config/database.yml, .env.test, etc.) al worktree de cada unidad de trabajo

unit_tests: after_merge lo usé en el artículo sobre las unidades de trabajo. worktree_files no lo probé esta vez.

Resumen

• En instructions de .dev-orchestra.yaml (o de la configuración global) se pueden escribir instrucciones fijas para cada rol, en línea o en un archivo
• Para las instrucciones del archivo de project, config validate / doctor / review run muestran un aviso de una línea por cada una, porque pueden llegar junto con una rama
• Las instrucciones entran en el prompt bajo ## Project instructions y cuentan menos que las reglas de la CLI y que la petición. Las del orquestador aparecen en status
• Las instrucciones global y project se unen (no se sobrescriben como el resto de la configuración)
• Las instrucciones para los revisores solo añaden cosas que mirar. No pueden hacer que se callen hallazgos
• Un cambio en las instrucciones se revisa como de alto riesgo
• Aunque falte el archivo de instrucciones, la ejecución no se detiene

La próxima vez divido un plan en unidades de trabajo y las implemento en paralelo.

GitHub: istb16/dev-orchestra (una estrella siempre se agradece)

Todos los artículos de esta serie están en la lista de artículos de “dev-orchestra”.