From d68c28825f7ddaf147ac9f505b38df47404cdffe Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Fri, 31 Jul 2026 00:35:22 +0000
Subject: [PATCH] docs: ban _v2 forks of our own modules

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 AGENTS.md       |  2 ++
 CLAUDE.md       |  1 +
 CONTRIBUTING.md | 10 ++++++++++
 3 files changed, 13 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 41921fdff4d..fa8be3e9217 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1 +1,3 @@
 Read @CLAUDE.md for coding guidelines
+
+Never fork a module into a `_v2` copy (`s3.py` -> `s3_v2.py`, `FooV2`, etc); rewrite it in place. See the coding conventions in @CLAUDE.md and the "No `_v2` module forks" section of @CONTRIBUTING.md
diff --git a/CLAUDE.md b/CLAUDE.md
index 1a4826d51e9..af3d8f0b5b5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -78,6 +78,7 @@ Follow these coding conventions for new/updated code (a three-line fix in a lega
 - Use tagged unions + match
 - No monster files or god objects
 - No file sprawl: deliberate file and folder structure
+- No `_v2` forks of our own modules (`s3.py` -> `s3_v2.py`, `FooV2`, etc). Rewrite in place and gate new behavior behind a flag or an injected strategy, then delete the old path; a fork means every bug has to be fixed twice and it never is. Genuinely versioned upstream APIs are the only exception
 - Standard over hand-rolled: use the official SDK or a library where one exists; where none does, follow industry standards instead of inventing local conventions
 - API-fragmentation-aware: when logic must branch on which API surface produced or consumes data (e.g. chat completions vs Anthropic Messages vs Responses API shapes), proactively look for an existing shared helper (e.g. `litellm_core_utils/prompt_templates/factory.py`) before writing per-surface parsing in the new module; if none exists, add one there instead of duplicating the same format-detection logic in every new guardrail/integration
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d995ddcc87e..19074a5568b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -222,6 +222,16 @@ Our automated quality checks include:
 
 All checks must pass before your PR can be merged.
 
+### No `_v2` module forks
+
+Do not rewrite a module by copying it to a `_v2` sibling (`s3.py` -> `s3_v2.py`, `foo_v2.py`, `FooV2`, and so on)
+Every fork doubles the surface a bug fix has to land on and silently diverges, so a fix in one copy leaves the other broken
+Change the existing module in place instead; if the new behavior has to be opt-in, gate it behind a flag or inject a
+different strategy, and delete the old path once the new one is the default
+
+An exception is a provider or protocol whose upstream API is genuinely versioned (for example a vendor's own `v1` and `v2`
+endpoints living side by side); the ban is on forking our own implementation
+
 ## Common Issues and Solutions
 
 ### 1. Linting Failures