AGENTS.md no DeepSeek Harness: por que o repositório separa instruções para humanos e para agentes?

Tem repositório que já parte do princípio de que boa parte de quem vai ler ele não é gente

E o DeepSeek Harness, publicado pela DeepSeek AI em deepseek-ai/deepseek-harness, deixa isso escrito na cara do leitor: o README encaminha os agentes para outro arquivo com uma linha só, "For agents, follow AGENTS.md."

Parece detalhe bobo, mas é uma decisão de arquitetura de documentação

De um lado, o texto que ensina humano a instalar e rodar

Do outro, o texto que diz para a IA como se comportar dentro daquele código

Bora entender como o projeto organiza isso, e o que dá pra roubar dessa convenção pro teu repositório 😀

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

O que é o DeepSeek Harness e o que é o AGENTS.md

O DeepSeek Harness foi anunciado pela própria DeepSeek como v0.1 em developer preview, com código aberto sob licença MIT e apoiado no meta-framework Cordis

O repositório foi publicado no GitHub em 13 de agosto de 2026

E o README não esconde o estágio da coisa, tem aviso em caixa alta avisando que "THERE WILL BE COMPATIBILITY-BREAKING CHANGES"

Ou seja: dá pra brincar, dá pra estudar, mas não é hora de casar com a API

Se você já acompanha os modelos da casa, é o mesmo time por trás da linha que a gente comentou quando falou do preço por token do DeepSeek V4 Pro, só que aqui o assunto é a ferramenta de agente, não o modelo

E o AGENTS.md, o que é?

O AGENTS.md é um formato aberto em Markdown, agnóstico de fornecedor, que fica na raiz do projeto pra dar contexto operacional a agentes de código

Ele nasceu no contexto das ferramentas da OpenAI, com comandos de build, testes, convenções e limites

É como aquele arquivo de onboarding que você mandaria pro dev novo no primeiro dia, só que o dev novo é uma IA que entra no repositório todo santo dia sem lembrar de nada

Em 9 de dezembro de 2025 o formato passou a ser governado pela Agentic AI Foundation, sob a Linux Foundation, tendo AGENTS.md (OpenAI), MCP (Anthropic) e goose (Block) como projetos âncora

E desde o lançamento, em agosto de 2025, já são mais de 60.000 projetos open source e ferramentas usando o formato

Então o DeepSeek Harness não inventou nada aqui, ele adotou uma convenção que já virou padrão da indústria

Como o projeto decide o que vai em cada arquivo

Essa é a parte mais interessante, e é onde o AGENTS.md do DeepSeek Harness deixa de ser "documentação" e vira REGRA

O arquivo define regras de colocação, isto é, onde cada tipo de conteúdo mora

Repara no último item: ordem permanente vai pra raiz, mas com link pro racional

O "o quê" fica curto e no lugar de sempre, o "por quê" fica em outro canto e não polui a regra

AGENTS.md não é só um, é vários:

O repositório mantém um AGENTS.md na raiz, e a partir dali o mesmo arquivo se repete em subárvores do projeto: packages/, examples/, docs/ e .agents/notes/

O docs/AGENTS.md é justamente um desses, o AGENTS.md que governa a pasta de documentação

A lógica é a mesma de um .gitignore por pasta, se você já mexeu com isso a analogia serve: a regra fica perto do código que ela governa

Escreva o estado atual, não o diário de bordo:

Tem uma instrução no AGENTS.md do projeto que eu achei mto massa

Ele orienta a documentar o estado atual e evitar "previously/now/no longer", PRs, commits e posições de stack na prosa durável, nomeando o mecanismo vivo

Traduzindo: nada de "antes a gente fazia assim, agora faz assado"

Porque o agente lê aquilo como contexto válido e pode agir com base num passado que não existe mais

Documentação de agente é foto do presente, não linha do tempo

Onde o harness procura instruções e skills do projeto

Beleza, mas quem lê esse arquivo na hora que o agente roda?

O DeepSeek Harness lê instruções de workspace por meio de um plugin dedicado, o @deepseek-ai/dsh-agent-instructions

E os candidatos padrão de arquivo de instrução são dois: AGENTS.md e CLAUDE.md

Ou seja, o projeto não obriga você a abandonar o arquivo que já tem

Esse papo de um projeto atender mais de um agente é bem parecido com o que rolou em quais agentes de IA o Claude-Mem cobre, a ferramenta se adapta ao arquivo que já vive no repositório

E as skills?

O provedor de skills por sistema de arquivos do dsh descobre skills de projeto em pastas específicas: .dsh/skills e .agents/skills

Então a convenção não para no Markdown

Instrução tem lugar, skill tem lugar, nota de agente tem lugar

É tudo descoberta por caminho, sem configuração espalhada

O que você precisa antes de rodar o DeepSeek Harness

A lista é curtinha:

• Node.js na faixa exigida pelo projeto: ^22.19 ou >= 24
• Se você for pelo caminho do checkout, também vai precisar de git e pnpm

E um pré-requisito que não é técnico: expectativa calibrada

O projeto está em developer preview e o README avisa em caixa alta que vai ter mudança quebrando compatibilidade

Então não monte fluxo de produção em cima disso e depois venha reclamar, tá avisado 😛

Como rodar o DeepSeek Harness na sua máquina

1. Suba pelo caminho rápido, sem clonar nada

npx @deepseek-ai/dsh web

O erro comum deste passo: rodar com uma versão de Node fora da faixa suportada

Confira antes com node -v e garanta ^22.19 ou >= 24

2. Abra a interface web local no navegador

O endereço padrão é http://127.0.0.1:3080

O erro comum deste passo: tentar abrir em outra porta que você viu num tutorial aleatório, ou fechar o terminal achando que o serviço continua vivo

O processo tem que seguir rodando pra interface responder

3. Se preferir rodar a partir de um checkout do repositório, o caminho é este

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

O erro comum deste passo: pular o pnpm run build e ir direto pro pnpm dsh web

É instalar, buildar e só então subir, nessa ordem

E vale repetir o alerta do passo anterior: em developer preview, comando e comportamento podem mudar entre versões, então confira o README oficial se algo não bater

O que essa convenção resolve no seu repositório

Agora a parte que interessa pra quem mantém projeto próprio

Público diferente pede formato diferente. O README existe pra convencer e ensinar humano: contexto, screenshot, motivação. O AGENTS.md existe pra instruir máquina: regra, caminho, limite. Misturar os dois deixa os dois piores

Regra de colocação mata documentação solta. Quando o projeto define que bug vai pra postmortem, procedimento vai pra cookbook e contrato vai pro README, ninguém fica na dúvida sobre onde escrever, e o agente também não fica na dúvida sobre onde procurar

Estado atual evita ação com base em coisa superada. Aquela instrução de não escrever "previously/now/no longer" é ouro puro pra quem já viu IA reviver um padrão que o time abandonou faz meses

AGENTS.md em subárvore aproxima a regra do código. Uma regra que só vale dentro de packages/ não precisa ocupar espaço na raiz e disputar atenção com o resto

Nada disso é fórmula mágica, é organização

Mas é organização que passou a ter um leitor a mais: o agente

Vídeo: meta harness e agentes na prática

Se você curte ver o assunto em movimento, dá o play aqui embaixo antes de abrir o repositório 😀

Conclusão

A ideia central do AGENTS.md no DeepSeek Harness é simples de enunciar e difícil de manter: o repositório é escrito pra dois públicos

O README cuida da pessoa que vai instalar e rodar

O AGENTS.md cuida do agente que vai trabalhar dentro do código, com regra de colocação, arquivo por subárvore e prosa descrevendo o estado atual

Próximo passo, se você quiser sentir na mão: sobe o projeto com npx @deepseek-ai/dsh web, abre http://127.0.0.1:3080 e depois lê o AGENTS.md da raiz e o de docs/ direto no repositório oficial

Aí você volta pro teu projeto e escreve o primeiro AGENTS.md dele, nem que seja com três regras

Três regras certas já valem mais que um README gigante que a IA lê torto…

até o próximo post! 🙂