跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

top-down-typescript

TypeScript and JavaScript coding style conventions, centered on top-down narrative ordering (caller first, helpers below) and functions over classes. Read before writing or reviewing TypeScript/JavaScript code, including code inside a spec or a plan.

paleo · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add paleo/alignfirst --skill top-down-typescript

技能说明


name: top-down-typescript description: TypeScript and JavaScript coding style conventions, centered on top-down narrative ordering (caller first, helpers below) and functions over classes. Read before writing or reviewing TypeScript/JavaScript code, including code inside a spec or a plan. license: CC0 1.0 metadata: author: Paleo version: "0.4.0" repository: https://github.com/paleo/skills

Top-Down TypeScript Coding Style

General Rules

  • Dead (unused) code SHOULD NOT be kept (YAGNI principle).
  • Do not write multiple consecutive blank lines.
  • Changes to linter rules MUST be discussed before being implemented.
  • Code SHOULD NOT contain commented-out code, unless a comment explains why.

Code Organization

Usage comes first, implementation after. Exception: with inheritance — when an interface extends another, write the parent first.

  • Order code top-down: each file reads as a story, from entry point to leaves. The reader meets the highest-level thing first, then drills down into its dependencies:

    // 1. Imports
    import { ... } from "...";
    
    // 2. Module-level constants and variables (exported first, then internal)
    export const PUBLIC_CONST = ...;
    const INTERNAL_CONST = ...;
    
    // 3. Shared types — main type first, then types it references
    export interface MainType {
      detail: DetailType;
    }
    export interface DetailType { ... }
    
    // 4. Entry-point (exported) function
    export function doThing() {
      stepOne();
      stepTwo();
    }
    
    // 5. Internal functions called by the entry point, in call order
    function stepOne() {
      stepOneHelper();
    }
    function stepOneHelper() { ... }
    
    function stepTwo() { ... }
    
  • Module-level constants and variables (const, let, var value declarations at the top of the file — both exported and internal) MUST be placed immediately after imports, before any type definitions, functions, or classes. The reader sees them first and treats them as the file's configuration surface.

  • Functions: write the caller first, then the functions it calls, recursively. A helper appears just below its caller, not grouped at the bottom of the file. If a helper is called by several siblings, place it after its first caller.

  • Types: write the main (top-level) type first, then the types it references, recursively. Same top-down rule as functions.

  • Types attached to a single function (or class, or other declaration) — i.e. used only in that one signature, like a MyComponentProps interface used only by MyComponent — must be placed immediately before that declaration, not in the top type block.

  • Exports are not a sorting criterion on their own: a function being exported does not pull it to the top — its position is determined by who calls it. The entry points of a file are usually exported, which is why they tend to appear first, but that is a consequence of the top-down rule, not the rule itself.

Code Quality Standards

  • Strive for elegant solutions from the first implementation
  • Avoid redundant operations, especially expensive ones like image conversion
  • Avoid duplicated code and logic
  • Pass previously calculated values between functions instead of recalculating
  • Use early returns to simplify code flow when possible
  • For code that leaves the current flow (throw, return, continue, break), when it fits on one line, write it on one line (e.g., if (!condition) return false; instead of multi-line format)
  • Use function and variable names that clearly convey intent, reducing the need for comments
  • Keep functions small with a single responsibility
  • Avoid any; take the time to find the proper type. If you fail to find one, always insert a /* FIXME */ after the any. For example: let myVariable: any /* FIXME */;.
  • Export only functions (or variables, classes) that are imported from elsewhere. By default, do not export.
  • When an interface is used in the signature of an exported function or component, that interface must also be exported.

Imports

  • Always use ESM import syntax (e.g., import { X } from "y.js" instead of require).
  • Avoid circular imports between modules.

TypeScript, JavaScript

  • Never use enum and namespace.
  • Prefer const over let.
  • Prefer undefined over null.
  • Prefer ?? over ||.
  • Prefer ++i and --i over i++ and i--.
  • Prefer new Error() over Error().
  • At the top level, prefer the function and class declarative syntax over creating them as constants.
  • Keep an empty line between top-level functions, classes, interfaces.
  • Implementation of a getter or setter (EcmaScript 5 syntax) must never throw exceptions.
  • Prefer interface declarations over type aliases.
  • Prefer a single capital letter for generics parameters, such as T, K, etc.
  • Do not differentiate between an absent property and a property with an undefined value.
  • Use camelCase for string literal values in TypeScript union types (e.g., "normal" | "gracefulShutdown" | "backupMode" instead of "normal" | "graceful-shutdown" | "backup-mode").
  • Never use an empty string as a default value unless you really mean an empty string. If a variable might not have a value, use undefined or throw an error if the absence of value indicates a problem.
  • The existence of string, number, boolean values (and identifiers when they are string or number) must NEVER be tested by coercing to boolean. Use explicit comparisons with undefined or null.
  • Existence checks for objects and arrays MAY use boolean coercion.
  • Never explicitly assign or return undefined when it is the default value. Use return; instead of return undefined; and let myVariable; instead of let myVariable = undefined;. Explicitly passing undefined is fine when intentionally setting a value.
  • Avoid as any or any kind of type assertion. Always make the effort to find the proper type. Exception: when the type is incorrect or truly unknown — justify with an inline comment.
  • Nev
阅读完整来源 ↗