CANDOR.md

Summary

AI-generated code is a reality of our time and it is both a blessing and a curse. The problem is not the code in itself but transparency and clarity. At least, that is the working theory of this specification. The suggestion is simple: to invite everyone to include a structured CANDOR.md file like they include other files in a repository to make the AI-usage crystal clear and, more importantly, to make it a widespread convention to do so.

This is not to discourage usage of LLM- and other code-generation in the future. On the contrary, it is an enabler. When you declare what parts of the code were, in fact, generated, a skeptic can immediately look into just those parts to satisfy their urge to re-verify and double-check. And, it lets the creator showcase their skillset with code and their skillset with planning and other soft skills simultaneously and with clarity.

The name is intentional. Candor is a noun meaning:

The quality of being open and honest; frankness.

Specification

The contents of a CANDOR.md are simple. The file is split into brief headings and lists. There are 6 (six) Levels that mark the usage. At the top, you can include a global Levels section. This is enough.

Optionally, you can mark Processes and Components, each with their individual levels. The highest level in that case must be the global level. You can also add a final Notes section with specific notes as a simple list with no hierarchy.

The specification only formally defines Levels and Processes.

Levels

noneNo AI tools were used at any point.
hintAI autocomplete or inline suggestions only. The human writes all code. AI occasionally completes a line or block.
assistHuman-led. AI is used on demand for specific tasks (generating a function, explaining code, drafting a test) but does not drive the work.
pairActive human-AI collaboration throughout. Contribution is roughly equal.
copilotAI implements while the human plans and reviews. The human defines what to build and validates the output, but the AI does most of the writing.
autoAI acts autonomously with minimal human direction. The human may steer at a high level or approve outcomes, but does not write or closely direct the code.

Processes

designArchitecture, system design, technical planning, and decision-making.
implementationWriting production code.
testingWriting tests, test plans, and quality assurance.
documentationWriting docs, comments, READMEs, and changelogs.
reviewCode review and pull request feedback.
deploymentCI/CD configuration, infrastructure, and release scripts.

Examples

Below, you will find some examples of different scenarios.

Simple

The simplest CANDOR.md will only have one tag.

# CANDOR

level: none

# CANDOR

level: auto

## Notes

- Claude Code was used to create the whole application.

With Processes

You can include a Process heading with tags for the different processes of the development flow. Note that the highest level will also be applied to the global level but this allows you to granularly define which components had what LLM-involvement. If a process is not provided, its assumed to be none implicitly.

# CANDOR

level: auto

## Process

- design: auto
- testing: copilot

With Components

You can also mention specific files, directories, components, modules (only filepaths but be as global or local as you want) with their level similar to Processes above.

# CANDOR

level: auto

## Components

- src/helpers: auto

With Notes

Optionally, you can also add a notes section to provide more context. For example, you can discuss which tools were used and how.

# CANDOR

level: assist

## Notes

- Mostly no AI involvement except some copied code from ChatGPT.

Badges

Add a badge to your README to declare your CANDOR level at a glance.

FAQ

What if I lie?

Well, that defeats the purpose entirely, doesn't it? The idea is for all of us to have a social contract that we can trust. If you see a repo with a CANDOR.md in it, you can use it as a single source of truth.

Can I build tooling to generate this automatically?

Be my guest. I envision tooling to build it automatically as well as parse it. While I will do it at some point, I appreciate any or all contributions.

Can I contribute to a translation?

Absolutely! Please. Just fork the repository and add a README_<two_letter_locale>.md e.g. README_es.md. Then, raise a PR. I'll take it from there.

I want to suggest a change to the specification?

Well, good thing it is open-source then. I see the specification evolving naturally with feedback and PRs. So, let us all discuss.

What is this logo?

䷼ Hexagram 61 or Hexagram For Inner Truth (Unicode: U+4DFC) is one of 64 hexagrams in the Yi (I) Ching to illustrate principles where each line is either Yin (broken) or Yang (solid). (source)