Ir para o conteúdo

Workflow Compartilhado dos Agentes

Antes de alterar

  1. Leia .agents/README.md.
  2. Leia .agents/project-context.md.
  3. Leia .agents/shared-rules.md.
  4. Consulte backlog.md.
  5. Leia o documento técnico mais relacionado à tarefa.
  6. Identifique se a mudança é conceitual, técnica, científica, operacional, segurança ou documentação.

Backlog obrigatório

backlog.md é o registro único de tarefas técnicas.

Para mudanças não triviais:

  1. Antes de implementar, crie ou atualize item com status em andamento.
  2. Ao concluir, marque como implementado.
  3. Preencha data planejada, data implementada e arquivos afetados.
  4. Tarefas identificadas mas não executadas devem ficar como planejado.

Durante a alteração — Ciclo TDD obrigatório

Para todo código de produção novo ou modificado, siga obrigatoriamente:

1. RED    → Escreva o teste que descreve o comportamento desejado.
            Confirme que falha por razão legítima (sem a implementação).

2. GREEN  → Escreva o mínimo de código para o teste passar.
            Não antecipe abstrações além do necessário.

3. REFACTOR → Limpe o código sem quebrar os testes existentes.
              Execute sh scripts/run-tests.sh antes de concluir.

Fluxo de trabalho TDD no projeto:

  1. Localize (ou crie) o caso de teste em ArchitectureComponentTestSuite correspondente ao comportamento.
  2. Registre o novo run("descrição", this::testNomeDoComportamento) no setUp().
  3. Implemente o método private void testNomeDoComportamento() com os asserts.
  4. Execute: sh scripts/run-tests.sh → confirme que o novo caso FALHA (Red).
  5. Implemente o código de produção mínimo.
  6. Execute: sh scripts/run-tests.sh → confirme que TODOS os casos passam (Green).
  7. Refatore se necessário → revalide com sh scripts/run-tests.sh.
  8. Atualize documentação e backlog.
  9. Crie um commit Git local com a mudança concluída, salvo instrução explícita do usuário para não commitar.

Exceções permitidas (mas devem ser declaradas): - Scripts shell e arquivos de configuração não precisam de testes automatizados, mas devem ser validados manualmente. - Código de experimento exploratório em research/ pode ser desenvolvido sem TDD estrito, mas deve ter pelo menos um teste ponta a ponta na suíte antes de ser considerado estável.

Regras adicionais durante a alteração:

  • Preserve Java-only.
  • Preserve MQTT como comunicação federada alvo.
  • Preserve Hyperledger Fabric como auditoria/governança.
  • blockchain é o único modo de ledger suportado (HYBRID e memory puro foram removidos) — Fabric é sempre obrigatório; qualquer falha bloqueia a operação, não há mais tolerância silenciosa.
  • Use padrões existentes do repositório antes de criar abstrações novas.
  • Ao alterar código, atualize documentação correspondente.
  • Ao criar arquivo novo de documentação, atualize índices.
  • Ao estabelecer nova regra obrigatória, atualize agent/shared-rules.md.

Mapa de documentação por impacto

Impacto Documentos a verificar
Módulos Java docs/components/README.md e documento do componente afetado em docs/components/
Dados locais ou DataComponent docs/components/07-data-component.md e docs/components/08-local-cdm.md
Monitor web docs/components/01-admin-api-monitor-web.md
Clientes Docker docs/components/06-federated-client.md e docs/components/01-admin-api-monitor-web.md
Chaincode ou world state docs/blockchain/02-chaincodes.md e docs/blockchain/03-assets-world-state.md
Modos de ledger docs/blockchain/04-system-integration.md
MQTT docs/mqtt/01-envelope.md e docs/mqtt/02-topics-and-payloads.md
Agregação docs/components/11-aggregator.md
ML, Android ou Apple Silicon docs/components/09-experiment-sdk.md e docs/components/10-training-local-model.md
Testes e qualidade docs/backlog.md e documentação do componente testado
Execução de software docs/README.md, docs/components/README.md e scripts em scripts/
Dados pessoais, clientId, consentimento, privacidade, Fabric docs/components/03-hyperledger-fabric.md, docs/components/06-federated-client.md e .agents/shared-rules.md

Validação

Quando possível, execute:

sh scripts/run-tests.sh

Para simulação Docker:

FEDERATED_CLIENT_EXECUTION_MODE=docker sh scripts/run-admin-web.sh

Para monitor web:

sh scripts/run-admin-web.sh

Registre na resposta final quais validações foram executadas e quaisquer limitações de ambiente.

Atualização do RAG

Após qualquer mudança técnica não trivial, atualize a base de conhecimento:

# Atualizar data de todos os chunks
sh .agent-config/rag/update.sh

# Ou somente o chunk afetado (mais rápido):
sh .agent-config/rag/update.sh chunk-007  # exemplo: mudança no Fabric

Depois edite o conteúdo do chunk para refletir a mudança. O script atualiza apenas a data.

Arquivo modificado Chunk
.agents/project-context.md chunk-001
.agents/shared-rules.md chunk-002
ExperimentContract.java, docs/components/03-*.md chunk-003
modules/federated-client/... chunk-004
modules/federated-aggregator/... chunk-005
modules/federated-orchestrator/... chunk-006
docs/blockchain/04-system-integration.md chunk-007
docs/mqtt/... chunk-008
docs/components/07-data-component.md chunk-009
research/experiments/... chunk-010
modules/federated-rest-api/...AdminWebServer.java chunk-011
.agent-config/rag/chunks/chunk-012-lgpd.md e documentos de Fabric/cliente chunk-012
docs/execution-guide.md ou scripts/ chunk-013
modules/federated-package-experiment-service/... chunk-014
backlog.md chunk-015

Antes de concluir

  1. Rode buscas por termos obsoletos quando a mudança tocar arquitetura:
rg -n "gRPC|framework: pytorch|train.py|requirements.txt|Flower|PyTorch|Chaincode em Go|DigitalTwinDataComponent|Artifact Service|Audit Chaincode" docs modules research agent codex AGENTS.md CLAUDE.md .github
  1. Confirme que backlog.md foi atualizado.
  2. Confirme que documentação afetada foi atualizada.
  3. Confirme que os arquivos de entrada dos agentes continuam apontando para .agents/README.md.
  4. Confirme que um commit Git local foi criado para a mudança concluída, salvo exceção explícita do usuário.