Directory Validate API
䷼

AI-DECLARATION.md

Resumo · Especificação · Esquema · Exemplos · Badges · FAQ · Recursos

Resumo

O código gerado por IA é uma realidade do nosso tempo e é tanto uma bênção quanto uma maldição. O problema não é o código em si, mas a transparência e a clareza. Pelo menos, essa é a teoria de trabalho desta especificação. A sugestão é simples: convidar todos a incluírem um arquivo AI-DECLARATION.md estruturado, assim como incluem outros arquivos em um repositório, para deixar claro o uso de IA e, o mais importante, para que isso se torne uma convenção amplamente adotada.

Isso não tem o objetivo de desencorajar o uso de LLMs e outras gerações de código no futuro. Pelo contrário, é um facilitador. Quando você declara quais partes do código foram, de fato, geradas, um cético pode imediatamente examinar apenas essas partes para satisfazer seu impulso de verificar e checar novamente. E, isso permite que o criador mostre suas habilidades com código, planejamento e outras habilidades interpessoais simultaneamente e com clareza.

Especificação

Um arquivo AI-DECLARATION.md usa frontmatter YAML para campos estruturados, seguido por uma seção ## Notes obrigatória no corpo do markdown para contexto humano. Os requisitos mínimos do arquivo são version, level e uma seção ## Notes.

Opcionalmente, você pode declarar processes, cada um com seu próprio nível. O level global deve ser o nível mais alto presente. Qualquer processo não listado é implicitamente considerado como none. Você também pode listar components (caminhos de arquivos ou diretórios) com níveis individuais.

A especificação define formalmente version, level, processes e components.

Níveis

Os níveis visam abranger não apenas a geração de código, mas também atividades relacionadas, como revisão de código. Eles são definidos como uma combinação dos verbos act e prompt juntamente com entidades como Human, AI e task.

Processos

Esquema

O seguinte esquema YAML define formalmente a estrutura de um arquivo AI-DECLARATION.md. Use-o para validar declarações ou construir ferramentas.

type: object
required: [version, level]
definitions:
  level:
    type: string
    enum: [none, hint, assist, pair, copilot, auto]
properties:
  version:
    type: string
    pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
  level:
    $ref: "#/definitions/level"
  processes:
    type: object
    propertyNames:
      enum: [design, implementation, testing, documentation, review, deployment]
    additionalProperties:
      $ref: "#/definitions/level"
  components:
    type: object
    additionalProperties:
      $ref: "#/definitions/level"
additionalProperties: false

Exemplos

Abaixo, você encontrará alguns exemplos de diferentes cenários.

Simples

O AI-DECLARATION.md mais simples requer version, level e uma seção ## Notes.

---
version: "0.1.1"
level: none
---

This format is based on [AI-DECLARATION.md](https://ai-declaration.md/en/0.1.1).

## Notas

- - No AI tools were used..
---
version: "0.1.1"
level: auto
---

This format is based on [AI-DECLARATION.md](https://ai-declaration.md/en/0.1.1).

## Notas

- Claude Code was used to create the whole application.

Com Processos

Use processes para declarar granularmente o envolvimento de IA por fase de desenvolvimento. O level global deve ser o nível mais alto presente. Qualquer processo não listado é implicitamente considerado como none.

---
version: "0.1.1"
level: auto
processes:
  design: auto
  testing: copilot
---

This format is based on [AI-DECLARATION.md](https://ai-declaration.md/en/0.1.1).

## Notas

- AI drove architecture decisions and test generation. All output was reviewed by a human.

Com Componentes

Use components para declarar o envolvimento de IA para arquivos ou diretórios específicos.

---
version: "0.1.1"
level: auto
components:
  src/helpers: auto
---

This format is based on [AI-DECLARATION.md](https://ai-declaration.md/en/0.1.1).

## Notas

- The helpers directory was fully generated. All other code is human-written.

Badges

Adicione uma badge ao seu README para declarar o nível do seu AI-DECLARATION de relance. Observe que isso é apenas por conveniência, pois para estar em conformidade com a especificação, você deve incluir um arquivo AI-DECLARATION.md.

FAQ

E se eu mentir?
Bem, isso anula completamente o propósito, não é? A ideia é que todos tenhamos um contrato social em que possamos confiar. Se você vir um repositório com um AI-DECLARATION.md nele, pode usá-lo como uma única fonte de verdade.
Posso construir ferramentas para gerar isso automaticamente?
Fique à vontade. Eu vislumbro ferramentas para construí-lo automaticamente, bem como para analisá-lo. Embora eu vá fazê-lo em algum momento, agradeço toda e qualquer contribuição.
Posso contribuir com uma tradução?
Com certeza! Por favor. Basta fazer um fork do repositório e adicionar um README_<locale>.md, por exemplo, README_es.md. Em seguida, abra um PR. Eu cuidarei do resto.
Posso sugerir uma mudança na especificação?
Sim, a iniciativa open-source é para isso. Eu vejo a especificação evoluindo naturalmente com feedback e PRs. Então, vamos nos falando.
Preciso incluir o arquivo se adicionei uma badge ao meu README?
Sim, a recomendação é incluir um AI-DECLARATION.md como a fonte primária de verdade. A badge no README é apenas uma forma rápida de alguém verificar que A, o AI-DECLARATION.md estaria disponível e B, o nível.
O que é este logotipo?
䷼ O Hexagrama 61 ou Hexagrama da Verdade Interior (Unicode: U+4DFC) é um dos 64 hexagramas do Yi (I) Ching para ilustrar princípios onde cada linha é Yin (quebrada) ou Yang (sólida). (source)

Recursos