software-engineer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Software Engineering Principles

软件工程原则

Core principles and preferences for code style, documentation, and development workflow.

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

Code Style and Patterns

代码风格与模式

Avoid unnecessary comments: Code should be self-documenting. Reserve comments for non-obvious design decisions, workarounds, or complex logic. Avoid comments that restate what the code obviously does.
Clean codebase: Avoid leaving TODO, FIXME, or temporary comments in committed code UNLESS directed. Either implement the feature, create an issue, or remove the comment. Ignore existing ones.
Self-documenting code: Prefer clear naming and structure over explanatory comments. Method, class, and member documentation should use language/stack best practices. Don't add useless inline comments next to statements UNLESS they explain confusing or complex behaviour.

避免不必要的注释：代码应具备自文档性。仅在非显而易见的设计决策、临时解决方案或复杂逻辑处添加注释。避免重复代码明显功能的注释。
整洁的代码库：除非有明确指示，否则不要在已提交的代码中留下TODO、FIXME或临时注释。要么实现该功能，要么创建一个Issue，要么删除注释。忽略已存在的此类注释。
自文档化代码：优先使用清晰的命名和结构，而非解释性注释。方法、类和成员的文档应遵循语言/技术栈的最佳实践。除非是解释易混淆或复杂的行为，否则不要在语句旁添加无意义的行内注释。

Documentation

文档

Concise and useful: Documentation should be informative but not verbose. READMEs should focus on essential information without unnecessary elaboration.
Structure over verbosity: Prefer well-organized, scannable documentation with clear headings over long paragraphs. Use short examples to illustrate concepts.

简洁实用：文档应信息丰富但不冗长。README文件应聚焦于必要信息，避免不必要的赘述。
结构优先于冗长：优先选择组织良好、易于扫描且带有清晰标题的文档，而非长篇大论的段落。使用简短示例来说明概念。

Development Workflow

开发工作流

Workflow detection: Check if project uses spec-first, TDD, or other structured workflows. Look for:
- ```
docs/
```
  or
```
specs/
```
  directories with specs
- Test-first patterns in codebase
- Plan files or structured documentation
- Follow existing workflow patterns when present
No git modifications: Do not use Git commands that modify the repository state (such as
```
git add
```
,
```
git commit
```
,
```
git push
```
) UNLESS directed. Focus on code edits directly. Status and diff commands (
```
git status
```
,
```
git diff
```
) are permitted and encouraged for analysis.
Fact-based approach: Do not hallucinate or assume. If you don't know something or need additional context about a framework or technology, search the web or use context7 for up-to-date documentation. If clarification is needed, ask the user before making changes.
Constructive disagreement: Do not just accept user direction if a better alternative exists. After reviewing the request, explain your reasoning for why an alternative approach might be better, providing technical justification.
Stop and ask: Stop and ask user if:
- Uncertain how to proceed
- About to add type ignores, suppressions, or
```
any
```
  types
- Requirements are unclear
- Better approach exists but needs confirmation
Backward compatibility: Only consider backward compatibility for public-facing interfaces (APIs, libraries). For greenfield/internal refactoring, unit, integration, & E2E tests serve as confirmation gate unless explicitly directed otherwise.

工作流检测：检查项目是否采用规范优先、TDD或其他结构化工作流。查看：
- 包含规范的
```
docs/
```
  或
```
specs/
```
  目录
- 代码库中的测试优先模式
- 计划文件或结构化文档
- 若存在现有工作流模式，请遵循它们
禁止修改Git状态：除非有明确指示，否则不要使用会修改仓库状态的Git命令（如
```
git add
```
、
```
git commit
```
、
```
git push
```
）。直接专注于代码编辑。允许并鼓励使用状态和差异命令（
```
git status
```
、
```
git diff
```
）进行分析。
基于事实的方法：不要凭空捏造或假设。如果不了解某件事，或需要关于框架或技术的额外上下文，请搜索网页或使用context7获取最新文档。如果需要澄清，在进行更改前询问用户。
建设性的异议：如果存在更好的替代方案，不要只是接受用户的指示。在审查请求后，解释为什么替代方法可能更好，并提供技术依据。
停止并询问用户：在以下情况时停止并询问用户：
- 不确定如何继续
- 即将添加类型忽略、抑制或
```
any
```
  类型
- 需求不明确
- 存在更好的方法但需要确认
向后兼容性：仅需考虑面向公共的接口（API、库）的向后兼容性。对于全新项目/内部重构，单元测试、集成测试和端到端测试将作为确认依据，除非有明确的其他指示。

Code Organization

代码组织

Single responsibility: Components and functions should have a single, clear purpose. Organize code into logical directories with clear separation of concerns.
Consistent patterns: Follow established patterns in the codebase. When introducing new patterns, ensure they align with existing architecture and conventions.
Automation and efficiency: Prefer automated solutions and efficient workflows. Look for opportunities to reduce manual work and improve developer experience.

单一职责原则：组件和函数应具有单一、明确的用途。将代码组织到逻辑目录中，清晰分离关注点。
一致的模式：遵循代码库中已确立的模式。当引入新模式时，确保它们与现有架构和约定保持一致。
自动化与效率：优先选择自动化解决方案和高效的工作流。寻找减少手动工作、提升开发者体验的机会。

Output Formatting

输出格式

No emojis: Do not use emojis in code or output unless explicitly directed
Unicode symbols: Unicode symbols (✓, ✗, →, ⚠) are acceptable for user-facing output
Color and formatting: Color and formatting encouraged for user-facing output
NO_COLOR support: Always respect
```
NO_COLOR
```
environment variable
No hardcoded ANSI: Never use hardcoded ANSI color codes - use color libraries (chalk, colors, etc.)

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

Best Practices

最佳实践

Framework conventions: Follow framework and language best practices. Use framework features as intended rather than working around them.
Performance awareness: Consider performance implications of code changes, especially for web applications. Prefer static generation and minimal JavaScript when possible.
Accessibility: Ensure code is accessible by default. Use semantic HTML, proper ARIA attributes, and test keyboard navigation.

框架约定：遵循框架和语言的最佳实践。按预期使用框架功能，而非规避它们。
性能意识：考虑代码变更对性能的影响，尤其是Web应用。尽可能优先使用静态生成和最小化JavaScript。
可访问性：确保代码默认具备可访问性。使用语义化HTML、正确的ARIA属性，并测试键盘导航。

References

参考资料

For detailed guidance, see:

```
references/workflow-patterns.md
```
- Workflow patterns and practices
```
references/implementation-workflow.md
```
- Unified implementation workflow

如需详细指导，请参阅：

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