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.

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)
├── 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)
├── 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.

Decisões de Design (e o porquê)

Design Decisions (and why)

Próximas Iterações

Next Iterations

• Harness Builder: um harness que cria outros harnesses a partir de uma conversa.
• Integração com skills.sh: descobrir e reutilizar skills públicas quando necessário.
• Auto-melhoria: scripts que refinam o harness com base no uso real.

• Harness Builder: a harness that creates other harnesses from conversation.
• skills.sh integration: discover and reuse public skills when needed.
• Self-improvement: scripts that refine the harness based on actual usage.