AGENTS.md

• API descriptions
  • Add concise, factual, behavioral API descriptions in source code for public API members. Move prescriptive advice and conventions to a separate best-practices document.
  • Do not add doc comments to bare re-exports or passthrough exports.
  • State clearly where type inference comes from when that affects how the API should be written or consumed.
  • Prefer positive framing in API documentation. Describe what something does or receives, and avoid mixing positive and negative framing in the same explanation.
  • Label reactivity clearly in API documentation so it is obvious which values are reactive and when an API makes a value reactive.
  • Call out especially useful behavior when it clarifies intent, particularly for nested or non-obvious use cases.
  • Prefer plain prose doc comments over JSDoc tags like @param and @returns, and use those tags only when they materially clarify a complex API.
  • Keep AI-specific authoring conventions, naming guidance, and other best-practice material out of the public API surface.
  • Group related guidance together in docs. Do not combine unrelated recommendations into the same bullet, paragraph, or section item just to save space.
• Import style
  • Prefer namespace imports for runtime helper modules when that avoids local aliasing, for example import * as moduleName instead of renamed imports.
• Performance guidance
  • Avoid speculative performance memoization. Prefer plain derivation until benchmarks justify caching, and if one cached derivation is kept, make the tradeoff explicit.
  • Prefer simple parameters over one-off options objects on hot internal paths when a single boolean or scalar is enough.
  • Avoid cloning argument arrays on internal hot paths when an existing array-like value can be passed through directly.
• Testing guidance
  • Write runtime tests only for supported runtime contract behavior, plus intentional runtime guards for invalid inputs.
  • Use type tests for behavior that is enforced by the type system in supported usage.
  • Do not define runtime behavior with tests when reaching that behavior requires bypassing or silencing the type system, unless behavior under that bypass is itself part of the supported contract.
  • Do not lock tests to implementation details or optimizations unless those details are explicitly part of the public contract.
  • Do not add tests just to cover re-exports or passthrough exports.
• Agent maintenance
  • When the user corrects the agent on a general style or discipline preference, and the correction is not domain-specific or overly specific, add that guidance to AGENTS.md so it applies going forward.
  • Keep that AGENTS.md update in a separate commit from other work.
  • Add guidance under the category it actually belongs to. Keep categories broad and generally reusable rather than narrowly scoped.
  • Do not add domain-specific terminology, conventions, or project-specific guidance to AGENTS.md. Keep it reusable across projects.