在编辑代码或开发软件时遵循的工程规范：代码风格、文档与工作流

适用于任何代码编辑、软件仓库操作或软件开发任务，提供代码风格、文档、工作流、代码组织、输出格式与最佳实践的通用原则。

适用场景

解决思路

1. 避免不必要的注释：代码应自文档化，注释仅用于非显而易见的设计决策、变通方案或复杂逻辑，不要重复代码已明显表达的内容。
2. 保持代码库整洁：除非被明确指示，否则不要在提交的代码中留下 TODO、FIXME 或临时注释；要么实现功能、要么创建 issue、要么删除注释；忽略已存在的此类注释。
3. 编写自文档化代码：优先使用清晰的命名和结构而非解释性注释；方法、类和成员的文档应遵循语言/技术栈的最佳实践；除非解释令人困惑或复杂的行为，否则不要在语句旁添加无用的行内注释。
4. 文档要简洁有用：文档应有信息量但不冗长；README 应聚焦必要信息，避免不必要的赘述。
5. 以结构代替冗长：优先使用组织良好、可快速浏览、标题清晰的文档，而非长段落；用简短示例说明概念。
6. 检测工作流：检查项目是否使用 spec-first、TDD 或其他结构化工作流，查找 docs/ 或 specs/ 目录中的规格、代码库中的测试优先模式、计划文件或结构化文档；若存在则遵循现有工作流模式。
7. 不做 git 修改：除非被明确指示，否则不要使用会修改仓库状态的 Git 命令（如 git add、git commit、git push）；专注于直接编辑代码；允许并鼓励使用 git status、git diff 等状态和差异命令进行分析。
8. 基于事实：不要臆造或假设；如果不了解某框架或技术或需要额外上下文，搜索网络或使用 context7 获取最新文档；如果需要澄清，在修改前询问用户。
9. 建设性分歧：如果存在更好的替代方案，不要只是接受用户指示；在审阅请求后，解释为什么替代方案可能更好，并提供技术论证。
10. 停下来询问：在以下情况停下来询问用户：不确定如何继续；即将添加类型忽略、抑制或 any 类型；需求不清晰；存在更好方案但需要确认。
11. 向后兼容：仅对面向公众的接口（API、库）考虑向后兼容；对于全新/内部重构，除非被明确指示，否则以单元、集成和 E2E 测试作为确认关卡。
12. 单一职责：组件和函数应有单一、明确的目的；将代码组织到逻辑目录中，清晰分离关注点。
13. 一致的模式：遵循代码库中已建立的模式；引入新模式时，确保其与现有架构和约定一致。
14. 自动化与效率：优先使用自动化方案和高效工作流；寻找减少手工工作和改善开发者体验的机会。
15. 不使用 emoji：除非被明确指示，否则不要在代码或输出中使用 emoji。
16. Unicode 符号：面向用户的输出可接受 Unicode 符号（✓、✗、→、⚠）。
17. 颜色与格式：鼓励在面向用户的输出中使用颜色和格式。
18. 支持 NO_COLOR：始终尊重 NO_COLOR 环境变量。
19. 不硬编码 ANSI：绝不使用硬编码的 ANSI 颜色代码——使用颜色库（chalk、colors 等）。
20. 框架约定：遵循框架和语言的最佳实践；按预期使用框架特性，而不是绕过它们。
21. 性能意识：考虑代码变更的性能影响，尤其是 Web 应用；尽可能优先使用静态生成和最少 JavaScript。
22. 可访问性：确保代码默认可访问；使用语义化 HTML、正确的 ARIA 属性，并测试键盘导航。