maintainable-typescript

可维护的 TypeScript

当项目需要可维护性准则，而不只是局部代码更改时，请使用此技能。

加载顺序

默认情况下不要读取整个技能目录。

1. 首先阅读此文件。
2. 仅加载与任务匹配的文件。
3. 如果仓库符合内部技术栈，请阅读 stack/start-here.md。
4. 将 doctrine/、stack/、prompts/、scripts/ 和 assets/tooling-templates/ 视为参考资料，而非必需上下文。

配套技能

Fallow 技能适用于 Fallow 配置、命令、JSON 输出、修复、CI 门禁和结果解读。如果缺少该技能：

npx skills add https://github.com/fallow-rs/fallow/tree/main/npm/fallow/skills/fallow --skill fallow

任务路由

• 核心原则：maintainability-equals-correctness、resolve-uncertainty-into-contracts、ssot-or-die、integration-first-testing、external-boundary-mocks-only、assert-observable-outcomes
• 清理/重构：clean-up-what-you-touch、delete-obsolete-code、no-backwards-compat-shims、delete-fake-layers、edit-real-owners、build-deep-modules-not-shallow-abstractions、cleanup-module-rewrite、review-structural-slop
• 包/边界：structure-typescript-apps-around-feature-owners、monorepo-package-boundaries、treat-critical-code-like-a-library、naming-is-navigation、no-re-exports、no-barrel-exports
• 技术栈/API/类型：stack-overview、design-openapi-for-inference、errors-are-schema、document-fields-in-derived-zod-schemas、use-canonical-named-types、jsdoc-with-first-party-sources、no-magic-values、use-branded-scalar-types
• 测试/前端/工具：contract-gate-synthetic-fixtures、test-ai-apps-by-artifacts-not-prose、no-type-casts、boundaries-validate-internals-trust、do-not-synchronize-state-with-useeffect、use-the-design-system-not-ad-hoc-tailwind、test-react-apps-in-real-browsers、maintainability-tooling
• 编辑此技能：阅读你要修改的文件，然后运行随附的验证脚本。

审计工作流

用于清理或审查：

skill_dir="<path-to-this-skill>"
bash "$skill_dir/scripts/audit-typescript-repo.sh" .

将审计输出视为信号，而非权威依据。删除 API 表面或合并模式前，先检查实际用法。

如果目标仓库使用 Vite+，请使用 vp 作为常规工具链入口：vp lint、vp test、vp fmt、vp pack、vp add 和 vp dlx。

默认原则

• 结构代价高昂；保留契约、测试和不变量。
• 优先选择删除而非垫片、真正的负责人而非虚假层，以及稳定的子系统文件而非辅助文件丛林。
• 将不确定性落实为契约，而非适配器、默认值、可选项、展开操作或捕获逻辑。
• 优先选择派生类型／模式、持久的集成测试、仅针对外部边界的模拟，以及对可观察结果的断言。
• 优先使用 Fallow 检查死代码、重复代码、依赖项卫生、健康状况、循环依赖和依赖边界。
• 让代码库现在变得更加一致。