Workflow Compartilhado dos Agentes¶
Antes de alterar¶
- Leia
.agents/README.md. - Leia
.agents/project-context.md. - Leia
.agents/shared-rules.md. - Consulte
backlog.md. - Leia o documento técnico mais relacionado à tarefa.
- 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:
- Antes de implementar, crie ou atualize item com status
em andamento. - Ao concluir, marque como
implementado. - Preencha data planejada, data implementada e arquivos afetados.
- 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:
- Localize (ou crie) o caso de teste em
ArchitectureComponentTestSuitecorrespondente ao comportamento. - Registre o novo
run("descrição", this::testNomeDoComportamento)nosetUp(). - Implemente o método
private void testNomeDoComportamento()com os asserts. - Execute:
sh scripts/run-tests.sh→ confirme que o novo caso FALHA (Red). - Implemente o código de produção mínimo.
- Execute:
sh scripts/run-tests.sh→ confirme que TODOS os casos passam (Green). - Refatore se necessário → revalide com
sh scripts/run-tests.sh. - Atualize documentação e backlog.
- 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:
Para simulação Docker:
Para monitor web:
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¶
- 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
- Confirme que
backlog.mdfoi atualizado. - Confirme que documentação afetada foi atualizada.
- Confirme que os arquivos de entrada dos agentes continuam apontando para
.agents/README.md. - Confirme que um commit Git local foi criado para a mudança concluída, salvo exceção explícita do usuário.