Spec

Version 0.1 · Draft · Updated 2026-10-05 · Permanent link: /spec/0.1/ · All versions

This page defines AI Code Rating and the ACR.md file that publishes it. It is a draft. Anything here can change before version 1.0.

The Rating

A rating is three characters. Each position uses a different kind of symbol, so a rating can't be misread.

Position	Measures	Symbol	Values
1	Maintainer Expertise	Uppercase letter	`A` to `E`
2	AI Share	Digit	`0` to `4`
3	Oversight	Lowercase letter	`a` to `e`

A rating is always letters and digits only. Both letter positions are grades, with the best first: A and a. A valid rating matches the regular expression ^[A-E][0-4][a-e]$, with one more condition: if position 2 is 0, position 3 is a.

Position 1: Maintainer Expertise

Rate the people who approve changes to the project's code, not every contributor. Use the level of the least experienced person who can approve a change for merging on their own. In a solo project, that's the author. If every change needs more than one approval, use the most experienced approval each change is guaranteed to get.

If AI tools can merge changes without a person approving them, rate the person responsible for the project, and position 3 can be no better than d, because nobody reads those changes before they're merged.

Value	Name	Meaning
`A`	Expert	Deep experience in this language and domain. Would catch subtle bugs in review.
`B`	Experienced	Works professionally in this stack. Could write the whole project unaided.
`C`	Capable	Can read, debug and change all of the code. Needs help writing some parts.
`D`	Learning	Understands parts of the code. Relies on AI or others for much of it.
`E`	Non-programmer	Can't read the code in a useful way. Directs the work by describing results.

Position 2: AI Share

The share of the project's code, by lines, that was generated by AI instead of typed by a person. Count code that is in the project today, not code that was generated and later deleted.

"Code" means everything a computer reads or runs: source code, tests, styles, scripts, build and CI configuration, infrastructure as code, and database schemas and queries. Prose documentation, such as a README or a docs site, isn't code. To rate documentation, give it its own rating with scopes.

Single-word or single-line autocomplete doesn't count.
Accepted multi-line suggestions, files generated by AI and agent-written changes count, even if a person edited them afterwards.
Leave out code the project doesn't maintain, such as dependencies and vendored libraries, and files produced by non-AI tools, such as lockfiles, compiled output and code generators.
Most projects will have to estimate. Pick the band your estimate falls in, and say in the file how you estimated.
If you can't tell, for example because contributors don't say whether they used AI, estimate from what you do know. When you're unsure between two bands, pick the higher one, and say in the file what you don't know.

Value	Name	Meaning
`0`	None	No code in the project was written by AI. Every line was written by people.
`1`	A Little	1–25% of the code. AI wrote pieces such as tests, boilerplate or single functions.
`2`	Some	26–50% of the code. AI wrote whole features alongside code written by people.
`3`	Most	51–75% of the code. AI wrote most features. People wrote or rewrote the rest.
`4`	Nearly All	76–100% of the code. People mostly direct and edit what AI writes.

Position 3: Oversight

How carefully a person checked AI-written code before it was merged. When the project's practice varies, use the level that applies to most AI-written code.

Only checks done by people count. Review by AI tools, including AI code review, doesn't raise this level; mention it in the file's text instead.
This position measures reading. Testing decides only between d and e, however thorough it is. A strong automated test suite is worth describing in the file's text, because it can catch problems a quick read would miss.
A project with no AI-written code uses a, because no AI code was left unchecked; position 2 already shows that no AI was used. Tools should display it as "No AI Code" rather than "Verified".

Value	Name	Meaning
`a`	Verified	Every AI change read line by line, understood and tested, like human code. Also used when AI Share is 0.
`b`	Reviewed	Every AI change read by a person before merge. Tests where practical.
`c`	Spot-Checked	Some AI changes read. The rest checked by running the program or its tests.
`d`	Tested Only	AI changes not read, but tested before merge by running the program or its tests.
`e`	Unchecked	Merged as generated, without being read or tested.

Consistent Ratings

Some combinations claim more checking than the people approving merges could do. They aren't invalid, but tools should warn about them, and projects should check that the rating is right.

Position 1	Position 3	Why it's unlikely
`E`	`a`, `b`	At level E, the person approving merges can't read the code in a useful way, so they can't have read every AI change. If someone more experienced reviews every change, rate that person in position 1 instead.
`D`	`a`	Verified means every AI change was read and understood. At level D, the person approving merges understands only parts of the code.

Writing a Rating

In text, write a rating with the ACR prefix: ACR B2b. On its own, a three-character code is easy to miss and hard to search for, and some ratings match common terms (B2b matches "B2B"). Badges use ACR as their label for the same reason. The rating field in ACR.md holds just the three characters.

The File

Location and Name

The file is named ACR.md and sits in the root of the repository. Tools should look for that exact name first, then match it without regard to case.

Because the file lives in the repository, every branch, tag and release carries its own rating. A rating describes the code it was committed with, so an older release keeps the rating it shipped with.

Front Matter

The file starts with a YAML front matter block. Tools read this block. People read the text below it.

Field	Required	Meaning
`rating`	Yes	The three-character rating for the whole project.
`spec`	Yes	The spec version the rating follows, as a string. For this version, `"0.1"`.
`updated`	Yes	The date the rating was last checked, as YYYY-MM-DD.
`scopes`	No	A map from a path in the repository to a rating for that part. Paths end in `/` for directories.

Tools must ignore fields they don't recognize, so later versions can add fields.

Body

The body gives readers context for the rating. After a short heading with the rating, write a paragraph in plain English about how AI is used in the project, so readers get a feel for it. It doesn't need to list tools or figures.

Example

---
rating: B2b
spec: "0.1"
updated: 2026-10-05
---

# AI Code Rating

**ACR B2b** (Maintainer: Experienced · AI Share: 26–50% · Oversight: Reviewed)

This project is rated with [AI Code Rating](https://aicoderating.com/spec/0.1/), spec version 0.1.

## How AI Was Used

We use AI to write tests and some smaller features, and to draft most of
our documentation. Every AI change goes through the same pull request
review as code written by people.

Badge

Projects can show the rating in their README with a badge that links to the file:

[![ACR B2b](https://img.shields.io/badge/ACR-B2b-2140B5)](ACR.md)

Versioning

The spec uses MAJOR.MINOR versions. A minor version can add optional fields or clarify wording. A major version can change what a rating means. Version 1.0 will be the first stable version.

Every version keeps a permanent page at /spec/<version>/, and /spec/ always shows the latest. Read a rating against the version named in its file's spec field. The changelog lists every version.

Open Questions

AI used only for planning or review. A project where AI helped plan, review or document the work, but wrote no code, is rated 0 and a, the same as a project that never used AI. A fourth, optional character could tell these apart.
Measuring AI share. Most projects can only estimate it. A small tool that counts AI co-author trailers in git history would make estimates more consistent.
Who checks ratings. Ratings are self-reported. Whether and how the community should be able to dispute a rating is still open.

Licence

This spec is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You can copy, adapt and build on it, including commercially, as long as you credit AI Code Rating and link to this page.