Draft Spec v0.1 ChangelogRelated WorkGitHub
AI Code Rating

Who Wrote the Code?

Three simple characters that tell a reader who maintains a project, how much of its code is written by AI, and how closely a human checks the AI's work.

To rate a project, generate your ACR.md file using the form below and save it in the root of your repo. Readers decide what a rating means, and it doesn't judge whether using AI is good or bad.

AI Code Rating Example
A
Maintainer
Expert
2
AI Share
26–50% of code
b
Oversight
Reviewed before merge
The Levels

Reading a Rating

Each position uses a different kind of symbol, so a rating can't be misread: an uppercase letter, then a digit, then a lowercase letter. Most other AI disclosure standards use a single level; keeping these three questions apart is what makes AI Code Rating different. See how it compares.

1

Maintainer Expertise

Rate the person responsible for the code. In a solo project, that's you. On a team, it's the least experienced person who can approve a change without someone more experienced also approving it. Ask: could they have written this without AI, and can they explain every line?

  • AExpert Deep experience in this language and domain. Would catch subtle bugs in review.
  • BExperienced Works professionally in this stack. Could write the whole project unaided.
  • CCapable Can read, debug, and change all of the code. Needs help writing some parts.
  • DLearning Understands parts of the code. Relies on AI or others for much of it.
  • ENon-programmer Can't read the code in a useful way. Directs the work by describing results.
2

AI Share

How much of the code, by lines, was generated by AI instead of typed by a person. Single-word or single-line autocomplete doesn't count. Accepted multi-line suggestions do.

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

Oversight

How carefully a person checked AI-written code before it was merged. AI review doesn't count. Projects with no AI code use a, since nothing was left unchecked.

  • aVerified Every AI change read line by line, understood, and tested, like human code. Also used when AI Share is 0.
  • bReviewed Every AI change read by a person before merge. Tests where practical.
  • cSpot-Checked Some AI changes read. The rest checked by running the program or its tests.
  • dTested Only AI changes not read, but tested before merge by running the program or its tests.
  • eUnchecked Merged as generated, without being read or tested.
Adopters

Rated Projects

Real projects that publish a rating in ACR.md. For common setups across the whole range and the reasoning behind each rating, see the rating examples.

B4b

aicoderating.com

This site. Claude Code writes nearly all of the code, directed by its author.

B0a

DomainMOD

An app for managing domains and SSL certificates, maintained by hand since 2010.

B4c

Email Health Check

A self-hosted checker that emails back a report on a domain's PTR, SPF, DKIM, and DMARC setup.

B0a

HomelabAPI

A self-hosted API that gathers a homelab's notifications and other outputs in one place.

Your Project

Rate your project, add ACR.md to its repo, then ask to be listed.

Rate Your Project

Get Your Rating

Answer for the project as it stands today. The form starts with an example. Change any answer and the rating, badge, and file update.

1How experienced is the person responsible for the code?

In a solo project, that's you. On a team, it's the least experienced person who can approve a change without someone more experienced also approving it.

2How much of the code did AI write?
3How was AI-written code checked?
Your Rating
Maintainer
AI Share
Oversight
README Badge

            


            

                
ACR.md

                

            

            
Save it as ACR.md in the root of your repo and check it with the validator. To check it on every push, add the GitHub Action.

        

    






    

        

            The File
            
ACR.md

            
Put the file in the repo root. The front matter at the top is for tools like badge services, linters, and code hosts to read. Below it, a short paragraph in plain English gives people a little context on how AI is used in the project.

            
The name is deliberately different from AGENTS.md and CLAUDE.md. Those files give instructions to AI tools. This one tells people how AI was used. The full spec has the details, the validator checks your file, and the GitHub Action checks it on every push.

        

        

            

                
FieldRequiredMeaning

                
                    
ratingYesThe three-character rating, such as A2b.

                    
specYesThe spec version the rating follows. Currently 0.1.

                    
updatedYesThe date the rating was last checked, as YYYY-MM-DD.

                
            

        

    






    

        Rules
        
Using the Rating

    

    
    
        
  • Rate Accurately, Even When the Result Looks Worse
    A rating is only useful if readers trust it. An honest D4c tells people more than an inflated A4b.
    • 
        
  • AI Share Is Not a Score
    An A3a project can be stronger than a C1e one. The other two positions tell readers how much to trust the code.
    • 
        
  • Rate the People Responsible for the Code
    Contributors come and go. Whoever approves changes before they're merged is responsible for what ships, so position 1 describes them. In a solo project, that's you.
    • 
        
  • Keep It Current
    Projects change. Check the rating when the way you work changes, and update the updated date when you do.
    • 
        
  • Rate the Whole Project
    One rating covers the whole repository. If a part was built differently, such as one package in a monorepo, say so in the text of the file.
    • 
        
  • Explain in Your Own Words
    Use the text of the file to add what three characters can't, such as which parts AI wrote and how you test.
    • 
    






    

        Roadmap
        
From a File to a Standard

        
GitHub started recognizing files like SECURITY.md and FUNDING.yml after many projects already used them. This plan follows the same path.

    

    

        
1. Spec and Site
Publish the spec, the rating form, and the file format. Collect feedback on the draft.

        
2. Tooling
A GitHub Action that checks ACR.md on every push, and badges for Markdown, HTML, and reStructuredText READMEs.

        
3. Adoption
Get well-known projects to publish ratings, and list them here.

        
4. Platform Support
Propose that GitHub and other code hosts show the rating on the repo page.