Skip to content

doc: refactor the AI guidelines #65269

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
joyeecheung wants to merge 2 commits into
base: main
Choose a base branch
from
+65 −64
Open

doc: refactor the AI guidelines #65269

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1f3ec25
doc: refactor the AI guidelines
joyeecheung Aug 13, 2026
4783c93
fixup! doc: refactor the AI guidelines
joyeecheung Aug 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 65 additions & 64 deletions doc/contributing/ai-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,35 +1,30 @@
# AI use policy and guidelines

* [Core principle](#core-principle)
* [When AI is used in contributions](#when-ai-is-used-in-contributions)
* [When AI is used in communications](#when-ai-is-used-in-communications)
* [Node.js AI use policy](#nodejs-ai-use-policy)
* [Practical guidelines](#practical-guidelines)
* [Naming AI tools in disclosures](#naming-ai-tools-in-disclosures)
* [When AI is used in code contributions](#when-ai-is-used-in-code-contributions)
* [When AI is used in communications](#when-ai-is-used-in-communications)

This document aligns with the [OpenJS Foundation AI Coding Assistants Policy][].

## Core principle
## Node.js AI use policy

Tools should never replace human judgment, regardless of whether they are
powered by AI.
In the Node.js project, decision making should always be based on human judgement
instead of machine automation, regardless of whether the automation
is powered by AI. Contributors must take full responsibility for their actions in
the Node.js project.

Node.js requires contributors to understand and take full responsibility for
every change they propose. The answer to "Why is X an improvement?" can
never be "I'm not sure. The AI did it."
The Node.js project does not prohibit the use of AI tools in contributions, but
when the contribution is generated with AI, the contributor must disclose the use

@legendecas legendecas Aug 13, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think in the current text does not require disclosure and we did not expect mandatory disclosure.

And I think it is worth to keep "disclosure does not serve as a disclaimer of responsibility".

@joyeecheung joyeecheung Aug 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The previous wording was:

If AI tools assisted in generating a contribution, acknowledge that honestly.

The new wording is:

when the contribution is generated with AI, the contributor must disclose the use of such tools

IMO they are equivalent only that the first version (unnecessarily) assumes dishonesty and is rather imperative.

@joyeecheung joyeecheung Aug 13, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

disclosure does not serve as a disclaimer of responsibility

hmm yeah I was thinking maybe "Contributors must take full responsibility for their actions in the Node.js project" + the detailed the guidelines below is enough to cover, repeating responsibility multiple times feels rather repetitive..

@joyeecheung joyeecheung Aug 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inserted

Disclosure about the use of AI does not serve as a disclaimer of this responsibility.

into the "must understand and explain" section, which I think is where it would've belonged in the first place.

I think the disclosure requirement was the consensus of the last PR, at least that was what If AI tools assisted in generating a contribution, acknowledge that honestly is supposed to mean. If we want to soften the wording to make disclosure non-mandatory, I think we need to look for new consensus. At least from my interpretation, when the code is generated by AI, disclosure is expected. If it's pure assistance but not generation, this is not necessary (otherwise every Google user needs to disclose the use of Gemini overview which can't be turned off..)

of such tools, and the extent to which the contributor has personally verified
the generated output. The changes submitted to the Node.js code base must still satisfy
the project's [Developer's Certificate of Origin][] and licensing requirements.

If AI tools assisted in generating a contribution, acknowledge that honestly.
Regardless of how much code is generated by AI, disclosure does not serve
as a disclaimer of responsibility.

Be aware that the mention of for-profit trademarks or commercial brands in
commit messages, which are part of the code base, can be abused for
profit-driven marketing. If the disclosure involves for-profit trademarks or
commercial brands, it's recommended to either anonymize the branding (e.g. say
`a frontier reasoning model`, `a closed-source coding agent` instead of
`<brand>`), or only mention the for-profit brand/trademark in the PR
description, but not in the commit message, unless the message would not have
made sense without mentioning the specific brand/trademark. These
recommendations only apply to for-profit tools/models, not any non-profit ones.

Pull requests that contain AI-generated code the contributor has not
Contributors who choose to submit changes generated with AI must be able to explain
the value proposition and the implementation of their contributions during the
review process. Disclosure about the use of AI does not serve as a disclaimer of this
responsibility. Pull requests with AI-generated code that the contributor has not
personally understood, tested, and verified waste collaborator time and
will be subject to closure without additional review. Contributors who
repeatedly submit such changes, show no understanding of the project or
Expand All @@ -42,53 +37,59 @@ approved in advance by the project. To request approval, either open an issue in
be done in the form of a GitHub workflow, submit a pull request to add the
workflow and use the usual pull request review process to seek consensus.

## When AI is used in contributions

Contributors may use AI tools to assist with contributions, but such tools
never replace human judgment.

When using AI as a coding assistant:

* **Understand the codebase first.** Do not skip familiarizing yourself with
the relevant subsystem. Always verify analysis generated by tools against
the actual source code with human judgement.
It's prohibited to use AI to automate fixes to issues marked as "good first issue".
These issues are meant to help new human contributors, not an AI, learn about the
code base and the contribution processes.

* **Own every line you submit.** You are responsible for all code in your
pull request, regardless of how it was created. The submitted changes
must satisfy the project's [Developer's Certificate of Origin][] and licensing
requirements. Be prepared to explain any change in detail during review.
## Practical guidelines

* **Keep the commits logical.** The [commit message guidelines][]
and [commit squashing guidelines](./pull-requests.md#commit-squashing)
must be followed regardless of what tool is used in the pull request.
### Naming AI tools in disclosures

* **Test thoroughly.** Existing tests should not be removed or modified
without human verification. It is crucial to verify, with human judgement,
the correctness of new tests against the intended behavior of the feature
being tested, independently of how the implementation happens to behave.

* **Do not disappear.** If you open a PR, follow it through. Respond to
feedback and iterate until the work lands or is explicitly closed. If you
can no longer pursue it, close the PR. Stalled PRs block progress.

* **Do not use AI to claim "good first issue" tasks.** These issues exist to
help new contributors learn the codebase and processes hands-on.

* **Keep the comments useful.** Verify with human judgement that the
comments are necessary and accurate. Remove comments that simply
restate what the code does. Add comments only where the logic is non-obvious.

## When AI is used in communications
Be aware that the mention of for-profit trademarks or commercial brands in
commit messages, which are part of the code base, can be abused for
profit-driven marketing. If the disclosure involves for-profit trademarks or
commercial brands, it's recommended to either anonymize the branding (e.g. say
`a frontier reasoning model`, `a closed-source coding agent` instead of
`<brand>`), or only mention the for-profit brand/trademark in the PR
description, but not in the commit message, unless the message would not have
made sense without mentioning the specific brand/trademark. These
recommendations only apply to for-profit tools/models, not any non-profit ones.

Node.js values concise, precise communication that respects collaborator and
contributor time.
### When AI is used in code contributions

* Contributors should treat the analysis generated by AI tools as a hypothesis
instead of a fact, and verify the output against the actual source code before
making any decisions.
* Commits must still follow the [commit message guidelines][] and
[commit squashing guidelines](./pull-requests.md#commit-squashing),
even if they are organized with the help of AI tools.
* Existing tests should not be removed or modified without human verification.
When new tests are added with the help of AI, contributors should personally
verify that the new tests are necessary and test the intended behavior
instead of merely reflecting how the implementation happens to behave.
* If the comments are generated by AI, contributors should personally verify
that the comments are accurate. The comments should not restate what the code
does but instead should provide additional context that's not obvious from the code
itself, such as the history or motivation behind the choices.
* During the review process, responses to feedback should be made by contributors
based on their own judgement and must not be automated by AI tools. Contributors
are expected to iterate in this manner until the work lands or is explicitly closed.
If they are unable to follow the review process personally, they should close
the PR so that someone else can take over the work.

### When AI is used in communications

In the Node.js project, if a contributor chooses to use AI for assistance in communications, they
should respect the time spent by other contributors reading and responding to their
communication, and avoid increasing the cognitive load of others with their own use of AI.

* **Do not paste messages generated entirely by AI** in pull requests, issues,
or the project's communication channels. Such communication may be removed in
accordance to [the Node.js moderation policy][].
* **Verify claims about the code with human judgement before using them in
communications**. Results from AI tools should only be treated as hypothesis.
Link to actual code, documentation and specifications as source of truth.
accordance with [the Node.js moderation policy][].
* When making a claim based on AI output in discussions, contributors should
personally verify the claim. Contributors are expected to provide a link
to actual code, documentation or specifications, instead of an AI summary of
them, as source of truth during discussions.
* Grammar and spell-check tools are acceptable when they improve clarity and
conciseness.

Expand Down
Loading