Ficheros que escribe gdd¶

Todos los ficheros y carpetas que gdd escribe en un proyecto: lo que deja gdd init, el estado local en .gdd/ (registros, informes, el log, la Decision Inbox, las salidas de los agentes), cuáles se versionan, cuáles solo puede escribir gdd y qué lleva el commit de fusión de un Change.

Un proyecto después de gdd init¶

gdd init --name notes --platform cli --stack python --agents claude codex en un repositorio vacío hace commit de estos ficheros (los comandos de los agentes aparecen una sola vez por carpeta de agente):

.agents/skills/gdd-<command>/SKILL.md   # Codex: the GDD commands and gdd-stack-python
.claude/skills/gdd-<command>/SKILL.md   # Claude Code: the same
.github/workflows/gdd.yml               # CI: the stack setup, gitleaks, gdd, bin/gdd ci
.gitignore                              # the stack's lines and .gdd/
AGENTS.md                               # instructions for agents, when the project had none
CLAUDE.md                               # @AGENTS.md, when the project had none
bin/gdd                                 # entry point of the agents and CI
docs/brief.md                           # the Project Brief
features/.gitkeep                       # the scenario folder
gdd/commands.toml
gdd/generated.toml
gdd/models.toml
gdd/project.toml
gdd/rules.toml
gdd/zones.toml
osv-scanner-licenses.toml               # from here on: the Python skeleton
osv-scanner.toml
pyproject.toml
src/notes/__init__.py
src/notes/greeting.py
tests/__init__.py
tests/acceptance/__init__.py
tests/acceptance/steps/__init__.py
tests/acceptance/test_features.py
tests/unit/__init__.py
tests/unit/test_greeting.py

gdd init nunca sobrescribe un fichero, nunca escribe a través de un enlace y solo hace commit de lo que escribió (gdd init <version>), en un repositorio nuevo si la carpeta no está en ninguno. Después, gdd bootstrap hace commit de los lockfiles (gdd bootstrap). gdd adopt hace commit de gdd/debt.toml.

Versionado y local¶

El registro de cada Change solo llega a git a través de su commit de fusión.

.gdd/¶

El estado local. Todos los worktrees de un repositorio comparten la .gdd/ de su checkout principal (la raíz del estado): un Change se ejecuta en su propio worktree y aun así lee y escribe los mismos registros. gdd se niega a ejecutarse en un worktree de un repositorio bare.

.gdd/
├── log.jsonl                 # one JSON line per agent call, gate decision and machine step
├── g0.json                   # G0, opened by the machines
├── zones.json                # the human's approval of the red zones
├── selftest.json             # the last harness self-test
├── headless_sessions.txt     # sessions gdd started for its agents
├── imported_requests.json    # requests of interactive sessions already in the log
├── agents.lock  launch.lock  merge.lock  state.lock
├── adoption/<command>.txt    # gdd adopt: what each failing command said
├── learn/<tool>.txt          # gdd learn: what each Learn tool said
├── selftest/kept/            # gdd selftest: a file set aside while the check runs
├── upgrade/                  # gdd upgrade: scratch folder, removed after each run
├── bin/                      # protected; gdd does not write it
└── changes/<id>/
    ├── change.json           # the record
    ├── inbox.md              # the Decision Inbox
    ├── plan.md               # the plan of a red change (the Orchestrator)
    ├── package.md            # the minimum context package (the Orchestrator)
    ├── replan.md             # the last replan (the Orchestrator, headless)
    ├── review.md             # the last review (the Reviewer's text, kept by gdd)
    ├── g2.json  g3.json      # the last report of each gate
    ├── snapshot.json         # gdd snapshot
    ├── snapshot-build.json   # the snapshot taken after test mode
    ├── run.json              # while the change waits at G4
    ├── outputs/              # every agent call: <role>-<n>.md and <role>-<n>.raw
    └── demo/                 # what the demo step leaves for G4

change.json¶

El registro de un Change: qué planea, qué decidieron sus puertas, sus notas y su estado. JSON indentado. Solo lo escribe gdd: los comandos de gdd que puede ejecutar un agente (gdd note, una puerta en modo build) solo cambian inbox y out_of_scope, y gdd deshace cualquier otra modificación que haga un agente.

El registro de un Change fusionado y promovido en un proyecto desechable, recortado:

{
  "build_start": "ca7bc9c0d5369ef863aab8d6f7651f64056215ed",
  "changelog": {
    "breaking": false,
    "line": "The cart shows its total",
    "section": "Added"
  },
  "commit": "8b14c1a9ab22d8931b010ad51499c8242ff03e4a",
  "created": "2026-10-30T13:11:40+00:00",
  "decision": {
    "builder": {
      "integration": "claude",
      "model": "sonnet"
    },
    "builder_session": "separate",
    ...
    "type": "Feature"
  },
  "features": [
    "features/cart.feature"
  ],
  "gates": {
    "G1": {
      "by": "human",
      "decision": "ok",
      "hashes": {
        "features/cart.feature": "06a581fd190d4dc2e48f33c21323302a67e522e74b8bacce3dd2b51c3fdce716"
      },
      "note": "approved at the sitting",
      "ts": "2026-10-30T13:11:46+00:00"
    },
    ...
  },
  "id": "cart-total",
  "inbox": [
    {
      "kind": "decided",
      "text": "Kept the total as an integer",
      "ts": "2026-10-30T13:11:53+00:00"
    },
    ...
  ],
  "min_color": null,
  "out_of_scope": [
    "docs/extra.md"
  ],
  "paths": [
    "src/shop/**",
    "features/cart.feature"
  ],
  "resumable": false,
  "state": "closed",
  "title": "Show the cart total",
  "type": "Feature",
  "version": "0.1.0"
}

Los registros escritos por una versión anterior de la herramienta pueden tener otros campos; gdd los ignora.

gates¶

Cada entrada tiene decision (ok o ko), by (human o machines), ts y note. G1 tiene además hashes: cada fichero de escenarios sellado y su SHA-256.

inbox¶

Cada nota tiene kind, text y ts, y además resolved (cuándo se resolvió) una vez que un relanzamiento la resolvió. kind es needs (una decisión para la persona), decided (tomada sin él), parked (por qué se detuvo) o polish (las notas de la persona en G4).

decision¶

La clasificación del Change cuando se preparó, y el modelo de cada rol.

reviews¶

Una entrada por cada llamada al Reviewer, en orden, incluidos los relanzamientos.

variants¶

Una entrada por cada variante de un Spike: option (la opción que construye, o null para el mismo brief), branch (change/<id>-v<n>) y, una vez construida, state (ready o parked), reason, g2, adrs, decision (la primera línea de la decisión de su ADR), files, minutes, usd y tokens.

Estados¶

inbox.md¶

La Decision Inbox: un mensaje por Change, generado a partir del registro y de los informes de puerta cada vez que cambian. gdd inbox <id> la imprime.

# Decision Inbox · cart-total · Show the cart total

Color yellow · lane full · state closed

## Needs your decision
- Should the total show taxes

## Decided without you
- Kept the total as an integer
- Paths outside the package, same or lower color, accepted by rule: docs/extra.md

## Parked
- Nothing.

Sus grupos, en orden, cada uno solo cuando tiene algo (los tres grupos de notas aparecen siempre): How it works (del OK del Reviewer), Variants, Needs your decision, Decided without you, Parked, Security exceptions this change adds, Known debt, Known debt paid, Polish; después, cuántas peticiones anteriores se resolvieron antes del último lanzamiento.

Informes de puerta¶

g2.json y g3.json guardan la última ejecución de cada puerta en el Change.

{
  "ok": true,
  "gate": "G2",
  "color": "yellow",
  "passed": [
    "lint",
    "unit",
    "path-guard",
    "scope"
  ],
  "skipped": [],
  "failures": [],
  "out_of_scope": [
    "docs/extra.md"
  ]
}

log.jsonl¶

Un objeto JSON por línea, añadido bajo un lock, para que las líneas de dos ejecuciones nunca se mezclen. gdd escribe una línea por cada llamada de agente, decisión de puerta, comando de puerta, ejecución de Path Guard y paso de máquina. gdd session añade las sesiones interactivas de Claude Code. Los informes dejan fuera las líneas que no son de gdd (no son JSON, o su coste no es un número mayor o igual que cero) e indican cuántas son.

{"ts":"2026-10-30T13:11:46+00:00","change":"cart-total","phase":"2-build","gate":"G2","role":"machine","agent":"lint","model":"-","tokens_in":0,"tokens_cache":0,"tokens_out":0,"cost_usd":0.0,"duration_s":0.0,"result":"ok","retry":0,"note":""}
{"ts":"2026-10-30T13:11:46+00:00","change":"cart-total","phase":"2-build","gate":"G2","role":"machine","agent":"checks","model":"-","tokens_in":0,"tokens_cache":0,"tokens_out":0,"cost_usd":0.0,"duration_s":0.0,"result":"ok","retry":0,"note":""}

El commit de fusión¶

gdd merge fusiona un Change en la rama principal con un commit cuyo mensaje lleva su registro, así que qué era el Change y quién lo aprobó viaja con el código mientras .gdd/ sigue siendo local. El commit de fusión del mismo Change, recortado:

gdd(cart-total): G3 Merge Gate · Show the cart total

Color: yellow · lane full · type Feature
Approvals: G1 ok (human, 2026-10-30, 1 scenario file(s) sealed)
Decided without the human:
  - Kept the total as an integer
...
Record: .gdd/changes/cart-total/ (local)

Changelog: Added · The cart shows its total
Breaking: no

gdd changelog y gdd release leen los trailers Changelog: y Breaking: de los commits de fusión de main para escribir CHANGELOG.md y elegir la siguiente versión.

Ver también¶

• Configuración: los ficheros de gdd/.
• Variables de entorno: lo que reciben los comandos y los agentes que escriben estos ficheros.
• Volver a poner en marcha un Change aparcado: cómo leer la Decision Inbox.
• Medir el trabajo: informes construidos a partir de log.jsonl.