From 8fa167de54317c5565568e1890fe15d47cd3ae81 Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Wed, 4 Mar 2026 18:23:19 -0300 Subject: [PATCH 1/2] doc: create ai-guidelines and include to CONTRIBUTING Co-Authored-By: Beth Griggs --- CONTRIBUTING.md | 10 ++++++ doc/contributing/ai-guidelines.md | 57 +++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+) create mode 100644 doc/contributing/ai-guidelines.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ae787bc6d8e84f..18da5f6b8ed26b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,6 +19,7 @@ works. * [Code of Conduct](#code-of-conduct) * [Issues](#issues) * [Pull Requests](#pull-requests) +* [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) @@ -47,6 +48,15 @@ dependencies, and tools contained in the `nodejs/node` repository. * [Reviewing Pull Requests](./doc/contributing/pull-requests.md#reviewing-pull-requests) * [Notes](./doc/contributing/pull-requests.md#notes) +## [AI Use Policy and Guidelines](./doc/contributing/ai-guidelines.md) + +Node.js expects contributors to understand and take full responsibility for +every change they propose. Pull requests consisting of AI-generated code the +contributor has not personally understood, tested, and verified will 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 diff --git a/doc/contributing/ai-guidelines.md b/doc/contributing/ai-guidelines.md new file mode 100644 index 00000000000000..c3a8d950051b3f --- /dev/null +++ b/doc/contributing/ai-guidelines.md @@ -0,0 +1,57 @@ +# AI use policy and guidelines + +* [Core principle](#core-principle) +* [Using AI for code contributions](#using-ai-for-code-contributions) +* [Using AI for communication](#using-ai-for-communication) + +## Core principle + +Node.js expects contributors to understand and take full responsibility for +every change they propose. The answer to "Why is X an improvement?" should +never be "I'm not sure. The AI did it." + +Pull requests that consist of AI-generated code the contributor has not +personally understood, tested, and verified waste collaborator time and +will be closed without review. + +## Using AI for code contributions + +AI tools may assist contributors, but must not replace contributor judgment. +When using AI as a coding assistant: + +* **Understand the codebase first.** Do not skip familiarizing yourself with + the relevant subsystem. LLMs frequently produce inaccurate descriptions of + Node.js internals — always verify against the actual source. + +* **Own every line you submit.** You are responsible for all code in your + pull request, regardless of how it was generated. Be prepared to explain + any change in detail during review. + +* **Keep logical commits.** Structure commits coherently even when an LLM + generates multiple changes at once. Follow the existing + [commit message guidelines][]. + +* **Test thoroughly.** AI-generated code must pass the full test suite and + any manually written tests relevant to the change. Do not rely on the LLM + to assess correctness. + +* **Edit generated comments critically.** LLM-produced comments are often + verbose or inaccurate. Remove comments that simply restate what the code + does; add comments only where the logic is non-obvious. + +## Using AI for communication + +Node.js values concise, precise communication that respects collaborator time. + +* **Do not post AI-generated messages** in pull requests, issues, or the + project's communication channels. +* **Verify accuracy** of any LLM-generated content before including it in a + PR description or comment. +* **Complete pull request templates fully** rather than replacing them with + LLM-generated summaries. +* **Link to primary sources** — code, documentation, specifications — rather + than quoting LLM answers. +* Grammar and spell-check tools are acceptable when they improve clarity and + conciseness. + +[commit message guidelines]: ./pull-requests.md#commit-message-guidelines From cee1884366139a637ff5c4bffa746bef56a108c1 Mon Sep 17 00:00:00 2001 From: Rafael Gonzaga Date: Thu, 5 Mar 2026 11:03:50 -0300 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Aditi <62544124+Aditi-1400@users.noreply.github.com> Co-authored-by: Joyee Cheung --- doc/contributing/ai-guidelines.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/contributing/ai-guidelines.md b/doc/contributing/ai-guidelines.md index c3a8d950051b3f..0981c37705af63 100644 --- a/doc/contributing/ai-guidelines.md +++ b/doc/contributing/ai-guidelines.md @@ -21,7 +21,10 @@ When using AI as a coding assistant: * **Understand the codebase first.** Do not skip familiarizing yourself with the relevant subsystem. LLMs frequently produce inaccurate descriptions of - Node.js internals — always verify against the actual source. + Node.js internals — always verify against the actual source. When using an AI + tool, ask it to cite the exact source files/PRs/docs it’s relying on, and then + match the claim against that resource to verify if it holds up in the current + code. * **Own every line you submit.** You are responsible for all code in your pull request, regardless of how it was generated. Be prepared to explain @@ -32,7 +35,8 @@ When using AI as a coding assistant: [commit message guidelines][]. * **Test thoroughly.** AI-generated code must pass the full test suite and - any manually written tests relevant to the change. Do not rely on the LLM + any manually written tests relevant to the change. Existing Tests should not + be removed or modified without human verification. Do not rely on the LLM to assess correctness. * **Edit generated comments critically.** LLM-produced comments are often