Prompt workflows

ContractForge AI trata os prompts como intenção do usuário, não como verdade executável. O prompt é normalizado em uma especificação determinística do projeto antes de qualquer provider-backed enrichment is allowed.

Good prompt shape

Um forte prompt de geração de projeto inclui:

• sistema de origem;
• tipo de conector;
• local ou tabela de origem;
• plataforma ou plataformas alvo;
• padrão de catálogo/esquema/tabela de destino;
• requested layers;
• modo de gravação por conjunto de dados quando diferente;
• horário e fuso horário;
• requisitos de qualidade e governação;
• chaves explícitas ou uma solicitação para deixar as chaves como decisões.

Exemplo:

Create a Supabase medallion project for AWS and Databricks.
Use one shared JDBC connection for products and product_movements.
Products should use hash_diff_upsert with product_id as merge key.
Movements should append by movement_uid.
Run daily with cron 0 6 * * * in America/Sao_Paulo.
Add quality checks for product_id not null, movement_uid not null and quantity >= 0.
Generate review reports and keep platform differences minimal.

Solicitar planejamento

Comece com plan-project quando o prompt ainda for ambíguo:

contractforge-ai plan-project \
  --intent "Create Supabase medallion for AWS and Databricks daily at 6 Sao Paulo time." \
  --schema schemas/products.json \
  --preferred-target contractforge-yaml \
  --format markdown

O planejador relata comandos de geração recomendados e decisões não resolvidas. Use isto antes de gravar arquivos quando o prompt puder omitir chaves, detalhes da fonte ou escolhas de plataforma.

Prompt de projeto

Use generate para geração de projeto com intenção inicial:

contractforge-ai generate \
  --prompt "Create a USGS earthquake REST GeoJSON medallion for Databricks, AWS, Snowflake, Fabric and GCP. Bronze reads the all_day.geojson endpoint, silver extracts event fields, gold aggregates by magnitude band." \
  --schemas schemas/usgs-events.json \
  --with-ai \
  --provider openai \
  --output-dir generated/usgs-earthquakes

Para solicitações de vários conjuntos de dados, passe todos os esquemas:

contractforge-ai generate \
  --prompt "Create one USGS GeoJSON medallion project with bronze raw response, silver event extraction and gold summaries. Generate AWS, Databricks, Snowflake, Fabric and GCP-ready project files." \
  --schemas schemas/products.json schemas/product_movements.json \
  --with-ai \
  --provider openai \
  --output-dir generated/supabase

O usuário pode substituir o comportamento por tabela no prompt. Se uma mesa precisar de um conector, tabela de origem, modo de gravação ou chaves diferentes, diga isso explicitamente.

Decisões necessárias

ContractForge AI deve produzir RequiredDecision em vez de adivinhar quando um prompt omits production-critical details:

Missing detail	Por que não é adivinhado
Merge keys	Eles definem a identidade de atualização e a idempotência.
Hash-diff columns	They define change detection semantics.
Gold grain	It defines aggregation correctness.
Política PII	Ele define o comportamento legal e de governança.
Secret names	Eles devem vir do tempo de execução ou da equipe da plataforma de destino.
Production compute	Ele altera o comportamento do custo e do tempo de execução.

A orientação do prestador pode sugerir respostas prováveis, mas essas respostas permanecem revisão necessária.

Dicas de plataforma

As dicas da plataforma são explícitas:

Prompt wording	Resultado
Databricks, Unity Catalog, DAB, Auto Loader	Databricks hint.
AWS Glue, Athena, Lake Formation, Glue job	AWS hint.
s3://... only	Dica de conector/armazenamento, não automaticamente AWS.
Iceberg only	Dica em formato de tabela, não automaticamente AWS.

Isso evita que o armazenamento de origem escolha silenciosamente a plataforma.

Valide o projeto gerado

Sempre valide após a geração:

contractforge-ai validate-project-structure generated/supabase \
  --adapter databricks \
  --adapter aws \
  --format html > generated/supabase/project_validation.html

Trate READY e READY_WITH_WARNINGS como portas de validação utilizáveis. Tratar NEEDS_DECISIONS, INVALID e UNSAFE não podem ser implementados até serem resolvidos.