From 3d38dd1411e10c8246de32cd8293efe536a7c2d6 Mon Sep 17 00:00:00 2001 From: Oleh Omelchenko Date: Fri, 5 Jun 2026 01:29:11 +0300 Subject: [PATCH] Clarify trim-content principle: judge by user-path, not category --- AGENTS.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fe7bcb4..29b0343 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -84,12 +84,20 @@ npm run format # Prettier smaller bundle prove nothing about behavior: when a change touches what the user sees or does, confirm it by exercising the feature, not by the compiler alone. - **Trim content, not capability** — when narrowing a third-party import or build to cut - size, remove optional _content_ (languages, locales, themes, icon sets), never the - library's _features_. The smallest/lowest-level entry point is seldom the right one — it - often drops capabilities you meant to keep. Prefer the entry that excludes the unwanted - content while retaining behavior, and validate the behavior survived. (This bit us once: - importing Monaco's `editor.api` to drop unused languages also stripped every editor - feature — see `docs/architecture/08`.) + size, remove optional _content_, never the library's _features_. The smallest/lowest-level + entry point is seldom the right one — it often drops capabilities you meant to keep. Prefer + the entry that excludes the unwanted content while retaining behavior, and validate the + behavior survived. (This bit us once: importing Monaco's `editor.api` to drop unused + languages also stripped every editor feature — see `docs/architecture/08`.) + - The line isn't "content vs. capability" by category — it's **"does any real user path + depend on this?"** Safe to drop: data no user path exercises (a date formatter's unused + locale tables, an icon set you never render, themes you don't ship). _Not_ safe, even + though it looks like "content": **human-language coverage** — font script subsets, + translatable strings — which is capability the moment the app is meant to be usable in + that language. Treat dropping it like dropping a feature. (This bit us a second time: + trimming IBM Plex to the latin subsets dropped Cyrillic — capability for an + internationally-usable app. We ship every script subset and precache them for offline; + `unicode-range` means the browser only downloads what a glyph needs anyway.) - **Spec is the contract** — when in doubt, read `docs/spec/`. If the spec is wrong or silent, raise it; change the spec deliberately rather than drifting from it. - **Core-first** — for each feature, build the pure `src/core/` logic with tests before UI.