searxng-mcp-go/docs/agents/code-review.md

241 lines
9.4 KiB
Markdown

# Code Review
Use this guide when an AI agent is asked to review a pull request, branch,
commit, or working-tree diff. Review means finding defects and review-blocking
risks. It is not a summary task, not a style pass, and not a rubber stamp.
## Review Standard
Start from the assumption that the change can be wrong in ways that compile.
Read the actual diff, then read the adjacent code that the diff calls, mutates,
or depends on. A review that only comments on changed lines is incomplete.
A code review must answer:
- Does the patch preserve the existing behavior that callers rely on?
- Does the new behavior match the PR title, body, issue, tests, and docs?
- Does the patch integrate with nearby types, helpers, tests, CI, docs, and ADRs?
- Does it introduce a correctness, reliability, security, or maintainability
risk that should block merge?
Do not approve a change because tests are green. Tests are evidence, not proof.
Use CI to calibrate risk, then inspect the code.
## Required Inputs
For GitHub PR review, inspect at least:
- PR title and body
- Changed files and full diff
- Latest commit SHA and CI status
- Existing review comments when the user asks for follow-up
- Linked issue or ADR when the PR claims to close, implement, supersede, or
challenge one
Use `gh` for GitHub operations. Useful commands:
- `gh pr view <number> --json number,title,body,headRefOid,files,statusCheckRollup,reviewDecision`
- `gh pr diff <number>`
- `gh pr checks <number>`
- `gh pr view <number> --comments`
For local branch or commit review, inspect the merge base and the full patch:
- `git status --short --branch`
- `git diff --stat <base>...HEAD`
- `git diff <base>...HEAD`
- `git show --stat --oneline <commit>`
- `git show <commit>`
## Scope Discipline
Review the patch and the integration surface around it. Read adjacent code until
you can explain how the changed code is reached, what invariants it depends on,
and what tests should fail if it is wrong.
Do not expand into a repository-wide audit unless the user asked for one. If you
notice unrelated problems outside the patch, mention them only when they make the
patch unsafe or misleading.
Do not rewrite the code during review unless the user explicitly asks for fixes.
Review output should be actionable findings, not an unsolicited patch.
## Findings
Lead with findings, ordered by severity. A finding must be specific enough for a
maintainer to act without guessing.
Each finding should include:
- Severity: `[P0]`, `[P1]`, `[P2]`, or `[P3]`
- File and line reference
- The broken invariant or concrete failure mode
- Why this patch introduces or exposes the problem
- The minimal condition that triggers it
Severity:
- `[P0]` blocks everything: data loss, credential exposure, remote code
execution, or a guaranteed production outage.
- `[P1]` must be fixed before merge: incorrect public behavior, CI/release
breakage, security boundary weakening, panic on valid input, race, leak, or
broken compatibility.
- `[P2]` should be fixed before merge: missing edge-case handling, incomplete
tests for risky logic, unclear API contract, brittle workflow, or misleading
documentation.
- `[P3]` is non-blocking: cleanup, clarity, naming, or local maintainability.
Do not invent findings. If you are uncertain, state the assumption and the
evidence needed. If no actionable findings exist, say that directly and name the
residual risk or test gap.
## Output Format
Use this order:
1. Findings
2. Open questions or assumptions
3. Brief summary
4. Tests or CI evidence inspected
Keep summaries short. The value of a review is in the findings.
## Go Review Focus
Pay special attention to failures that AI-generated Go code often misses:
- Ignored errors, especially `result, _ := ...`, unchecked `Close`, unchecked
encoder/decoder writes, and fire-and-forget cleanup.
- Error wrapping that loses the chain. Internal propagation should usually use
`%w`, not `%v`, and add useful context.
- Log-and-return error handling. An error should normally be logged or returned,
not both.
- `:=` shadowing of `err`, config values, or normalized arguments.
- Typed nil values returned as interfaces.
- Nil map writes, nil channel waits, and nil slice JSON behavior when API output
expects `[]`.
- Slice aliasing after `append`, subslice retention, and returned mutable maps or
slices that expose internal state.
- Numeric conversions that can truncate or wrap.
- `time.Time` comparison with `==` instead of `Equal` when monotonic clock data
may differ.
- `strings.Trim` used as if it removed a prefix or suffix.
- Context not passed as the first parameter, not propagated to I/O, or ignored
inside retry/loop/concurrency code.
- Goroutines without a clear owner, cancellation path, wait path, or panic/error
propagation.
- Channel ownership mistakes: receiver closes, missing close, send after close,
missing `ok` check when close is meaningful.
- `time.After` in hot or long-running loops.
- `sync.WaitGroup.Add` inside a goroutine.
- Mutex copied by value receiver, mutex held across I/O, or shared map without
synchronization.
- `http.Get` or default clients without timeout.
- `http.Error` without `return`.
- Resource cleanup deferred inside loops where resources accumulate until
function exit.
- Reflection or `any` used where generics or concrete types would preserve type
safety.
- Positional composite literals for non-local structs.
- Public surface area added without a durable reason.
## Tests in Review
Check whether tests constrain behavior, not just coverage.
Flag tests that:
- Assert implementation details instead of observable behavior.
- Add happy-path coverage while missing error, boundary, cancellation, or
malformed-input cases.
- Use table-driven tests without named cases.
- Depend on execution order, wall-clock sleeps, external network, or shared
mutable state.
- Add flakiness through real time, unbounded goroutines, or retries without
deterministic failure evidence.
- Fail to update golden data when output format changes intentionally.
- Change CLI, MCP schema, formatting, warnings, or defaults without regression
coverage.
For this repository, remember that `golden_capture_test.go` is a byte-for-byte
lock on `formatResults()` output. Any intentional formatting change must update
the inline golden string in that test.
## `//nolint` Review Rules
Treat every new or modified `//nolint` as suspicious until justified.
A `//nolint` is acceptable only when all are true:
- It names the exact linter, for example `//nolint:gocyclo`.
- It includes a specific reason, not a placeholder.
- The reason explains why fixing the root cause would make the code worse or why
the linter is a false positive.
- The suppression is scoped to the smallest possible line or declaration.
- It does not hide correctness, resource lifecycle, security, or error handling
issues.
Flag:
- Bare `//nolint`
- `//nolint` without an explanatory comment
- Vague reasons such as "needed", "ignore", "false positive" without evidence,
"AI generated", or "lint"
- Suppression of `errcheck`, `govet`, `staticcheck`, `bodyclose`,
`sqlclosecheck`, `rowserrcheck`, or security linters unless the justification
is exceptional and verifiable
- File-wide or function-wide suppression where a line-level suppression would
work
- A suppression added next to code that could be made clearer instead
## Documentation and Workflow Review
When a patch changes behavior visible to users, agents, or CI, verify matching
documentation changes. This includes CLI flags, environment variables, defaults,
MCP schema, output formatting, warning text, test commands, release process,
GitHub Actions, and agent instructions.
When a patch changes workflows, check that:
- `uses:` entries are pinned to SHA with a `# vX.Y.Z` comment.
- Go version is fixed, not `stable`.
- Job and step names do not encode version numbers.
- Permissions are minimal and match the operation.
- Agent workflows do not grant write permissions without a documented reason.
- Any workflow that can commit uses an explicit, verified identity.
## Optional Go Skill Corpus
The optional `cc-skills-golang/skills` corpus is useful review context, but it
is not a substitute for repository rules.
GitHub Actions OpenCode workflows install a pinned checkout of
`samber/cc-skills-golang` into `~/.agents/skills/cc-skills-golang`, an OpenCode
auto-discovery path outside the repository working tree. Do not depend on a
maintainer's personal filesystem layout.
On a developer machine, use the corpus only if it is already available or can be
located from the local environment. Do not assume a fixed path and do not require
cloning it into `/tmp`.
When the corpus is available, an AI reviewer must locate and read the relevant
skill files before producing review findings. Start code review with these
review-relevant skills:
- `golang-troubleshooting/references/code-review-flags.md`
- `golang-lint/references/nolint-directives.md`
- `golang-error-handling/SKILL.md`
- `golang-concurrency/SKILL.md`
- `golang-safety/SKILL.md`
- `golang-testing/SKILL.md`
- `golang-code-style/SKILL.md`
Read other `cc-skills-golang` skills when the patch touches their domain, such
as context propagation, CLI behavior, dependency management, security, or
performance.
For coding tasks, do not use this review-focused list as the default. Choose the
skills that match the implementation work, then read them before editing, as
described in `AGENTS.md`.
Repository rules win over generic skill advice, and the PR diff still has
priority over background reading.