writing-clean-ts

TypeScript 专家

编写、重构和审查 TypeScript，使其遵循单一分层架构（Controller → Use Case → Component → Service → Repository → DAL → Entity）以及统一的命名、风格和 lint 规范，并确保新代码与现有风格一致、无缝集成。

在创建或迁移服务、存储库、DAL、实体、模型、枚举、控制器、处理程序、用例、应用启动代码或 UI 组件时；根据这些规范重构或审查 TypeScript 时；以及使用 #src 别名配置 lint 或 ES 模块时使用。

核心工作流

1. 检测技术栈：读取目标包的 package.json（在 monorepo 中，读取正在处理的包，而不是根目录），并检查下方框架表中的文件。
2. 加载参考资料：先阅读 references/core-rules.md，然后只阅读下方与技术栈和任务匹配的行。每个加载的文件都要从头到尾阅读；绝不设置阅读范围限制。
3. 编写功能代码前检查项目配置：检查 ES 模块、#src 别名，以及带有相应配置的 lint / lint-fix 脚本。若有任何一项缺失，先完成配置（references/linting.md）——小型、新建或现有项目都不例外。
4. 按分层顺序构建：后端 App Boot → Controller → Entity → DAL → Repository → Component/Service/Use Case；前端 Controller → UI Component。每个新文件都从其起始模板开始。
5. 使用工具执行 lint：运行 lint-fix，然后运行 lint。脚本检查的内容只能根据其输出判定——绝不通过肉眼或 AI agent/审查者审查代码。仅手动修复工具报告但无法自动修复的问题。绝不通过禁用规则来通过检查。
6. 测试属于 contract-testing-ts 技能。

仅加载所需内容

绝不要预先加载所有参考文件。始终先阅读 references/core-rules.md；之后只阅读符合条件的文件。不要阅读其他文件。

框架

一个项目可能匹配多行（例如 Express + TypeORM + Zod）。阅读每个匹配的行，不要阅读其他内容。

检测条件	阅读
依赖中包含 expo 或 expo-router、"main": "expo-router/entry"，或 app.json / app.config.ts 中有 expo 键。编写、迁移或审查代码前阅读	references/frameworks/expo.md
依赖中包含 react（包括 React Native、Expo 和 Electron 渲染进程）	references/frameworks/react.md
依赖中包含 express	references/frameworks/express.md
依赖中包含 typeorm	references/frameworks/typeorm.md
依赖中包含 amqplib，或存在 src/controller/rmq/	references/frameworks/rmq.md
依赖中使用 rxjs 作为事件总线，或存在 src/controller/rxjs-bus/	references/frameworks/rxjs.md
依赖中包含 electron，或同时存在 src/main/ 和 src/renderer/	references/frameworks/electron.md
依赖中包含 zod，或任务需要编写或审查控制器处理程序、架构或负载校验	references/frameworks/zod.md

主题

任务涉及……	阅读
任何代码任务（始终优先阅读）	references/core-rules.md
创建、命名或重命名文件、导出项、枚举、函数、变量或布尔值	references/style/naming-convention.md
编写或编辑函数体（三元表达式、循环、let、switch、箭头函数、变更、默认值）	references/style/code-style.md
错误处理、穷尽式 switch，或名称必须涵盖其行为的函数	references/style/function-guidelines.md
超过约 30 行的函数，或拆分函数或文件	references/style/function-size.md
编写或更改函数签名（参数、默认值、回调）	references/style/object-params-pattern.md
日期／时间字段（*At 字段、Date 值、时间戳列）	references/style/timestamp-handling.md
创建文件或文件夹、移动代码，或决定代码所属层级	references/architecture/file-organization-pattern.md
为模块选择 class、普通对象还是 singleton	references/architecture/class-vs-object.md
常量、环境／配置值、运行时状态或平台检查	references/architecture/constant-config-pattern.md
模型类型，或在实体与模型之间转换	references/architecture/model-vs-entity.md
各层中的缺失值（null、undefined、可选字段）	references/architecture/null-undefined-pattern.md
启动或关闭代码（src/app-boot/、生命周期）	references/architecture/app-boot-layer.md
任何控制器（src/controller/）	references/architecture/controller-layer.md
src/business/component/ 中的单元（选择器 + 策略、公共 API + 私有辅助函数）	references/architecture/component-layer.md
src/business/service/ 中的服务	references/architecture/service-layer.md
src/business/use-case/ 中的用例	references/architecture/use-case-layer.md
src/business/repo/ 中的仓库	references/architecture/repository-layer.md
src/dal/ 中的 DAL（数据库、文件、内存或 API 存储）	references/architecture/dal-layer.md
src/dal/*/entity/ 中的实体	references/architecture/entity-layer.md
src/ui-component/ 中的 UI 组件	references/architecture/ui-component-layer.md
设计或审查 REST 端点 URL	references/architecture/rest-api-url-conventions.md
设置 lint（新项目，或没有 lint / lint-fix 脚本的项目）、编辑 ESLint/Prettier/jsonsort 配置、检查 lint 脚本验证的内容，或理解 lint 规则	references/linting.md

命令

用户说……	阅读
“清理这段代码”、“审查这个文件”、“检查代码质量”、“验证代码结构”	references/commands/cleanup.md，以及与被审查代码相匹配的框架和主题对应的文件
“审查架构”、“clean-arch”、“检查结构”、“这个代码属于正确的层级吗”	references/commands/clean-arch.md，以及 references/architecture/ 中的 file-organization-pattern.md、class-vs-object.md、model-vs-entity.md、constant-config-pattern.md、null-undefined-pattern.md、rest-api-url-conventions.md、被审查层级对应的文件；控制器属于审查范围时，还需阅读 references/frameworks/express.md 和 references/frameworks/zod.md；Expo 项目还需阅读 references/frameworks/expo.md。不要加载 references/style/
“审查风格”、“clean-style”、“检查可读性”或仅提供风格方面的反馈	references/commands/clean-style.md，以及 references/style/ 中的所有文件；Expo 项目还需阅读 references/frameworks/expo.md。不要加载 references/architecture/

入门模板

复制粘贴脚手架。只打开要创建的文件对应的模板。

创建内容……	模板
包含独立方法的服务（单例）	templates/service-template.ts
包含相互依赖方法的服务（类）	templates/service-class-template.ts
解析器服务（正则表达式、日期等）	templates/parser-service-template.ts
仓储类	templates/repository-template.ts
TypeORM DAL 类	templates/dal-template.ts
TypeORM 实体	templates/entity-template.ts
编排多个服务的用例	templates/use-case-template.ts
Express GET 列表端点	templates/express-handler-template.ts
Express POST 创建端点	templates/express-handler-post-template.ts
React Router 控制器（不在 Expo 中）	templates/react-controller-template.tsx
React UI 组件	templates/react-component-template.tsx
模型类型定义	templates/model-template.ts
枚举（如果键和值不同，则使用 -mapper-enum）	templates/enum-template.ts
组件或服务子文件夹中的策略/可插拔类	templates/subfolder-component-template.ts

许可证

本技能根据 LICENSE.txt 中的条款授权。