software-development

软件开发

此技能可帮助你按照项目预期进行更改：完成格式化和 lint 检查，将范围控制在满足任务所需的最小程度，针对可能受影响的部分进行验证，使用项目文档记录的命令进行操作，在依赖项快速变化时以最新的供应商文档为依据，并提交一份说明完善的拉取请求。凡是涉及项目的任务，都应使用此技能——它是其他更具体技能的基础。

仅加载任务涉及的参考章节；下方每项都会指向相应的详细说明。

本文档中的关键词“MUST”“MUST NOT”“REQUIRED”“SHALL”“SHALL NOT”“SHOULD”“SHOULD NOT”“RECOMMENDED”“MAY”和“OPTIONAL”，应按照 RFC 2119 中的说明进行解释。

独立操作

一个轮次的成本取决于它承载的上下文大小，而非执行的操作：发出一项操作的轮次，其成本大致等同于发出几项互不相关操作的轮次，因为成本取决于轮次，而不是其中打包的操作。因而，将 N 项互不依赖的操作分散到 N 个轮次中，成本大约是将相同的 N 项操作集中在一个轮次中执行的 N 倍，却不会比单轮执行带来更多收益。

请参阅 independent-operations.md，了解：

• 完整的成本依据——轮次按什么计费，以及乘数为何是轮次数而非操作数
• 如何通过依赖关系测试判断一项操作是否依赖另一项操作的结果，并通过一组正反示例进行说明
• 为什么没有规定每个轮次应包含多少项操作的数值目标
• 如何解决本规则与 change-management.md 中渐进式更改规则之间表面上的冲突

以下内容就是规则本身，而不是进一步阅读的要求：它适用于本技能管辖的每个轮次，而非某种更狭窄的情形——一个轮次要么有可一起发出的相互独立操作，要么没有；本规则决定应如何处理，因此规则直接列于此处，而不是放在一个每个轮次都会触发的链接后面。

准则：

• MUST 在同一个轮次中发出互不依赖的操作，而不是将其拆分到连续的多个轮次中。
• MUST NOT 将某项操作与其他操作打包到同一个轮次中，前提是该操作的目标、参数或必要性取决于另一项操作的结果——这项操作存在依赖，打包执行会导致针对错误目标发出调用，或者发出本不该执行的调用。
• MUST NOT 将此规则理解为允许在进入下一步前跳过对更改的验证：change-management.md 中的“渐进式更改”适用于这种情况；此类步骤从其构造上就存在依赖——是否有必要执行取决于上一步的验证结果，因此它应排除在本规则的批次之外，而非视为例外。

代码质量

请参阅 code-quality.md，了解：

• 任何变更后运行 format → lint → fix → re-lint 循环
• 语言规范合规性和导入整理
• 当承载文本的格式本身没有注释语法时，哪些文本算作注释，以及为什么程序读取为数据的字段不属于注释范围
• 注释的语气——使用小写文字，不用全大写来强调，以及哪些内容应保留其实际大小写
• 注释必须通过的准入测试——内容不能是通过阅读代码或顺着代码即可得出的信息；不符合时应删除，而不是改写
• 源文件中的文档注释和说明性注释规范，包括行注释形式、说明性注释约 300 个字符的文字限额，以及注释主题测试，确保两种注释描述的都是代码，而非产生代码的工作
• TODO(#123): 规范、代码未完成到什么程度才应添加该标记、它必须对应的已跟踪后续事项，以及仍可包含标识符或 URL 的标准形式
• 注释不再适合承载某项规范、领域术语、决策依据或无法精简的文件局部“原因”时，应将其放在何处

变更管理

请参阅 change-management.md，了解：

• 实施缺陷修正、处理评审意见或重构行为
• 将工作限制在任务范围内
• 追溯修正到有证据支持的原因和责任方，而不是修补表面症状
• 选择连贯的解决方案，包括处理共同原因和临时缓解措施
• 以增量方式进行可独立验证的变更
• 优先遵循现有模式，再引入新模式
• 权衡是否添加依赖项

项目文档

请参阅 project-docs.md，了解：

• 执行项目专属操作前，先查阅项目自身的贡献者文档
• 文档未说明时，询问相关人员，而不是自行推断命令
• 经批准后记录答案，让后续任务能在文档中找到相关说明

持续更新的文档

项目还可能维护描述产品本身的文档——产品是什么、其领域使用什么语言、目前如何运行，以及有哪些决策对其有所约束；如果项目将这些内容放在同一目录树中，也可能说明旁边的约定和操作流程采用何种结构。这类文档面向的受众不同于上述贡献者文档，并且有自己的负责人：如果项目提供持续更新文档的能力，该能力会说明何时阅读这些文档、变更需要据此修正哪些内容，以及如何修正。本节仅引导你查阅该能力，不重复其规则。如果项目未提供此类能力，则无需执行任何要求。

指南：

• 只要变更涉及持续更新文档所描述的行为，且项目提供了相应能力，就必须查阅该能力，并遵循其中列明的要求，而不是采用此处的任何摘要。
• 当两类要求均适用时，必须根据时态判断应遵循哪一类：即将构建内容的规范属于项目的产品需求实践；上述能力仅涵盖对现有内容的描述。这里明确说明这一点，而不将其留给任一负责人决定，因为判断错误会导致两者都未被采用。

验证

请参阅 verification.md，了解：

• 如何为缺陷修复或由评审驱动的变更选择验证方式
• 如何根据回归、基线来源、生成内容／本地状态以及不可用路由等证据诊断检查失败，包括基线版本和当前版本中相同的失败
• 如何在选择验证路径前，将变更文件对应到可能受影响的输出形式
• 如何在执行前，为脆弱的义务规划独立的预期结果和具有区分度的检查
• 确认变更完成前所需的手动验证步骤，以及为何通过门禁并不等同于完成验证
• 如何依据适用规则和有效例外检查当前集成输出，并将其与技能获取分开
• 如何根据材料、范围、平台和观测阶段限定证据；跳过或不足的检查应标记为未验证
• 如何检查修正是否实现了预期结果，同时未牺牲必需行为

当前外部文档

请参阅 current-docs.md，了解：

• 何时应查阅项目所依赖的快速演进框架、服务或工具的最新官方文档
• 如何将官方文档视为主要来源，并报告查阅过的内容

提交消息

提交消息的标题格式——包括允许的类型、范围和描述约定、破坏性变更标记、与 SemVer 的对应关系，以及可运行的标题验证器——由项目的 Conventional Commits 实践规定；相同规范也适用于拉取请求标题。编写提交消息或拟定拉取请求标题时，请查阅这项能力；本技能有意不重复说明该格式。

拉取请求描述

请参阅 pull-request-descriptions.md，了解：

• 描述面向的对象——即将阅读差异的开发者——以及由此产生的约 200 词上限
• 拉取请求正文应包含哪些内容，以及为何应先说明“原因”
• 如何在通过 API 撰写的正文中复现代码库的拉取请求模板
• 问题链接、正文中可通过差异验证的标准和指定的代码树外标准及其证据链接、风险披露和评审者指引
• 如何在多轮评审中保持描述内容最新

特定主题技能

请参阅 topic-specific-skills.md，了解：

• 如何在规划、说明、实现、验证或评审之前，依据受影响的职责选择适用技能
• 如何区分有明确边界的结构探索与依赖完整技能正文及适用参考资料的判断
• 如何在新影响的工作出现前重新评估技能选择，而不将初始技能集合视为上限