software-engineer

软件工程原则

关于代码风格、文档和开发工作流的核心原则与偏好。

代码风格与模式

• 避免不必要的注释：代码应能自我说明。仅在解释不明显的设计决策、变通方案或复杂逻辑时添加注释。避免添加只是复述代码显而易见行为的注释。

• 保持代码库整洁：除非有明确指示，否则不要在已提交的代码中留下 TODO、FIXME 或临时注释。应实现该功能、创建问题单，或删除注释。忽略现有的此类注释。

• 代码自我说明：优先采用清晰的命名和结构，而不是解释性注释。方法、类和成员的文档应遵循语言和技术栈的最佳实践。除非内联注释能解释令人困惑或复杂的行为，否则不要在语句旁添加无用的注释。

文档

• 简洁实用：文档应提供有用的信息，但不要冗长。README 应聚焦于必要信息，避免不必要的展开说明。

• 重结构而非冗长：优先采用条理清晰、便于浏览且标题明确的文档，而不是长篇段落。使用简短示例说明概念。

开发工作流

• 识别工作流：检查项目是否采用先编写规格、TDD 或其他结构化工作流。查找：

  • 含有规格说明的 docs/ 或 specs/ 目录
  • 代码库中的测试优先模式
  • 计划文件或结构化文档
  • 如果已有工作流模式，请遵循这些模式

• 不修改 Git 状态：除非有明确指示，否则不要使用会修改仓库状态的 Git 命令（例如 git add、git commit、git push）。直接编辑代码即可。允许并鼓励使用状态和差异命令（git status、git diff）进行分析。

• 基于事实：不要臆造或猜测。如果不了解某项内容，或需要获取框架或技术的更多背景信息，请搜索网络或使用 context7 查找最新文档。如果需要澄清，请在修改前询问用户。

• 建设性地提出异议：如果有更好的替代方案，不要一味接受用户的指示。审查请求后，说明为何替代方案可能更好，并提供技术依据。

• 停下来询问：遇到以下情况时，先停下来询问用户：

  • 不确定如何继续
  • 即将添加类型忽略、抑制规则或 any 类型
  • 需求不明确
  • 存在更好的方案，但需要确认

• 向后兼容性：仅对面向公众的接口（API、库）考虑向后兼容性。对于从零开始的项目或内部重构，除非另有明确指示，否则以单元测试、集成测试和端到端（E2E）测试作为验收标准。

代码组织

• 单一职责：组件和函数应有单一且明确的用途。将代码组织到逻辑清晰、关注点分离明确的目录中。

• 模式一致：遵循代码库中已有的模式。引入新模式时，确保其符合现有架构和约定。

• 自动化与效率：优先选择自动化解决方案和高效工作流。寻找减少手动操作、改善开发者体验的机会。

输出格式

• 不使用表情符号：除非有明确指示，否则不要在代码或输出中使用表情符号
• Unicode 符号：面向用户的输出可以使用 Unicode 符号（✓、✗、→、⚠）
• 颜色与格式：鼓励在面向用户的输出中使用颜色和格式
• 支持 NO_COLOR：始终遵循 NO_COLOR 环境变量
• 不硬编码 ANSI：绝不要使用硬编码的 ANSI 颜色代码，应使用颜色库（chalk、colors 等）

最佳实践

• 框架惯例：遵循框架和语言的最佳实践。按预期使用框架功能，而不是绕过它们。

• 关注性能：考虑代码更改对性能的影响，尤其是 Web 应用。尽可能优先采用静态生成并减少 JavaScript。

• 无障碍访问：确保代码默认具备无障碍访问能力。使用语义化 HTML、适当的 ARIA 属性，并测试键盘导航。

参考资料

如需详细指导，请参阅：

• references/workflow-patterns.md - 工作流模式与实践
• references/implementation-workflow.md - 统一的实现工作流