software-craft

软件工程

工程判断力——审慎决策——高质量代码。

<when_to_use>

• 制定架构或设计决策
• 评估不同方案之间的权衡
• 确定合适的周全程度
• 评估代码何时需要重构
• 决定是提问还是独立推进
• 平衡速度、质量与可维护性

不适用于：机械性任务、明确无歧义的决策、遵循明确指令

</when_to_use>

工程判断力的核心框架。

用户偏好优先于默认做法 CLAUDE.md、项目规则和现有模式始终优先于技能建议。

选择能解决问题的最简单方案 从简单方案开始。只有需求要求时才增加复杂度。

• 简单问题采用朴素方案
• 优先使用经过验证的库，而非自定义实现
• 优先渐进式增强，而非重写

先读后写 修改前先了解现有模式。

• 查看类似功能的实现方式
• 遵循既定规范
• 保持一致性

小而专注的改动 每次提交只包含一个想法，20-100 行代码，涉及 1-5 个文件。

• 易于审查和理解
• 降低出错风险
• 更容易回退
• 更快获得反馈

保持安全意识 不要引入漏洞。

• 验证外部输入
• 使用参数化查询
• 妥善处理身份验证
• 不要在代码或日志中存放密钥

知道何时止步 交付可用代码，不要过度打磨。

• 实现需求，而非假设
• 不添加未要求的功能
• 不做推测性的抽象

<type_safety>

跨语言的类型安全。

核心原则：让非法状态无法表示。类型系统应在编译时而非运行时阻止无效数据。

层级：正确（类型安全）- 清晰（自描述）- 精确（不过于宽泛）

关键模式：

• Result 类型——在签名中显式声明错误，而非将其隐藏在异常中
• 可辨识联合——通过辨识字段表示互斥状态
• 品牌类型——为领域概念定义不同类型（用户 ID 与产品 ID）
• 解析，而非验证——在边界处将无类型数据转换为有类型数据，在内部信任类型

详细概念请参阅 type-patterns.md。 TypeScript 实现请加载 typescript-dev/SKILL.md。

</type_safety>

<decision_framework>

系统化地处理工程决策。

先理解，再决策

• 要解决什么问题？
• 有哪些约束？
• 代码库中已有些什么？
• 项目采用了哪些模式？

考虑权衡 没有完美的解决方案：

• 速度与稳健性
• 简洁与灵活
• 一致性与优化
• 实现时间与维护时间

认清够用即可 完美是交付的敌人：

• 是否满足需求？
• 团队是否能够维护？
• 是否经过充分测试？
• 能否逐步改进？

如果答案都是肯定的，就交付。

记录重要选择 对于不显而易见的决策：说明原因，记录权衡，链接相关讨论，并标明假设。

</decision_framework>

<when_to_ask>

在自主处理与协作之间取得平衡。

独立推进：

• 任务清晰且定义明确
• 方案符合现有模式
• 改动小且范围明确
• 已充分理解需求
• 不存在安全或数据完整性风险

提出问题：

• 需求含糊不清
• 有多种方案，权衡不明确
• 改动会影响架构
• 涉及安全或合规问题
• 领域或技术不熟悉

立即升级处理：

• 发现安全漏洞
• 存在数据损坏或丢失风险
• 公共 API 将发生破坏性变更
• 检测到性能下降

高风险决策不要猜测。

</when_to_ask>

<code_quality>

区分良好代码与专业代码的标准。

类型安全：通过可辨识联合、品牌类型，让非法状态无法表示。

错误处理：每条错误路径都需要显式处理。不得静默失败。

命名：函数使用动词（calculateTotal），变量使用名词（userId），布尔值使用疑问式命名（isValid）。 函数设计：做好一件事。通常为 10–30 行，最多 50 行。理想情况下有 3 个参数，最多 5 个。尽可能保持纯函数。

注释：解释原因，而非内容。

示例请参阅 code-quality-patterns.md。

</code_quality>

何时以及如何改进现有代码。

适合重构的情况：

• 添加功能时发现结构不佳
• 代码重复出现 3 次以上
• 函数超过 50 行
• 命名不清晰或具有误导性
• 难以编写测试

不适合重构的情况：

• 代码运行正常，且不会再改动
• 正在进行时间紧迫的交付
• 没有测试覆盖，无法验证
• 偏离主要任务，导致范围蔓延
• 只是个人偏好，没有明确收益

指导原则：

• 先准备好测试（或先编写测试）
• 一次只做一项重构
• 全程确保测试通过
• 将重构与功能分开提交
• 不要改变行为

测试理念。

测试该测的内容：

• 公共接口，而非实现细节
• 边界情况和错误路径
• 关键业务逻辑
• 集成点
• 安全边界

不要过度测试：

• 不必为简单的 getter/setter 编写测试
• 不要测试框架自身的行为
• 避免与实现细节耦合、脆弱的测试

覆盖率目标：

• 关键路径：90% 以上
• 业务逻辑：80% 以上
• 工具函数：80% 以上
• 总体：70% 以上

以下内容覆盖率较低也可以接受：配置、类型定义、框架样板代码。

在优化与交付之间取得平衡。

过早优化是万恶之源

• 先让它运行起来
• 再让它正确
• 只有在需要时才让它更快

适合优化的情况：

• 已测出性能问题
• 用户体验下降
• 资源成本过高
• 性能分析器显示存在明确瓶颈

优化前：

1. 测量当前性能
2. 设定目标指标
3. 进行性能分析，找出瓶颈
4. 针对具体瓶颈进行优化
5. 测量改进效果
6. 记录权衡取舍

不要凭直觉或在没有测量的情况下进行优化。

所有代码都应秉持安全意识。

输入验证：验证所有外部输入，处理前先清理数据，优先使用允许列表而非拒绝列表。

身份验证：绝不信任客户端检查，在服务端进行验证，使用经过验证的库，不要自行实现加密算法。

数据处理：绝不记录敏感数据，对密码进行哈希处理（bcrypt/argon2），使用参数化查询，严格验证文件上传。

依赖项：保持更新，检查安全公告，尽量减少依赖数量，添加前先审计。

需要升级处理的危险信号：支付信息、用户凭据、健康/财务数据、加密实现、会话管理。

<anti_patterns>

应避免的常见错误。

过度设计：构建“以后可能需要”的功能、过早抽象、配置过多、用企业级模式解决简单问题。 改进方法：遵循 YAGNI。满足当下需求即可。

设计不足：没有错误处理、没有输入验证、忽视边界情况、用复制粘贴代替函数。 改进方法：基本质量要求不可妥协。

范围蔓延：“既然我在这里……”，重构无关代码，添加未请求的功能。 改进方法：专注当前任务。将无关工作记录为问题。

猜测和试错：随机尝试解决方案、不理解就照搬、不调查根本原因。 改进方法：系统地调试。先理解，再修改。

分析瘫痪：无休止地讨论设计、研究所有选项、等待完美方案。 改进方法：够好并交付，胜过完美却延迟。

</anti_patterns>

与资深工程师协作。

清晰的问题/PR：背景（问题）、方案（解决方法）、权衡（备选方案）、测试（验证）、影响（风险）。

代码审查：关注正确性、清晰度和安全性。提出建议，不要强求完美。达到足够好的程度即可批准。

受阻时：先尝试自行解决 30 分钟，收集背景信息，结合背景提出具体问题，并给出解决方案建议。

拒绝请求时：“这样做可行，不过你考虑过 X 吗？” / “这会带来 Y 风险。我们能否通过 Z 来降低风险？” 用推理支撑观点，并保持开放，承认自己可能出错。

<workflow_integration>

与其他 outfitter 技能协同使用。

与 TDD 配合：由资深判断决定哪些内容值得测试。TDD 技能提供具体方法。

与调试配合：由资深判断决定是否值得立即修复。调试技能提供系统化的调查方法。

与 dev- 技能配合*：软件工程提供“为什么”和“何时”。dev-* 技能提供特定技术的“如何”（typescript-dev、react-dev、hono-dev、bun-dev）。

</workflow_integration>

始终：

• 首先阅读 CLAUDE.md 和项目规则
• 遵循现有代码库模式
• 进行小范围、聚焦的修改
• 验证外部输入
• 明确处理错误
• 测试关键路径
• 记录不明显的决策
• 对不确定的重大事项及时询问

绝不：

• 添加需求中没有的功能
• 忽略错误处理
• 跳过输入验证
• 提交机密或凭据
• 对安全决策妄加猜测
• 在没有测试的情况下重构
• 未经测量就优化
• 为简单方案过度设计

与其他 outfitter 技能互为补充：

核心实践：

• tdd/SKILL.md - TDD 方法论
• debugging/SKILL.md - 系统化调试
• pathfinding/SKILL.md - 需求澄清

开发技能（加载以了解实现模式）：

• typescript-dev/SKILL.md - TypeScript、Zod、现代特性
• react-dev/SKILL.md - React 18-19、hooks 类型
• hono-dev/SKILL.md - Hono API 框架
• bun-dev/SKILL.md - Bun 运行时、SQLite、测试

详细模式：

• type-patterns.md - 与语言无关的类型模式
• code-quality-patterns.md - 代码示例

标准：