O que Arquiteto ICM faz?
Construa espaços de trabalho onde a estrutura de pastas faz a orquestração. Um agente, lendo os arquivos certos no momento certo, substitui um framework multi-agente: pastas numeradas carregam a sequência, a hierarquia carrega o escopo do contexto, arquivos markdown simples carregam o estado. Um humano pode abrir qualquer pasta e ver exatamente em que estado o sistema está, porque estado é apenas arquivos.
Pense no espaço de trabalho como uma biblioteca. Os arquivos de roteamento são o catálogo: pequenos, estáveis, apontam para tudo e armazenam quase nada. O conteúdo vive nas prateleiras (pastas de estágio, arquivos de nó, material de referência). Um bibliotecário — um modelo — percorre o prédio, e a pergunta decide para qual prateleira ir. Ninguém fotocopia a biblioteca inteira em uma mochila; isso é o que seria "entupir o contexto". O catálogo é pequeno de propósito.
Método: Metodologia de Contexto Interpretável (Van Clief & McDermott, arXiv:2603.16021, licenciado sob MIT).
Os invariantes
Todo ICM, seja qual for sua forma, obedece a estes. Ao construir ou reestruturar, aplique todos os dez:
- Uma pasta, um trabalho. Cada pasta executa uma única etapa ou contém um único tipo de coisa, e declara seu próprio propósito em um arquivo dentro de si. A estrutura é a documentação.
- Um arquivo de entrada pequeno e estável.
CLAUDE.md(ouAGENTS.md) na raiz responde "onde estou, onde tudo vive, para onde vou para a tarefa X" — e nada mais. Alvo de ~60 linhas. Ele roteia; nunca armazena conteúdo. - Numeração codifica ordem.
01_,02_, … onde a sequência importa. Renomear pastas reordena o pipeline — essa é a ideia. - Todo contrato de nível de pasta é explícito. Um
CONTEXT.mdpor pasta de trabalho: o que ela lê (entradas), o que faz (processo), o que escreve (saídas), o que um humano verifica. Veja assets/templates/stage-CONTEXT.md. - Fábrica vs. produto. Material de referência (regras, voz, esquemas, modelos — estáveis entre execuções) vive estruturalmente separado dos artefatos de trabalho (saídas, rascunhos — novos a cada execução). Configure a fábrica uma vez; o produto é o que cada execução emite.
- Toda saída é uma superfície de edição. Saídas intermediárias são arquivos de texto simples que um humano pode abrir, editar e salvar antes que a próxima etapa os leia. Nada avança até que uma pessoa tenha lido a última saída.
- Carregue apenas o que a etapa precisa. Um agente executando uma etapa lê seu contrato, suas referências e suas entradas — não o espaço de trabalho inteiro. 2.000–8.000 tokens por etapa é a faixa saudável.
- Texto simples, linkável, consultável. Markdown + frontmatter YAML. Links (
[[wikilinks]]ou caminhos relativos) fazem dele um grafo; rótulos de frontmatter o tornam consultável. Um lar por fato — um link vence uma cópia. - O sistema de arquivos é a máquina de estado. "Status" é derivável escaneando o que existe nas pastas de saída. Índices gerados (mapas de arquivos, logs) são reconstruídos por script, nunca editados manualmente.
- Instancie copiando. Nova unidade de trabalho = copiar uma pasta de modelo, não uma página em branco. Mantenha modelos em uma pasta
_templates/ou_system/.
Escolha um modo
- Construindo a partir de um processo, ideia ou problema descrito → Modo Construir.
- Uma pasta, repositório ou vault existente que precisa de estrutura ICM → Modo Reestruturar.
Modo Construir
1. Extraia a estrutura do diálogo. A estrutura já está em como a pessoa descreve o trabalho — não imponha uma forma, revele a deles. Pergunte (algumas de cada vez, não todas de uma vez):
- Qual é a unidade repetitiva de trabalho? (um episódio, um cliente, um relatório, uma pessoa, uma equipe?)
- Me guie por uma execução, do início ao fim. Onde você para e verifica algo antes de continuar?
- O que permanece igual a cada execução (voz, regras, marca, esquema) vs. o que é novo a cada execução?
- Como é "pronto" — que artefato sai do espaço de trabalho?
- Quem mais toca nisto, e o que eles precisam encontrar sem perguntar a você?
As pausas deles se tornam limites de estágio. Seus "sempre verifico X antes de Y" se tornam portões humanos. Seu "sempre tem que soar como / seguir Z" se torna material de referência da fábrica.
2. Escolha a forma. Leia references/forms.md e escolha:
| Forma | Use quando |
|---|---|
| Pipeline | A mesma sequência é executada repetidamente, produzindo uma entrega a cada execução |
| Guarda-chuva | Vários pipelines distintos compartilham uma camada de marca/voz/referência |
| Biblioteca de registros | A unidade é um registro (pessoa, cliente, sessão) que se acumula, não uma execução |
| Pacote de conhecimento | O produto é o próprio conhecimento navegável (um cérebro, uma wiki, um modelo de algo) |
| Mapa de contexto | O assunto é uma organização — equipes, processos, dados e as conexões entre eles |
Espaços de trabalho reais misturam formas (uma biblioteca de registros cujos registros são minipacotes de conhecimento; um pipeline que emite para uma biblioteca de registros). Componha livremente — os invariantes se mantêm em todos os níveis, recursivamente.
3. Monte a menor estrutura que suporta o trabalho. Copie iniciadores de assets/templates/ e preencha-os. Não crie pastas para estágios que ainda não existem, baldes "diversos" vazios ou profundidade especulativa. Três estágios reais vencem sete imaginados. Se todo o trabalho couber em um prompt salvo, diga isso e não construa um espaço de trabalho.
4. Escreva os contratos. Root CLAUDE.md (identidade + tabela de roteamento), root CONTEXT.md (definição do pipeline ou esquema), um CONTEXT.md por pasta de estágio/hub, setup/questionnaire.md se a fábrica precisar ser configurada por usuário. Escreva as entradas como caminhos de arquivo explícitos, divididos em trabalho (esta execução) e referência (todas as execuções).
5. Valide com o teste de caminhada (abaixo).
Modo Reestruturar
1. Faça inventário antes de tocar. Liste a árvore. Para cada área, anote: o que é, quando foi tocada pela última vez, o que se refere a ela. Nunca delete ou mova nesta passagem.
2. Encontre a forma oculta. Pergunte ao proprietário (ou infira e confirme): qual é a unidade repetitiva aqui? Onde o trabalho entra e sai? A bagunça geralmente contém um pipeline, biblioteca ou mapa real que cresceu sem um esqueleto — extraia-o, não o substitua. Entreviste a pasta como entrevistaria a pessoa.
3. Classifique cada arquivo em um dos cinco papéis:
- Catálogo — identidade/roteamento (torna-se ou alimenta
CLAUDE.md/ arquivos de índice) - Contrato — descreve como uma etapa funciona (torna-se um
CONTEXT.md) - Fábrica — referência estável (→
_shared/,_system/oureferences/) - Produto — artefatos específicos da execução (→ pasta
output/do estágio ou pastas de registro) - Morto — desatualizado, duplicado ou substituído (→ propor
_archive/, nunca deletar silenciosamente)
4. Proponha antes de mover. Apresente a árvore alvo e um mapa de migração (caminho antigo → caminho novo → papel). Obtenha aprovação. Este é um portão humano em um método construído sobre portões humanos — honre-o.
5. Migre. Mova arquivos, escreva o arquivo de entrada e os contratos, desduplique em direção a um lar por fato (deixe um link onde a cópia estava se algo puder referenciá-lo). Separe método de instância: se a estrutura for reutilizada em outro lugar, o modelo em branco vive separado desta implantação preenchida.
6. Valide com o teste de caminhada.
O teste de caminhada
Valide qualquer ICM — novo ou reestruturado — percorrendo-o a frio, como um agente sem memória:
- Abra a raiz. Você consegue responder onde estou e para onde vou para a tarefa atual dentro do arquivo de entrada mais no máximo duas outras leituras?
- Escolha qualquer estágio/nó. O contrato dele nomeia caminhos de entrada exatos, o trabalho, a saída e a verificação humana?
- Você consegue declarar o status do pipeline puramente escaneando o que existe nas pastas
output/(ou frontmatter do nó)? - Algum arquivo de roteamento está carregando payload de conteúdo? Mova o payload para uma prateleira; deixe um ponteiro.
- Algum fato está armazenado em dois lugares? Escolha um lar; link do outro.
- Verificação de tokens: arquivo de entrada + um contrato + suas entradas deve cair em aproximadamente 2k–8k tokens.
Se uma etapa falhar, corrija a estrutura — não explicando mais, mas movendo ou dividindo arquivos até que a caminhada funcione.
Diretrizes de segurança
- Não superestruturar. A escada corre: chat → prompt/skill salvo → pastas + um agente. Só suba quando o degrau abaixo estiver genuinamente automatizado e repetindo. Um espaço de trabalho para algo feito duas vezes é andaime, não arquitetura.
- Saiba onde o ICM perde. Colaboração multi-agente em tempo real, atendimento multi-usuário de alta concorrência e ramificação automatizada no meio do pipeline precisam genuinamente de código de framework. O ICM é para trabalho sequencial, revisado por humanos e repetível — que é a maior parte do trabalho de conhecimento, mas não todo ele.
- Antipadrões vistos na prática: arquivos de entrada duplicados que divergem (gere um a partir do outro, ou faça de um um ponteiro); documentos de esquema que exigem nomes que os arquivos reais pararam de usar (atualize o esquema ou os arquivos — escolha um); edições manuais em índices gerados; sessões de workshop que produzem slides em vez de dados estruturados (toda sessão de trabalho deve terminar em um artefato que a estrutura possa conter); padrões declarados de cima para baixo (uma equipe reclamando é uma queixa — a mesma forma aparecendo três vezes independentemente é estrutura).
Referências
- references/core.md — os cinco princípios de design, a hierarquia de contexto de cinco camadas, convenções de nomenclatura, disciplina de tokens. Leia ao escrever contratos ou quando uma decisão estrutural for contestada.
- references/forms.md — as cinco formas em profundidade: árvores esqueleto, movimentos definidores, modos de falha. Leia na etapa 2 do modo Construir ou etapa 2 do modo Reestruturar.
- assets/templates/ — iniciadores copiáveis:
CLAUDE.md, workspaceCONTEXT.md,stage-CONTEXT.md,node.md,schema.md,questionnaire.md.