AGENTS.md: um arquivo de formato aberto que fornece orientação para inteligências programadas por IA

AGENTS.md é um formato simples e de código aberto que foi criado pela OpenAI e outros. Ele foi projetado para fornecer orientação para inteligências de programação de IA (agentes de codificação) e funciona de forma semelhante à leitura de IA especialmente projetadaREADME.mdDocumentação. Em projetos de software, aREADME.mdA documentação geralmente é escrita para desenvolvedores humanos e abrange itens como descrições de projetos, como começar e diretrizes de contribuição. Considerando queAGENTS.mdEm vez disso, ele se concentra em fornecer as instruções técnicas mais específicas que as inteligências de IA precisam para entender e participar de um projeto, como etapas detalhadas de construção, comandos de teste e especificações específicas da base de código. Ao separar essas instruções dedicadas à IA em uma seção especializada deAGENTS.mdé possível ter o arquivoREADME.mdMantenha a simplicidade e, ao mesmo tempo, forneça uma fonte clara e previsível de instruções para as inteligências de IA para ajudá-las a realizar tarefas de codificação com mais eficiência e precisão.

Lista de funções

• Forneça instruções clarasArquivo de Inteligência Artificial: Como um arquivo projetado especificamente para inteligências de IA, ele fornece um local centralizado e bem definido para todas as instruções e o contexto que a IA precisa seguir ao processar o código.
• Simplificar a documentação do projetoRemover instruções técnicas específicas de IA (por exemplo, detalhes de construção e teste) da página principalREADME.mdé separado, tornando o arquivoREADME.mdPode se concentrar mais em fornecer informações essenciais aos desenvolvedores humanos.
• Formato padronizado:: Como um formato aberto.AGENTS.mdUsando a sintaxe Markdown padrão, não há requisitos de campos obrigatórios e os desenvolvedores têm liberdade para organizar o conteúdo de acordo com as necessidades do projeto.
• Suporte a projetos complexosEm grandes repositórios monorepresentativos, é permitido ter subprojetos separados dentro do repositórioAGENTS.mdArquivos. A inteligência lerá automaticamente o que estiver mais próximo do diretório de trabalho atual, permitindo, assim, uma orientação detalhada para diferentes módulos.
• compatível com o ecossistemaEsse formato foi projetado para ser compatível com o crescente ecossistema de ferramentas de programação de IA, incluindo uma ampla gama de inteligências de programação de IA da OpenAI, Google e outros.

Usando a Ajuda

AGENTS.mdA documentação tem o objetivo de ser um "manual de instruções" para que as inteligências de programação de IA compreendam e manipulem a base de código. Ela ajuda as IAs a concluir com eficiência as tarefas, desde a configuração do ambiente até o envio do código, fornecendo instruções claras. Abaixo está uma descrição detalhada de como usá-la e como operá-la.

Etapa 1: Criar o arquivo AGENTS.md

No diretório raiz de sua base de código, crie manualmente um arquivo chamadoAGENTS.mdO arquivo. Esse arquivo é onde as inteligências de IA procuram instruções. A maioria das inteligências de programação de IA é projetada para reconhecer e ler automaticamente esse arquivo.

Etapa 2: Escreva o conteúdo principal

AGENTS.mdUsando o formato Markdown padrão, você pode criar títulos e listas da mesma forma que escreveria um documento normal. O conteúdo deve se concentrar em fornecer etapas claras e acionáveis para a IA. Aqui estão algumas sugestões para as principais seções a serem abordadas:

1. dicas de ambiente de desenvolvimento
Esta seção informa à IA como preparar um ambiente de desenvolvimento local, especialmente para projetos que usam um gerenciador de pacotes específico.

• Código de amostra (computação)::

  # AGENTS.md 示例
  ## 开发环境提示
  - 使用 `pnpm dlx turbo run where <project_name>` 命令跳转到特定包的目录，而不是用 `ls` 扫描。
  - 运行 `pnpm install --filter <project_name>` 为工作区添加依赖，确保Vite、ESLint和TypeScript能够识别它。
  - 使用 `pnpm create vite@latest <project_name> -- --template react-ts` 快速创建一个包含TypeScript配置的React + Vite新包。
  - 检查每个包内 `package.json` 文件中的 `name` 字段来确认包的正确名称，忽略顶层的 `package.json`。
  

2. instruções de teste
Esta seção instrui a IA sobre como executar testes para garantir que o código gerado atenda aos padrões de qualidade do projeto. A IA tenta executar esses comandos e corrige o código com base nos resultados dos testes.

• Código de amostra (computação)::

  ## 测试指令
  - CI计划文件位于 `.github/workflows` 文件夹中。
  - 运行 `pnpm turbo run test --filter <project_name>` 来执行该包定义的所有检查。
  - 在包的根目录中，可以直接调用 `pnpm test`。合并代码前必须通过所有测试。
  - 若要专注于某个特定的测试，可以添加Vitest匹配模式：`pnpm vitest run -t "<test name>"`。
  - 修复所有测试或类型错误，直到整个测试套件全部通过。
  - 修改文件或导入后，运行 `pnpm lint --filter <project_name>` 来确保ESLint和TypeScript规则仍然通过。
  - 即使没有被要求，也为你修改的代码添加或更新测试。
  

3. instruções de solicitação de pull (instruções de PR)
Se quiser que os envios de IA estejam em conformidade com as especificações da equipe, você pode declarar isso explicitamente aqui.

• Código de amostra (computação)::

  ## PR 指令
  - 标题格式: [<project_name>] <标题>
  - 在提交（commit）之前，务必运行 `pnpm lint` 和 `pnpm test`。
  

Etapa 3: Configurações especiais para grandes projetos

Se o seu projeto for uma única base de código (monorepo) que contém vários subprojetos ou pacotes independentes, você poderá colocar na raiz de cada subprojeto umAGENTS.mdDocumentação.

• Princípio de funcionamentoQuando uma inteligência de IA estiver trabalhando em um subdiretório, ela lerá preferencialmente o subdiretório mais próximoAGENTS.mdarquivo. Isso significa que o arquivoAGENTS.mdComandos globais podem ser fornecidos, e cada subprojetoAGENTS.mdEm seguida, podem ser fornecidas instruções mais específicas exclusivas para esse módulo.
• exemplo típicoDescrição: supõe-se que o projeto seja estruturado da seguinte forma:

  /my-monorepo
  ├── AGENTS.md         # 全局指令
  ├── /packages
  │   ├── /frontend
  │   │   ├── AGENTS.md # 前端专用指令
  │   │   └── ...
  │   └── /backend
  │       ├── AGENTS.md # 后端专用指令
  │       └── ...
  └── ...
  

  Quando a IA está em/packages/frontendele seguirá o diretórioAGENTS.mdinstruções no arquivo.

Etapa 4: Atualização contínua

AGENTS.mdEle deve ser tratado como um "documento vivo" dinâmico. Quando o processo de construção, os comandos de teste ou as especificações de codificação do seu projeto mudarem, lembre-se de sincronizar e atualizar esse documento para garantir que as inteligências de IA sempre tenham as instruções mais precisas.

cenário do aplicativo

1. Lançamento de novo projeto e colaboração de IA
   Quando um novo projeto é iniciado, é possível criar desde o início umAGENTS.mdDocumentação. O arquivo pode definir a pilha de tecnologia do projeto, os comandos de criação de ambiente, o estilo de código e o processo de teste. Dessa forma, as inteligências de programação de IA subsequentes envolvidas no projeto podem "ler e entender" imediatamente as especificações do projeto e começar a concluir diretamente a tarefa de codificação, o que garante a padronização e a consistência da base de código inicial.
2. Manutenção de uma grande base de código única (Monorepo)
   Em grandes bases de código que contêm vários aplicativos de front-end, serviços de back-end e bibliotecas compartilhadas, diferentes módulos geralmente têm diferentes comandos de compilação e teste. Ao colocar umAGENTS.mdque pode fornecer à inteligência de IA uma orientação contextual precisa sobre quais comandos específicos ela deve executar ao modificar um determinado módulo, evitando confusão e erros.
3. Refatoração e migração automatizadas de código
   Quando for necessária uma refatoração de código em grande escala, como a atualização de uma versão da estrutura ou a substituição de bibliotecas obsoletas, as etapas e regras detalhadas a serem observadas podem ser gravadas noAGENTS.mdAs inteligências de IA podem modificar sistematicamente toda a base de código com base nesse "manual de ação" e executar comandos de teste especificados para verificar a exatidão de cada etapa, o que melhora muito a eficiência da refatoração.

QA

1. AGENTS.md Há campos obrigatórios no documento?
   Não.AGENTS.md O formato Markdown padrão é usado e é muito flexível. Você pode usar os cabeçalhos e o conteúdo que achar adequado, e a inteligência de IA analisará o texto que você fornecer e seguirá as instruções nele contidas.
2. Se o prompt de bate-papo do usuário não for o mesmo que o AGENTS.md O que acontece quando as instruções no
   O prompt de bate-papo explícito do usuário (prompt) tem a prioridade mais alta e substituirá todas as instruções no arquivo. Na ausência de instruções diretas do usuário, a IA segue oAGENTS.mdregras. Para arquivos aninhados, o mais próximo do arquivo atualmente editadoAGENTS.mdAs instruções do testamento entram em vigor.
3. A inteligência de IA executará automaticamente AGENTS.md Você deseja testar os comandos listados na seção
   Sim, se você listar os comandos de teste no arquivo, as inteligências de IA tentarão executar as verificações de procedimento relevantes (por exemplo, testes de unidade, verificação de tipo etc.) antes de concluir a tarefa e corrigir o código com base nos resultados dos testes que falharam.
4. AGENTS.md Um arquivo pode ser modificado depois de ser criado?
   Com certeza. Você deve colocarAGENTS.mdPense nele como um "documento vivo" que é atualizado dinamicamente. À medida que o projeto evolui, o documento é atualizado para garantir que reflita com precisão o status e as especificações atuais do projeto.