Configuração do projeto

Faça com que os fluxos de trabalho planejem as mudanças do jeito que você quer com algumas linhas no config.yaml.

openspec/config.yaml informa aos fluxos de trabalho como você quer que as mudanças sejam planejadas.

Por exemplo, a configuração a seguir atualiza as regras de criação do artefato tasks.md:

rules:
  tasks:
    - End every task with a commit

Quando o agente é executado, ele se baseia nessas regras e garante que cada tarefa termine com uma etapa de commit.

Mantenha as regras curtas. Tudo aqui entra no contexto do agente, e regras muito detalhadas podem piorar a saída.

Como funciona

O config.yaml contém instruções que o agente recebe ao criar artefatos ou percorrer o fluxo de trabalho.

Veja o que acontece a cada execução:

1. Você executa um fluxo de trabalho (por exemplo, /openspec-propose).
2. O agente chama o comando openspec instructions.
3. O comando lê seu contexto e suas regras do config.yaml.
4. As instruções integradas do OpenSpec e suas personalizações são combinadas em um único prompt para o agente.
5. O agente segue esse prompt para escrever o artefato.

Por exemplo, com um campo context e a regra do início desta página, veja o que openspec instructions retorna para tasks.md (resumido e anotado):

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

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

  <!-- Do seu config.yaml: regras para tasks -->
  <rules>
    - End every task with a commit
  </rules>

  <!-- Do OpenSpec: a orientação integrada -->
  <instruction>
    ...how to write a good tasks.md...
  </instruction>

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

</artifact>

Sua configuração chega primeiro, depois vêm a instrução e o modelo integrados do OpenSpec. As regras são adicionadas às instruções integradas e nunca as substituem. Edições no config.yaml chegam ao agente na próxima execução.

Os campos

Três campos definem o que o agente recebe. O contrato exato de cada campo (tipos, limites, validação) está em Configuração do projeto (config.yaml).

Campo	O que faz	Injetado em
context	Instruções que o agente sempre recebe	Tudo: todos os artefatos, apply, archive
rules	Instruções extras para um artefato	Apenas a criação desse artefato
operations	Orientações sobre como uma etapa do fluxo de trabalho é executada	Apenas apply e archive

Os outros campos do config.yaml (schema, store, references) selecionam qual schema e qual raiz do OpenSpec o projeto usa. A página de contrato cobre esses campos.

A última coluna é exata, então um campo atinge apenas as etapas listadas nela. Em particular, verify nunca recebe rules. Ele verifica a implementação em relação aos artefatos conforme escritos.

context

context é o contexto de base que o agente recebe quando cria um artefato, aplica tarefas ou arquiva uma mudança.

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

Use context para fatos e restrições que devem moldar a saída do fluxo de trabalho. Mantenha a documentação permanente do projeto nos arquivos de documentação do projeto e omita tudo o que o agente puder aprender lendo o código.

Outro idioma: como o context chega a todos os artefatos, você pode adicionar Write all artifacts in Spanish. para instruir o agente a escrever os artefatos de proposta, especificação, design e tarefas em espanhol.

rules

As rules se vinculam a um artefato, identificado pelo id do artefato. Cada linha é adicionada às orientações integradas desse artefato:

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

As propostas agora ficam curtas e o tasks.md sempre planeja testes de navegador. Todos os outros artefatos permanecem intactos.

operations

operations orienta como o agente executa apply e archive, e não o que os artefatos dizem:

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

Durante o apply, o agente executa o linter à medida que conclui tarefas. Durante o archive, ele encerra com um resumo.

Quando o config.yaml não é suficiente

A configuração adiciona instruções além do fluxo de trabalho padrão, mas não pode mudar quais artefatos existem nem como eles são estruturados. Quando você quiser esse nível de controle, ou quando as regras não estiverem orientando o comportamento de forma consistente, faça um fork de um schema.