FAQ

Answers to the questions people ask most about AI Code Rating. The spec is the final word wherever the two differ.

About the Rating

What Is AI Code Rating?

A three-character rating, such as B2b, that a project publishes in an ACR.md file at the root of its repository. It tells readers who maintains the project (Maintainer Expertise), how much of the code AI wrote (AI Share), and how carefully a person checked that AI-written code (Oversight).

Does a Higher AI Share Mean a Worse Project?

No. AI Share describes how the code was made, not how good it is. An A3a project, where an expert wrote most of the code with AI and checked every change, can be stronger than a C1e project with little AI code that nobody checked. Maintainer Expertise and Oversight are the positions that tell readers how much to trust the code.

Why Rate the Maintainers at All?

Because the same AI-written code means different things in different hands. When an expert directs AI and reviews its work, they can catch subtle mistakes. When nobody on the project can read the code, nobody can. Readers need to know which situation they're in, and AI Share and Oversight alone can't tell them: Oversight says whether AI code was checked, and Maintainer Expertise says how well the people checking it could judge it.

A few things it isn't:

• It's not a rating of every contributor. It describes the people who approve and merge code, because they decide what ships.
• It's not a judgement of anyone's worth. It's about experience with this project's language and domain. An expert in one field can honestly be a C in another.
• It's not a ranking of projects. An E project can be useful, popular and well loved. The rating tells people what they're getting, so they can decide how to use it.

The level is self-assessed against two practical questions: could the people who merge code have written it without AI, and can they explain every line?

How Is This Different From Other AI Disclosure Standards?

Most of them describe AI involvement with a single level. AI Code Rating keeps three things apart: who checks the code, how much of it was written by AI, and how carefully it was checked. The Related Work page compares it with AI-DECLARATION.md, Quillx and others.

Why Should I Publish a Rating?

People who use or contribute to your project increasingly want to know how AI was involved, and right now they have to guess. A rating answers the question up front, in a format they can compare across projects. It also shows that you're comfortable being open about how you work.

Can't People Just Give Themselves a Good Rating?

Yes. Ratings are self-reported, and nothing stops a project from inflating one. But an inflated rating is easy to contradict: a project's commit history, pull requests and issue tracker show how it really works, and a rating that doesn't match them costs the project trust. An honest D4c tells readers more than a doubtful B4b. How the community could dispute a rating is an open question in the spec.

Choosing Your Rating

Does Using AI for Planning, Research or Code Review Count?

Not toward AI Share. AI Share counts only code that AI wrote and that is in the project today. A project where AI helped plan or review the work, but wrote none of the code, is 0 with Oversight a. Mention that kind of use in the text of your ACR.md. Whether the rating itself should show it is an open question in the spec.

What Counts as Code?

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, doesn't count. If AI wrote much of your documentation, give it its own rating with scopes.

What About Autocomplete?

Single-word or single-line completions don't count. Multi-line suggestions you accepted do, even if you edited them afterwards.

What About Dependencies, Vendored Code and Generated Files?

Leave out code your project doesn't maintain, such as dependencies and vendored libraries. Also leave out files produced by non-AI tools, such as lockfiles, compiled output and code from code generators. Files that AI generated do count.

How Do I Estimate AI Share?

Most projects can only estimate it, which is why the bands are a quarter wide. Some ways to get a number:

• Count commits with AI co-author trailers, such as Co-Authored-By: Claude, against all commits, or better, the lines those commits changed.
• Go through the main parts of the project and estimate each one, then combine them by size.
• If you use an AI agent for whole features, list those features and compare them with the rest.

Pick the band your estimate falls in and say in the file how you estimated.

Our Maintainers Have Different Levels of Experience. Which Do We Use?

Use the level of the least experienced person who can approve a change for merging on their own, because that person's judgement can be the last check on what ships. If every change needs more than one approval, use the most experienced approval each change is guaranteed to get. For example, if every change needs sign-off from a senior maintainer, rate that maintainer.

What If AI Tools Merge Changes Without a Person Approving Them?

Rate the person responsible for the project in position 1. Position 3 can be no better than d (Tested Only), because nobody reads those changes before they're merged. Say in the file which changes AI can merge on its own.

We Have Thorough Tests but Don't Read AI Changes. Which Level?

d (Tested Only). Oversight measures whether people read AI-written code, so testing alone can't go higher, however thorough it is. Describe your test suite in the file: readers will want to know about it, and good tests can catch problems that a quick read would miss.

Does AI Code Review Count as Oversight?

No. Oversight measures checking done by people. AI review can still catch real problems, so say in the file if you use it, but it doesn't raise the Oversight level.

Parts of the Project Were Built Differently. What Then?

Use scopes to rate those parts separately, keyed by path, for example docs/: B4b. The top-level rating still covers the project as a whole.

Our Practice Changed Over Time. Which Period Do We Rate?

Rate the code as it is today. If older code was written by hand and recent code mostly by AI, AI Share reflects the mix that's in the project now. Say in the file when and how your practice changed.

What If I Don't Know Whether Contributors Used AI?

Estimate from what you do know. When you're unsure between two AI Share bands, pick the higher one, and say in the file what you don't know. Many projects now ask contributors to disclose AI use in their pull request template, which makes the next rating easier.

How Often Should I Update the Rating?

Whenever the way you work changes, and at least once for each major release. Change the updated date whenever you check the rating, even if the rating stays the same, so readers know it's current.

What About Forks and Monorepos?

A fork rates the code as its own maintainers maintain it. If the fork is mostly unchanged upstream code, say so in the file and link to the upstream project's rating. A monorepo can publish one rating at its root and use scopes to rate each package.

The File

Why a Separate ACR.md and Not AGENTS.md or CLAUDE.md?

Those files give instructions to AI tools. ACR.md tells people how AI was used. Keeping them separate means each file has one audience, and tools can find the rating without reading instructions meant for an AI.

How Should I Write a Rating in Text?

With the ACR prefix, as in "ACR B2b". On their own, three-character codes are hard to search for, and some match common terms, such as B2b and "B2B". The prefix makes a rating easy to recognize and find. In the rating field of ACR.md, write just the three characters.

Where Does the File Go?

In the root of the repository, named exactly ACR.md.

Why Are Ratings Only Letters and Digits?

So a rating works anywhere without escaping: in URLs, badge services, file names, commit messages and search.

How Can I Check My File?

Paste it into the validator. It checks the front matter against the spec and explains anything that's wrong.

What Happens to My Rating When the Spec Changes?

Nothing, until you change it. Your file names the spec version it follows, and every version keeps a permanent page, so readers can always look up what your rating meant. The changelog lists what changed in each version.

The Project

Who Runs AI Code Rating?

It was started by Greg Chetcuti as a proposal. The spec is a draft, and a process for proposing changes is being set up.

Can I Use the Spec in My Own Work?

Yes. The spec is licensed under 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 the spec. The website's code is under the MIT licence.