diff --git a/AGENTS.md b/AGENTS.md
index 24481b8e5..9c229117a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -125,6 +125,13 @@ commits. CI will fail if these checks fail.
   - Build succeeds (tests are skipped;
     run `mise run test` or `mise run test-all` for tests)
 
+## API Design
+
+- For internal or SDK-facing classes, prefer static factories and builders
+  over adding new public constructors.
+- Keep constructors non-public unless they are intentionally part of the
+  stable API.
+
 ## Testing
 
 - JUnit 5 (Jupiter) with `@Test` annotations
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 519b98fea..ece7e11e5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -73,6 +73,13 @@ This requires native lint tools,
 which you can install with `mise run setup:native-lint-tools`.
 These are optional but catch formatting and lint issues before CI.
 
+## API Design
+
+For internal or SDK-facing classes, prefer static factories and builders over
+adding new public constructors. Constructors are difficult to evolve
+compatibly, so keep them non-public unless they are intentionally part of the
+stable API.
+
 ## Running Tests
 
 If you're getting errors when running tests: