Referencia de configuración

Nota: Las referencias (v4-A1), (v4-B1), etc. se refieren a fases del plan de desarrollo interno (Plan base v4). Todas están incluidas en la v1.0.0.

Sistema de capas

La configuración se resuelve en 4 capas (menor a mayor prioridad):

1. Defaults de Pydantic (código)
        ↓
2. Archivo YAML (-c config.yaml)
        ↓
3. Variables de entorno (ARCHITECT_*)
        ↓
4. Flags de CLI (--model, --workspace, etc.)

El deep_merge() de config/loader.py combina las capas de forma recursiva: los dicts anidados se fusionan en lugar de reemplazarse. Así puedes sobreescribir llm.model desde CLI sin perder llm.timeout del YAML.

---

Variables de entorno

Variable	Campo de config	Ejemplo
LITELLM_API_KEY	Leída por LiteLLM directamente (no por architect)	sk-...
ARCHITECT_MODEL	llm.model	gpt-4o
ARCHITECT_API_BASE	llm.api_base	http://localhost:8000
ARCHITECT_LOG_LEVEL	logging.level	debug
ARCHITECT_WORKSPACE	workspace.root	/home/user/project

LITELLM_API_KEY es la API key por defecto. Si necesitas una variable diferente, configura llm.api_key_env en el YAML.

---

Flags de CLI que sobreescriben config

Flag	Campo sobrescrito
--model MODEL	llm.model
--api-base URL	llm.api_base
--api-key KEY	llm.api_key_env → key directa
--timeout N	Timeout total de sesión (watchdog). No sobreescribe llm.timeout (per-request)
--no-stream	llm.stream = False
--workspace PATH	workspace.root
--max-steps N	agent_config.max_steps
--mode MODE	agent_config.confirm_mode
-v / -vv / -vvv	logging.verbose (count)
--log-level LEVEL	logging.level
--log-file PATH	logging.file
--self-eval MODE	evaluation.mode (off/basic/full)
--allow-commands	commands.enabled = True
--no-commands	commands.enabled = False
--budget FLOAT	costs.budget_usd
--cache	llm_cache.enabled = True
--no-cache	llm_cache.enabled = False
--json	Salida JSON a stdout (desactiva streaming)
--dry-run	Modo dry-run: simula sin ejecutar tools de escritura
--report FORMAT	Formato reporte: json, markdown, github
--report-file PATH	Escribir reporte a archivo (si no, stdout)
--session ID	Reanudar sesión existente por ID
--confirm-mode MODE	Override confirm mode (yolo/confirm-all/confirm-sensitive)
--context-git-diff REF	Inyectar diff git diff REF como contexto adicional
--exit-code-on-partial	Retornar exit code 2 si status=partial (default en CI)

Comandos adicionales:

Comando	Descripción
architect loop TASK --check CMD	Ralph Loop: iterar hasta que checks pasen
architect pipeline FILE	Pipeline: ejecutar workflow YAML multi-step
architect parallel --task CMD	Parallel: ejecutar en worktrees paralelos
architect parallel-cleanup	Limpiar worktrees de ejecuciones paralelas
architect eval TASK --models CSV --check CMD	Evaluación competitiva multi-modelo
architect init --preset NAME	Inicializar proyecto con preset de configuración
--health (en architect run)	Análisis de salud del código antes/después

---

Schema YAML completo

# ==============================================================================
# LLM
# ==============================================================================
llm:
  provider: litellm        # siempre "litellm"
  mode: direct             # "direct" | "proxy" (LiteLLM Proxy Server)
  model: gpt-4o-mini       # cualquier modelo LiteLLM

  # api_base: http://localhost:8000   # custom endpoint (Proxy, Ollama, etc.)

  api_key_env: LITELLM_API_KEY       # env var con la API key

  timeout: 60              # segundos por llamada al LLM
  retries: 2               # reintentos en errores transitorios (no auth)
  stream: true             # streaming por defecto; desactivado con --no-stream/--json/--quiet
  prompt_caching: false    # marca system prompt con cache_control → ahorro 50-90% en Anthropic/OpenAI

# ==============================================================================
# Agentes (custom o overrides de defaults)
# ==============================================================================
agents:
  # Override parcial de un default:
  build:
    confirm_mode: confirm-all    # solo sobreescribe este campo
    max_steps: 10

  # Agente completamente nuevo:
  deploy:
    system_prompt: |
      Eres un agente de deployment especializado.
      ...
    allowed_tools:
      - read_file
      - list_files
      - write_file
    confirm_mode: confirm-all
    max_steps: 15

# ==============================================================================
# Logging
# ==============================================================================
logging:
  level: human             # "debug" | "info" | "human" | "warn" | "error"
                           # v3: "human" muestra la trazabilidad del agente
  verbose: 0               # 0=solo human logs, 1=info, 2=debug, 3+=all
  # file: logs/architect.jsonl   # JSON Lines; DEBUG completo siempre

# ==============================================================================
# Workspace
# ==============================================================================
workspace:
  root: .                  # directorio raíz; todas las ops de archivos confinadas aquí
  allow_delete: false      # true = habilitar delete_file tool

# ==============================================================================
# MCP (Model Context Protocol — herramientas remotas)
# ==============================================================================
mcp:
  servers:
    - name: github
      url: http://localhost:3001
      token_env: GITHUB_TOKEN         # env var con Bearer token

    - name: database
      url: https://mcp.example.com/db
      token_env: DB_TOKEN

    # token inline (no recomendado en producción):
    # - name: internal
    #   url: http://internal:8080
    #   token: "hardcoded-token"

# ==============================================================================
# Indexer — árbol del repositorio en el system prompt (F10)
# ==============================================================================
indexer:
  enabled: true            # false = sin árbol en el prompt; las search tools siguen disponibles
  max_file_size: 1000000   # bytes; archivos más grandes se omiten del índice
  exclude_dirs: []         # dirs adicionales a excluir (además de .git, node_modules, etc.)
  # exclude_dirs:
  #   - vendor
  #   - .terraform
  exclude_patterns: []     # patrones adicionales a excluir (además de *.pyc, *.min.js, etc.)
  # exclude_patterns:
  #   - "*.generated.py"
  #   - "*.pb.go"
  use_cache: true          # caché del índice en disco, TTL de 5 minutos

# ==============================================================================
# Context — gestión del context window (F11)
# ==============================================================================
context:
  # Nivel 1: truncar tool results largos
  max_tool_result_tokens: 2000   # ~4 chars/token; 0 = desactivar truncado

  # Nivel 2: comprimir pasos antiguos con el LLM
  summarize_after_steps: 8       # 0 = desactivar compresión
  keep_recent_steps: 4           # pasos recientes a preservar íntegros

  # Nivel 3: hard limit del context window total
  max_context_tokens: 80000      # 0 = sin límite (peligroso para tareas largas)
  # Referencia: gpt-4o/mini → 80000, claude-sonnet-4-6 → 150000

  # Tool calls paralelas
  parallel_tools: true           # false = siempre secuencial

# ==============================================================================
# Evaluation — auto-evaluación del resultado (F12)
# ==============================================================================
evaluation:
  mode: off                # "off" | "basic" | "full"
                           # Override desde CLI: --self-eval basic|full
  max_retries: 2           # reintentos en modo "full" (rango: 1-5)
  confidence_threshold: 0.8  # umbral de confianza para aceptar resultado (0.0-1.0)

# ==============================================================================
# Commands — ejecución de comandos del sistema (F13)
# ==============================================================================
commands:
  enabled: true            # false = no registrar run_command; --allow-commands/--no-commands
  default_timeout: 30      # segundos por defecto (1-600)
  max_output_lines: 200    # líneas de stdout/stderr antes de truncar (10-5000)
  blocked_patterns: []     # regexes extra a bloquear (además de los built-in)
  # blocked_patterns:
  #   - "git push --force"
  #   - "docker rm"
  safe_commands: []        # comandos adicionales clasificados como 'safe'
  allowed_only: false      # si true, solo safe/dev; dangerous rechazados en execute()

# ==============================================================================
# Costs — seguimiento de costes de llamadas al LLM (F14)
# ==============================================================================
costs:
  enabled: true            # false = sin tracking de costes
  # prices_file: my_prices.json  # precios custom (mismo formato que default_prices.json)
  # budget_usd: 1.0        # detener si se superan $1.00; Override: --budget 1.0
  # warn_at_usd: 0.5       # log warning al alcanzar $0.50

# ==============================================================================
# LLM Cache — cache local de respuestas LLM para desarrollo (F14)
# ==============================================================================
llm_cache:
  enabled: false           # true = activar; Override: --cache / --no-cache
  dir: ~/.architect/cache  # directorio donde guardar las entradas
  ttl_hours: 24            # validez de cada entrada (1-8760 horas)

# ==============================================================================
# Hooks — lifecycle completo (v4-A1, retrocompat v3-M4)
# ==============================================================================
hooks:
  # Pre-hooks: se ejecutan ANTES de la acción. Exit code 2 = BLOCK.
  pre_tool_use:
    - name: validate-secrets
      command: "bash scripts/check-secrets.sh"
      matcher: "write_file|edit_file"      # regex para filtrar tools
      file_patterns: ["*.py", "*.env"]
      timeout: 5

  # Post-hooks: se ejecutan DESPUÉS de la acción.
  post_tool_use:
    - name: python-lint
      command: "ruff check {file} --no-fix"    # {file} se reemplaza con el path editado
      file_patterns: ["*.py"]                    # patrones glob
      timeout: 15                                # segundos (1-300, default: 10)
      enabled: true                              # false = ignorar este hook
    - name: python-typecheck
      command: "mypy {file} --no-error-summary"
      file_patterns: ["*.py"]
      timeout: 30

  # Hooks de sesión (notificación, no pueden bloquear)
  session_start: []
  session_end: []
  on_error: []
  agent_complete: []
  budget_warning: []
  context_compress: []

  # Pre/post LLM call
  pre_llm_call: []
  post_llm_call: []

  # Retrocompatibilidad v3-M4: post_edit se mapea a post_tool_use
  # con matcher automático para edit_file/write_file/apply_patch
  post_edit:
    - name: legacy-lint
      command: "ruff check {file}"
      file_patterns: ["*.py"]
      timeout: 15

  # Campos de cada hook:
  # name:          str           — nombre descriptivo
  # command:       str           — comando shell ({file} se reemplaza)
  # matcher:       str = "*"    — regex/glob para filtrar tools
  # file_patterns: list[str]    — patrones glob para filtrar archivos
  # timeout:       int = 10     — segundos (1-300)
  # async:         bool = false — true = ejecutar en background sin bloquear
  # enabled:       bool = true  — false = ignorar

# ==============================================================================
# Guardrails — seguridad determinista (v4-A2)
# ==============================================================================
guardrails:
  enabled: false              # true = activar guardrails
  protected_files: []         # globs: [".env", "*.pem", "secrets/**"]
  blocked_commands: []        # regexes: ["git push --force", "docker rm"]
  max_files_modified: null    # límite de archivos distintos por sesión (null = sin límite)
  max_lines_changed: null     # límite de líneas cambiadas acumuladas
  max_commands_executed: null  # límite de comandos ejecutados
  require_test_after_edit: false  # forzar test cada N ediciones

  code_rules: []              # reglas de análisis estático simple
  # - pattern: "eval\\("
  #   message: "Uso de eval() detectado"
  #   severity: block          # block | warn

  quality_gates: []           # verificación final al completar
  # - name: tests
  #   command: "pytest tests/ -x"
  #   required: true           # true = bloquea si falla
  #   timeout: 120

# ==============================================================================
# Skills — contexto de proyecto y workflows (v4-A3)
# ==============================================================================
skills:
  auto_discover: true         # descubrir skills en .architect/skills/ automáticamente
  inject_by_glob: true        # inyectar skills según archivos activos

# ==============================================================================
# Memory — memoria procedural (v4-A4)
# ==============================================================================
memory:
  enabled: false              # true = activar detección de correcciones
  auto_detect_corrections: true  # detectar correcciones automáticamente en mensajes del usuario

# ==============================================================================
# Sessions — persistencia y resume (v4-B1)
# ==============================================================================
sessions:
  auto_save: true             # guardar estado después de cada paso (default: true)
  cleanup_after_days: 7       # días tras los cuales `architect cleanup` elimina sesiones

# ==============================================================================
# Ralph Loop — iteración automática con checks (v4-C1)
# ==============================================================================
ralph:
  max_iterations: 25           # máximo de iteraciones (1-100)
  max_cost: null               # coste máximo total en USD (null = sin límite)
  max_time: null               # tiempo máximo total en segundos (null = sin límite)
  completion_tag: COMPLETE     # tag que el agente emite al declarar completado
  agent: build                 # agente a usar en cada iteración

# ==============================================================================
# Parallel Runs — ejecución paralela en git worktrees (v4-C2)
# ==============================================================================
parallel:
  workers: 3                   # número de workers paralelos (1-10)
  agent: build                 # agente a usar en cada worker
  max_steps: 50                # máximo de pasos por worker
  budget_per_worker: null      # USD por worker (null = sin límite)
  timeout_per_worker: null     # segundos por worker (null = 600s)

# ==============================================================================
# Checkpoints — puntos de restauración git (v4-C4)
# ==============================================================================
checkpoints:
  enabled: false               # true = activar checkpoints automáticos en el AgentLoop
  every_n_steps: 5             # crear checkpoint cada N pasos (1-50)

# ==============================================================================
# Auto-Review — revisión automática post-build
# ==============================================================================
auto_review:
  enabled: false               # true = activar auto-review tras completar
  review_model: null           # modelo para el reviewer (null = mismo que builder)
  max_fix_passes: 1            # pases de corrección (0 = solo reportar, 1-3 = corregir)

# ==============================================================================
# Telemetry — OpenTelemetry traces (v1.0.0)
# ==============================================================================
telemetry:
  enabled: false               # true = activar trazas OpenTelemetry
  exporter: console            # "otlp" | "console" | "json-file"
  endpoint: http://localhost:4317  # endpoint gRPC para OTLP
  trace_file: null             # path del archivo para json-file (ej: .architect/traces.json)

# ==============================================================================
# Health — análisis de salud del código (v1.0.0)
# ==============================================================================
health:
  enabled: false               # true = análisis automático (sin necesidad de --health flag)
  include_patterns:            # patrones glob de archivos a analizar
    - "**/*.py"
  exclude_dirs:                # directorios a excluir del análisis
    - .git
    - venv
    - __pycache__
    - node_modules

---

Función load_config()

def load_config(
    config_path: Path | None = None,
    cli_args: dict | None = None,
) -> AppConfig:
    # 1. Carga YAML (vacío si config_path=None)
    yaml_dict = load_yaml_config(config_path)

    # 2. Lee env vars ARCHITECT_*
    env_dict = load_env_overrides()

    # 3. Fusiona: yaml ← env
    merged = deep_merge(yaml_dict, env_dict)

    # 4. Aplica CLI flags
    if cli_args:
        merged = apply_cli_overrides(merged, cli_args)

    # 5. Valida con Pydantic (extra="forbid")
    return AppConfig(**merged)

Si el YAML tiene claves desconocidas, Pydantic lanza ValidationError → CLI muestra el error y sale con código 3 (EXIT_CONFIG_ERROR).

---

Ejemplos de configuraciones comunes

Mínima (solo API key en env)

export LITELLM_API_KEY=sk-...
architect run "analiza el proyecto" -a resume

OpenAI con config explícita

llm:
  model: gpt-4o
  api_key_env: OPENAI_API_KEY
  timeout: 120
  retries: 3

workspace:
  root: /mi/proyecto
  allow_delete: false

Anthropic Claude

llm:
  model: claude-sonnet-4-6
  api_key_env: ANTHROPIC_API_KEY
  stream: true

context:
  max_context_tokens: 150000   # Claude tiene ventana más grande

Ollama (local, sin API key)

llm:
  model: ollama/llama3
  api_base: http://localhost:11434
  retries: 0    # local, sin necesidad de reintentos
  timeout: 300  # modelos locales pueden ser lentos

context:
  parallel_tools: false   # sin paralelismo en modelos locales lentos

LiteLLM Proxy (equipos)

llm:
  mode: proxy
  model: gpt-4o-mini
  api_base: http://proxy.interno:8000
  api_key_env: LITELLM_PROXY_KEY

CI/CD (modo yolo, sin confirmaciones, con evaluación)

llm:
  model: gpt-4o-mini
  timeout: 120
  retries: 3
  stream: false

workspace:
  root: .

logging:
  verbose: 0
  level: warn

evaluation:
  mode: basic              # evalúa el resultado en CI
  confidence_threshold: 0.7  # menos estricto que en interactivo

architect run "actualiza imports obsoletos en src/" \
  --mode yolo --quiet --json \
  -c ci/architect.yaml

Repos grandes (con optimización de contexto)

indexer:
  exclude_dirs:
    - vendor
    - .terraform
    - coverage
  exclude_patterns:
    - "*.generated.py"
    - "*.pb.go"
  use_cache: true

context:
  max_tool_result_tokens: 1000   # más agresivo en repos grandes
  summarize_after_steps: 5       # comprimir más rápido
  keep_recent_steps: 3
  max_context_tokens: 60000      # más conservador
  parallel_tools: true

Con ejecución de comandos (F13) y costes (F14)

llm:
  model: claude-sonnet-4-6
  api_key_env: ANTHROPIC_API_KEY
  prompt_caching: true     # ahorra tokens en llamadas repetidas al mismo system prompt

commands:
  enabled: true
  default_timeout: 60
  max_output_lines: 200
  safe_commands:
    - "pnpm test"
    - "cargo check"

costs:
  enabled: true
  budget_usd: 2.0          # máximo $2 por ejecución
  warn_at_usd: 1.0         # aviso al alcanzar $1

# Cache local para desarrollo: evita llamadas repetidas al LLM
llm_cache:
  enabled: false           # activar con --cache en CLI durante desarrollo
  ttl_hours: 24

# Con cache local activo y presupuesto desde CLI
architect run "PROMPT" -a build --cache --budget 1.5 --show-costs

Con hooks del lifecycle (v4-A1)

hooks:
  post_tool_use:
    - name: python-lint
      command: "ruff check {file} --no-fix"
      file_patterns: ["*.py"]
      timeout: 15
    - name: python-typecheck
      command: "mypy {file} --no-error-summary"
      file_patterns: ["*.py"]
      timeout: 30
  pre_tool_use:
    - name: no-secrets
      command: "bash scripts/check-secrets.sh"
      matcher: "write_file|edit_file"
      timeout: 5

# Los hooks se ejecutan automaticamente — el LLM ve el output de lint/typecheck
# y puede auto-corregir errores. Pre-hooks pueden bloquear acciones.
architect run "refactoriza utils.py" -a build --mode yolo -c config.yaml

Con guardrails (v4-A2)

guardrails:
  enabled: true
  protected_files: [".env", "*.pem", "deploy/**"]
  blocked_commands: ["git push", "docker rm"]
  max_files_modified: 10
  max_lines_changed: 500
  require_test_after_edit: true
  code_rules:
    - pattern: "eval\\("
      message: "No usar eval()"
      severity: block
  quality_gates:
    - name: tests
      command: "pytest tests/ -x"
      required: true
      timeout: 120

Con skills y memoria (v4-A3/A4)

skills:
  auto_discover: true
  inject_by_glob: true

memory:
  enabled: true
  auto_detect_corrections: true

CI/CD con reportes y sessions (v4-B)

llm:
  model: gpt-4o-mini
  stream: false
  prompt_caching: true

commands:
  enabled: true
  allowed_only: true

costs:
  enabled: true
  budget_usd: 2.00

sessions:
  auto_save: true
  cleanup_after_days: 30

# Ejecución con reporte y contexto de diff del PR
architect run "revisa los cambios del PR" \
  --mode yolo --quiet \
  --context-git-diff origin/main \
  --report github --report-file pr-report.md \
  --budget 2.00 \
  -c ci/architect.yaml

# Reanudar si quedó parcial
architect resume SESSION_ID --budget 2.00

# Limpiar sesiones antiguas en CI
architect cleanup --older-than 30

Config completa con self-eval

llm:
  model: gpt-4o
  api_key_env: OPENAI_API_KEY
  timeout: 120

workspace:
  root: .

indexer:
  enabled: true
  use_cache: true

context:
  max_tool_result_tokens: 2000
  summarize_after_steps: 8
  max_context_tokens: 80000
  parallel_tools: true

evaluation:
  mode: full               # reintentar automáticamente si falla
  max_retries: 2
  confidence_threshold: 0.85

# O usar solo el flag de CLI (ignora evaluation.mode del YAML)
architect run "genera tests para src/auth.py" -a build --self-eval full

Ralph Loop con checks (v4-C1)

ralph:
  max_iterations: 10
  max_cost: 5.0
  agent: build

# Iterar hasta que los tests pasen
architect loop "corrige los tests que fallan en src/auth.py" \
  --check "pytest tests/test_auth.py -x" \
  --max-iterations 10

# Con múltiples checks
architect loop "implementa validación de email" \
  --check "pytest tests/" \
  --check "ruff check src/" \
  --max-cost 2.0

Ejecución paralela (v4-C2)

parallel:
  workers: 3
  agent: build
  budget_per_worker: 1.0
  timeout_per_worker: 300

# Misma tarea con diferentes modelos
architect parallel "optimiza las queries SQL" \
  --models gpt-4o,claude-sonnet-4-6,deepseek-chat

# Tareas diferentes en paralelo
architect parallel \
  --task "tests para auth" \
  --task "tests para users" \
  --task "tests para billing" \
  --workers 3 --budget-per-worker 1.0

# Limpiar worktrees después
architect parallel-cleanup

Pipeline YAML multi-step (v4-C3)

# pipeline.yaml
name: implement-and-test
steps:
  - name: implement
    prompt: "Implementa la feature descrita en {{task}}"
    agent: build
    checkpoint: true

  - name: test
    prompt: "Genera tests para los cambios del paso anterior"
    agent: build
    checks:
      - "pytest tests/ -x"
    checkpoint: true

  - name: review
    prompt: "Revisa los cambios realizados"
    agent: review
    output_var: review_result

variables:
  task: "añadir autenticación JWT"

# Ejecutar pipeline
architect pipeline pipeline.yaml

# Ejecutar desde un paso específico
architect pipeline pipeline.yaml --from-step test

# Dry-run del pipeline
architect pipeline pipeline.yaml --dry-run

Checkpoints y rollback (v4-C4)

checkpoints:
  enabled: true
  every_n_steps: 5

# Ver checkpoints creados
git log --oneline --grep="architect:checkpoint"

# Rollback manual a un checkpoint
git reset --hard <commit_hash>

Evaluación competitiva (v1.0.0)

# Comparar modelos en la misma tarea
architect eval "optimiza las queries SQL" \
  --models gpt-4o,claude-sonnet-4-6,deepseek-chat \
  --check "pytest tests/test_queries.py -q" \
  --check "ruff check src/" \
  --budget-per-model 1.0 \
  --report-file eval_report.md

Inicialización con presets (v1.0.0)

# Generar config para proyecto Python
architect init --preset python

# Config máxima seguridad
architect init --preset paranoid --overwrite

Telemetry con Jaeger (v1.0.0)

telemetry:
  enabled: true
  exporter: otlp
  endpoint: http://localhost:4317

# Ejecutar con tracing
architect run "implementa feature" -c config.yaml --mode yolo
# → Traces visibles en Jaeger UI: http://localhost:16686

Health delta (v1.0.0)

health:
  enabled: true
  include_patterns: ["**/*.py"]

# O usar el flag directamente
architect run "refactoriza utils.py" --health --mode yolo
# → Muestra tabla markdown con delta de métricas

Auto-review post-build

auto_review:
  enabled: true
  review_model: claude-sonnet-4-6
  max_fix_passes: 1

# El auto-review se activa automáticamente al completar una tarea
# con auto_review.enabled: true. No requiere flags de CLI adicionales.
architect run "implementa feature X" --mode yolo -c config.yaml
# → Build completa → Review automática → Fix-pass si hay issues