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..0981c37705af63 --- /dev/null +++ b/doc/contributing/ai-guidelines.md @@ -0,0 +1,61 @@ +# 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. 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 + 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. 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 + 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