From 7b0023471e1bb7e4029346f3c33f4ac8ddf37271 Mon Sep 17 00:00:00 2001 From: Andrey Avtomonov Date: Tue, 9 Jun 2026 16:31:00 +0200 Subject: [PATCH] docs(agents): sync Opinionated Product Defaults guidance into AGENTS.md (#280) --- AGENTS.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 2c61a7e5..ffe324bb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -64,6 +64,25 @@ When rules conflict, follow this order: 4. Code quality: types, readable boundaries, focused modules 5. Performance where it matters +## Opinionated Product Defaults + +- **MUST**: Prefer one canonical behavior over configurable alternatives. A new + flag, config field, environment variable, mode, strategy option, adapter hook, + or fallback path is a product feature and must be justified by an explicit + user request or a real correctness requirement. +- **MUST NOT**: Add speculative flexibility for imagined users, migrations, + review preferences, local workflows, or "just in case" scenarios. If the + requested behavior can work with one solid default, implement that default. +- **MUST NOT**: Add boolean switches that create two runtime paths unless both + paths are essential and the user explicitly asked for the choice. Boolean + policy knobs are especially suspect because they double the state space and + test surface. +- **MUST**: When a design seems to need a new option, first try to remove the + need by choosing the stronger default, tightening the invariant, or failing + clearly. Ask the user before adding the option if it still seems necessary. +- **MUST**: Delete obsolete branches, tests, docs, and config when removing a + behavior. Do not preserve dormant compatibility paths. + ## Repository Shape **ktx** is a pnpm + uv workspace. @@ -229,12 +248,21 @@ Before presenting a design, answer these explicitly: implementation? If so, am I routing through that path instead of forking a parallel one — and if I'm fixing a bug, am I fixing the shared layer rather than one branch? +7. Am I adding a user-visible option or alternate runtime path that the user did + not ask for? If yes, can one opinionated default solve the problem instead? +8. Does this option multiply behavior by caller path, config value, or local + state? If yes, remove it unless it is explicitly required. A user question that nudges toward an alternative ("would X help?", "should I always do Y?", "will you hardcode Z?") is a signal that a better option exists. Investigate the implied direction and reason it through *before* defending the original proposal — and prefer to have asked yourself the question first. +Example: If generated context changes should be saved, choose one save policy +and route ingest, setup, memory, indexing, and docs through it. Do not add an +`auto_commit`-style switch unless the user explicitly asks for staged-only runs +and accepts the extra runtime path. + ## TypeScript Standards - Use Node 22+ and pnpm workspace commands.