Draft Spec v0.1 ChangelogRelated WorkGitHub

Spec

Version 0.1 · Draft · Updated 2026-10-09 · 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 person responsible for the project's code. In a solo project, that's the author. On a team, it's the people who approve changes, not every contributor: use the level of the least experienced person who can approve a change for merging without someone more experienced also approving it. More precisely, think of every combination of approvals that could get a change merged under the project's review rules. For each combination, take the most experienced person in it. Use the level of the least experienced of those people. A combination is made of different people, and includes a change's author only if the rules let authors approve their own changes. Go by the rules people actually follow: count anyone who can merge, even if they rarely do, and don't count a required approval that people skip in practice. For example:

  • If one approval is enough, that's the least experienced person who can approve a change for merging on their own.
  • If no change can merge without approval from one of the senior maintainers, that's the least experienced senior maintainer.
  • If every change needs any two approvals, that's the more experienced of the two least experienced approvers, since those two could approve a change between them.
  • If the rules differ between parts of the project, such as code owners for different directories, use the part that gives the least experienced level.
  • Anyone who can merge a change without an approval, such as an admin who can bypass review, counts as approving it on their own.

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. If AI wrote much of it, say so in the body of the file.

  • 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 A2b. 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.

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: A2b
spec: "0.1"
updated: 2026-10-05
---

# AI Code Rating

**ACR A2b** (Maintainer: Expert · 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 features, alongside code we write
ourselves. 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 A2b](https://img.shields.io/badge/ACR-A2b-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.
  • Rating parts of a repository separately. One rating covers the whole repository. A later version could let a file give parts that were built differently, such as AI-written docs or one package in a monorepo, their own ratings, for example with a scope field in the front matter that names the parts. Whether it should is still open.
  • Who checks ratings. Ratings are self-reported. Whether and how the community should be able to dispute a rating is still open.

To discuss any of these, or anything else in the spec, send a spec suggestion on GitHub.

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.