Back to Details

post-implementation-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Post-Implementation Review

实现后代码评审

Review the code after the implementation exists. Focus on issues that were hard to see upfront and only became obvious once the change touched real interfaces, control flow, state, or tests.
This skill is for cautious design review, not aggressive redesign. A strange-looking design is not enough on its own. Prefer keeping the current structure when the evidence is thin or when hidden constraints could plausibly explain the shape.
在代码完成实现后进行评审。重点关注那些前期难以发现，只有当变更涉及实际接口、控制流、状态或测试时才会显现的问题。
本技能用于谨慎的设计评审，而非激进的重新设计。仅仅是设计看起来奇怪并不足以成为重构的理由。当证据不足，或者可能存在隐藏约束可以解释当前设计时，倾向于保留现有结构。

Workflow

工作流程

  1. Anchor the review in the actual change.
  • Read the changed files, nearby interfaces, and affected tests or docs.
  • Distinguish between:
    • pre-existing design debt
    • issues introduced by the change
    • issues the change merely made easier to see
  1. Look for post-implementation signals.
  • Repeated branching, mapping, or glue code that suggests the abstraction boundary is off.
  • A module now knows details it should not need to know.
  • The change forced edits across too many files for one concept.
  • Naming became awkward because responsibilities are blurred.
  • Data is being reshaped repeatedly between layers.
  • Tests became hard to set up because dependencies or ownership are misplaced.
  • The implementation needed workarounds that will probably repeat.
  1. Keep the refactor bar high.
  • Do not recommend a refactor just because another design looks cleaner in theory.
  • Do not treat unfamiliar code as broken code.
  • Assume there may be constraints you cannot yet see unless the code gives clear contrary evidence.
  • Suggest refactoring only when the current shape creates recurring cost, blocks straightforward extension, or makes correctness meaningfully harder to preserve.
  1. Separate evidence from recommendation.
  • First state what the implementation revealed.
  • Then state whether that evidence is strong enough to justify action.
  • If the evidence is weak, say so directly and recommend leaving the design in place for now.
  1. 基于实际变更开展评审。
  • 阅读变更的文件、相关接口以及受影响的测试或文档。
  • 区分以下三类问题：
    • 预先存在的设计债务
    • 本次变更引入的问题
    • 本次变更只是使其更容易被发现的问题
  1. 寻找实现后的信号。
  • 重复出现的分支、映射或粘合代码，表明抽象边界不合理。
  • 某个模块现在了解了它本无需知晓的细节。
  • 针对一个概念的变更需要修改过多文件。
  • 由于职责模糊，命名变得尴尬。
  • 数据在各层之间被反复重新格式化。
  • 由于依赖关系或归属权错位，测试的搭建变得困难。
  • 实现中使用了可能会重复出现的临时解决方案（workaround）。
  1. 提高Refactor的门槛。
  • 不要仅仅因为另一种设计在理论上看起来更简洁就推荐Refactor。
  • 不要将不熟悉的代码视为有问题的代码。
  • 除非代码给出明确的相反证据，否则假设可能存在你尚未了解的约束。
  • 只有当当前设计产生重复成本、阻碍直接扩展，或显著降低正确性保障难度时，才建议进行Refactor。
  1. 区分证据与建议。
  • 首先说明实现所揭示的问题。
  • 然后说明该证据是否足够充分以证明采取行动的合理性。
  • 如果证据不足，直接说明并建议暂时保留现有设计。

Review Standard

评审标准

Treat these as strong signals for a refactor recommendation:
  • The same workaround or translation layer now appears in multiple places.
  • A single change required cross-cutting edits that are likely to recur.
  • One abstraction claims to hide complexity but instead leaks it to callers.
  • Ownership of data, side effects, or orchestration is ambiguous enough to create likely bugs.
  • The new code had to special-case around an existing interface in a way that will spread.
Treat these as weak signals that usually do not justify a refactor by themselves:
  • The code feels inelegant but is still locally understandable.
  • A helper or abstraction is slightly misnamed but still usable.
  • There is some duplication, but it is small and isolated.
  • The current design is awkward only for one edge case with no sign of repetition.
将以下情况视为建议Refactor的强烈信号：
  • 相同的临时解决方案或转换层现在出现在多个地方。
  • 单次变更需要进行跨领域的修改，且这类修改可能会重复发生。
  • 某个抽象声称能隐藏复杂性，但实际上却将其暴露给了调用者。
  • 数据、副作用或编排的归属权模糊，很可能导致bug。
  • 新代码必须针对现有接口进行特殊处理，且这种情况可能会扩散。
将以下情况视为通常不足以单独证明Refactor合理性的弱信号：
  • 代码看起来不够优雅，但仍具备局部可理解性。
  • 某个辅助工具或抽象的命名略有不当，但仍可使用。
  • 存在一些重复，但规模小且孤立。
  • 当前设计仅在某个边缘场景下显得尴尬，且没有重复出现的迹象。

Output

输出格式

Use this structure when reporting:
报告时使用以下结构：

Findings

发现

  • List only concrete design or abstraction issues supported by the code.
  • For each issue, explain why it became visible after implementation rather than being obvious upfront.
  • 仅列出有代码支持的具体设计或抽象问题。
  • 针对每个问题，解释为什么它在实现后才显现，而非前期就显而易见。

Keep As-Is

保持现状

  • Call out odd-looking choices that should probably remain unchanged for now.
  • Explain what evidence is missing for a refactor recommendation.
  • 指出那些看起来奇怪，但目前可能仍需保持不变的选择。
  • 解释为什么缺乏足够证据来建议Refactor。

Refactor Candidates

Refactor候选项

  • Include only changes that clear the bar above.
  • For each one, state:
    • the smallest reasonable refactor scope
    • what it would improve
    • what it would cost or risk
    • why now is or is not the right time
  • 仅包含符合上述门槛的变更。
  • 针对每个候选项，说明：
    • 最小的合理Refactor范围
    • 它将带来哪些改进
    • 它将产生的成本或风险
    • 现在是否是合适的时机

Open Questions

待解决问题

  • List hidden constraints, ownership questions, or missing context that could change the recommendation.
  • 列出可能会改变建议的隐藏约束、归属权问题或缺失的上下文。

Verdict

结论

  • End with one of: 
    • No refactor recommended
    • Small targeted refactor is justified
    • Broader redesign may be warranted, but only after clarifying constraints
  • 以以下结论之一结尾： 
    • No refactor recommended
    • Small targeted refactor is justified
    • Broader redesign may be warranted, but only after clarifying constraints

Communication Rules

沟通规则

  • Be direct and specific.
  • Prefer file-level or seam-level observations over vague architectural commentary.
  • If there are no meaningful design flaws, say so explicitly.
  • If a concern is plausible but not yet well supported, label it as a watch item rather than a recommendation.
  • Do not manufacture findings to make the review feel useful.
  • 直接且具体。
  • 优先关注文件层面或衔接层面的观察，而非模糊的架构评论。
  • 如果没有有意义的设计缺陷，明确说明。
  • 如果某个担忧看似合理但证据不足，将其标记为观察项而非建议。
  • 不要为了让评审看起来有用而编造发现。

Example Triggers

触发示例

  • "Now that this feature is implemented, do you see any design flaws we missed?"
  • "Did this change reveal any abstraction problems?"
  • "Should we refactor this now, or leave it alone?"
  • "Review this implementation and tell me if the current design will age poorly."
  • "现在这个功能已经实现了，你能看到我们之前忽略的设计缺陷吗？"
  • "这次变更是否暴露了抽象设计的问题？"
  • "我们现在应该Refactor这个，还是暂时不管它？"
  • "评审这个实现，告诉我当前设计是否会随着时间推移变得难以维护。"