best-practices

name	best-practices
description	Code Quality Best Practices

TypeScript and Code Quality

• Use TypeScript for all files.
• Only use types, not interfaces.
• Do not use any type.
• Use undefined over null.
• Do not add any comments to the code that you generate.
• Don’t cast to any.
• Don’t unnecessarily add try/catch.
• Use computed for derived state instead of reactive variables when possible.
• Use knip to remove unused code if making large changes.
• When refactoring, avoid creating alias types like this:

export type Options = ScanConfig;

Instead, actually rename the type and fix all occurrences if needed.

Structure, Naming, and Organization

• Follow consistent naming conventions:
  • Folders: camelCase (intercept, replay, httpHistory).
  • Component folders: PascalCase (PassiveFormCreate, PassiveTable).
  • All other files: camelCase (useForm.ts, assistant.graphql).
• Avoid massive template blocks; compose smaller components.
• Colocate code that changes together.
• Declare variables close to their usage:
  • Avoid declaring all variables at the top of functions/files.
  • Place variable declarations as close as possible to where they are first used.
  • Group related variables together (e.g., event bus declarations next to their corresponding listeners).

Simplicity and Readability

• Only create an abstraction if it is actually needed.
• Prefer clear function and variable names over inline comments.
• Avoid helper functions when a simple inline expression would suffice.
• Use built-in Tailwind values, occasionally allow dynamic values, rarely globals.
• Try to use utils like isPresent where possible

Result Types

• Use existing Result types from the codebase (ToolResult, ActionResult, Result) instead of creating custom ones.
• Return ToolResult.ok({ message, ...data }) or ToolResult.err(message, detail?) for agent tools.
• Return ActionResult.ok(message) or ActionResult.err(message, detail?) for float actions.
• Return Result.ok(value) or Result.err(error) for normal functions that need proper safe error handling.
• Never throw exceptions in tool/action implementations; always return Result types.