develop-typescript（develop TypeScript 搜索）

Develop TypeScript

Write, review, or refactor framework-agnostic TypeScript with strict type safety, correct tsconfig, and idiomatic patterns.

Trigger boundary

Use this skill when:

• writing new TypeScript code that must be strictly typed
• reviewing existing TypeScript for type safety, anti-patterns, or missing narrowing
• configuring or auditing tsconfig.json and linting rules
• migrating JavaScript to TypeScript (or upgrading TS versions)
• diagnosing and resolving type errors, inference failures, or performance issues

Do not use this skill when:

• the task is primarily React/Vue/Angular component work (use framework-specific skills)
• the task is exclusively about Node.js runtime APIs (use a Node.js skill)
• the task is about build tooling only (use tooling-specific skills)

Repositories that happen to contain .tsx files are still in scope when the requested work is about TypeScript itself: tsconfig, safer typing, exported contracts, result/error patterns, or strictness audits.

Definitions

• Load — read the file into working context so you can reference its content
• Checked as — a cast following a runtime guard that proves the type (safe)
• Unchecked as — a cast with no runtime proof; hides bugs (almost always wrong)
• Block — in review mode, flag the issue and stop approving; do not auto-fix

Mode detection

Before starting, determine your mode:

Required workflow

Step 1 — Classify the task

Identify the primary category and optionally one adjacent category:

Steering note: Most tasks span two categories. Load the primary reference plus one adjacent. If uncertain which category fits, scan the table above for keywords that match the user request.

Step 2 — Load references

Load the reference file(s) identified in Step 1. Read the full file — do not skim.

If the task involves existing code, also load:

• The project's tsconfig.json (compare against strict-config.md baseline)
• The project's ESLint/Biome config (check for rule conflicts)

Steering note: When reviewing tsconfig.json, only flag moduleResolution: "node" as legacy. "node16", "nodenext", and "bundler" are all modern and correct for their contexts. Choose the baseline that matches the repo's runtime first; strictness flags are orthogonal to module mode. Do not "upgrade" node16/nodenext projects to bundler unless the user explicitly wants that runtime change. If the repo has multiple tsconfig files, start with the config that governs the files you are touching, then follow its extends chain to shared base configs. If there is no ESLint/Biome config, record that absence and skip Step 5 conflict handling rather than inventing lint policy.

Step 3 — Execute the task

Apply the patterns and rules from the loaded references.

In authoring mode:

• Write code that follows the patterns in the reference files
• Use satisfies for config objects, explicit return types for public functions
• Never use bare any, @ts-ignore, or unchecked as
• Prefer unknown + narrowing over any for dynamic data

In review mode:

• Scan for every item in the anti-patterns.md review-mode checklist (Section: Review-Mode Scanning Checklist)
• For each finding, classify as P0 (blocks approval) or P1 (should fix) or P2 (nit)
• Block on: bare any in new code, @ts-ignore (should be @ts-expect-error), unchecked as, missing error narrowing
• Flag but don't block on: style preferences, minor naming issues

Steering note: Distinguish lint warnings from type errors. Lint warnings are project-specific (respect the project's config). Type errors from tsc are universal and always blocking.

Step 4 — Audit and verify

Run these checks:

# Find unannotated exported functions (authoring mode)
grep -rnE --include="*.ts" --include="*.tsx" "^export (default )?function" . | grep -v node_modules | grep -v ": " | head -20

# Find bare 'any' usage
grep -rnE --include="*.ts" --include="*.tsx" ": any\\b" . | grep -v node_modules | head -20

# Find @ts-ignore (should be @ts-expect-error)
grep -rn --include="*.ts" --include="*.tsx" "@ts-ignore" . | grep -v node_modules

# Find unchecked type assertions
grep -rn --include="*.ts" --include="*.tsx" " as [A-Z]" . | grep -v node_modules | grep -v "// checked" | head -20

# Search for satisfies opportunities (config objects typed with annotation)
grep -rnE --include="*.ts" --include="*.tsx" "^const .* : Record<" . | grep -v node_modules | head -10
grep -rnE --include="*.ts" --include="*.tsx" "^const .* : {" . | grep -v node_modules | head -10

Steering note: The satisfies audit catches config objects that use type annotations where satisfies would preserve literal types. This is a common missed opportunity. Run these audits from the repository root, or replace . with the target package path in a monorepo. If the repo contains TSX and jsx is react-jsx, verify the React runtime/types are actually installed before treating the typecheck result as meaningful.

Step 5 — Handle conflicts

If the project's lint config contradicts skill recommendations:

1. For new code you're writing: follow the skill's stricter rules
2. For existing code under review: respect the project's config, flag conflicts as informational
3. Document the conflict: "Project disables X — consider re-enabling for new code"

Steering note: Do not unilaterally re-enable lint rules. The project may have valid reasons for disabling them (e.g., gradual migration from JavaScript, third-party type issues).

Step 6 — Deliver

In authoring mode: Output the complete, compilable code. Ensure every exported function has an explicit return type annotation. For exported TSX components, follow the repo's existing convention; if none exists, prefer ReactElement via import type {ReactElement} from 'react' over relying on the global JSX.Element namespace.

In review mode: Output findings as a structured list with severity levels. Include specific line references and fix suggestions for each P0 and P1 finding.

Steering note: Always produce a deliverable — code or findings list. Never end with only commentary or advice. The user expects actionable output.

Common mistakes to avoid

Reference routing

Guardrails

• Never introduce any — use unknown and narrow
• Never use @ts-ignore — use @ts-expect-error with explanation
• Never use unchecked as — always guard first, then cast
• Always add explicit return types to exported functions
• Always verify tsconfig against strict-config.md baseline before suggesting config changes
• In review mode: report findings, never silently modify code