AI Code Rating Draft Spec v0.1

How Was the Code Made?

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

Put the rating in an ACR.md file at the root of your repo. Readers decide what it means for them, and the rating doesn't judge whether using AI is good or bad.

AI Code Rating Example
B
Maintainer
Experienced
2
AI Share
26–50% of code
b
Oversight
Reviewed before merge
The Scale

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 least experienced person who can approve a change on their own, not every contributor. 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 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.
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.

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

            


            

                
ACR.md

                

            

        

    






    

        Examples
        
What Ratings Look Like

        
These are made-up projects that show the range of the scale.

    

    

        
        
A0a
A long-running C library maintained by its original author. No AI-written code.

        
        
A3a
An expert uses an agent to write most of a new service, reads every diff and keeps test coverage high.

        
        
B1b
A team's web app. AI suggestions are accepted in places and everything goes through normal code review.

        
        
C3c
A hobby project. AI writes the features. The author reads the tricky parts and tests the rest by hand.

        
        
E4e
A weekend app built entirely by prompting. AI's changes are committed as they come, without being read or tested.

        
    






    

        

            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, and the validator checks your file.

        

        

            

                
FieldRequiredMeaning

                
                    
ratingYesThe three-character rating, such as B2b.

                    
specYesThe spec version the rating follows. Currently 0.1.

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

                    
scopesNoSeparate ratings for parts of the repo that differ, keyed by path. Example: docs/: B4b.

                
            

        

    






    

        Rules
        
Using the Rating

    

    





    

        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 scale, this calculator and the file format. Collect feedback on the draft.

        
2. Tooling
A badge service and a GitHub Action that checks ACR.md is valid.

        
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.