Harnesses: Construindo Contexto Estruturado para Agentes Harnesses: Building Structured Context for Agents

O Problema

The Problem

Chamar um modelo de linguagem via API ou chat é simples. Mas há um custo oculto: cada invocação é isolada. O modelo não sabe quem você é, não lembra do contexto anterior, não conhece as restrições do seu domínio.

Calling a language model via API or chat is simple. But there's a hidden cost: each invocation is isolated. The model doesn't know who you are, doesn't remember previous context, doesn't understand your domain's constraints.

Você poderia colocar tudo isso num prompt manualmente toda vez. Funciona uma vez. Funciona duas vezes. Mas não escala: fica inconsistente, difícil de manter, impossível de reutilizar em outro contexto.

You could put all of this into a prompt manually every time. It works once. It works twice. But it doesn't scale: it becomes inconsistent, hard to maintain, impossible to reuse in another context.

Um harness é a solução estruturada para este problema: uma camada de contexto versionada — perfil, skills, memória e workflows — que vive ao lado do código, não dentro de um prompt efêmero.

A harness is the structured solution to this problem: a versioned context layer — profile, skills, memory, and workflows — that lives next to your code, not inside an ephemeral prompt.

Os Seis Blocos de um Harness

The Six Blocks of a Harness

Todo harness funcional é composto por seis camadas bem definidas:

Every functional harness is composed of six well-defined layers:

1. Profile

Define a identidade do agente: papel, tom, restrições de segurança, contexto de domínio. Alimenta o system prompt de cada sessão.

Defines the agent's identity: role, tone, security constraints, domain context. Feeds the system prompt of each session.

2. Skills

Comportamentos discretos e documentados. Cada skill tem: trigger (quando ativar), pré-condições, passos numerados, output esperado, pitfalls.

Discrete, documented behaviors. Each skill has: trigger (when to activate), pre-conditions, numbered steps, expected output, pitfalls.

3. Prompts Canônicos

3. Canonical Prompts

Templates de invocação que garantem consistência. Exemplos: new-session, new-feature, code-review.

Invocation templates that ensure consistency. Examples: new-session, new-feature, code-review.

4. Memória

4. Memory

O que persiste entre sessões. Pode ser estruturada e explícita (arquivos que o agente consulta) ou dinâmica (atualizada durante a sessão).

What persists between sessions. Can be structured and explicit (files the agent consults) or dynamic (updated during the session).

5. Harness de Sessão

5. Session Harness

Roteiro de inicialização. Antes de qualquer trabalho, injeta contexto: quem é o usuário, qual é o estado atual, que decisões já foram tomadas.

Initialization workflow. Before any work, it injects context: who the user is, what the current state is, what decisions have been made.

6. Agent

A composição dos cinco blocos acima, instanciado com um papel e um domínio específicos.

The composition of the five blocks above, instantiated with a specific role and domain.

Anatomia de uma Skill

Anatomy of a Skill

A unidade de trabalho de um harness é a skill. Ela não é código: é um documento Markdown com cinco partes obrigatórias. Abaixo, uma skill real do repositório, concept-to-code, que converte um conceito abstrato em implementação comentada:

The unit of work in a harness is the skill. It isn't code: it's a Markdown document with five required parts. Below, a real skill from the repository, concept-to-code, which turns an abstract concept into annotated code:

---
name: concept-to-code
description: Conceito abstrato -> implementacao comentada (TS/Python).
version: 0.1.0
---

# Concept to Code

## Trigger
O usuario diz "nao estou entendendo X" sobre um conceito abstrato.

## Pre-condicoes
- O conceito foi nomeado explicitamente.
- A linguagem-alvo e conhecida (default: TypeScript).

## Passos
1. Reformular o conceito em uma frase.
2. Escrever a MENOR implementacao que o demonstra.
3. Comentar apenas as linhas que carregam a ideia central.
4. Mostrar um caso de uso e um contra-exemplo.

## Output esperado
Bloco de codigo executavel + 3 a 5 linhas de explicacao. Sem teoria solta.

## Pitfalls
- Codigo longo demais: passando de ~20 linhas, o conceito se perde.
- Explicar a sintaxe em vez do conceito.

Cada parte tem uma função: o trigger diz ao agente quando ativar a skill; as pré-condições evitam rodar sem o necessário; os passos tornam o comportamento repetível; o output esperado fixa o formato; os pitfalls codificam erros já cometidos para não se repetirem. O efeito prático: a qualidade não depende de quem opera — depende da skill estar bem definida.

Each part has a job: the trigger tells the agent when to activate the skill; the pre-conditions prevent running without what's needed; the steps make the behavior repeatable; the expected output pins the format; the pitfalls encode mistakes already made so they don't recur. The practical effect: quality doesn't depend on who's operating — it depends on the skill being well-defined.

Três Skills Concretas

Three Concrete Skills

Para validar a arquitetura, construímos três skills com essa mesma anatomia:

To validate the architecture, we built three skills with this same anatomy:

Padrões de Orquestração

Orchestration Patterns

Como múltiplas skills se compõem numa sessão:

How multiple skills compose within a session:

Routing Simples

Simple Routing

O harness roteia para a skill correta baseado na intenção do usuário. Transparente, fácil de depurar.

The harness routes to the correct skill based on user intent. Transparent, easy to debug.

Chaining

A saída de uma skill vira input da próxima. O contexto acumula ao longo da cadeia.

The output of one skill becomes the input to the next. Context accumulates along the chain.

Meta-skill

Uma skill que sabe quando chamar outras. Raramente necessário — se você precisa encadear mais de 3 skills, o design provavelmente está errado.

A skill that knows when to call others. Rarely necessary — if you need to chain more than 3 skills, the design is probably wrong.

Chaining na Prática

Chaining in Practice

O padrão fica concreto num harness encadeado, exam-prep-session. Entrada do usuário: "Tenho prova sobre portas lógicas e mapas de Karnaugh em três dias e não sei por onde começar." A cadeia roda três skills, cada uma consumindo o resultado da anterior:

The pattern becomes concrete in a chained harness, exam-prep-session. User input: "I have an exam on logic gates and Karnaugh maps in three days and I don't know where to start." The chain runs three skills, each consuming the previous output:

1. session-planner lê a memória (prioridades, gaps do tópico) e devolve um plano de 3 blocos: revisar portas lógicas, praticar simplificação por Karnaugh, simulado final.
2. concept-to-code recebe os conceitos fracos do plano e gera, para cada um, uma implementação comentada (ex.: simular portas lógicas em TypeScript) — abstrato vira tangível.
3. exam-simulator recebe o material já estudado e produz um simulado com gabarito comentado, fechando o ciclo de revisão.

1. session-planner reads memory (priorities, topic gaps) and returns a 3-block plan: review logic gates, practice Karnaugh simplification, final mock exam.
2. concept-to-code takes the weak concepts from the plan and generates, for each, an annotated implementation (e.g., simulating logic gates in TypeScript) — abstract becomes tangible.
3. exam-simulator takes the studied material and produces a mock exam with an annotated answer key, closing the review loop.

Nenhuma das três skills sabe da existência das outras. Quem as compõe é o harness de sessão — por isso cada skill continua testável e reutilizável isoladamente.

None of the three skills knows the others exist. The session harness composes them — which is why each skill stays independently testable and reusable.

Memória em Três Camadas

Memory in Three Layers

Um harness sem memória age como um assistente genérico. A memória que usamos tem três camadas, separadas por frequência de mudança:

A harness without memory acts like a generic assistant. The memory we use has three layers, separated by how often they change:

• Estável: como o usuário aprende, objetivos de longo prazo. Muda raramente.
• Ativa (sazonal): responsabilidades correntes, prioridades, gaps. Muda a cada ciclo.
• De sessão: o que ficou pendente, últimos focos, próximos passos. Muda toda sessão.

• Stable: how the user learns, long-term goals. Changes rarely.
• Active (seasonal): current responsibilities, priorities, gaps. Changes each cycle.
• Session: what's pending, recent focuses, next steps. Changes every session.

Separar por frequência de mudança não é cosmético: define o que recarregar a cada sessão (a camada de sessão) e o que tratar como quase constante (a estável). Uma skill como session-planner depende criticamente dessa estrutura — sem ela, não há o que priorizar.

Splitting by change frequency isn't cosmetic: it defines what to reload each session (the session layer) and what to treat as near-constant (the stable one). A skill like session-planner depends critically on this structure — without it, there's nothing to prioritize.

Memória que Melhora com o Uso

Memory That Improves with Use

As três camadas acima respondem o que persiste. Mas há uma pergunta mais profunda: como a memória fica melhor com o tempo, em vez de só acumular? A inspiração veio da arquitetura do Hermes (Nous Research), estudada como referência — não instalada. Dois mecanismos foram adaptados.

The three layers above answer what persists. But there's a deeper question: how does memory get better over time, instead of merely accumulating? The inspiration came from the Hermes architecture (Nous Research), studied as a reference — not installed. Two mechanisms were adapted.

1. Uma memória curada e sempre injetada (MEMORY.md)

1. A curated, always-injected memory (MEMORY.md)

Um único arquivo lido no início de toda sessão. Não é um log bruto: é a destilação de insights, padrões e decisões. E é limitado — no máximo ~50 entradas. Quando enche, remove-se uma entrada obsoleta antes de adicionar uma nova. O limite é o ponto: não é um depósito, é um resumo vivo. Na prática, o cabeçalho do arquivo carrega o próprio contrato de uso:

A single file read at the start of every session. Not a raw log: it's the distillation of insights, patterns, and decisions. And it's bounded — at most ~50 entries. When it fills up, you remove a stale entry before adding a new one. The bound is the point: it's not a warehouse, it's a living summary. In practice, the file's own header carries its usage contract:

# Memory

Status: canonical
Bounded: max ~50 entradas curadas - distile, nao apenas adicione.
Injetar no inicio de cada sessao.

## Conceitos-chave
- Harness = perfil + skills + memoria + workflows.
- Context engineering > prompt engineering: o que entra no
  contexto, e quando, importa mais que o texto da instrucao.
- Tool scoping: menos ferramentas expostas = melhor performance.

## Padroes descobertos
- Dual memory (Hermes): MEMORY.md (bounded, sempre injetado)
  + historico de sessoes (searchable, consultado sob demanda).
- Session-end distillation: extrair 1-3 insights de alta
  qualidade ao fechar - nao a transcricao bruta.

## Perguntas em aberto
- Curador: cron automatico vs. checklist manual?

# Memory

Status: canonical
Bounded: max ~50 curated entries - distill, do not just append.
Inject at the start of every session.

## Key concepts
- Harness = profile + skills + memory + workflows.
- Context engineering > prompt engineering: what enters the
  context, and when, matters more than the instruction text.
- Tool scoping: fewer exposed tools = better performance.

## Discovered patterns
- Dual memory (Hermes): MEMORY.md (bounded, always injected)
  + session history (searchable, queried on demand).
- Session-end distillation: extract 1-3 high-quality insights
  on close - not the raw transcript.

## Open questions
- Curator: automatic cron vs. manual checklist?

2. Destilação no fim da sessão

2. Distillation at session-end

Ao encerrar, o agente roda um workflow curto (session-end) e se pergunta: o que aprendi que não sabia antes? Que padrão reutilizável emergiu? O que eu erraria de novo se não registrasse agora? Daí escreve 1 a 3 entradas de alta qualidade — nunca a transcrição inteira da conversa. O workflow não é prosa solta; é um procedimento com regras de curadoria explícitas:

On close, the agent runs a short workflow (session-end) and asks itself: what did I learn that I didn't know before? What reusable pattern emerged? What would I get wrong again if I didn't record it now? It then writes 1 to 3 high-quality entries — never the entire conversation transcript. The workflow isn't loose prose; it's a procedure with explicit curation rules:

# Harness: Session End

## 1. Distilacao para MEMORY.md
Perguntar:
- O que aprendi hoje que nao sabia ontem?
- Qual padrao reutilizavel emergiu?
- O que eu erraria de novo se nao documentar agora?

Regras de curacao:
- Maximo 1-3 entradas novas por sessao.
- Se MEMORY.md > 50 entradas: remover 1 stale antes
  de adicionar 1 nova.
- Entradas DISTILADAS (principio/padrao), nao transcricao.
- Preferir atualizar entrada existente a duplicar.

## Curadoria (a cada ~5 sessoes)
- Fundir entradas sobrepostas; remover obsoletas.
- Arquivar perguntas ja respondidas.

# Harness: Session End

## 1. Distillation into MEMORY.md
Ask:
- What did I learn today that I didn't know yesterday?
- What reusable pattern emerged?
- What would I get wrong again if I didn't document it now?

Curation rules:
- At most 1-3 new entries per session.
- If MEMORY.md > 50 entries: remove 1 stale entry before
  adding a new one.
- DISTILLED entries (principle/pattern), not transcript.
- Prefer updating an existing entry over duplicating.

## Curation (every ~5 sessions)
- Merge overlapping entries; remove stale ones.
- Archive questions already answered.

Fecha o ciclo o padrão curador: a cada ~5 sessões, audita-se o MEMORY.md — funde entradas sobrepostas, remove o que deixou de ser verdade, arquiva perguntas já respondidas. É o mesmo princípio que o Hermes aplica automaticamente com um cron semanal; aqui, vira um checklist manual. A diferença entre um harness que estagna e um que compõe valor está nesse ritual.

The curator pattern closes the loop: every ~5 sessions, you audit MEMORY.md — merge overlapping entries, drop what's no longer true, archive questions already answered. It's the same principle Hermes applies automatically with a weekly cron; here, it becomes a manual checklist. The difference between a harness that stagnates and one that compounds lives in this ritual.

Estrutura de Monorepo

Monorepo Structure

Um harness individual é um diretório com docs, agentes, skills e workflows. Múltiplos harnesses convivem num monorepo compartilhando skills comuns:

A single harness is a directory with docs, agents, skills, and workflows. Multiple harnesses coexist in a monorepo sharing common skills:

harnessStudy/
├── harness-template/       # Esqueleto reutilizável
├── harness-study/          # Meta-harness (aprender harnesses)
├── harness-builder/        # Harness que cria outros harnesses
├── cs-study-harness/       # Domínio específico (educação)
├── finance-harness/        # Outro domínio (investimentos)
└── skills/                 # Skills COMPARTILHADAS
    ├── concept-to-code/
    ├── exam-simulator/
    ├── session-planner/
    └── paper-writer/

harnessStudy/
├── harness-template/       # Reusable skeleton
├── harness-study/          # Meta-harness (learning harnesses)
├── harness-builder/        # A harness that builds other harnesses
├── cs-study-harness/       # Specific domain (education)
├── finance-harness/        # Another domain (investments)
└── skills/                 # SHARED skills
    ├── concept-to-code/
    ├── exam-simulator/
    ├── session-planner/
    └── paper-writer/

A regra que mantém isso limpo é simples: skill usada por mais de um harness vive na raiz skills/; skill exclusiva de um harness vive em <harness>/skills/. Resultado: zero duplicação, e um novo harness nasce de um cp -r harness-template/.

The rule that keeps this clean is simple: a skill used by more than one harness lives in the root skills/; a skill exclusive to one harness lives in <harness>/skills/. Result: zero duplication, and a new harness is born from a cp -r harness-template/.

Arquitetura de Privacidade: Fonte Privada, Superfície Pública

Privacy Architecture: Private Source, Public Surface

Um harness pessoal útil contém contexto real — como você aprende, no que está trabalhando. Mas você quer publicar os aprendizados. Esses dois objetivos parecem conflitar. A solução não é manter dois repositórios; é separar fonte de superfície:

A useful personal harness contains real context — how you learn, what you're working on. But you want to publish the learnings. These two goals seem to conflict. The solution isn't keeping two repositories; it's separating source from surface:

• Fonte privada: o repositório é privado. O interior pode conter contexto real — só o agente o lê.
• Superfície pública: apenas papers/ vai ao ar, e nunca expõe nome real, instituição ou empregador.
• Guarda automatizada: um passo de CI faz grep por termos proibidos em papers/ e falha o build se encontrar algum.

• Private source: the repository is private. Its interior may hold real context — only the agent reads it.
• Public surface: only papers/ ships, and it never exposes a real name, institution, or employer.
• Automated guard: a CI step runs grep for forbidden terms in papers/ and fails the build if it finds any.

Do Plano à Prática: o Harness Builder

From Plan to Practice: the Harness Builder

Criar um harness à mão significa preencher ~10 arquivos — repetitivo e sujeito a esquecimentos. O passo natural foi transformar esse processo num harness: o harness-builder, um harness cujo domínio é criar outros harnesses. É a ideia de meta-skill levada ao nível do repositório inteiro.

Building a harness by hand means filling ~10 files — repetitive and easy to get wrong. The natural step was to turn that process into a harness: the harness-builder, a harness whose domain is creating other harnesses. It's the meta-skill idea taken to the level of the whole repository.

Ele opera em duas skills encadeadas, com um ponto de controle humano no meio:

It runs as two chained skills, with a human checkpoint in the middle:

1. interview-for-harness conduz uma entrevista em quatro blocos — domínio, usuário e agente, restrições, stack e memória — e produz um sumário revisável.
2. checkpoint humano: o sumário é aprovado antes de gerar um único arquivo. Corrigir o sumário leva dois minutos; corrigir dez arquivos com a premissa errada leva trinta.
3. scaffold-harness recebe o sumário aprovado e gera a estrutura completa — docs, agente, workflows e a primeira skill — já com um MEMORY.md desde o dia zero.

1. interview-for-harness runs a four-block interview — domain, user and agent, constraints, stack and memory — and produces a reviewable summary.
2. human checkpoint: the summary is approved before a single file is generated. Fixing the summary takes two minutes; fixing ten files built on the wrong premise takes thirty.
3. scaffold-harness takes the approved summary and generates the full structure — docs, agent, workflows, and the first skill — shipping a MEMORY.md from day zero.

A entrevista é deliberadamente curta — menos de dez perguntas, agrupadas para o agente confirmar entendimento a cada bloco antes de avançar:

The interview is deliberately short — fewer than ten questions, grouped so the agent confirms understanding after each block before moving on:

# Skill: interview-for-harness

Bloco 1 - Dominio
1. Em uma frase: qual e o dominio deste harness?
2. Que problema concreto resolve? Quem sente, quando,
   com que frequencia?

Bloco 2 - Usuario e agente
3. Quem usa? (papel, contexto, expertise)
4. Qual o papel do agente? (tutor / consultor / revisor)
5. Quais 3-5 tarefas recorrentes ele deve executar bem?

Bloco 3 - Restricoes
6. O que o harness deliberadamente NAO faz?
7. Que dados sensiveis existem? Como isolar?

Bloco 4 - Stack e memoria
8. Qual LLM/plataforma?
9. O que persiste entre sessoes?

-> Saida: um Sumario de Entrevista, revisado pelo
   usuario ANTES de qualquer arquivo ser gerado.

# Skill: interview-for-harness

Block 1 - Domain
1. In one sentence: what is this harness's domain?
2. What concrete problem does it solve? Who feels it,
   when, how often?

Block 2 - User and agent
3. Who uses it? (role, context, expertise)
4. What is the agent's role? (tutor / advisor / reviewer)
5. Which 3-5 recurring tasks must it do well?

Block 3 - Constraints
6. What does the harness deliberately NOT do?
7. What sensitive data exists? How to isolate it?

Block 4 - Stack and memory
8. Which LLM/platform?
9. What persists between sessions?

-> Output: an Interview Summary, reviewed by the user
   BEFORE any file is generated.

Este próprio harness sobre investimentos — o finance-harness citado na árvore acima — nasceu dessa entrevista. O builder deixou de ser plano e virou ferramenta.

The very investments harness — the finance-harness shown in the tree above — was born from that interview. The builder stopped being a plan and became a tool.

Decisões de Design (e o porquê)

Design Decisions (and why)

Próximas Iterações

Next Iterations

O Harness Builder e a memória que se destila no fim da sessão saíram do backlog e viraram parte do repositório. O que segue em aberto:

The Harness Builder and the memory that distills at session-end have left the backlog and become part of the repository. What remains open:

• Curador automatizado: trocar o checklist manual de curadoria do MEMORY.md por um passo que rode sozinho a cada N sessões.
• Integração com skills.sh: descobrir e reutilizar skills públicas antes de criar do zero.
• Avaliação de skills: medir se o agente de fato segue cada skill — verificação, não só confiança.

• Automated curator: replace the manual MEMORY.md curation checklist with a step that runs on its own every N sessions.
• skills.sh integration: discover and reuse public skills before building from scratch.
• Skill evaluation: measure whether the agent actually follows each skill — verification, not just trust.

Referências

References

As decisões de arquitetura deste harness — especialmente memória e auto-melhoria — foram informadas pelas seguintes fontes, estudadas como referência:

This harness's architecture decisions — memory and self-improvement in particular — were informed by the following sources, studied as reference:

• Nous Research. Hermes Agent — persistent memory, skills, and self-improvement architecture. github.com/nousresearch/hermes-agent
• M. Fowler. Harness Engineering for Coding Agent Users — guides (feedforward) vs. sensors (feedback). martinfowler.com
• LangChain. The Anatomy of an Agent Harness — context rot and tool scoping. langchain.com
• Agent Harness for Large Language Model Agents: A Survey. Preprints.org, 2026. preprints.org/manuscript/202604.0428
• awesome-harness-engineering — design primitives for agent harnesses. github.com/ai-boost/awesome-harness-engineering