Referência
Configuração.
Quase tudo que muda o comportamento da fábrica está no t25.yaml da raiz —
roteamento de agentes, limites, risco, GitHub, autenticação. Esta página é o mapa das
seções; a referência campo a campo é
docs/CONFIGURATION.md.
O merge raso é por seção, não por chave aninhada. Uma seção presente no
YAML substitui o default naquele nível — ela não é fundida em profundidade. Declarou
routing? Declare os papéis que quer, porque os que faltarem não voltam do
default.
Segredo não entra no YAML versionado. A URL do banco vem de
DATABASE_URL, a credencial de worker vem de
T25_WORKER_CREDENTIAL, e os segredos de OAuth vêm do ambiente. Um valor
real commitado é incidente, não deslize.
As seções
| Seção | Para quê |
|---|---|
t25 | Nome, diretório de estado, diretório de worktrees, tempo máximo por ordem, retries, exigência de aprovação de plano. |
repository | O repositório que a fábrica opera e o branch padrão de onde os worktrees saem. |
projects | Outros checkouts locais registrados, para operar mais de um repositório. |
routing | Papel do pipeline → cadeia de CLIs, em ordem de preferência. |
skills | Substitui a lista de skills de um papel específico. |
timeouts | Teto de minutos por papel; quem não aparece usa o teto global. |
limits | Guardrails anti-loop e anti-runaway. |
risk | Nível de risco → quanto a fábrica automatiza. |
team | Modo time: mapa de conhecimento por área, alerta de pessoa só e rodízio de revisores. Desligado por padrão. |
live_docs | Instrução de documentação viva para dev e QA. Ainda não entrega ferramenta ao agente (#444 aberto). |
sandbox_image | Imagem Docker para os papéis de dev quando o nível pede sandbox. |
github | Importação de issues e abertura de PR. |
server | Porta, chaves de API e, opcionalmente, login por GitHub ou OIDC. |
cost e observability | Contabilidade de custo por run e telemetria. |
control_plane | Banco e artifact store. A URL vem do ambiente, sempre. |
Roteamento: uma cadeia, não um CLI fixo
É o conceito que mais gera engano. Cada papel recebe uma lista ordenada, e a T25 usa o primeiro CLI que estiver disponível na máquina. Não é escolha por qualidade nem sorteio: é a primeira porta que abre.
routing: triage: [kimi, claude, codex] planner: [claude, codex, kimi] research: [kimi, claude] dev-frontend: [claude, kimi, codex] dev-backend: [codex, claude, kimi] qa-frontend: [claude, kimi] qa-backend: [codex, claude, kimi] reviewer: [claude, codex, kimi] security: [claude, codex] docs: [kimi, claude, codex] release: [claude, codex]
São doze papéis, e cada lista precisa ser um array não vazio — lista vazia ou de tipo
errado é rejeitada no carregamento, não descoberta em execução. Os adapters de CLI
disponíveis hoje são claude, codex, kimi,
gemini, grok, opencode, cursor,
pi e vibe; mock é o adapter de teste.
Risco: quanto ela anda sozinha
risk:
low: { approval: none, sandbox: docker }
medium: { approval: plan, sandbox: docker }
high: { approval: plan_and_pr, sandbox: docker }
critical: { approval: human_required, sandbox: docker }
| Nível | O que muda |
|---|---|
low | Abre o PR sem gate de plano. |
medium | Exige aprovação do plano. |
high | Exige aprovação do plano e do PR. |
critical | Sempre exige intervenção humana. |
Nenhum nível automatiza o merge. A configuração de risco mexe em quanto a
fábrica anda sem perguntar até o PR; o merge é sempre seu, pelo cockpit ou pela CLI. E a
aprovação do briefing em SPEC é obrigatória em todos os níveis, salvo a chave
t25.auto_approve_spec, que nasce desligada (ver a seção de aprovações abaixo).
O padrão isola o estágio. O código, o t25 init e o t25.yaml deste repositório usam sandbox: docker nos quatro níveis. sandbox: none é escape explícito: o agente roda no host com o ambiente do worker, e o Claude usa --dangerously-skip-permissions quando T25_CLAUDE_SKIP_PERMISSIONS não está definida. Em máquina compartilhada, rode o worker num usuário ou VM dedicados, sem segredos pessoais, ou defina T25_CLAUDE_SKIP_PERMISSIONS=0 para o Claude aceitar só edições de arquivo (acceptEdits).
Uma ordem de tipo chore sem --risk explícito assume
low. É o caminho de adoção deliberado: upgrade, CVE, lint — critério
verificável e custo de erro baixo.
Aprovações: spec, plano e merge
São as chaves que decidem onde a fábrica para e espera uma pessoa. Os nomes são os do
t25.yaml; as chaves por projeto ficam dentro de cada entrada de
projects.
| Chave | Padrão | Efeito |
|---|---|---|
t25.auto_approve_spec | false | Assina sozinha a spec de risco low ou medium, desde que não haja gate de spec, comentário aberto nem critério de aceite faltando. high e critical continuam manuais. |
t25.require_plan_approval | true | Gate global do plano. Só vale para riscos cujo approval não é none. |
projects[].requirePlanApproval | ausente (herda a global) | Overlay do projeto: true mantém o gate com a flag global desligada; false tira o gate com ela ligada. |
projects[].planApprovalLowRisk | ausente | Faz o gate do plano valer também no risco low, que tem approval: none. Só age com o gate ligado. |
delegation (e projects[].delegation) | enabled: false | Delegação institucional por ação: merge, approve-spec, approve-plan e apply-improvement. Ligar a delegação e promover uma ação não tira a pessoa do merge: a execução do merge delegado não é chamada pelo pipeline. |
semantic_decisions | enabled: false, mode: shadow | Camada de decisões semânticas (JEV). Nasce desligada, com provedor fake, send_code: false (só aceita false) e routing: manual. Também tem overlay por projeto, com enabled e routing. |
Limites: o freio
limits: max_runtime_minutes: 60 max_queue_attempts: 5 max_failed_commands: 8 max_same_error_retries: 2 max_files_changed: 40 max_diff_lines: 2000 max_duplicate_line_ratio: 0.5
Os dois primeiros da segunda metade são o guardrail contra o agente que resolveu reescrever
o mundo: teto de arquivos alterados e de linhas de diff, conferidos depois da
implementação. Passou, a ordem falha. O max_duplicate_line_ratio pega
copy-paste excessivo e é o único que se desliga sozinho em modo bootstrap, onde repetição
legítima dispararia falso positivo.
Autenticação
Chaves de API funcionam sem nenhuma configuração extra e são o caminho de scripts e CLI. O login de pessoas por GitHub ou OIDC é opcional: quando ligado, exige segredo de sessão e o conjunto completo de um dos dois provedores. Os usuários autorizados começam declarados no YAML e passam a viver num overlay local depois da primeira edição no cockpit — não existe banco de usuários. Token de acesso do GitHub nunca é persistido, e tirar a pessoa da lista revoga a sessão dela na requisição seguinte.
Antes de mexer
- Rode
t25 doctor: ele falha em checkserror. Docker,psqlouweb/distausentes geram warning. - Referência a papel ou skill que não existe é rejeitada no carregamento — o erro aparece ao subir, não no meio de uma ordem.
- Nenhum segredo no YAML versionado. Nenhum.