Back to Details

system-evolution-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

System Review

系统审查

Perform a meta-level analysis of how well the implementation followed the plan and identify process improvements.
对实现方案遵循计划的情况进行元级别分析，识别流程改进方向。

Purpose

目的

System review is NOT code review. You're not looking for bugs in the code - you're looking for bugs in the process.
Your job:
  • Analyze plan adherence and divergence patterns
  • Identify which divergences were justified vs problematic
  • Surface process improvements that prevent future issues
  • Suggest updates to AI-Layer assets (CLAUDE.md, plan templates, skills)
Philosophy:
  • Good divergence reveals plan limitations → improve planning
  • Bad divergence reveals unclear requirements → improve communication
  • Repeated issues reveal missing automation → create skills
系统审查≠代码审查。你不需要寻找代码中的漏洞——而是要发现流程中的问题。
你的职责：
  • 分析计划合规性与差异模式
  • 区分合理差异与问题差异
  • 提出可预防未来问题的流程改进方案
  • 建议更新AI-Layer资产（CLAUDE.md、计划模板、Skill）
核心理念：
  • 合理差异暴露计划局限性 → 优化规划流程
  • 问题差异暴露需求不明确 → 提升沟通效率
  • 重复出现的问题表明缺少自动化 → 创建对应的Skill

Context & Inputs

背景与输入

You will analyze four key artifacts:
Plan Skill: Read this to understand the planning process and what instructions guide plan creation. 
.claude/skills/piv-plan-implementation/SKILL.md
Generated Plan: Read this to understand what the agent was SUPPOSED to do. Plan file: $plan
Execute Skill: Read this to understand the execution process and what instructions guide implementation. 
.claude/skills/piv-implement/SKILL.md
Execution Report: Read this to understand what the agent ACTUALLY did and why. Execution report: $report
你将分析四类关键工件：
计划Skill： 阅读此文档以了解规划流程及指导计划创建的指令。 
.claude/skills/piv-plan-implementation/SKILL.md
生成的计划： 阅读此文档以了解Agent本应完成的任务。 计划文件：$plan
执行Skill： 阅读此文档以了解执行流程及指导实现的指令。 
.claude/skills/piv-implement/SKILL.md
执行报告： 阅读此文档以了解Agent实际完成的工作及原因。 执行报告：$report

Analysis Workflow

分析流程

Step 1: Understand the Planned Approach

步骤1：理解计划方案

Read the generated plan ($plan) and extract:
  • What features were planned?
  • What architecture was specified?
  • What validation steps were defined?
  • What patterns were referenced?
阅读生成的计划（$plan）并提取以下信息：
  • 计划包含哪些功能？
  • 指定了何种架构？
  • 定义了哪些验证步骤？
  • 参考了哪些模式？

Step 2: Understand the Actual Implementation

步骤2：理解实际实现情况

Read the execution report ($report) and extract:
  • What was implemented?
  • What diverged from the plan?
  • What challenges were encountered?
  • What was skipped and why?
阅读执行报告（$report）并提取以下信息：
  • 实际实现了什么？
  • 哪些内容与计划存在差异？
  • 遇到了哪些挑战？
  • 跳过了哪些内容及原因？

Step 3: Classify Each Divergence

步骤3：分类每一处差异

For each divergence identified in the execution report, classify as:
Good Divergence ✅ (Justified):
  • Plan assumed something that didn't exist in the codebase
  • Better pattern discovered during implementation
  • Performance optimization needed
  • Security issue discovered that required different approach
Bad Divergence ❌ (Problematic):
  • Ignored explicit constraints in plan
  • Created new architecture instead of following existing patterns
  • Took shortcuts that introduce tech debt
  • Misunderstood requirements
针对执行报告中识别的每一处差异，分类为：
合理差异 ✅（有正当理由）：
  • 计划假设的内容在代码库中不存在
  • 实现过程中发现了更优模式
  • 需要进行性能优化
  • 发现安全问题，需采用不同方案
问题差异 ❌（存在问题）：
  • 忽略计划中的明确约束
  • 未遵循现有模式，创建了新架构
  • 采取捷径引入技术债务
  • 误解需求

Step 4: Trace Root Causes

步骤4：追溯根本原因

For each problematic divergence, identify the root cause:
  • Was the plan unclear, where, why?
  • Was context missing, where, why?
  • Was validation missing, where, why?
  • Was manual step repeated, where, why?
针对每一处问题差异，识别根本原因：
  • 计划是否不明确？具体在哪里、为什么？
  • 是否缺少上下文？具体在哪里、为什么？
  • 是否缺少验证？具体在哪里、为什么？
  • 是否重复执行手动步骤？具体在哪里、为什么？

Step 5: Generate Process Improvements

步骤5：提出流程改进方案

Based on patterns across divergences, suggest:
  • CLAUDE.md updates: Universal patterns or anti-patterns to document
  • Plan skill updates: Instructions that need clarification or missing steps
  • New skills: Manual processes that should be automated
  • Validation additions: Checks that would catch issues earlier
基于差异中的模式，提出以下建议：
  • CLAUDE.md更新： 记录通用模式或反模式
  • 计划Skill更新： 明确模糊指令或补充缺失步骤
  • 新增Skill： 将重复的手动流程自动化
  • 添加验证环节： 提前发现问题的检查项

Output Format

输出格式

Save your analysis to: 
.claude/system-reviews/[feature-name]-review.md
将分析结果保存至：
.claude/system-reviews/[feature-name]-review.md

Report Structure:

报告结构：

Meta Information

元信息

  • Plan reviewed: [path to $plan]
  • Execution report: [path to $report]
  • Date: [current date]
  • 审查的计划：[$plan的路径]
  • 执行报告：[$report的路径]
  • 日期：[当前日期]

Overall Alignment Score: __/10

整体合规评分：___/10

Scoring guide:
  • 10: Perfect adherence, all divergences justified
  • 7-9: Minor justified divergences
  • 4-6: Mix of justified and problematic divergences
  • 1-3: Major problematic divergences
评分指南：
  • 10分：完全符合计划，所有差异均合理
  • 7-9分：存在少量合理差异
  • 4-6分：合理差异与问题差异并存
  • 1-3分：存在大量问题差异

Divergence Analysis

差异分析

For each divergence from the execution report:
yaml
divergence: [what changed]
planned: [what plan specified]
actual: [what was implemented]
reason: [agent's stated reason from report]
classification: good ✅ | bad ❌
justified: yes/no
root_cause: [unclear plan | missing context | etc]
针对执行报告中记录的每一处差异：
yaml
divergence: [what changed]
planned: [what plan specified]
actual: [what was implemented]
reason: [agent's stated reason from report]
classification: good ✅ | bad ❌
justified: yes/no
root_cause: [unclear plan | missing context | etc]

Pattern Compliance

模式合规性评估

Assess adherence to documented patterns:
  • Followed codebase architecture
  • Used documented patterns (from CLAUDE.md)
  • Applied testing patterns correctly
  • Met validation requirements
评估对已记录模式的遵循情况：
  • 遵循代码库架构
  • 使用了CLAUDE.md中记录的模式
  • 正确应用测试模式
  • 满足验证要求

System Improvement Actions

系统改进措施

Based on analysis, recommend specific actions:
Update CLAUDE.md:
  • Document [pattern X] discovered during implementation
  • Add anti-pattern warning for [Y]
  • Clarify [technology constraint Z]
Update Plan Skill ($plan):
  • Add instruction for [missing step]
  • Clarify [ambiguous instruction]
  • Add validation requirement for [X]
Create New Skill:
  • A new skill for [manual process repeated 3+ times]
Update Execute Skill:
  • Add [validation step] to execution checklist
基于分析结果，提出具体改进措施：
更新CLAUDE.md：
  • 记录实现过程中发现的[模式X]
  • 添加针对[Y]的反模式警告
  • 明确[技术约束Z]
更新计划Skill（$plan）：
  • 添加[缺失步骤]的指令
  • 明确[模糊指令]
  • 添加针对[X]的验证要求
创建新Skill：
  • 为[重复3次以上的手动流程]创建新Skill
更新执行Skill：
  • 在执行检查清单中添加[验证步骤]

Key Learnings

关键经验总结

What worked well:
  • [specific things that went smoothly]
What needs improvement:
  • [specific process gaps identified]
For next implementation:
  • [concrete improvements to try]
表现良好的方面：
  • [具体的顺畅环节]
需要改进的方面：
  • [识别出的具体流程缺口]
针对下一次实现的建议：
  • [可落地的改进措施]

Important

注意事项

  • Be specific: Don't say "plan was unclear" - say "plan didn't specify which auth pattern to use"
  • Focus on patterns: One-off issues aren't actionable. Look for repeated problems.
  • Action-oriented: Every finding should have a concrete asset update suggestion
  • Suggest improvements: Don't just analyze - actually suggest the text to add to CLAUDE.md or skills
  • 具体明确： 不要笼统说“计划不明确”，要具体说明“计划未指定应使用哪种认证模式”
  • 聚焦模式： 偶发问题不具备可操作性，需关注重复出现的问题
  • 注重行动： 每个发现都应对应具体的资产更新建议
  • 提出改进细节： 不要仅做分析，需实际建议添加到CLAUDE.md或Skill中的具体文本