qa-quick

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Systematic Project QA

系统化项目QA

Procedures

流程

Step 1: Discover the Repository QA Contract

Read root instructions, repository docs, and CI/build files before running commands.
Execute
```
python3 scripts/discover-project-contract.py --root .
```
to surface candidate install, verify, build, test, lint, and start commands.
Prefer repository-defined umbrella commands such as
```
make verify
```
,
```
just verify
```
, or CI entrypoints over language-default commands.
Read
```
references/project-signals.md
```
when command ownership is ambiguous or when multiple ecosystems are present.
Identify the changed surface and the regression-critical surface before choosing scenarios.
Choose a QA artifact location using repository conventions. If the repository has no QA artifact convention, store scratch artifacts under
```
/tmp/codex-qa-<slug>
```
.

Step 2: Define the QA Scope

Build a short execution matrix covering baseline verification, changed workflows, and unchanged business-critical workflows.
Read
```
references/checklist.md
```
and ensure every required category has a planned validation.
Prefer public entry points such as CLI commands, HTTP endpoints, browser flows, worker jobs, and documented setup commands over internal test helpers.
Create the smallest realistic fixture or fake project needed to exercise the workflow when the repository does not already include one.
Treat mocks as a local unit-test boundary only. Do not use mocks or stubs as final proof that a user flow works.

Step 3: Establish the Baseline

Install dependencies with the repository-preferred command before testing runtime flows.
Run the canonical verification gate once before scenario testing to establish baseline health.
If the baseline fails, read the first failing output carefully and determine whether it is pre-existing or introduced by current work before moving on.
Start services in the closest supported production-like mode and confirm readiness through observable signals such as health checks, startup logs, or successful handshakes.

Step 4: Execute User-Like Flows

Drive workflows through the same interfaces a real operator or user would use.
Capture the exact command, input, and observable result for each scenario.
Validate changed features first, then validate at least one regression-critical flow outside the changed surface.
Exercise live integrations when credentials and local prerequisites exist. When they do not, validate every reachable local boundary and record the blocked live step explicitly.
Re-run the scenario from a clean state when the first attempt leaves the environment ambiguous.

Step 5: Diagnose and Fix Regressions

Reproduce each failure consistently before proposing a fix.
Activate companion debugging and test-hygiene skills when available, especially root-cause debugging and anti-workaround guidance.
Add or update the narrowest regression test that proves the bug when the repository supports automated coverage for that surface.
Fix production code or real configuration at the source of the failure. Do not weaken tests to match broken behavior.
Re-run the narrow reproduction, the impacted scenario, and the baseline gate after each fix.
Use
```
assets/issue-template.md
```
when the user wants persisted issue files or when the repository already has a QA issue convention.

Step 6: Verify the Final State

Re-run the full repository verification gate from scratch after the last code change.
Re-run the most important user-like scenarios after the full gate passes.
Summarize the evidence using
```
assets/verification-report-template.md
```
.
Report blocked scenarios, missing credentials, or environment gaps with the exact command or prerequisite that stopped execution.
Do not claim completion without fresh verification evidence from the current state of the repository.

步骤1：发现仓库QA契约

在运行命令前，阅读根目录说明、仓库文档和CI/构建文件。
执行
```
python3 scripts/discover-project-contract.py --root .
```
以获取候选的安装、验证、构建、测试、lint和启动命令。
优先使用仓库定义的统一命令，如
```
make verify
```
、
```
just verify
```
或CI入口点，而非语言默认命令。
当命令归属不明确或存在多个生态系统时，阅读
```
references/project-signals.md
```
。
在选择测试场景前，确定变更范围和回归关键范围。
使用仓库约定选择QA产物存储位置。若仓库无相关约定，则将临时产物存储在
```
/tmp/codex-qa-<slug>
```
下。

步骤2：定义QA范围

构建一个简短的执行矩阵，涵盖基线验证、变更工作流和未变更的业务关键工作流。
阅读
```
references/checklist.md
```
，确保每个必填类别都有计划好的验证环节。
优先使用公开入口点，如CLI命令、HTTP端点、浏览器流程、worker任务和文档化的设置命令，而非内部测试辅助工具。
当仓库未包含所需内容时，创建最小化的真实测试数据（fixture）或模拟项目来演练工作流。
仅将mocks视为本地单元测试边界，不要将mocks或stubs作为用户流程正常工作的最终证明。

步骤3：建立基线

在测试运行时流程前，使用仓库首选命令安装依赖。
在场景测试前先运行一次标准验证流程，以确定基线健康状态。
若基线失败，仔细查看首个失败输出，在继续操作前判断该问题是预先存在的还是当前工作引入的。
以最接近生产环境的支持模式启动服务，并通过可观测信号（如健康检查、启动日志或成功握手）确认服务就绪。

步骤4：执行类用户流程

通过真实操作员或用户会使用的相同界面驱动工作流。
记录每个场景的精确命令、输入和可观测结果。
先验证变更的功能，然后至少验证一个变更范围外的回归关键流程。
当存在凭据和本地先决条件时，演练实时集成。若不存在，则验证所有可访问的本地边界，并明确记录受阻的实时步骤。
当首次尝试导致环境状态不明确时，从干净状态重新运行场景。

步骤5：诊断并修复回归问题

在提出修复方案前，先持续复现每个失败案例。
若有配套的调试和测试卫生技能可用，尤其是根源调试和反 workaround 指导，可激活这些技能。
当仓库支持该范围的自动化覆盖率时，添加或更新最精准的回归测试以证明漏洞已修复。
在失败根源处修复生产代码或真实配置，不要为了匹配错误行为而弱化测试。
每次修复后，重新运行窄范围复现案例、受影响的场景以及基线验证流程。
当用户需要持久化问题文件或仓库已有QA问题约定时，使用
```
assets/issue-template.md
```
。

步骤6：验证最终状态

在最后一次代码变更后，从头重新运行完整的仓库验证流程。
在完整流程通过后，重新运行最重要的类用户场景。
使用
```
assets/verification-report-template.md
```
总结验证证据。
报告受阻场景、缺失凭据或环境缺口，并附上导致执行停止的精确命令或先决条件。
若没有来自仓库当前状态的新鲜验证证据，请勿宣称完成。

Error Handling

错误处理

If command discovery returns multiple plausible gates, prefer the broadest repository-defined command and explain the tie-breaker.
If no canonical verify command exists, read
```
references/project-signals.md
```
, choose the broadest safe install, lint, test, and build commands for the detected ecosystem, and state that assumption explicitly.
If a required live dependency is unavailable, validate every local boundary that does not require the missing dependency and report the blocked live validation separately.
If a workflow requires data or services absent from the repository, create the smallest realistic fixture outside the main source tree unless the repository has its own fixture convention.
If a failure appears unrelated to the requested change, prove that with a clean reproduction before excluding it from the QA scope.

若命令发现返回多个合理的验证流程，优先选择最全面的仓库定义命令，并解释取舍依据。
若不存在标准验证命令，阅读
```
references/project-signals.md
```
，为检测到的生态系统选择最全面的安全安装、lint、测试和构建命令，并明确说明该假设。
若所需的实时依赖不可用，验证所有不需要该缺失依赖的本地边界，并单独报告受阻的实时验证环节。
若工作流需要仓库中不存在的数据或服务，除非仓库有自己的测试数据（fixture）约定，否则在主源码树外创建最小化的真实测试数据。
若失败案例似乎与请求的变更无关，在将其排除出QA范围前，需通过干净环境复现来证明这一点。