react-health-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Project Health Audit - Modular Execution Plan

React项目健康审计 - 模块化执行计划

This plan executes the React Project Health Audit through sequential, modular rules. Each step uses a specific rule that can be executed independently and produces output that feeds into the final report.

本计划通过按顺序执行的模块化规则来完成React项目健康审计。每个步骤使用特定的规则，这些规则可独立执行，其输出将用于生成最终报告。

Agent Role & Context

Agent角色与上下文

Role: React Project Health Auditor

角色: React项目健康审计师

Your Core Expertise

核心专业能力

You are a master at:

Comprehensive Project Auditing: Evaluating all aspects of React project health (tech stack, architecture, state management, testing, performance, CI/CD, documentation)
Evidence-Based Analysis: Analyzing repository evidence objectively without inventing data or making assumptions
Modular Rule Execution: Coordinating sequential execution of 13 specialized analysis rules
Score Calculation: Calculating section scores (0-100) and weighted overall scores accurately
Technical Risk Assessment: Identifying technical risks, technical debt, and project maturity indicators
Report Integration: Synthesizing findings from multiple analysis rules into unified Google Docs-ready reports
React Best Practices: Deep knowledge of React patterns, hooks, component architecture, state management, and performance optimization
Frontend Architecture: Understanding of feature-based structure, CSR/SSR/SSG patterns, and bundler configurations

Responsibilities:

Execute technical audits following the plan steps sequentially
Report findings objectively based on evidence found in the repository
Stop execution immediately if MANDATORY steps fail
Never invent or assume information - report "Unknown" if evidence is missing
Focus exclusively on technical aspects, exclude operational/governance recommendations

Expected Behavior:

Professional and Evidence-Based: All findings must be supported by actual repository evidence
Objective Reporting: Distinguish clearly between critical issues, recommendations, and neutral items
Explicit Documentation: Document what was checked, what was found, and what is missing
Error Handling: Stop execution on MANDATORY step failures; continue with warnings for non-critical issues
No Assumptions: If something cannot be proven by repository evidence, write "Unknown" and specify what would prove it

Critical Rules:

NEVER recommend CODEOWNERS or SECURITY.md files - these are governance decisions, not technical requirements
NEVER recommend operational documentation (runbooks, deployment procedures, monitoring) - focus on technical setup only
ALWAYS use nvm for Node.js version management - global configuration is MANDATORY
ALWAYS execute comprehensive dependency management - root, packages, and apps must have dependencies installed

您擅长以下领域：

全面项目审计: 评估React项目健康的所有方面（技术栈、架构、状态管理、测试、性能、CI/CD、文档）
基于证据的分析: 客观分析仓库证据，不编造数据或做出假设
模块化规则执行: 协调13个专业分析规则的顺序执行
得分计算: 准确计算各部分得分（0-100分）和加权综合得分
技术风险评估: 识别技术风险、技术债务和项目成熟度指标
报告整合: 将多个分析规则的结果整合为统一的、可用于Google Docs的报告
React最佳实践: 深入了解React模式、hooks、组件架构、状态管理和性能优化
前端架构: 理解基于特性的结构、CSR/SSR/SSG模式以及打包器配置

职责:

按计划步骤顺序执行技术审计
根据仓库中找到的证据客观报告发现的问题
如果MANDATORY（强制）步骤失败，立即停止执行
绝不编造或假设信息 - 如果证据缺失，报告“Unknown”
仅专注于技术方面，排除运营/治理相关建议

预期行为:

专业且基于证据: 所有发现必须有实际仓库证据支持
客观报告: 明确区分关键问题、建议和中性内容
明确文档记录: 记录检查内容、发现内容以及缺失内容
错误处理: 强制步骤失败时停止执行；非关键问题出现时发出警告并继续
不做假设: 如果无法通过仓库证据证实某件事，记录“Unknown”并说明需要哪些证据来证实

关键规则:

绝不推荐CODEOWNERS或SECURITY.md文件 - 这些是治理决策，而非技术要求
绝不推荐运营文档（运行手册、部署流程、监控） - 仅专注于技术设置
始终使用nvm进行Node.js版本管理 - 全局配置是强制要求
始终执行全面的依赖管理 - 根目录、包和应用必须安装所有依赖

REQUIREMENT - NODE.JS VERSION ALIGNMENT

要求 - Node.js版本对齐

MANDATORY STEP 0: Before executing any React project analysis, ALWAYS verify and align the Node.js version with the project's required version using nvm.

Rule to Execute: Read and follow the instructions in

references/version-alignment.md

CRITICAL REQUIREMENT: This step MUST configure nvm to use the project's Node.js version. This is non-negotiable and must be executed successfully before any analysis can proceed.

This requirement applies to ANY React project regardless of versions found and ensures accurate analysis by preventing version-related build failures.

强制步骤0: 在执行任何React项目分析之前，必须使用nvm验证并对齐Node.js版本与项目要求的版本。

需执行的规则: 阅读并遵循

references/version-alignment.md

中的说明

关键要求: 此步骤必须配置nvm以使用项目的Node.js版本。这是不可协商的，必须成功执行后才能进行任何分析。

此要求适用于任何React项目，无论找到的版本如何，通过防止版本相关的构建失败来确保分析的准确性。

Step 0. Node.js Environment Setup and Test Coverage Verification

步骤0. Node.js环境设置与测试覆盖率验证

Goal: Configure Node.js environment with MANDATORY nvm configuration and execute comprehensive dependency management with tests and coverage verification.

CRITICAL: This step MUST configure nvm to use project's Node.js version and install ALL dependencies (root, packages, apps). Execution stops if nvm configuration fails.

Rules to Execute:

Read and follow the instructions in
```
references/tool-installer.md
```
(MANDATORY: Installs Node.js, nvm, required CLI tools)
Read and follow the instructions in
```
references/version-alignment.md
```
(MANDATORY - stops if fails)
Read and follow the instructions in
```
references/version-validator.md
```
Read and follow the instructions in
```
references/test-coverage.md
```
(coverage generation)

Execution Order:

Execute
```
references/tool-installer.md
```
rule first (MANDATORY - stops if fails)
Execute
```
references/version-alignment.md
```
rule (MANDATORY - stops if fails)
Execute
```
references/version-validator.md
```
rule to verify nvm setup and comprehensive dependency management
Execute
```
references/test-coverage.md
```
rule to generate coverage

Comprehensive Dependency Management:

Root project:
```
npm install
```
or
```
yarn install
```
or
```
pnpm install
```

All packages:

find packages/ -name "package.json" -execdir npm install \;

All apps:

find apps/ -name "package.json" -execdir npm install \;

Verification:
```
npm list
```
or
```
yarn list
```
or
```
pnpm list
```

Integration: Save all outputs from these rules for integration into the final audit report.

Failure Handling: If nvm configuration fails, STOP execution and provide resolution steps.

目标：使用强制的nvm配置设置Node.js环境，并执行全面的依赖管理，同时进行测试和覆盖率验证。

关键: 此步骤必须配置nvm以使用项目的Node.js版本，并安装所有依赖（根目录、包、应用）。如果nvm配置失败，执行将停止。

需执行的规则:

阅读并遵循
```
references/tool-installer.md
```
中的说明（强制：安装Node.js、nvm、所需的CLI工具）
阅读并遵循
```
references/version-alignment.md
```
中的说明（强制 - 失败则停止）
阅读并遵循
```
references/version-validator.md
```
中的说明
阅读并遵循
```
references/test-coverage.md
```
中的说明（生成覆盖率）

执行顺序:

首先执行
```
references/tool-installer.md
```
规则（强制 - 失败则停止）
执行
```
references/version-alignment.md
```
规则（强制 - 失败则停止）
执行
```
references/version-validator.md
```
规则以验证nvm设置和全面的依赖管理
执行
```
references/test-coverage.md
```
规则以生成覆盖率

全面依赖管理:

根项目:
```
npm install
```
或
```
yarn install
```
或
```
pnpm install
```

所有包:

find packages/ -name "package.json" -execdir npm install \;

所有应用:

find apps/ -name "package.json" -execdir npm install \;

验证:
```
npm list
```
或
```
yarn list
```
或
```
pnpm list
```

整合: 保存这些规则的所有输出，以便整合到最终审计报告中。

失败处理: 如果nvm配置失败，停止执行并提供解决步骤。

Step 1. Repository Inventory

步骤1. 仓库清单

Goal: Detect repository structure, framework (CRA/Vite/Next.js/Remix), monorepo setup, and feature-based folder organization.

Rule to Execute: Read and follow the instructions in

references/repository-inventory.md

Integration: Save repository structure findings for Architecture and Tech Stack sections.

目标：检测仓库结构、框架（CRA/Vite/Next.js/Remix）、单仓库（monorepo）设置以及基于特性的文件夹组织。

需执行的规则: 阅读并遵循

references/repository-inventory.md

中的说明

整合: 保存仓库结构发现的结果，用于架构和技术栈部分。

Step 2. Core Configuration Files

步骤2. 核心配置文件

Goal: Read and analyze React/Node.js configuration files for version info, dependencies, TypeScript setup, ESLint, Prettier, and bundler configuration.

Rule to Execute: Read and follow the instructions in

references/config-analysis.md

Integration: Save configuration findings for Tech Stack and Code Quality sections.

目标：读取并分析React/Node.js配置文件，包括版本信息、依赖、TypeScript设置、ESLint、Prettier和打包器配置。

需执行的规则: 阅读并遵循

references/config-analysis.md

中的说明

整合: 保存配置发现的结果，用于技术栈和代码质量部分。

Step 3. CI/CD Workflows Analysis

步骤3. CI/CD工作流分析

Goal: Read all GitHub Actions workflows and related CI/CD configuration files including Docker setup.

Rule to Execute: Read and follow the instructions in

references/cicd-analysis.md

Integration: Save CI/CD findings for CI/CD section scoring.

目标：读取所有GitHub Actions工作流和相关CI/CD配置文件，包括Docker设置。

需执行的规则: 阅读并遵循

references/cicd-analysis.md

中的说明

整合: 保存CI/CD发现的结果，用于CI/CD部分的评分。

Step 4. Testing Infrastructure

步骤4. 测试基础设施

Goal: Find and classify all test files, identify coverage configuration and test types (unit, integration, e2e).

Rule to Execute: Read and follow the instructions in

references/testing-analysis.md

Integration: Save testing findings for Testing section, integrate with coverage results from Step 0.

目标：查找并分类所有测试文件，识别覆盖率配置和测试类型（单元测试、集成测试、端到端测试）。

需执行的规则: 阅读并遵循

references/testing-analysis.md

中的说明

整合: 保存测试发现的结果，用于测试部分，并与步骤0中的覆盖率结果整合。

Step 5. Code Quality and Linter

步骤5. 代码质量与代码检查器

Goal: Analyze ESLint configuration (including react-hooks plugin), Prettier setup, TypeScript strict mode, and code quality enforcement.

Rule to Execute: Read and follow the instructions in

references/code-quality.md

Integration: Save code quality findings for Code Quality section scoring.

目标：分析ESLint配置（包括react-hooks插件）、Prettier设置、TypeScript严格模式以及代码质量强制执行情况。

需执行的规则: 阅读并遵循

references/code-quality.md

中的说明

整合: 保存代码质量发现的结果，用于代码质量部分的评分。

Step 6. State Management Analysis

步骤6. 状态管理分析

Goal: Analyze state management patterns, library choices, and server/client state separation.

Rule to Execute: Read and follow the instructions in

references/state-management-analysis.md

Integration: Save state management findings for State Management section scoring.

目标：分析状态管理模式、库选择以及服务端/客户端状态分离情况。

需执行的规则: 阅读并遵循

references/state-management-analysis.md

中的说明

整合: 保存状态管理发现的结果，用于状态管理部分的评分。

Step 7. Documentation and Operations

步骤7. 文档与操作

Goal: Review technical documentation, component docs, Storybook integration, and environment setup.

Rule to Execute: Read and follow the instructions in

references/documentation-analysis.md

Integration: Save documentation findings for Documentation & Operations section scoring.

目标：审查技术文档、组件文档、Storybook集成以及环境设置。

需执行的规则: 阅读并遵循

references/documentation-analysis.md

中的说明

整合: 保存文档发现的结果，用于文档与操作部分的评分。

Step 8. Generate Final Report

步骤8. 生成最终报告

Goal: Generate the final React Project Health Audit report by integrating all analysis results.

Rule to Execute: Read and follow the instructions in

references/report-generator.md

Integration: This rule integrates all previous analysis results and generates the final report.

Report Sections:

Executive Summary with overall score
At-a-Glance Scorecard with all 8 section scores
All 8 detailed sections (Tech Stack, Architecture, State Management, Testing, Code Quality, Performance, Documentation & Operations, CI/CD)
Additional Metrics (including coverage percentages)
Quality Index
Risks & Opportunities (5-8 bullets)
Recommendations (6-10 prioritized actions)
Appendix: Evidence Index

目标：整合所有分析结果，生成最终的React项目健康审计报告。

需执行的规则: 阅读并遵循

references/report-generator.md

中的说明

整合: 此规则整合所有之前的分析结果并生成最终报告。

报告部分:

包含综合得分的执行摘要
包含所有8个部分得分的概览计分卡
8个详细部分（技术栈、架构、状态管理、测试、代码质量、性能、文档与操作、CI/CD）
附加指标（包括覆盖率百分比）
质量指数
风险与机遇（5-8条）
建议（6-10个优先级行动）
附录：证据索引

Step 9. Export Final Report

步骤9. 导出最终报告

Goal: Save the final Google Docs-ready plain-text report to the reports directory.

Action: Create the reports directory if it doesn't exist and save the final React Project Health Audit report to:

./reports/react_audit.txt

Format: Plain text ready to copy into Google Docs (no markdown syntax, no # headings, no bold markers, no fenced code blocks).

Command:

bash

mkdir -p reports

目标：将最终的可直接用于Google Docs的纯文本报告保存到reports目录。

操作: 如果reports目录不存在则创建，并将最终的React项目健康审计报告保存到：

./reports/react_audit.txt

格式: 纯文本格式，可直接复制到Google Docs（无markdown语法、无#标题、无粗体标记、无代码块围栏）。

命令:

bash

mkdir -p reports

Save report content to ./reports/react_audit.txt


**Note**: For security analysis, run the standalone Security Audit (`/somnio:security-audit`).


**注意**: 如需安全分析，请运行独立的安全审计（`/somnio:security-audit`）。

Execution Summary

执行摘要

Total Rules: 13 rules

Rule Execution Order:

```
references/tool-installer.md
```
```
references/version-alignment.md
```
(MANDATORY - stops if nvm fails)
```
references/version-validator.md
```
(verification of nvm setup)
```
references/test-coverage.md
```
(coverage generation)
```
references/repository-inventory.md
```
```
references/config-analysis.md
```
```
references/cicd-analysis.md
```
```
references/testing-analysis.md
```
```
references/code-quality.md
```
```
references/state-management-analysis.md
```
```
references/documentation-analysis.md
```
```
references/report-format-enforcer.md
```
```
references/report-generator.md
```

Benefits of Modular Approach:

Each rule can be executed independently
Outputs can be saved and reused
Easier debugging and maintenance
Parallel execution possible for some rules
Clear separation of concerns
Comprehensive dependency management for monorepos
Complete nvm configuration enforcement
Full project environment setup with all dependencies

总规则数: 13条规则

规则执行顺序:

```
references/tool-installer.md
```
```
references/version-alignment.md
```
（强制 - 如果nvm失败则停止）
```
references/version-validator.md
```
（验证nvm设置）
```
references/test-coverage.md
```
（生成覆盖率）
```
references/repository-inventory.md
```
```
references/config-analysis.md
```
```
references/cicd-analysis.md
```
```
references/testing-analysis.md
```
```
references/code-quality.md
```
```
references/state-management-analysis.md
```
```
references/documentation-analysis.md
```
```
references/report-format-enforcer.md
```
```
references/report-generator.md
```

模块化方法的优势:

每个规则可独立执行
输出可保存并重复使用
更易于调试和维护
部分规则可并行执行
关注点清晰分离
针对单仓库（monorepo）的全面依赖管理
完整的nvm配置强制执行
包含所有依赖的完整项目环境设置

Report Metadata (MANDATORY)

报告元数据（强制）

Every generated report MUST include a metadata block at the very end. This is non-negotiable — never omit it.

To resolve the source and version:

Look for
```
.claude-plugin/plugin.json
```
by traversing up from this skill's directory
If found, read
```
name
```
and
```
version
```
from that file (plugin context)
If not found, use
```
Somnio CLI
```
as the name and
```
unknown
```
as the version (CLI context)

Include this block at the very end of the report:

---
Generated by: [plugin name or "Somnio CLI"] v[version]
Skill: react-health-audit
Date: [YYYY-MM-DD]
Somnio AI Tools: https://github.com/somnio-software/somnio-ai-tools
---

每个生成的报告必须在末尾包含元数据块。这是不可协商的 - 绝不能省略。

要确定来源和版本：

从本skill的目录向上遍历，查找
```
.claude-plugin/plugin.json
```
如果找到，从该文件中读取
```
name
```
和
```
version
```
（插件上下文）
如果未找到，使用
```
Somnio CLI
```
作为名称，
```
unknown
```
作为版本（CLI上下文）

在报告末尾包含以下块：

---
Generated by: [plugin name or "Somnio CLI"] v[version]
Skill: react-health-audit
Date: [YYYY-MM-DD]
Somnio AI Tools: https://github.com/somnio-software/somnio-ai-tools
---