diff --git a/AGENTS.md b/AGENTS.md index eb084856a..500bc5fcb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,10 +23,7 @@ - Never remove or downgrade code to fix type errors from outdated deps; upgrade the dep instead. - Use only erasable TypeScript syntax (Node strip-only mode) in code checked by the root config (`packages/*/src`, `packages/*/test`, `packages/coding-agent/examples`): no parameter properties, `enum`, `namespace`/`module`, `import =`, `export =`, or other constructs needing JS emit. Use explicit fields with constructor assignments. - Always ask before removing functionality or code that appears intentional. -- Preserve backward compatibility of public APIs, exports, types, CLI flags, settings, and file formats in minor and patch releases. Breaking changes ship only in major releases. - - Instead of removing or changing something, keep the old form working (deprecated alias, re-export, shim, fallback) next to the new one. - - Mark every such compatibility shim with a `// remove-in-next-major: ` comment so it can be found (`rg remove-in-next-major`) and deleted in the next major release. Exported symbols additionally get a `/** @deprecated Use . */` JSDoc so users see the deprecation in their editor. - - If a change cannot be made backward compatible, stop and ask the user before making it. +- Never break public APIs outside a major release. Keep the old form working next to the new one and mark it `// remove-in-next-major: `. If that is not possible, ask first. - Never hardcode key checks (e.g. `matchesKey(keyData, "ctrl+x")`). Add defaults to `DEFAULT_EDITOR_KEYBINDINGS` or `DEFAULT_APP_KEYBINDINGS` so they stay configurable. - Never modify `packages/ai/src/models.generated.ts` directly; update the catalog definitions in `packages/ai/catalog/` instead (see its README), then regenerate. Including the resulting `models.generated.ts` diff is always OK, even if regeneration includes unrelated upstream model metadata changes. The generated model data in `packages/ai/src/providers/data/` is gitignored: never stage it, and don't look for it in git history.