用途
该技能适用于需要工程判断的场合，包括：做架构或设计决策、评估不同方案之间的权衡、判断需要多大程度的严谨性、评估代码何时需要重构、决定何时提问还是独立推进、以及在速度、质量与可维护性之间取得平衡。
不适用于：机械性任务、已有明确结论的决策、按明确指令执行的工作。
核心理念
- 用户偏好高于默认建议：CLAUDE.md、项目规则、既有模式始终覆盖本技能的建议。
- 采用能解决问题的最简方案：从简单开始，只有需求要求时才增加复杂度；用成熟无聊的方案解决无聊的问题；优先使用经过验证的库而非自研；优先渐进增强而非重写。
- 先读后写：修改前先理解既有模式，查看类似功能如何实现，遵循已有约定，保持一致性。
- 小步聚焦的改动：一次提交只表达一个想法，20-100 行代码，涉及 1-5 个文件，便于评审、降低缺陷风险、便于回滚、反馈更快。
- 安全意识到位：不引入漏洞，校验外部输入，使用参数化查询，正确处理鉴权，代码与日志中不含密钥。
- 知道何时停止：交付可运行的代码，不做镀金；只实现需求而非假设；不添加未被要求的功能；不做投机性抽象。
类型安全
核心原则是让非法状态无法表达——类型系统应在编译期而非运行期阻止非法数据。优先级为：正确（类型安全）→ 清晰（自文档化）→ 精确（不过度宽泛）。
关键模式：
- Result 类型：错误显式体现在签名中，而非隐藏在异常里。
- 可辨识联合：用判别字段表达互斥状态。
- 品牌类型：为领域概念区分不同类型（用户 ID 与商品 ID）。
- 解析而非校验：在边界处把无类型数据转换为有类型数据，内部信任类型。
详细概念参见 type-patterns.md；TypeScript 实现参见 typescript-dev/SKILL.md。
决策框架
在决定前先理解：要解决什么问题、存在哪些约束、代码库中已有什么、项目使用什么模式。
权衡取舍：没有完美方案，需要在速度与健壮性、简单与灵活、一致性与优化、实现时间与维护时间之间取舍。
接受“足够好”：完美是交付的敌人。如果满足需求、团队可维护、测试充分、可增量改进，就交付。
记录重要选择：对非显而易见的决策，注释说明原因、记录权衡、关联讨论、标注假设。
何时提问
可独立推进：任务清晰明确、方案遵循既有模式、改动小而局部、需求已完全理解、无安全或数据完整性风险。
需要提问：需求含糊、存在多种方案且权衡不清、改动影响架构、涉及安全或合规、领域或技术不熟悉。
立即上报：发现安全漏洞、存在数据损坏或丢失风险、对公共 API 造成破坏性变更、检测到性能下降。
高风险决策不要靠猜。
代码质量
- 类型安全：通过可辨识联合、品牌类型让非法状态无法表达。
- 错误处理：每条错误路径都要显式处理，不允许静默失败。
- 命名：函数用动词（calculateTotal），变量用名词（userId），布尔值用问句形式（isValid）。
- 函数设计：一件事做好；通常 10-30 行，最多 50 行；理想 3 个参数，最多 5 个；尽可能保持纯函数。
- 注释：解释为什么，而不是做什么。
示例参见 code-quality-patterns.md。
何时重构
应当重构：增加功能时暴露出结构不佳、代码重复 3 次以上、函数超过 50 行、命名不清或误导、测试难以编写。
不应重构：代码可用且不会再改、正处于时间紧迫的交付中、没有测试覆盖可供验证、偏离主任务的范畴蔓延、只是个人偏好而无明确收益。
指导原则：先有测试（或补上测试）；一次只做一项重构；全程保持测试通过；重构与功能分开提交；不改变行为。
测试理念
测试正确的对象：公开接口而非实现细节、边界情况与错误路径、关键业务逻辑、集成点、安全边界。
避免过度测试：不为琐碎的 getter/setter 写测试，不测试框架行为，避免脆弱且耦合实现的测试。
覆盖率目标：关键路径 90%+，业务逻辑 80%+，工具函数 80%+，整体 70%+。配置、类型定义、框架样板代码可采用较低覆盖率。
优化原则
过早优化是万恶之源。先让它能工作，再让它正确，最后只在必要时让它变快。
应当优化：存在可测量的性能问题、用户体验下降、资源成本过高、性能分析显示明确瓶颈。
优化前：测量当前性能、设定目标指标、用性能分析定位瓶颈、优化具体瓶颈、测量改进效果、记录权衡。
不要凭直觉或在未测量的情况下优化。
安全思维
- 输入校验：校验所有外部输入，处理前先净化，优先白名单而非黑名单。
- 鉴权：绝不相信客户端检查，在服务端验证，使用成熟库，不要自己实现加密。
- 数据处理：不记录敏感数据，密码使用 bcrypt/argon2 哈希，使用参数化查询，严格校验文件上传。
- 依赖：保持更新，关注安全公告，尽量减少数量，添加前先审计。
需要上报的红旗：支付信息、用户凭证、健康或财务数据、加密实现、会话管理。
反模式
- 过度工程：构建“可能会需要”的功能、过早抽象、过度配置、为简单问题套用企业级模式。对策：YAGNI，面向今天构建。
- 工程不足：无错误处理、无输入校验、忽略边界情况、用复制粘贴代替函数。对策：基本质量不是可选项。
- 范畴蔓延：“既然我在这里……”、重构无关代码、添加未要求的功能。对策：保持专注，把无关工作登记为待办问题。
- 猜测式试错：随机尝试方案、不理解就复制、不追查根因。对策：系统性调试，先理解再修改。
- 分析瘫痪：无休止的设计讨论、研究所有选项、等待完美方案。对策：足够好并交付优于完美但延迟。
协作方式
清晰的 issue/PR：包含背景（问题）、方案（解法）、权衡（备选方案）、测试（验证方式）、影响（风险）。
代码评审：关注正确性、清晰度和安全性；提建议而非强求完美；足够好即可通过。
受阻时：先自行尝试 30 分钟解除阻塞，收集上下文，带着上下文提出具体问题，并提出解决方案。
说“不”的方式：“那样可行，但你考虑过 X 吗？”或“这会引入 Y 风险，能否用 Z 缓解？”用推理支撑观点，同时保持自己可能出错的开放态度。
与其他技能的关系
- 与 TDD：本技能的高级判断决定哪些值得测试，TDD 技能提供怎么做。
- 与调试：本技能判断是否值得现在修，调试技能提供系统性排查方法。
- 与 dev-* 技能：本技能提供“为什么”和“何时”，各技术栈技能（typescript-dev、react-dev、hono-dev、bun-dev）提供具体“怎么做”。
配套技能包括：test-driven-development/SKILL.md、debugging-and-diagnosis/SKILL.md、pathfinding/SKILL.md；开发技能 typescript-dev/SKILL.md、react-dev/SKILL.md、hono-dev/SKILL.md、bun-dev/SKILL.md；详细模式 type-patterns.md、code-quality-patterns.md；规范 FORMATTING.md。
基本原则
始终：先读 CLAUDE.md 和项目规则；遵循既有代码库模式；做小而聚焦的改动；校验外部输入；显式处理错误；测试关键路径；记录非显而易见的决策；高风险不确定时提问。
绝不：添加需求之外的功能；忽略错误处理；跳过输入校验；提交密钥或凭证；在安全决策上猜测；在没有测试的情况下重构；在没有测量的情况下优化；把简单方案过度工程化。