2026-05-23站内改写

AI-DECLARATION.md: An Open Standard for Declaring AI Usage in Code

AI-DECLARATION.md is an open specification that enhances transparency by declaring the degree of AI involvement in software projects. It defines six levels from no AI to fully autonomous, with optional granularity for processes like design, implementation, and testing. The standard aims to establish a trustworthy social contract in the developer community.

Article intelligence

EngineersIntermediate

Key points

AI-DECLARATION.md provides a structured way to transparently declare AI usage in projects
Levels range from none to auto, with options to specify per process
Supports declaration per file or directory component
Community contributions for translations and specification improvements are welcome

Why it matters

This matters because AI-DECLARATION.md provides a structured way to transparently declare AI usage in projects.

Technical impact

May affect model selection, inference cost, product capability, and evaluation benchmarks.

Uh oh!

There was an error while loading. Please reload this page.

Notifications You must be signed in to change notification settings

Fork 3

Star 31

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

36 Commits

.github

.well-known

site

templates

.gitignore

AI-DECLARATION.md

CHANGELOG.md

LICENSE

NGINX

README.md

README_ko.md

package.json

Repository files navigation

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

About

An open standard for declaring AI usage in software projects.

ai-declaration.md

Topics

specification

candor

ai-governance

llms

ai-transparency

ai-declaration

Resources

Readme

License

MIT license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Custom properties

Stars

31 stars

Watchers

1 watching

Forks

3 forks

Report repository

Releases 3

v0.1.2

Latest

Apr 14, 2026

+ 2 releases

Sponsor this project

Uh oh!

There was an error while loading. Please reload this page.

buymeacoffee.com/deepansh

Learn more about GitHub Sponsors

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

HTML 73.4%

TypeScript 15.9%

CSS 10.7%