Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
10 changes: 10 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ works.
* [Issues](#issues)
* [Pull Requests](#pull-requests)
* [Automation and bots](#automation-and-bots)
* [AI Use Policy and Guidelines](#ai-use-policy-and-guidelines)
* [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11)

## [Code of Conduct](./doc/contributing/code-of-conduct.md)
Expand Down Expand Up @@ -60,6 +61,15 @@ by an automation that was not authorized by Node.js collaborators are
subject to immediate moderation enforcement on the automation and owner
without notice.

## [AI Use Policy and Guidelines](./doc/contributing/ai-guidelines.md)

Node.js requires contributors to understand and take full responsibility for
every change they propose. Pull requests containing AI-generated code the
contributor has not personally understood, tested, and verified will likely be closed
without review.

See [details on our AI use policy and guidelines](./doc/contributing/ai-guidelines.md).

## Developer's Certificate of Origin 1.1

```text
Expand Down
98 changes: 98 additions & 0 deletions doc/contributing/ai-guidelines.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# 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)

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

## Core principle

Tools should never replace human judgment, regardless of whether they are
powered by AI.

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."

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
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
its processes, or are dishonest about the use of automated assistance
may be blocked from further contributions.

Pull requests must not be opened by automated tooling, unless specifically
approved in advance by the project. To request approval, either open an issue in
[nodejs/admin](https://github.com/nodejs/admin/issues), or if the automation can
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.

* **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.

* **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.

* **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 expected behavior of the feature
being tested, independently of the feature's implementation.
Comment on lines +67 to +68

@joyeecheung joyeecheung Aug 6, 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.

Suggested change
the correctness of new tests against the expected behavior of the feature
being tested, independently of the feature's implementation.
the correctness of new tests against the intended behavior of the feature
being tested, independently of how the implementation happens to behave.

I was just reading a post by a maintainer of another prominent OSS project today who was frustrated by a 10K+ LOC AI-generated PR and saw some wording about this behavior that we can borrow - I also saw this behavior when reviewing #63115 which exposed internalModuleStat by mistake and then went on to make even more mistakes by ensuring the internal API is publicly usable 🤦🏻‍♀️, seems like a common issue of AI-generated big patches


* **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

Node.js values concise, precise communication that respects collaborator and
contributor time.

* **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.
* Grammar and spell-check tools are acceptable when they improve clarity and
conciseness.

[Developer's Certificate of Origin]: ../../CONTRIBUTING.md#developers-certificate-of-origin-11
[OpenJS Foundation AI Coding Assistants Policy]: https://openjsf.cdn.prismic.io/openjsf/aca4d5GXnQHGZDiZ_OpenJS_AI_Coding_Assistants_Policy.pdf
[commit message guidelines]: ./pull-requests.md#commit-message-guidelines
[the Node.js moderation policy]: https://github.com/nodejs/admin/blob/main/Moderation-Policy.md
Loading