quality-test-implementation

多语言代码质量与测试覆盖率

角色

专注于多语言代码库的质量、稳定性和技术债务削减的资深 SRE 工程师。

目标

对目标仓库进行全面改进，以稳定构建、减少静态分析警告、将测试覆盖率提升至对应语言的目标、应用高级架构模式，并生成经过量化的改进报告——但不自动创建拉取请求。

适用场景

• 仓库（.NET、Java 或 Python）积累了警告、代码异味或被抑制的异常。
• 测试覆盖率低于语言目标，需要有计划地提升。
• 发布或交接前必须减少技术债务。
• 必须解决安全 CVE（NU1903、OWASP、Bandit、Safety、Snyk）。

不适用场景： 单个小文件、单次变更审查或快速 Lint 检查。要审查单次变更，请使用 code-review-and-quality。

• 用户用英语请求或提及此技能（例如：“use /quality-test-implementation”、“run quality-test-implementation”）。
• 用户用葡萄牙语请求或提及此技能（例如：“use /quality-test-implementation”、“execute quality-test-implementation”）。

输入

• REPO_NAME：完整名称（owner/repo）。
• BASE_BRANCH：起始分支（默认为 main/develop）。
• OUTPUT_BRANCH：feature/{YYYYMMDD}-{function-name}。
• PRIMARY_LANGUAGE：dotnet、java 或 python。

---

阶段 1 — 准备与环境

1. 如果本地尚未存在 {REPO_NAME}，则将其克隆。
2. 创建工作分支 feature/{YYYYMMDD}-{function-name}。
3. 确定构建/测试工具：
   • .NET：*.sln、*.csproj、Directory.Build.props、global.json。
   • Java：pom.xml（Maven）或 build.gradle*（Gradle）。
   • Python：pyproject.toml、setup.py、requirements*.txt、tox.ini。
4. 仅在测试执行上下文中保留任何 Environment.SetEnvironmentVariable("Testing", "true")（或等效设置）。

---

阶段 2 — 静态分析与警告修复

运行相应的静态分析工具，并修复以下类别的问题。

.NET

类别	代码	修复方法
日志记录	CA2017, S2629, CA2254	使用静态模板和一致的占位符
异步处理	CS4014, CS1998	添加 await 或移除不必要的 async
清理	CS0105, CS0219	移除重复的 using 指令 / 未使用的变量
异常	S3445, S2139	将 throw ex; 替换为 throw;；重新抛出时补充上下文
Web/API	ASP0019	在标头中使用 .Append
安全	NU1903	解决软件包漏洞（高优先级）
文档	—	为公共类和方法添加 /// <summary>

工具：dotnet build、dotnet test、dotnet format、SonarScanner、Roslyn 分析器。

Java

类别	代码 / 工具	修复方法
日志记录	SLF4J 占位符、Checkstyle	使用参数化日志；避免在日志中进行字符串拼接
异步处理	SpotBugs NP_NULL、Sonar S2190	正确串联 CompletableFuture；避免即发即忘的异步操作
清理	PMD、Checkstyle	移除未使用的导入和变量
异常	Sonar S1166、S2221	保留堆栈跟踪；不要吞掉异常
Web/API	Sonar S3751、S2658	使用正确的标头 API；避免可变静态状态
安全	OWASP dependency-check、Snyk	更新存在漏洞的依赖项
文档	Javadoc	为公共类和方法添加 Javadoc

工具：mvn compile、mvn test、mvn spotbugs:spotbugs、mvn checkstyle:checkstyle、mvn org.owasp:dependency-check-maven:check。

Python

类别	代码 / 工具	修复方法
日志记录	Pylint W1203、Ruff G001	正确使用 % / f-string 格式化方式与 logging
异步处理	Pylint W0707、Ruff ASYNC	正确使用 await；避免使用 asyncio 即发即忘
清理	F401、F841（Ruff/Flake8）	移除未使用的导入和变量
异常	Pylint W0706、W0719	使用 raise 重新引发异常，或使用带 from 的 raise Custom()
Web/API	Bandit B104	避免在 CORS 中硬编码 *；验证标头
安全	Bandit、Safety、Snyk	修复 requirements.txt / pyproject.toml 中高危 / 严重的 CVE
文档	Pydocstyle、Ruff D	为公共类和方法添加文档字符串

工具：ruff check .、ruff format .、mypy、pylint、bandit -r .、pytest --cov=src --cov-report=xml。

---

阶段 3 — 架构与风格

仅在能够减少警告或提升可测试性时进行重构。

SOLID

• 单一职责：拆分混合了持久化、业务逻辑和表示层的类 / 模块。
• 依赖倒置：依赖抽象（接口 / 抽象类 / 协议），而非具体实现。

DDD

• 识别聚合、实体、值对象和仓储。
• 保持领域逻辑独立于框架和 UI。

整洁架构

• 验证领域、应用、基础设施和表示层之间的分离。
• 领域不得依赖外部框架、数据库或 UI 库。

---

阶段 4 — 测试与覆盖率

有关特定框架的命令（xUnit/NUnit/MSTest、Maven/Gradle、pytest/unittest）、阈值和 HTML 报告，请参阅 references/ 文件：

• references/coverage-dotnet.md
• references/coverage-java.md
• references/coverage-python.md

使用辅助分发器自动检测技术栈并运行覆盖率检查：

bash references/run-coverage.sh

.NET

dotnet test --collect:"XPlat Code Coverage" --results-directory ./TestResults

Java

mvn test
# or
./gradlew test jacocoTestReport

Python

pytest --cov=src --cov-report=term-missing --cov-report=xml

稳定化规则

• 创建新测试前，先修复现有故障。
• 仅当问题基础设施测试（例如 JWT、外部 API）需要深度重构时，才移除或跳过这些测试，并记录原因。
• 新测试遵循 BDD 风格：给定 / 当 / 则（pt-BR 项目使用 Dado / Quando / Então）。

覆盖率目标

语言	最低目标
.NET	行和分支均为 90%
Java	行和分支均为 85%
Python	行和分支均为 90%

使用 reportgenerator（.NET）、JaCoCo（Java）或 pytest-coverage（Python）生成报告。

---

阶段 5 — 文档与交付

README.md

更新以下内容：

• 仓库结构（带说明的分层目录树）。
• 测试覆盖率表：测试总数、行覆盖率 %、分支覆盖率 %。
• 技术栈列表。
• 业务愿景和技术愿景部分。

CHANGELOG.md

• 遵循 Keep a Changelog
• 使用 Semantic Versioning
• 在 README 中链接变更日志。

最终处理

使用 Conventional Commits：

• feat: — 新功能
• fix: — 缺陷修复
• test: — 测试
• docs: — 文档
• refactor: — 重构
• chore: — 维护任务

限制：不要自动创建 Pull Request。准备提交、更新 README/CHANGELOG，并生成包含所有变更的详细技术摘要，以便用户手动创建 PR。

---

质量检查清单

• 不存在高危 / 严重安全漏洞。
• 静态分析警告已减少到可接受的基线。
• 所有现有测试均通过。
• 已生成覆盖率报告，且达到相应语言的目标。
• README 已更新覆盖率和架构部分。
• CHANGELOG 已更新 Unreleased 变更。
• 提交消息符合 Conventional Commits。

常见错误

错误	后果	如何避免
使用 throw ex; 而不是 raise/throw	堆栈跟踪丢失，根本原因被隐藏	保留原始跟踪重新抛出；添加上下文，不要重置
在日志中拼接字符串	可能产生内存分配开销或类似 SQL 注入的风险，且没有结构化参数	使用参数化日志占位符
自动打开 PR	用户失去对合并时机的控制	生成摘要；让用户打开 PR
在修复失败的测试套件之前添加新测试	基准不稳定，造成虚假的信心	先稳定现有失败项
跳过覆盖率报告	无法证明达到目标	始终生成 cobertura/jacoco/xml 覆盖率报告

参考资料

• references/coverage-dotnet.md — .NET 覆盖率（xUnit/NUnit/MSTest、Coverlet、reportgenerator、阈值）。
• references/coverage-java.md — Java 覆盖率（Maven JaCoCo、Gradle JaCoCo、阈值）。
• references/coverage-python.md — Python 覆盖率（pytest-cov、unittest + coverage.py、mypy、阈值）。
• references/run-coverage.sh — 检测技术栈并运行相应覆盖率命令的调度脚本。

另请参阅

• 如需在合并前审查单项更改，请参阅 code-review-and-quality。
• 如需跨技术栈自动修复 SonarQube 问题，请参阅 sonarqube-autofix。

来源

根据 devin/playbooks/multi-language-quality/PLAYBOOK.md 操作手册改编为 agentskills.io 格式的技能，并遵循目录标准（license: MIT、metadata.version、包含明确 Do NOT use for 条款的三段式 description）。