AI-DECLARATION.md

Summary

AI-generated code is a reality of our time and it is both a blessing and a curse. The problem is not the code in itself but transparency and clarity. At least, that is the working theory of this specification. The suggestion is simple: to invite everyone to include a structured AI-DECLARATION.md file like they include other files in a repository to make the AI-usage crystal clear and, more importantly, to make it a widespread convention to do so.

This is not to discourage usage of LLM- and other code-generation in the future. On the contrary, it is an enabler. When you declare what parts of the code were, in fact, generated, a skeptic can immediately look into just those parts to satisfy their urge to re-verify and double-check. And, it lets the creator showcase their skillset with code and their skillset with planning and other soft skills simultaneously and with clarity.

Specification

An AI-DECLARATION.md file uses YAML frontmatter for structured fields, followed by a required ## Notes section in the markdown body for human context. At minimum, it requires version, level, and a ## Notes section.

Optionally, you can declare processes, each with their own level. The global level must be the highest level present. Any process not listed is assumed to be none implicitly. You can also list components (file paths or directories) with individual levels.

The specification formally defines version, level, processes, and components.

Levels

The levels aim to encompass not just code generation but related activities like code review. They are defined as a combination of the verbs act and prompt along with entities such as Human, AI and task.

• none: Human acts on the task alone with no AI involvement.
• hint: Human acts on the task and the AI surfaces suggestions passively.
• assist: Human prompts and the AI acts on a part of the task.
• pair: Human prompts as both human and AI both act on the task equally; Human understands internals clearly.
• copilot: Human prompts and AI acts on the whole task, prompting the Human for permission or clarification.
• auto: Human prompts and AI acts autonomously bringing the task to completion.

Processes

• design: Architecture, system design, and decision-making.
• implementation: Writing production code.
• testing: Writing tests, test plans, and quality assurance.
• documentation: Writing docs, comments, READMEs, and changelogs.
• review: Code review and pull request feedback.
• deployment: CI/CD configuration, infrastructure, and release scripts.

Schema

The following YAML schema formally defines the structure of an AI-DECLARATION.md file. Use this to validate declarations or build tooling.

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

Examples

Below, you will find some examples of different scenarios.

Simple

The simplest AI-DECLARATION.md requires version, level, and a ## Notes section.

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

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

## Notes

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

## Notes

- Claude Code was used to create the whole application.

With Processes

Use processes to granularly declare AI involvement per development phase. The global level must be the highest level present. Any process not listed is assumed to be none implicitly.

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

## Notes

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

With Components

Use components to declare AI involvement for specific files or directories.

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

## Notes

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

Badges

Add a badge to your README to declare your AI-DECLARATION level at a glance. Please note, this is just for convenience and to comply with the specification, you must include an AI-DECLARATION.md file.

• 
• 
• 
• 
• 
• 

FAQ

What if I lie?

Well, that defeats the purpose entirely, doesn't it? The idea is for all of us to have a social contract that we can trust. If you see a repo with an AI-DECLARATION.md in it, you can use it as a single source of truth.

Can I build tooling to generate this automatically?

Be my guest. I envision tooling to build it automatically as well as parse it. While I will do it at some point, I appreciate any or all contributions.

Can I contribute a translation?

Absolutely! Please. Just fork the repository and add a README_<locale>.md e.g. README_es.md. Then, raise a PR. I'll take it from there.

I want to suggest a change to the specification?

Well, good thing it is open-source then. I see the specification evolving naturally with feedback and PRs. So, let us all discuss.

Do I need to include the file if I added a badge to my README?

Yes, the recommendation is to include an AI-DECLARATION.md as the primary source of truth. The badge in the README is just a glanceable way for someone to check that A, the AI-DECLARATION.md would be available and B, the level.

What is the logo?

䷼ Hexagram 61 or Hexagram For Inner Truth (Unicode: U+4DFC) is one of 64 hexagrams in the Yi (I) Ching to illustrate principles where each line is either Yin (broken) or Yang (solid). (source)