pr-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Quality Review

PR质量审查

Perform a comprehensive quality review of a pull request or feature branch. This skill covers production readiness, code quality, UX, documentation, tests, and safety.

The review is structured as a checklist across seven dimensions. For each dimension, investigate the actual code and report specific findings -- not just "looks good" but concrete observations with file paths and line numbers.

对拉取请求（PR）或功能分支进行全面的质量审查。本Skill涵盖生产就绪性、代码质量、用户体验（UX）、文档、测试和安全性等方面。

审查按七个维度的清单展开。对于每个维度，需检查实际代码并报告具体发现——不能只说「看起来不错」，要附上文件路径和行号的具体观察结果。

Getting Started

开始使用

First, understand the scope of the change:

bash

undefined

首先，了解变更范围：

bash

undefined

What branch are we on, what's the base?

当前所在分支是什么，基准分支是什么？

git branch --show-current git log main..HEAD --oneline

What files changed?

哪些文件有变更？

git diff main...HEAD --stat

Full diff for review

完整差异用于审查

git diff main...HEAD


If reviewing a remote PR, fetch it first:

```bash
gh pr view <number> --json title,body,files
gh pr diff <number>

Read the PR description and all commits to understand the intent before diving into code.

git diff main...HEAD


如果审查远程PR，先拉取：

```bash
gh pr view <number> --json title,body,files
gh pr diff <number>

在深入代码之前，先阅读PR描述和所有提交记录以理解变更意图。

Review Dimensions

审查维度

Work through each dimension below. For each one, report a status:

Pass -- meets the bar, no issues
Needs work -- specific issues found (list them)
N/A -- not applicable to this change

逐一处理以下每个维度。针对每个维度，报告状态：

通过——符合标准，无问题
需改进——发现具体问题（列出问题）
不适用——与本次变更无关

1. Production Readiness

1. 生产就绪性

Does this code behave correctly and handle failure gracefully?

Error handling: Are all errors checked? Are they wrapped with context (
```
fmt.Errorf("context: %w", err)
```
)? Do they surface actionable messages to users?
Edge cases: Empty inputs, nil values, missing config, network failures, API rate limits, large datasets, pagination boundaries
Safety checks: All mutating commands (create, edit, apply, delete, update) must include safety checks after
```
LoadConfig()
```
and before client operations. Pattern:
go
```
checker, err := NewSafetyChecker(cfg)
if err := checker.CheckError(safety.OperationXXX, safety.OwnershipUnknown); err != nil { return err }
```
Verify correct operation type. Skip only in dry-run paths.
No stdout in library code:
```
pkg/
```
must return data, not print. Only
```
cmd/
```
handles output.
No hardcoded secrets or customer data: No real names, env IDs, tokens, or emails in code or tests. Use
```
@example.invalid
```
for emails (RFC 2606).

代码是否能正确运行并优雅处理故障？

错误处理：是否检查了所有错误？是否用上下文包装错误（
```
fmt.Errorf("context: %w", err)
```
）？是否向用户展示可操作的信息？
边缘情况：空输入、nil值、缺失配置、网络故障、API速率限制、大型数据集、分页边界
安全检查：所有变更命令（创建、编辑、应用、删除、更新）必须在
```
LoadConfig()
```
之后、客户端操作之前包含安全检查。模式：
go
```
checker, err := NewSafetyChecker(cfg)
if err := checker.CheckError(safety.OperationXXX, safety.OwnershipUnknown); err != nil { return err }
```
验证操作类型是否正确。仅在试运行路径中可跳过。
库代码中无标准输出：
```
pkg/
```
目录下的代码必须返回数据，而非打印输出。仅
```
cmd/
```
目录处理输出。
无硬编码密钥或客户数据：代码或测试中不得包含真实姓名、环境ID、令牌或邮箱。邮箱使用
```
@example.invalid
```
（符合RFC 2606标准）。

2. Code Quality

2. 代码质量

Is the code clean, idiomatic, and maintainable?

Go idioms: Follows Effective Go and Go Code Review Comments
Naming: Descriptive names, Go conventions (camelCase unexported, PascalCase exported),
```
-er
```
suffix for interfaces
File size: Files should be under 500 lines. Large files should be split.
Imports: Standard library first, then third-party, then internal (
```
github.com/dynatrace-oss/dtctl
```
)
Duplication: Look for copy-pasted code that should be extracted into helpers
Comments: Exported functions/types documented. Comments explain "why" not "what".
Consistent patterns: New code should follow existing patterns in the codebase. Check similar resources in
```
pkg/resources/
```
for reference implementations.

Run the linter to catch issues the eye might miss:

bash

make lint-strict

代码是否简洁、符合语言习惯且易于维护？

Go语言规范：遵循Effective Go和Go Code Review Comments
命名：描述性名称，符合Go约定（未导出标识符用小驼峰camelCase，导出标识符用大驼峰PascalCase），接口使用
```
-er
```
后缀
文件大小：文件应少于500行。大文件应拆分。
导入顺序：先标准库，再第三方库，最后内部库（
```
github.com/dynatrace-oss/dtctl
```
）
代码重复：查找应提取为辅助函数的复制粘贴代码
注释：导出的函数/类型需有文档注释。注释解释「为什么」而非「是什么」。
模式一致性：新代码应遵循代码库中的现有模式。可参考
```
pkg/resources/
```
中的类似资源实现。

运行检查器以发现肉眼可能遗漏的问题：

bash

make lint-strict

3. User Experience

3. 用户体验

Does this feel right from the user's perspective?

Command naming: Follows the
```
dtctl <verb> <resource>
```
pattern. No custom query flags -- use DQL passthrough.
Output formatting: Table output is readable, columns make sense, no misalignment. JSON/YAML output is clean.
Error messages: Clear, actionable, suggest next steps. In agent mode (
```
-A
```
), errors are structured JSON with machine-readable codes.
Interactive behavior: Name resolution, disambiguation prompts work.
```
--plain
```
disables interactive behavior.
Help text: Command has a
```
Short
```
description,
```
Long
```
description, and
```
Example
```
field. Parent verb commands have examples.
Aliases: Resource has sensible aliases (e.g.,
```
wf
```
for workflow,
```
dash
```
for dashboard).
Agent mode: Commands support
```
--agent
```
envelope with contextual suggestions. Test with
```
-A -o json
```
.
Color control: Respects
```
NO_COLOR
```
,
```
FORCE_COLOR
```
,
```
--plain
```
, and TTY detection.

Try running the actual commands to see how they feel:

bash

undefined

从用户角度看，体验是否良好？

命令命名：遵循
```
dtctl <动词> <资源>
```
模式。不使用自定义查询标志——使用DQL透传。
输出格式：表格输出易读，列合理，无对齐问题。JSON/YAML输出整洁。
错误信息：清晰、可操作，建议下一步操作。在Agent模式（
```
-A
```
）下，错误为结构化JSON，包含机器可读代码。
交互行为：名称解析、歧义提示正常工作。
```
--plain
```
参数可禁用交互行为。
帮助文本：命令包含
```
Short
```
描述、
```
Long
```
描述和
```
Example
```
字段。父动词命令需有示例。
别名：资源有合理的别名（例如，
```
wf
```
代表workflow，
```
dash
```
代表dashboard）。
Agent模式：命令支持带有上下文建议的
```
--agent
```
封装。使用
```
-A -o json
```
测试。
颜色控制：遵循
```
NO_COLOR
```
、
```
FORCE_COLOR
```
、
```
--plain
```
参数以及TTY检测。

尝试运行实际命令以感受体验：

bash

undefined

Does the help text look good?

帮助文本是否清晰？

dtctl <command> --help

Does table output look right?

表格输出是否正常？

dtctl <command> --plain

Does agent mode work?

Agent模式是否正常工作？

dtctl <command> -A

undefined

dtctl <command> -A

undefined

4. Test Coverage

4. 测试覆盖率

Are the changes well-tested?

Unit tests: New functions have tests. Table-driven tests preferred.
Coverage targets: 70% minimum overall, 80% for new packages, 90% for critical packages (
```
pkg/client
```
,
```
pkg/config
```
).
Edge case tests: Not just happy paths -- test error conditions, empty inputs, boundary values.
Mock server guards: Paginated mock servers must reject invalid parameter combinations (e.g.,
```
page-size
```
+
```
page-key
```
). Settings API mocks must also reject
```
schemaIds
```
/
```
scopes
```
with
```
nextPageKey
```
.
Golden tests: If output formatting changed or a new resource was added, golden files must be updated. Check:
bash
```
go test ./pkg/output/ -run TestGolden
```
Golden tests use real production structs from
```
pkg/resources/*
```
-- never test-only duplicates.
E2E tests: Integration scenarios in
```
test/e2e/
```
for new resources or complex workflows.

bash

undefined

变更是否经过充分测试？

单元测试：新函数有测试。优先使用表驱动测试。
覆盖率目标：整体最低70%，新包最低80%，关键包（
```
pkg/client
```
、
```
pkg/config
```
）最低90%。
边缘情况测试：不仅测试正常路径——还要测试错误条件、空输入、边界值。
Mock服务器防护：分页Mock服务器必须拒绝无效参数组合（例如，
```
page-size
```
+
```
page-key
```
）。Settings API Mock还必须拒绝带有
```
nextPageKey
```
的
```
schemaIds
```
/
```
scopes
```
。
Golden测试：如果输出格式变更或添加了新资源，必须更新Golden文件。检查：
bash
```
go test ./pkg/output/ -run TestGolden
```
Golden测试使用
```
pkg/resources/*
```
中的真实生产结构体——绝不要使用仅用于测试的副本。
端到端（E2E）测试：对于新资源或复杂工作流，在
```
test/e2e/
```
中添加集成场景。

bash

undefined

Run full suite

运行完整测试套件

go test ./...

Check coverage

检查覆盖率

make test-coverage

undefined

make test-coverage

undefined

5. Documentation

5. 文档

Is the change properly documented for users and contributors?

Always required:

CHANGELOG.md: Entry under
```
[Unreleased]
```
following Keep-a-Changelog format. Bold feature name with em dash and description.

Required for new features:

README.md: Updated if the feature is user-facing and significant (new resource type, new command category)
docs/QUICK_START.md: Usage examples for major new features
docs/dev/IMPLEMENTATION_STATUS.md: Feature matrix rows updated
docs/dev/API_DESIGN.md: Design patterns documented if introducing new conventions
docs/TOKEN_SCOPES.md: New scopes documented if the feature requires additional API permissions

Required for new resources:

Resource-specific doc page in
```
docs/
```
or
```
docs/site/_docs/
```
Command reference updated in
```
docs/site/_docs/command-reference.md
```

Required for new AI agent support:

README.md

CHANGELOG.md

docs/QUICK_START.md

docs/dev/API_DESIGN.md

docs/dev/IMPLEMENTATION_STATUS.md

(all five)

变更是否为用户和贡献者提供了适当的文档？

必须完成：

CHANGELOG.md：在
```
[Unreleased]
```
下添加条目，遵循Keep-a-Changelog格式。加粗功能名称，使用破折号和描述。

新增功能需完成：

README.md：如果功能面向用户且重要（新资源类型、新命令类别），需更新。
docs/QUICK_START.md：为重大新功能添加使用示例。
docs/dev/IMPLEMENTATION_STATUS.md：更新功能矩阵行。
docs/dev/API_DESIGN.md：如果引入了新约定，需记录设计模式。
docs/TOKEN_SCOPES.md：如果功能需要额外的API权限，需记录新的权限范围。

新增资源需完成：

在
```
docs/
```
或
```
docs/site/_docs/
```
中添加资源专属文档页面
更新
```
docs/site/_docs/command-reference.md
```
中的命令参考

新增AI Agent支持需完成：

README.md

、

CHANGELOG.md

、

docs/QUICK_START.md

、

docs/dev/API_DESIGN.md

、

docs/dev/IMPLEMENTATION_STATUS.md

（全部五个）

6. GitHub Pages

If the change adds a new user-facing feature, is the documentation site updated?

The site lives in

docs/site/

and deploys via GitHub Actions on pushes to main that touch

docs/site/**

Check:

New doc page: Does the feature need a page in
```
docs/site/_docs/
```
? Use YAML frontmatter with
```
title
```
,
```
layout: docs
```
.
Navigation: Is the new page added to
```
docs/site/_includes/docs-nav.html
```
in the correct section (Getting Started / Resources / Reference)?
Landing page: Does
```
docs/site/index.md
```
need updating? (e.g., new resource in the feature table, new capability mentioned)
Existing pages: Are related pages updated to mention the new feature? (e.g., a new output format should appear on the output-formats page)
Links: All links work, relative paths are correct, no broken references.

如果变更添加了面向用户的新功能，文档站点是否已更新？

站点位于

docs/site/

，当推送至main分支且触及

docs/site/**

时，通过GitHub Actions部署。

检查项：

新文档页面：功能是否需要在
```
docs/site/_docs/
```
中添加页面？使用YAML前置元数据，包含
```
title
```
、
```
layout: docs
```
。
导航：新页面是否添加到
```
docs/site/_includes/docs-nav.html
```
的正确章节（入门指南 / 资源 / 参考）？
首页：
```
docs/site/index.md
```
是否需要更新？（例如，功能表格中添加新资源，提及新功能）
现有页面：相关页面是否更新以提及新功能？（例如，新输出格式应出现在输出格式页面）
链接：所有链接正常工作，相对路径正确，无无效引用。

7. PR Description

7. PR描述

Is the PR itself well-described?

Title: Clear, follows conventional commit style (
```
feat: ...
```
,
```
fix: ...
```
)
Summary: Explains what changed and why (not just what files were touched)
Related issues: References issues with
```
Closes #NNN
```
or
```
Fixes #NNN
```
Breaking changes: Called out explicitly if any
Testing section: Describes how the change was tested
UX examples: Before/after CLI output for user-facing changes

PR本身的描述是否清晰？

标题：清晰，遵循约定式提交风格（
```
feat: ...
```
、
```
fix: ...
```
）
摘要：解释变更内容和原因（不只是提及哪些文件被修改）
相关问题：使用
```
Closes #NNN
```
或
```
Fixes #NNN
```
引用问题
破坏性变更：如有，需明确指出
测试部分：描述变更的测试方式
用户体验示例：面向用户的变更需提供CLI输出的前后对比

Review Output

审查输出

After completing the review, provide a summary in this format:

undefined

完成审查后，按以下格式提供摘要：

undefined

PR Review: <title>

PR审查：<标题>

Dimension	Status	Notes
Production readiness	Pass/Needs work	...
Code quality	Pass/Needs work	...
User experience	Pass/Needs work	...
Test coverage	Pass/Needs work	...
Documentation	Pass/Needs work	...
GitHub Pages	Pass/Needs work/N/A	...
PR description	Pass/Needs work	...

维度	状态	备注
生产就绪性	通过/需改进	...
代码质量	通过/需改进	...
用户体验	通过/需改进	...
测试覆盖率	通过/需改进	...
文档	通过/需改进	...
GitHub Pages	通过/需改进/不适用	...
PR描述	通过/需改进	...

Issues Found

发现的问题

[Dimension] file:line -- description of issue
...

[维度] 文件:行号 -- 问题描述
...

Suggestions (non-blocking)

建议（非阻塞）

Verdict

结论

Ready to merge / Needs revisions (list blockers)


Be direct and specific. Reference exact file paths and line numbers. Distinguish between blocking issues (must fix) and suggestions (nice to have). Don't pad the review with praise -- focus on what needs attention.

可合并 / 需要修订（列出阻塞项）


要直接且具体。引用准确的文件路径和行号。区分阻塞问题（必须修复）和建议（可选优化）。不要在审查中添加多余的赞美——专注于需要关注的内容。