From 00493b9676b757b41eaa6c4ddfd6e8b854c4a8ca Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Feb 2026 14:14:45 +0000 Subject: [PATCH 1/6] Add AI usage guidelines to developer documentation - Add doc/dev/ai-usage-guidelines.md with guidelines for AI-assisted development - Add AGENTS.md pointing to the documentation - Add CLAUDE.md as symlink to AGENTS.md - Add new document to documentation table of contents manager: @mmore500 https://claude.ai/code/session_01CAnhr6MGdgQghH43KZYLpE --- AGENTS.md | 5 +++++ CLAUDE.md | 1 + doc/dev/ai-usage-guidelines.md | 15 +++++++++++++++ doc/index.md | 1 + 4 files changed, 22 insertions(+) create mode 100644 AGENTS.md create mode 120000 CLAUDE.md create mode 100644 doc/dev/ai-usage-guidelines.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..788ab8c10a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,5 @@ +# AI Agent Guidelines + +AI agents contributing to this repository must read and follow the guidelines in the developer documentation: + +[Guidelines for AI-Assisted Development](doc/dev/ai-usage-guidelines.md) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/doc/dev/ai-usage-guidelines.md b/doc/dev/ai-usage-guidelines.md new file mode 100644 index 0000000000..e94034b173 --- /dev/null +++ b/doc/dev/ai-usage-guidelines.md @@ -0,0 +1,15 @@ +# Guidelines for AI-Assisted Development + +## Guiding Principle + +**A human must ultimately take responsibility for all aspects of library code.** + +All code contributed to Empirical, regardless of how it was generated, must meet the same standards of quality, correctness, and maintainability. + +1. **Human Manager Responsibility:** The human manager is responsible for reviewing and fully understanding all contributed code. + +2. **Commit Attribution:** Commits may be attributed to the AI tool used, but all commit messages should include the `@username` of the human manager. + +3. **Pull Request Review Process:** Pull requests should go through the usual peer review process, with the human manager completing a pull request code review process first before requesting peer review. + +4. **Effort Balance:** The effort contributed by the human manager should exceed the effort requested from peer reviewers. diff --git a/doc/index.md b/doc/index.md index c9c98d30ac..1645c3fe2c 100644 --- a/doc/index.md +++ b/doc/index.md @@ -55,6 +55,7 @@ bibliography dev/empirical-development-practices dev/getting-started dev/contribution-guidelines-and-review +dev/ai-usage-guidelines dev/adding-documentation dev/guide-to-testing ``` From 3881f671aa5245ff5bb2e72da10d00b08e218873 Mon Sep 17 00:00:00 2001 From: Matthew Andres Moreno Date: Wed, 4 Feb 2026 09:26:02 -0500 Subject: [PATCH 2/6] Line edit --- doc/dev/ai-usage-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/dev/ai-usage-guidelines.md b/doc/dev/ai-usage-guidelines.md index e94034b173..bbb590e83a 100644 --- a/doc/dev/ai-usage-guidelines.md +++ b/doc/dev/ai-usage-guidelines.md @@ -2,7 +2,7 @@ ## Guiding Principle -**A human must ultimately take responsibility for all aspects of library code.** +A human must ultimately take responsibility for all aspects of library code. All code contributed to Empirical, regardless of how it was generated, must meet the same standards of quality, correctness, and maintainability. From 5daee6707faca2d6d0b2e7b289787e43d12e3b5f Mon Sep 17 00:00:00 2001 From: Matthew Andres Moreno Date: Wed, 4 Feb 2026 09:26:19 -0500 Subject: [PATCH 3/6] Add AI usage guidelines to developer documentation - Add doc/dev/ai-usage-guidelines.md with guidelines for AI-assisted development - Add AGENTS.md pointing to the documentation - Add CLAUDE.md as symlink to AGENTS.md - Add new document to documentation table of contents manager: @mmore500 https://claude.ai/code/session_01CAnhr6MGdgQghH43KZYLpE --- doc/dev/ai-usage-guidelines.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/doc/dev/ai-usage-guidelines.md b/doc/dev/ai-usage-guidelines.md index bbb590e83a..f9f946c868 100644 --- a/doc/dev/ai-usage-guidelines.md +++ b/doc/dev/ai-usage-guidelines.md @@ -4,12 +4,20 @@ A human must ultimately take responsibility for all aspects of library code. -All code contributed to Empirical, regardless of how it was generated, must meet the same standards of quality, correctness, and maintainability. +## Rules 1. **Human Manager Responsibility:** The human manager is responsible for reviewing and fully understanding all contributed code. -2. **Commit Attribution:** Commits may be attributed to the AI tool used, but all commit messages should include the `@username` of the human manager. +2. **Commit Attribution:** Commits may be attributed to an agentic AI tool, but all commit messages should include the `@username` of the human manager who is ultimately responsible for them. For small features, consider squash merges to condense work into a single joint-authored commit to indicate the human associated with any AI contributions. -3. **Pull Request Review Process:** Pull requests should go through the usual peer review process, with the human manager completing a pull request code review process first before requesting peer review. +3. **Pull Request Review Process:** Pull requests involving LLM-assisted code generation or attributed to an agentic AI tool should go through the usual peer review process, with the human manager responsible for the PR completing a pull request code review process first before requesting peer review. -4. **Effort Balance:** The effort contributed by the human manager should exceed the effort requested from peer reviewers. +4. **Effort Balance:** The effort contributed by the human manager responsible for LLM-generated code and commits should exceed the effort requested from peer reviewers. + +5. **Limits on extent of Agentic AI use:** Agentic AI may be used to perform simple maintenance tasks (e.g., figuring out we need to update a version number) but not to generate new core-library source code. + +6. **Energy Safeguards for Agentic AI use:** Agentic AI should not be run automatically and there should be restrictions added to ensure it stops promptly if it is not able to solve a problem. + +7. **Research privacy:** Code that has not yet been made public should not be run through an external AI that may add the code to its database. + +8. **In-code citations:** Any code that was added via an AI should be clearly marked and ideally include a link to the chat session that generated it. From 51d9039c4fb50fd31f4c9333632d21bd3444cf06 Mon Sep 17 00:00:00 2001 From: Matthew Andres Moreno Date: Sat, 7 Mar 2026 13:54:48 -0500 Subject: [PATCH 4/6] Apply suggestion from @mmore500 --- doc/dev/ai-usage-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/dev/ai-usage-guidelines.md b/doc/dev/ai-usage-guidelines.md index f9f946c868..401c78a1eb 100644 --- a/doc/dev/ai-usage-guidelines.md +++ b/doc/dev/ai-usage-guidelines.md @@ -4,7 +4,7 @@ A human must ultimately take responsibility for all aspects of library code. -## Rules +## Project Policies 1. **Human Manager Responsibility:** The human manager is responsible for reviewing and fully understanding all contributed code. From 842f76866dee0e3e2b5bc11e407e5bf13d4f1aa7 Mon Sep 17 00:00:00 2001 From: Matthew Andres Moreno Date: Sun, 8 Mar 2026 20:56:11 -0400 Subject: [PATCH 5/6] Apply suggestions from @mercere99 --- doc/dev/ai-usage-guidelines.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/dev/ai-usage-guidelines.md b/doc/dev/ai-usage-guidelines.md index 401c78a1eb..2e730f511e 100644 --- a/doc/dev/ai-usage-guidelines.md +++ b/doc/dev/ai-usage-guidelines.md @@ -16,8 +16,6 @@ A human must ultimately take responsibility for all aspects of library code. 5. **Limits on extent of Agentic AI use:** Agentic AI may be used to perform simple maintenance tasks (e.g., figuring out we need to update a version number) but not to generate new core-library source code. -6. **Energy Safeguards for Agentic AI use:** Agentic AI should not be run automatically and there should be restrictions added to ensure it stops promptly if it is not able to solve a problem. +6. **Energy Safeguards for Agentic AI use:** Agentic AI should not be run automatically without first reaching a consensus among primary developers, and there should be restrictions added to ensure it stops promptly if it is not able to solve a problem. -7. **Research privacy:** Code that has not yet been made public should not be run through an external AI that may add the code to its database. - -8. **In-code citations:** Any code that was added via an AI should be clearly marked and ideally include a link to the chat session that generated it. +7. **In-code citations:** Any code that was added via an AI should be clearly marked and ideally include a link to the chat session that generated it. From c873b5b6260009b59f79107d31fc788cb7b419a9 Mon Sep 17 00:00:00 2001 From: Matthew Andres Moreno Date: Fri, 27 Mar 2026 08:38:02 -0400 Subject: [PATCH 6/6] Add suggestion from @emilydolson --- doc/dev/ai-usage-guidelines.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/dev/ai-usage-guidelines.md b/doc/dev/ai-usage-guidelines.md index 2e730f511e..4496136254 100644 --- a/doc/dev/ai-usage-guidelines.md +++ b/doc/dev/ai-usage-guidelines.md @@ -19,3 +19,5 @@ A human must ultimately take responsibility for all aspects of library code. 6. **Energy Safeguards for Agentic AI use:** Agentic AI should not be run automatically without first reaching a consensus among primary developers, and there should be restrictions added to ensure it stops promptly if it is not able to solve a problem. 7. **In-code citations:** Any code that was added via an AI should be clearly marked and ideally include a link to the chat session that generated it. + +8. **Standard of oversight:** Contributors and reviewers are expected to have mentally stepped through the code and made sense of it before requesting or approving a review. Exemptions should be requested explicitly where the judged effort tradeoff is not worthwhile. This standard will be subject to further consideration and possible future adjustment.