Back to Details

software-craft

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Software Engineering

软件工程

Engineering judgment - thoughtful decisions - quality code.
<when_to_use>
  • Making architectural or design decisions
  • Evaluating trade-offs between approaches
  • Determining appropriate level of thoroughness
  • Assessing when code needs refactoring
  • Deciding when to ask vs proceed independently
  • Balancing speed, quality, maintainability
NOT for: mechanical tasks, clear-cut decisions, following explicit instructions
</when_to_use>
<principles>
Core engineering judgment framework.
User preferences trump defaults 
CLAUDE.md
, project rules, existing patterns always override skill suggestions.
Simplest thing that works Start simple. Add complexity only when requirements demand.
  • Boring solutions for boring problems
  • Proven libraries over custom implementations
  • Progressive enhancement over rewrites
Read before write Understand existing patterns before modifying.
  • Check how similar features implemented
  • Follow established conventions
  • Maintain consistency
Small, focused changes One idea per commit, 20-100 LOC, 1-5 files.
  • Easy to review/understand
  • Lower bug risk
  • Simpler to revert
  • Faster feedback
Security awareness Don't introduce vulnerabilities.
  • Validate external input
  • Parameterized queries
  • Handle auth properly
  • No secrets in code/logs
Know when to stop Ship working code, don't gold-plate.
  • Implement requirements, not assumptions
  • No unrequested features
  • No speculative abstraction
</principles>
<type_safety>
Type safety across languages.
Core principle: Make illegal states unrepresentable. Type system should prevent invalid data at compile time, not runtime.
Hierarchy: Correct (type-safe) - Clear (self-documenting) - Precise (not overly broad)
Key patterns:
  • Result types - Errors explicit in signatures, not hidden in exceptions
  • Discriminated unions - Mutually exclusive states with discriminator field
  • Branded types - Distinct types for domain concepts (user ID vs product ID)
  • Parse, don't validate - Transform untyped to typed at boundaries, trust types internally
See type-patterns.md for detailed concepts. Load 
typescript-dev/SKILL.md
for TypeScript implementations.
</type_safety>
<decision_framework>
Systematic approach to engineering choices.
Understand before deciding
  • What problem being solved?
  • What constraints exist?
  • What's already in codebase?
  • What patterns does project use?
Consider trade-offs No perfect solutions:
  • Speed vs robustness
  • Simplicity vs flexibility
  • Consistency vs optimization
  • Implement time vs maintain time
Recognize good-enough Perfect is enemy of shipped:
  • Meets requirements?
  • Maintainable by team?
  • Tested adequately?
  • Can improve incrementally?
If yes to all - ship it.
Document significant choices Non-obvious decisions: comment why, note trade-offs, link discussions, flag assumptions.
</decision_framework>
<when_to_ask>
Balance autonomy with collaboration.
Proceed independently:
  • Task clear and well-defined
  • Approach follows existing patterns
  • Changes small and localized
  • Requirements fully understood
  • No security/data integrity risks
Ask questions:
  • Requirements ambiguous
  • Multiple approaches, unclear trade-offs
  • Changes affect architecture
  • Security/compliance implications
  • Unfamiliar domain/technology
Escalate immediately:
  • Security vulnerabilities discovered
  • Data corruption/loss risk
  • Breaking changes to public APIs
  • Performance degradation detected
Don't guess on high-stakes decisions.
</when_to_ask>
<code_quality>
Standards separating good from professional code.
Type safety: Make illegal states unrepresentable via discriminated unions, branded types.
Error handling: Every error path needs explicit handling. No silent failures.
Naming: Functions=verbs (
calculateTotal
), variables=nouns (
userId
), booleans=questions (
isValid
).
Function design: One thing well. 10-30 lines typical, max 50. 3 params ideal, max 5. Pure when possible.
Comments: Explain why, not what.
See code-quality-patterns.md for examples.
</code_quality>
<refactoring>
When and how to improve existing code.
Refactor when:
  • Adding feature reveals poor structure
  • Code duplicated 3+ times
  • Function exceeds 50 lines
  • Naming unclear/misleading
  • Tests difficult to write
Don't refactor when:
  • Code works and won't be touched
  • Time-critical delivery in progress
  • No test coverage to verify
  • Scope creep from main task
  • Just preference, no clear benefit
Guidelines:
  • Have tests first (or write them)
  • One refactoring at a time
  • Keep tests passing throughout
  • Commit refactors separately from features
  • Don't change behavior
</refactoring> <testing>
Testing philosophy.
Test the right things:
  • Public interfaces, not implementation
  • Edge cases and error paths
  • Critical business logic
  • Integration points
  • Security boundaries
Don't over-test:
  • No tests for trivial getters/setters
  • Don't test framework behavior
  • Avoid brittle implementation-coupled tests
Coverage targets:
  • Critical paths: 90%+
  • Business logic: 80%+
  • Utility functions: 80%+
  • Overall: 70%+
Low coverage acceptable for: config, type definitions, framework boilerplate.
</testing> <performance>
Balance optimization with delivery.
Premature optimization is root of evil
  • Make it work first
  • Make it right second
  • Make it fast only if needed
Optimize when:
  • Measured performance issue exists
  • User experience degraded
  • Resource costs excessive
  • Profiler shows clear bottleneck
Before optimizing:
  1. Measure current performance
  2. Set target metrics
  3. Profile to find bottleneck
  4. Optimize specific bottleneck
  5. Measure improvement
  6. Document trade-offs
Don't optimize based on gut feeling or without measurement.
</performance> <security>
Security mindset for all code.
Input validation: Validate all external input, sanitize before processing, allowlists over blocklists.
Auth: Never trust client-side checks, verify on server, use proven libraries, don't roll your own crypto.
Data handling: Never log sensitive data, hash passwords (bcrypt/argon2), parameterized queries, strict file upload validation.
Dependencies: Keep updated, review advisories, minimize count, audit before adding.
Red flags to escalate: Payment info, user credentials, health/financial data, encryption implementation, session management.
</security>
<anti_patterns>
Common mistakes to avoid.
Over-engineering: Building "might need" features, premature abstraction, excessive config, enterprise patterns for simple problems. Fix: YAGNI. Build for today.
Under-engineering: No error handling, no input validation, ignoring edge cases, copy-paste over functions. Fix: Basic quality isn't optional.
Scope creep: "While I'm here...", refactoring unrelated code, adding unrequested features. Fix: Stay focused. File issues for unrelated work.
Guess-and-check: Random solutions, copying without understanding, no root cause investigation. Fix: Systematic debugging. Understand before changing.
Analysis paralysis: Endless design discussions, researching every option, waiting for perfect. Fix: Good enough + shipping > perfect + delayed.
</anti_patterns>
<communication>
Senior engineer collaboration.
Clear issues/PRs: Context (problem), approach (solution), trade-offs (alternatives), testing (verification), impact (risks).
Code review: Focus on correctness/clarity/security. Suggest, don't demand perfection. Approve when good enough.
When blocked: Try 30 min self-unblock, gather context, ask specific question with context, propose solutions.
Saying no: "That would work, but have you considered X?" / "This introduces Y risk. Can we mitigate with Z?"
Back opinions with reasoning. Stay open to being wrong.
</communication>
<workflow_integration>
Connect with other outfitter skills.
With TDD: Senior judgment decides what's worth testing. TDD skill provides how.
With debugging: Senior judgment decides if worth fixing now. Debugging skill provides systematic investigation.
With dev- skills*: Software engineering provides the "why" and "when". dev-* skills provide the "how" for specific technologies (typescript-dev, react-dev, hono-dev, bun-dev).
</workflow_integration>
<rules>
ALWAYS:
  • Read 
    CLAUDE.md
    and project rules first
  • Follow existing codebase patterns
  • Make small, focused changes
  • Validate external input
  • Handle errors explicitly
  • Test critical paths
  • Document non-obvious decisions
  • Ask when uncertain on high-stakes
NEVER:
  • Add features not in requirements
  • Ignore error handling
  • Skip input validation
  • Commit secrets or credentials
  • Guess on security decisions
  • Refactor without tests
  • Optimize without measuring
  • Over-engineer simple solutions
</rules> <references>
Complements other outfitter skills:
Core Practices:
  • tdd/SKILL.md - TDD methodology
  • debugging/SKILL.md - systematic debugging
  • pathfinding/SKILL.md - requirements clarification
Development Skills (load for implementation patterns):
  • typescript-dev/SKILL.md - TypeScript, Zod, modern features
  • react-dev/SKILL.md - React 18-19, hooks typing
  • hono-dev/SKILL.md - Hono API framework
  • bun-dev/SKILL.md - Bun runtime, SQLite, testing
Detailed Patterns:
  • type-patterns.md - language-agnostic type patterns
  • code-quality-patterns.md - code examples
Standards:
</references>
工程判断——深思熟虑的决策——高质量的代码。
<when_to_use>
  • 制定架构或设计决策
  • 评估不同方案的取舍
  • 确定合适的严谨程度
  • 判断代码何时需要重构
  • 决定是询问他人还是独立推进工作
  • 平衡开发速度、代码质量与可维护性
不适用于：机械性任务、明确无歧义的决策、遵循明确指令的工作
</when_to_use>
<principles>
核心工程判断框架。
用户偏好优先于默认设置 
CLAUDE.md
、项目规则、现有模式始终优先于Skill的建议。
最简单可行方案 从简单开始。仅在需求要求时再增加复杂度。
  • 用常规方案解决常规问题
  • 优先使用经过验证的库而非自定义实现
  • 渐进式增强而非重写
先读再写 修改前先理解现有模式。
  • 查看类似功能的实现方式
  • 遵循已确立的约定
  • 保持一致性
小而聚焦的变更 每次提交一个想法，代码量20-100 LOC，涉及1-5个文件。
  • 便于评审和理解
  • 降低引入bug的风险
  • 更易回滚
  • 更快获得反馈
安全意识 不要引入漏洞。
  • 验证外部输入
  • 使用参数化查询
  • 正确处理认证
  • 代码/日志中不包含敏感信息
适可而止 交付可运行的代码，不要过度优化。
  • 实现需求，而非假设的功能
  • 不添加未被要求的功能
  • 不做投机性的抽象
</principles>
<type_safety>
跨语言类型安全。
核心原则：让非法状态无法被表示。类型系统应在编译时而非运行时防止无效数据。
优先级：正确（类型安全）- 清晰（自文档化）- 精确（不过于宽泛）
关键模式:
  • Result类型 - 错误在签名中显式声明，而非隐藏在异常中
  • 可区分联合类型 - 带有鉴别字段的互斥状态
  • 品牌类型 - 为领域概念创建不同类型（如用户ID vs 产品ID）
  • 解析而非验证 - 在边界处将无类型数据转换为有类型数据，内部信任类型
详细概念请参考type-patterns.md。 加载
typescript-dev/SKILL.md
查看TypeScript实现方案。
</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>
<refactoring>
何时以及如何改进现有代码。
重构时机:
  • 添加功能时发现结构不佳
  • 代码重复3次及以上
  • 函数超过50行
  • 命名不清晰/有误导性
  • 难以编写测试
不要重构的情况:
  • 代码可正常运行且不会再被修改
  • 处于时间紧迫的交付阶段
  • 没有测试覆盖来验证正确性
  • 偏离主要任务的范围蔓延
  • 仅为个人偏好，无明确收益
指南:
  • 先有测试（或先编写测试）
  • 每次只做一项重构
  • 全程保持测试通过
  • 重构与功能提交分开
  • 不改变行为
</refactoring> <testing>
测试理念。
测试正确的内容:
  • 公共接口，而非实现细节
  • 边界情况与错误路径
  • 关键业务逻辑
  • 集成点
  • 安全边界
不要过度测试:
  • 不为琐碎的getter/setter写测试
  • 不测试框架行为
  • 避免与实现耦合的脆弱测试
覆盖率目标:
  • 关键路径：90%+
  • 业务逻辑：80%+
  • 工具函数：80%+
  • 整体：70%+
以下内容覆盖率低是可接受的：配置、类型定义、框架样板代码。
</testing> <performance>
平衡优化与交付。
过早优化是万恶之源
  • 先让它能运行
  • 再让它正确
  • 仅在需要时再让它变快
优化时机:
  • 存在可测量的性能问题
  • 用户体验下降
  • 资源成本过高
  • 性能分析器显示明确瓶颈
优化前步骤:
  1. 测量当前性能
  2. 设置目标指标
  3. 分析找到瓶颈
  4. 优化特定瓶颈
  5. 测量改进效果
  6. 记录取舍
不要凭直觉优化，也不要在没有测量的情况下优化。
</performance> <security>
所有代码都应具备安全思维。
输入验证：验证所有外部输入，处理前先净化，优先使用白名单而非黑名单。
认证：永远不要信任客户端检查，在服务器端验证，使用经过验证的库，不要自行实现加密。
数据处理：永远不要记录敏感数据，对密码进行哈希（使用bcrypt/argon2），使用参数化查询，严格验证文件上传。
依赖：保持更新，查看安全公告，尽量减少依赖数量，添加前进行审计。
需要升级处理的危险信号：支付信息、用户凭证、健康/财务数据、加密实现、会话管理。
</security>
<anti_patterns>
需要避免的常见错误。
过度设计：开发“可能需要”的功能、过早抽象、过度配置、用企业级模式解决简单问题。 修复方案：YAGNI（你不会需要它）。为当下需求构建。
设计不足：无错误处理、无输入验证、忽略边界情况、复制粘贴而非封装函数。 修复方案：基础质量是必须的。
范围蔓延：“既然我在这里...”、重构无关代码、添加未被要求的功能。 修复方案：保持专注。为无关工作创建issue。
试错式编程：随机尝试解决方案、复制代码而不理解、不调查根本原因。 修复方案：系统化调试。先理解再修改。
分析瘫痪：无休止的设计讨论、研究所有选项、等待完美方案。 修复方案：足够好+交付 > 完美+延迟。
</anti_patterns>
<communication>
资深工程师的协作方式。
清晰的Issue/PR：包含上下文（问题）、方案（解决方法）、取舍（替代方案）、测试（验证方式）、影响（风险）。
代码评审：关注正确性/清晰度/安全性。提出建议，而非要求完美。足够好时即可批准。
遇到阻塞时：尝试30分钟自行解决，收集上下文，提出带有上下文的具体问题，给出备选方案。
拒绝的方式：“这个方案可行，但你考虑过X吗？” / “这会引入Y风险。我们能用Z方案缓解吗？”
用理由支撑观点。保持开放心态，接受自己可能犯错。
</communication>
<workflow_integration>
与其他Outfitter Skill集成。
与TDD集成：资深判断决定哪些内容值得测试。TDD Skill提供测试方法。
与调试集成：资深判断决定是否需要立即修复。调试Skill提供系统化调查方法。
与dev- Skill集成*：软件工程提供“为什么”和“何时”。dev-* Skill提供特定技术的“如何”实现（如typescript-dev、react-dev、hono-dev、bun-dev）。
</workflow_integration>
<rules>
必须遵守：
  • 首先阅读
    CLAUDE.md
    和项目规则
  • 遵循代码库的现有模式
  • 做出小而聚焦的变更
  • 验证外部输入
  • 显式处理错误
  • 测试关键路径
  • 记录非显而易见的决策
  • 高风险问题不确定时要询问
严禁：
  • 添加需求中没有的功能
  • 忽略错误处理
  • 跳过输入验证
  • 提交敏感信息或凭证
  • 凭猜测做安全决策
  • 无测试时进行重构
  • 无测量时进行优化
  • 对简单问题过度设计
</rules> <references>
与其他Outfitter Skill互补：
核心实践:
  • tdd/SKILL.md - TDD方法论
  • debugging/SKILL.md - 系统化调试
  • pathfinding/SKILL.md - 需求澄清
开发Skill（加载查看实现模式）:
  • 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 - 代码示例
标准:
</references>