AgentSkillsCN

Code Review

针对本仓库的 LLM 专属代码审查流程：明确审查要点，以不变量与测试为基础展开反馈，并高效验证变更效果（包括 test-report.json）。

SKILL.md
--- frontmatter
name: Code Review
description: "LLM-focused code review process for this repo: what to check, how to ground feedback in invariants/tests, and how to verify changes efficiently (including test-report.json)."

Code Review Skill

This skill is the canonical guidance for automated and interactive code reviews in this repo. It is written for LLM reviewers (CI bots and local agents).

Quick Start

  • •Read the PR description and ensure it matches .github/pull_request_template.md.
  • •Review the diff focusing on invariants, correctness, and performance-sensitive hotspots.
  • •If you can run commands locally, prefer targeted verification:
    • •ato dev test --llm -k <area> (fast filter)
    • •ato dev compile (if Zig/bindings changed)
    • •ato dev flags (if behavior depends on ConfigFlags)
  • •When summarizing failures/regressions, prefer artifacts/test-report.json over HTML.

What to Prioritize (In Order)

  1. •

    Correctness + invariants

    • •Identify the invariants the changed code is supposed to preserve and check the code that enforces them.
    • •If you can’t find an invariant in-code or in tests, flag it as “missing invariant coverage”.
  2. •

    Performance / scalability

    • •This branch prioritizes speed and maintainability; watch for accidental O(n^2) walks, repeated graph traversals, excessive allocations, or debug logging in hot paths.
    • •Zig/Python boundary changes are especially sensitive (ownership, lifetimes, deinit).
  3. •

    Maintainability

    • •Prefer small, well-named units and clear boundaries (compiler vs graph vs solver vs library).
    • •Avoid adding new “mini frameworks” unless the repo already uses that pattern.
  4. •

    Test coverage

    • •If behavior changed, require a test (or a strong reason it can’t be tested).
    • •Prefer targeted tests near the module; avoid broad end-to-end tests unless necessary.

Repo-Specific Review Anchors

  • •Dev workflow + reports: ato dev test --llm writes artifacts/test-report.json and artifacts/test-report.llm.json, and optionally artifacts/test-report.html (see test/runner/main.py).
  • •ConfigFlags: inventory via ato dev flags; prefer code-driven discovery over hand-maintained docs.
  • •Graph/fabll redesign: see AGENTS.md and the relevant .claude/skills/* docs for the area you’re reviewing.
  • •Solver invariants: src/faebryk/core/solver/README.md + src/faebryk/core/solver/symbolic/invariants.py.

How to Write Review Comments (LLM Style)

  • •Ground every non-trivial claim in the diff or a repo path (be explicit about file + symbol).
  • •Separate:
    • •Must-fix (correctness/security/regression risks)
    • •Should-fix (maintainability/perf improvements)
    • •Nice-to-have (style/ergonomics)
  • •Prefer actionable suggestions (what to change + why + where).
  • •If you’re uncertain, ask a concrete question and point to the ambiguous code.