ub-quality

UB Quality

关键约定

每当加载此 SKILL.md 时，立即应用其中的基线规则。

对于需要遵循更深入质量规则的工作，在生成输出前，按照此技能中的触发表加载相关参考文档。不要因为任务看起来简单或本地风格不同而跳过已触发的参考文档。

对于每个已修改且符合条件的竖线分隔块，分隔符必须对齐在同一列。使用分隔符列对齐（key : value），而不是值列对齐（key: value）。

当结构符合条件时，这适用于代码、配置、注释、文档字符串、标记语言属性和文档块。

将 <style> 和 <script> 等嵌入式语言块视为原生 CSS 和 JavaScript 格式区域，而不是通用 HTML 文本。

只有语法错误或经过验证的工具或运行时限制，才可以成为不对齐符合条件的已修改块的理由。

符合要求：

grid      : ''
solar     : ''
textMuted : ''

不符合要求：

grid:      ''
solar:     ''
textMuted: ''

适用场景

在执行以下工作时，将此技能与主要实现、审查或工作流技能配合使用：

• 生成新代码
• 修改和重构代码
• 回复代码审查意见
• 扫描仓库、解释架构以及提供可维护性反馈
• 规范化已修改区域中的文档、配置、注释和格式
• 提升面向用户的回复的结构清晰度或对比格式

每当你创建、修改、审查、重构或规范化代码或文档，且任务可从共享的质量或可读性规则中受益时，都应应用此技能。

不得视为可选项

• 不要将格式和对齐视为可选的清理工作。
• 加载此技能后，其格式和对齐规则适用于所有已修改且符合条件的块。
• 不要因为附近代码未对齐、较短的风格看起来更熟悉，或块位于文档而非代码中，就跳过对齐。
• 除非明确要求进行更广泛的规范化，否则不要规范化已修改逻辑范围之外的无关块。

参考文档加载约定

ub-quality 本身始终作为已加载的基线规则。更深入的参考文档不是可选项；应根据触发条件加载，以便在正确的时间应用相应约定，而不是将每项任务都视为涉及所有质量子领域。

必须加载并应用：

• 在进行架构、实现、重构、抽象、依赖或可维护性决策时，加载 references/design-patterns.md。
• 在创建或修改代码、配置、示例、注释、文档字符串、标记语言属性、文档表格，或任何其他包含符合条件的分隔符块的已修改内容前，加载 references/formatting-alignment.md。
• 在创建、编辑、审查、重组或重构文档、注释、文件结构、公共调用接口或大型源文件前，加载 references/documentation-structure-refactoring.md。
• 在创建或修改生成的文档、注释标签、类似 TODO 的标记，或任何可能包含特殊保留标签的内容前，加载 references/important-tags-and-doc-generation.md。
• 在编写较长的面向用户的计划、审查、说明、对比，或任何结构会显著影响可浏览性的答复前，加载 references/response-readability.md。
• 在判断某条指南属于仓库策略、强烈建议的项目默认规范、时效性建议还是可移植性考量时，加载 references/freshness-portability.md。

如果触发条件不止一个，则必须在生成相关输出前加载所有适用的参考文档。

不合规

在符合对齐条件的已修改代码块中，以下情况均属不合规：

• 符合条件的垂直分隔符代码块，其分隔符未对齐成同一列。
• 符合条件的代码块中，值列未对齐。
• 已修改内容符合对齐条件，但未将嵌入的 CSS/JS 代码块按原生语言代码块格式化。
• 因图省事、疏漏或沿用周边局部风格而跳过对齐。
• 规范化已修改逻辑范围之外的无关代码块。

决策分析基线

对于规划、设计、架构、实施方向和其他需要做出选择的指导：

• 默认提出 2+ 个合理方案。
• 优先提供经过筛选的 2-4 个选项，而不是穷举所有方案。
• 简要列出每个选项的优缺点，并指出推荐方案。
• 如果实质上只有一条有意义的路径，请明确说明，并解释为什么其他方案并无实质区别，而不是臆造一组选项。
• 如果同类技能能提供真正有价值的领域特定权衡维度，可允许其补充。

可读性基线

对于聊天、规划、评审、规范和解释等面向用户的回复：

• 开门见山地给出答案、建议或要点。
• 内容较多时使用信息明确的标题。
• 段落简短，并在视觉上分隔清楚。
• 集合使用项目符号，步骤顺序使用编号列表。
• 列表项在语法和意图上保持一致。
• 仅在确实需要比较多个属性且能保持简洁时使用表格。
• 如果结构化排版有助于浏览，避免堆砌密集文本。
• 简短回答应保持精炼，避免形式主义排版。

表格规则：

• 仅当紧凑表格能显著改善并排比较时才使用。
• 表格通常保持 2-4 列，列标题简短，单元格内容精炼。
• 不要将整句说明硬塞进表格单元格。
• 表格变得过宽、过密或难以稳定渲染时，应转换为更稳妥的结构，而不是强行保留表格。

核心工作流

1. 检查任务范围和已修改文件。
2. 立即应用内嵌基线。
3. 在生成依赖这些参考的内容之前，加载并应用任务触发的所有参考。
4. 对于规划、设计、架构、实施方向和其他需要做出选择的指导，应用决策分析基线。
5. 对于面向用户的回复，应用可读性基线，并据此选择表格或更稳妥的结构。
6. 选择能保留行为和约束的最简单方案。
7. 仅在已修改的逻辑代码块中应用格式、文档和结构规则。
8. 验证行为，并说明触发的参考允许的任何有意例外。

技能协作

• 如有最相关的语言/框架技能，请与本技能一并应用。
• 将本技能视为配套基线，而非主要实现或工作流技能的替代品。
• 将语法、运行时和框架正确性视为首要约束。
• 不要将格式化工具偏好或惯用团队风格视为违反对齐约定的正当理由。
• 优先通过代码和命名表达机制，再用文档和注释说明约定、理由及不明显的约束。

政策与默认做法

• 在本仓库中，加载 ub-quality 后，对齐约定和触发参考的工作流属于仓库政策。
• 通过同类技能协同提供的许多语言/框架建议是强默认做法，而非普遍适用的可移植性要求。
• 应首先将易变的设置步骤视为需要检查时效性的内容，而不是自动判定为阻塞项，除非仓库明确将其提升为政策。

输出要求

生成或修改代码时：

1. 对有意义的实现选择，简要说明优缺点并给出建议。
2. 保持方案简单，避免过度设计。
3. 除非明确要求更改，否则保留现有行为。
4. 指明有意保留的技术债务或推迟的清理工作。
5. 优先提供高信息密度的文档，避免泛泛叙述，尤其是在共享指南和复用频繁的代码中。
6. 让面向用户的说明便于快速浏览，然后再深入阅读。
7. 根据所含信息调整结构，不要默认使用密集的段落或过大的表格。

完成前检查

完成前：

• 检查每个被修改且符合条件的分隔符块。
• 将已修改的 <style> 和 <script> 内容视为原生 CSS 和 JavaScript 代码区域。
• 如有必要，按照 references/formatting-alignment.md 的要求，将可写成多行的密集结构（例如字面量、参数列表和配置／数据块）展开为每项一行，然后对齐符合条件的条目。
• 按照 references/formatting-alignment.md 中的最长左侧标记规则，将分隔符对齐到同一列。
• 确认没有规范化无关代码块。
• 如果仍有符合条件的代码块未对齐，则编辑尚未完成，除非 references/formatting-alignment.md 中列明了适用的例外。
• 确保遵守特殊注释标签和 AGENT_TODO 处理政策。
• 在面向用户的回复中，尽早给出答案或建议。
• 仅在有助于提高可读性时，使用标题、项目符号、步骤、表格或备用结构。
• 确认列表项结构平行且简洁。
• 确认表格能提高可读性，而不是增加宽度或信息密度问题。
• 如果对比表变得过宽或文本过多，请改用分层的备用结构，而不是勉强保留表格。
• 简短回答应保持简短。