AI-translated from English; not yet reviewed by a fluent editor.

# Configurar uma fábrica de software baseada em Archon e rever uma tarefa

> Um guia baseado em uma revisão fixa para planejar e rever uma tarefa com Archon, da missão do produto e das verificações de execução à decisão humana de integração. A BIG CHANGE não executou a fábrica.

By BIG CHANGE Editorial

Published: 2026-10-19T14:43:34.857Z
Updated: 2026-10-19T14:43:34.857Z
Canonical: https://bigchange.ai/blog/archon-software-factory-reviewed-issue

![Conceptual charcoal illustration of one reviewer studying an unbranded two-column code change printout clipped to a wall rail.](https://bigchange.ai/api/media/file/archon-reviewed-code-change-v2.png)
AI-generated conceptual illustration by BIG CHANGE; no factory installation, issue delivery, code review outcome or product interface is depicted.

O [repositório AI Software Factory](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md) descreve o caminho da missão do produto e de uma tarefa até uma solicitação de integração criada por Archon. O instalador e as verificações dos fluxos são apenas o começo. O [guia da primeira hora](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/docs/first-hour.md) do responsável pela manutenção diz que a validação real de ponta a ponta ainda precisa ser feita. Este guia acompanha o commit da fábrica `9e2d85298b45497031009597a6ae0811b66fe6d6` e a revisão fixa de Archon `fad09169ea1b43512bc7ee88470d47f960a3e0f8`. É uma leitura da documentação e do código; não relata uma instalação ou execução feita pela BIG CHANGE.

O procedimento destina-se a uma equipa que controla o repositório de uma aplicação ou um PRD, as permissões GitHub e a conta do fornecedor de modelos. O responsável documenta expressamente a clonagem e instalação da fábrica no seu próprio repositório. A árvore da revisão fixa não contém licença nem aviso; este guia não estabelece direitos mais amplos de reutilização ou redistribuição. A licença MIT de Archon aplica-se ao código separado de Archon. Mantenha os segredos do fornecedor fora das tarefas, dos prompts, dos registos e das provas de revisão.

## A grande mudança

- **O que mudou:** A implementação reúne escopo do produto, planejamento de tarefas, programação, revisão independente e verificações de execução em um pack fixo de fluxos Archon. A fábrica fornece entradas do projeto e inicializador; o pack partilhado contém as etapas de IA.
- **Por que importa:** A equipa pode rastrear uma proposta da tarefa até alterações, resultado de CI e candidato em execução específicos antes de decidir integrar. As verificações de instalação deixam essa trilha incompleta; o responsável pela manutenção afirma que a integração real ainda precisa de validação.
- **O que acompanhar:** A primeira prova útil é uma tarefa real cuja revisão entregue passe por jornadas significativas e casos reservados independentes, com custos e histórico de revisão visíveis à equipa. Agendamento e implantação continuam decisões separadas depois dessa revisão.

## 1. Verificar o repositório, as permissões e a fonte fixa

As [instruções de instalação do responsável pela manutenção](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md#instructions-for-the-agent) exigem Git, Python 3.10 ou posterior, `gh` autenticado com o escopo `workflow`, um remoto do GitHub, um agente de programação, Bun e uv. Git também precisa conseguir enviar ficheiros de fluxo (`gh auth setup-git`). Antes de executar o agente, confira os comandos existentes de teste, inicialização e CI, a proteção de branches, o acesso ao GitHub, a autenticação do provedor e a cobrança dos modelos. Conceda somente as permissões necessárias ao repositório e aos fluxos.

Clone a fábrica fora do repositório da aplicação e selecione o commit indicado. Na raiz da *aplicação*, o comando de instalação documentado é:

```bash
git clone https://github.com/coleam00/ai-software-factory ~/ai-software-factory
git -C ~/ai-software-factory checkout 9e2d85298b45497031009597a6ae0811b66fe6d6
python ~/ai-software-factory/bin/factory.py init
```

Use `python3` se necessário. O instalador copia os modelos de fábrica e projeto e instala a fonte de Archon indicada em [`pack.json`](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/pack.json). O README e o pack desse commit especificam `fad09169ea1b43512bc7ee88470d47f960a3e0f8`. O instalador não autentica um provedor, escolhe categorias de modelos nem inicia um agendamento. Examine as alterações nos ficheiros antes de aceitá-las no repositório.

Configure o provedor escolhido e os identificadores de modelos compatíveis conforme a orientação instalada de Archon. Defina os comandos reais de análise estática e testes unitários em `harness/harness.config.json`. Quando o GitHub não informar a proteção de branches, indique em `required_checks` os trabalhos de CI necessários à integração. Reveja `protected_paths` para exigir uma pessoa nas mudanças da missão, da estrutura de validação e das regras da fábrica. O modelo deixa vazios os comandos comuns de verificação e `required_checks`; copiá-lo não estabelece um critério de aceitação utilizável.

## 2. Escrever a missão e as verificações do produto existente

Escreva em `MISSION.md` o propósito do produto, os limites rígidos e solicitações plausíveis fora do escopo. Em `harness/END-TO-END.md`, descreva de duas a cinco jornadas que a aplicação atual realmente conclui, incluindo o valor visível ao utilizador. Uma jornada que dependa de uma função ainda não construída bloquearia a primeira entrega. Em `.factory/holdout/HOLDOUT.md`, crie casos separados que combinem comportamentos ou explorem situações-limite. O nome do diretório não os esconde de quem desenvolve com acesso à mesma cópia; coloque casos realmente privados fora dela e forneça-os apenas à verificação.

Para um repositório com apenas um PRD, o [README](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md#instructions-for-the-agent) pede que a missão, as jornadas previstas e os comandos de validação venham do documento. A primeira tarefa proposta deve tornar o produto executável e informar comando de inicialização, caminhos de saúde e identidade da compilação, testes e CI. Reveja a proposta antes de permitir a publicação das tarefas.

Transforme as jornadas nas entradas de cenário esperadas pelos fluxos de execução de Archon. Siga o ficheiro instalado [`factory/RUNTIME_HOST.md`](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/RUNTIME_HOST.md) para preparar uma cópia da aplicação a partir do commit entregue, um estado novo, verificações de saúde e identidade e os comandos de inicialização Python ou Node permitidos. O hospedeiro documentado não administra bancos remotos, contentores ou recursos de nuvem como recursos próprios de execução. Uma aplicação que os use precisa de um arranjo de verificação justificado à parte; uma verificação local bem-sucedida não demonstra seu isolamento.

Antes de confiar no avaliador, estabeleça uma referência aprovada que exercite valor real ao utilizador, mostre que uma falha deliberada relevante reprova e confira que a identidade errada do candidato produz um veredito inconclusivo. O guia do hospedeiro fornece as entradas e os campos exatos esperados, incluindo `expectations_passed: true` e `baseline_verified: true`. Guarde o retorno nativo real e a identidade do candidato como evidência. Verificar apenas o carregamento de uma página ou criar diretamente o estado final do teste é insuficiente.

## 3. Verificar a instalação e escolher uma tarefa

Execute na raiz da aplicação:

```bash
python factory/consumer.py doctor
python factory/consumer.py list
```

`doctor` verifica a fonte fixa, os recursos dos comandos e os fluxos disponíveis. `list` mostra os fluxos encontrados. Nenhum prova que um provedor conclui uma tarefa, que a CI passa ou que a aplicação funciona. Resolva as falhas informadas antes da entrega; mantenha o agendamento desativado.

Em uma base de código existente, escreva uma tarefa pequena com resultado claro e critérios de aceitação. O README documenta este comando para passar por triagem, entrega e revisão até uma solicitação de integração:

```bash
python factory/consumer.py run archon-ship --input target=https://github.com/OWNER/REPO/issues/1 --input discovery_publication=preview --detach --json
```

Substitua a URL por uma tarefa sob seu controle. A opção explícita `discovery_publication=preview` impede que descobertas próximas feitas na revisão sejam publicadas como tarefas; o fluxo fixo `archon-ship` usa `auto` por predefinição. Use `archon-lifecycle` somente com as entradas de cenário de execução e casos reservados prontas. Passe a tarefa como `target`, os caminhos de entrada como `scenario` e `holdout`, além de `merge_mode=approve` e `discovery_publication=preview`. Forneça também um `merge_method` aprovado pelo projeto: `merge`, `squash` ou `rebase`. Por exemplo, use `merge_method=squash` somente se o repositório permitir. Esse fluxo inclui verificação de execução e casos reservados, reparo e controle de integração. O modo de aprovação mantém uma decisão humana antes de integrar; uma indicação de pronto do fluxo não é essa decisão. Com o hospedeiro de execução da fábrica, a opção documentada `--runtime-host` funciona apenas em primeiro plano e não pode acompanhar `--detach` nem `--resume`.

Para um PRD, o comando documentado de backlog é:

```bash
python factory/consumer.py run archon-backlog --input 'prd=docs/PRD.md' --input publication=approve
```

Substitua `docs/PRD.md`, entre aspas no comando, pelo caminho real do PRD relativo à cópia da aplicação. Reveja as tarefas ordenadas propostas antes da publicação. Configure o hospedeiro de execução conforme o início da aplicação e o contrato de identidade declarados na primeira tarefa; depois processe-a com `archon-lifecycle`, usando jornadas e casos reservados preparados. A primeira tarefa exige o mesmo cuidado que as seguintes.

## 4. Avaliar as alterações e o resultado em execução antes de aprovar

Guarde o identificador retornado. O programa de controle oferece `get <run-id> --json --events` e `status --all --json` para acompanhar progresso e evidências. Compare a tarefa e o plano com `MISSION.md`; leia as alterações reais da solicitação e a revisão independente da versão atual; verifique a CI exigida e o relatório de caminhos protegidos. Execute as jornadas na revisão entregue e examine os resultados nativos de execução e casos reservados, incluindo a identidade do candidato. Compare o resultado observado pelo utilizador com os critérios de aceitação. Quem revisa deve devolver uma solicitação deficiente para reparo; o README descreve `archon-deliver --adopt <run id>` para uma entrega retida na fila de integração.

Somente uma pessoa com autoridade no repositório deve aprovar a integração após esses controles passarem. A implantação exige seus próprios comandos de implantação, saúde e identidade, além de uma releitura da revisão após implantar; uma solicitação integrada não prova que houve implantação. Deixe o agendamento desativado durante essa primeira tarefa e decida separadamente se haverá execuções recorrentes.

A [orientação de custos do responsável pela manutenção](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md#cost) não informa preço fixo por execução. Recomenda medir tokens desde o primeiro dia e observar chamadas de modelos em uma tarefa pequena antes de ativar um ciclo. As cobranças dependem do provedor, dos modelos e das condições da conta. A BIG CHANGE não mediu o gasto dessa fábrica.

Uma execução ativa também precisa de uma decisão explícita de parada. No [código do programa de controle](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/consumer.py), `halt` bloqueia novos inícios e continuações; `cancel <run-id>` se dirige ao trabalho ativo. `pause` interrompe os inícios do temporizador, mas permite reativar trabalhos em andamento. Nenhum comando substitui verificar o estado atual da execução e as alterações no repositório remoto.

## Fontes e leituras adicionais

- [README da fábrica na revisão fixa](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md): instalação, comandos, entradas do produto, escolhas de fluxos e limites declarados. Descrição do responsável pela manutenção, não evidência de execução pela BIG CHANGE.
- [Manifesto do pack fixo](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/pack.json) e [código do programa de controle](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/consumer.py): revisão de Archon, fluxos expostos e diferenças entre status, halt, cancel e pause.
- [Guia da primeira hora](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/docs/first-hour.md) e [guia do hospedeiro de execução](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/RUNTIME_HOST.md): ressalva do responsável pela manutenção sobre validação e requisitos de verificação vinculada ao candidato.
- [Reportagem relacionada da BIG CHANGE sobre agentes de programação e trabalho concluído](https://bigchange.ai/articles/ai-coding-agents-review-output-study): contexto para verificar resultados terminados. Trata de um estudo separado, não de uma continuação datada dessa implementação.

## Sources

- [README.md](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md) — Configuração, ficheiros do projeto, fluxos, caminhos de tarefa e PRD, política de integração e limites operacionais do responsável pela manutenção.
- [pack.json](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/pack.json) — Revisão exata de Archon, fluxos e recursos de linha de comando; coincide com o README fixo.
- [first-hour.md](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/docs/first-hour.md) — Sequência de configuração e necessidade explícita de validação real de ponta a ponta.
- [consumer.py](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/consumer.py) — Implementação de doctor/list, execução de fluxos, status, halt, pause e cancel.
- [RUNTIME_HOST.md](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/RUNTIME_HOST.md) — Vinculação ao candidato, referência e falha deliberada de calibração, tipos de aplicação compatíveis e limites.
- [harness.config.json](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/harness/harness.config.json) — Comandos de verificação e controlos exigidos vazios, e caminhos protegidos predefinidos.
- [LICENSE](https://github.com/coleam00/Archon/blob/fad09169ea1b43512bc7ee88470d47f960a3e0f8/LICENSE) — Termos da licença de Archon; não estabelecem concessão para o repositório separado da fábrica.
- [archon-ship.yaml](https://github.com/coleam00/Archon/blob/fad09169ea1b43512bc7ee88470d47f960a3e0f8/.archon/workflows/sdlc/ship/archon-ship.yaml) — Publicação de descobertas usa auto por predefinição; preview mantém descobertas próximas sem publicação.
- [archon-lifecycle.yaml](https://github.com/coleam00/Archon/blob/fad09169ea1b43512bc7ee88470d47f960a3e0f8/.archon/workflows/sdlc/lifecycle/archon-lifecycle.yaml) — Exige um método de integração explícito: merge, squash ou rebase.
- [archon-backlog.yaml](https://github.com/coleam00/Archon/blob/fad09169ea1b43512bc7ee88470d47f960a3e0f8/.archon/workflows/sdlc/backlog/archon-backlog.yaml) — O PRD é indicado por um caminho dentro da cópia do repositório.
- [BIG CHANGE](https://bigchange.ai/articles/ai-coding-agents-review-output-study) — Contexto relacionado, mas distinto, para verificar resultados concluídos.