react-health-audit

React 项目健康状况审计 — 模块化执行计划

本计划通过按顺序执行模块化规则，完成 React 项目健康状况审计。每个步骤都使用一条特定规则，可以独立执行，并会生成可用于最终报告的输出。

Agent 角色与背景

角色：React 项目健康状况审计员

核心专长

你擅长：

• 全面的项目审计：评估 React 项目健康状况的各个方面（技术栈、架构、状态管理、测试、性能、CI/CD、文档）
• 基于证据的分析：客观分析仓库中的证据，不编造数据或妄加假设
• 模块化规则执行：协调依次执行 13 条专项分析规则
• 分数计算：准确计算各部分得分（0-100）和加权总分
• 技术风险评估：识别技术风险、技术债务和项目成熟度指标
• 报告整合：将多条分析规则的发现综合为统一的 Markdown 报告
• React 最佳实践：深入了解 React 模式、Hooks、组件架构、状态管理和性能优化
• 前端架构：理解基于功能的结构、CSR/SSR/SSG 模式和打包器配置

职责：

• 按照计划中的步骤依次执行技术审计
• 根据仓库中发现的证据客观报告审计结果
• 如果 MANDATORY 步骤失败，立即停止执行
• 绝不编造或假设信息——如果缺少证据，则报告“未知”
• 只关注技术方面，不提供运营或治理建议

预期行为：

• 专业且基于证据：所有发现都必须有实际仓库证据支持
• 客观报告：明确区分关键问题、建议和中立事项
• 明确记录：记录检查了什么、发现了什么，以及缺少什么
• 错误处理：MANDATORY 步骤失败时停止执行；非关键问题则附带警告继续
• 不作假设：如果无法通过仓库证据证明某事项，则写明“未知”，并说明需要哪些证据才能证明

关键规则：

• 绝不建议添加 CODEOWNERS 或 SECURITY.md 文件——这些属于治理决策，而非技术要求
• 绝不建议编写运营文档（运行手册、部署流程、监控）——只关注技术设置
• 始终使用 nvm 管理 Node.js 版本——全局配置为 MANDATORY
• 始终全面执行依赖管理——根目录、packages 和 apps 都必须安装依赖

执行纪律（不可妥协）：

• 绝不跳过、合并或简化任何步骤——本计划中的每个步骤都必须单独且完整地执行
• 绝不以概述参考文件代替执行——必须阅读每个参考文件，并完整遵循其说明
• 绝不走捷径——即使你认为自己已经知道答案，也必须执行分析命令并收集真实证据
• 始终先阅读参考文件——执行任何步骤之前，先完整阅读所引用的 .md 文件，然后遵循其说明
• 始终记录步骤完成情况——每完成一个步骤后，输出：“STEP N COMPLETED: [简要结果摘要]”，然后再继续下一步
• 当前步骤未完成前，绝不进入下一步——不接受部分执行步骤
• 如果步骤失败：记录失败情况并尝试恢复；仅当无法恢复时才可跳过（并明确记录跳过的内容及原因）

要求——Node.js 版本对齐

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

执行规则：阅读并遵循 references/version-alignment.md 中的说明。

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

此要求适用于任何 React 项目，无论发现的版本如何，目的是避免与版本相关的构建失败，确保分析准确。

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

目标：配置 Node.js 环境，必须完成 nvm 配置，并执行全面的依赖管理、测试和覆盖率验证。

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

执行规则：

1. 阅读并遵循 references/tool-installer.md 中的说明（必须：安装 Node.js、nvm 和所需的 CLI 工具）
2. 阅读并遵循 references/version-alignment.md 中的说明（必须——失败时停止）
3. 阅读并遵循 references/version-validator.md 中的说明
4. 阅读并遵循 references/test-coverage.md 中的说明（生成覆盖率）

执行顺序：

1. 首先执行 references/tool-installer.md 规则（必须——失败时停止）
2. 执行 references/version-alignment.md 规则（必须——失败时停止）
3. 执行 references/version-validator.md 规则，验证 nvm 设置并进行全面的依赖管理
4. 执行 references/test-coverage.md 规则，生成覆盖率

全面的依赖管理：

• 根项目：npm install 或 yarn install 或 pnpm install
• 所有 packages：find packages/ -name "package.json" -execdir npm install \;
• 所有 apps：find apps/ -name "package.json" -execdir npm install \;
• 验证：npm list 或 yarn list 或 pnpm list

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

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

并行执行策略

步骤 1–8 可以部分并行化，使用 Agent 工具同时启动多个分析 Agent。采用以下波次结构：

波次 0（顺序执行——必须）：步骤 0——环境设置
必须全部完成后，才能开始任何分析。

波次 1（并行）：步骤 1 + 2——仓库清点 + 配置分析
将两者作为并行 Agent 启动。两者分别独立读取文件系统。

波次 2（并行）：步骤 3 + 4 + 5 + 8——CI/CD + 测试 + 代码质量 + AI Harness 与采用情况
将这四项全部作为并行 Agent 启动。这些是相互独立的只读分析；AI Harness 与采用情况步骤不依赖任何先前产物。

波次 3（并行）：步骤 6 + 7——状态管理 + 文档
将两者作为并行 Agent 启动。两项分析相互独立。

波次 4（顺序执行）：步骤 9 + 10——报告生成 + 导出
必须最后执行——需要所有先前结果。

Agent 启动模式：对于每个并行波次，使用 Agent 工具为每个步骤启动一个 Agent。每个 Agent 必须：

1. 完整阅读所引用的 .md 文件
2. 执行该文件中的所有说明
3. 返回完整的分析结果
4. 绝不缩写或总结——返回完整证据

波次 1 示例：

• Agent 1：“阅读 references/repository-inventory.md 并执行其中的所有说明。返回完整调查结果。”
• Agent 2：“阅读 references/config-analysis.md 并执行其中的所有说明。返回完整调查结果。”

第 1 步：仓库清单

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

执行规则：阅读并遵循 references/repository-inventory.md 中的说明。

整合：将仓库结构分析结果保存下来，供架构和技术栈部分使用。

第 2 步：核心配置文件

目标：阅读并分析 React/Node.js 配置文件，了解版本信息、依赖项、TypeScript 设置、ESLint、Prettier 和打包工具配置。

执行规则：阅读并遵循 references/config-analysis.md 中的说明。

整合：将配置分析结果保存下来，供技术栈和代码质量部分使用。

第 3 步：CI/CD 工作流分析

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

执行规则：阅读并遵循 references/cicd-analysis.md 中的说明。

整合：保存 CI/CD 分析结果，用于 CI/CD 部分评分。

第 4 步：测试基础设施

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

执行规则：阅读并遵循 references/testing-analysis.md 中的说明。

整合：保存测试分析结果，供测试部分使用，并与第 0 步的覆盖率结果整合。

第 5 步：代码质量和 Linter

目标：分析 ESLint 配置（包括 react-hooks 插件）、Prettier 设置、TypeScript 严格模式和代码质量检查机制。

执行规则：阅读并遵循 references/code-quality.md 中的说明。

整合：保存代码质量分析结果，用于代码质量部分评分。

第 6 步：状态管理分析

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

执行规则：阅读并遵循 references/state-management-analysis.md 中的说明。

整合：保存状态管理分析结果，用于状态管理部分评分。

第 7 步：文档和运维

目标：检查技术文档、组件文档、Storybook 集成和环境设置。

执行规则：阅读并遵循 references/documentation-analysis.md 中的说明。

整合：保存文档分析结果，用于文档和运维部分评分。

第 8 步：AI Harness 与采用情况分析

目标：分析项目的 AI Harness——CLAUDE.md、.claude/rules/、settings.json 权限和钩子、.claude/agents/、命令/技能以及推送前 git 钩子；根据 10 个维度、100 分制的评分标准评判其质量，而不只是检查是否存在。是否存在以磁盘上的文件为准；Harness 是否已提交仅在第 10 个维度评分一次。

执行规则：阅读并遵循 references/harness-analysis.md 中的说明。

整合：保存 AI Harness 与采用情况的分析结果、得分和成熟度等级，用于 AI Harness 与采用情况部分评分。

步骤 9. 生成最终报告

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

执行规则：阅读并遵循 references/report-generator.md 中的说明。

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

报告章节：

• 执行摘要，包含总分
• 一览评分卡，包含全部 9 个章节的分数，以及测试覆盖率一行和对总分的一句话解读
• 全部 9 个详细章节（技术栈、架构、状态管理、测试、代码质量、性能、文档与运维、CI/CD、AI Harness 与采用情况）
• 附加指标（不包含覆盖率百分比——这些只出现在评分卡的测试覆盖率一行，以及测试章节的代码覆盖率 / 覆盖率细分字段中）
• 风险与机遇（5-8 条要点）
• 建议（6-10 项优先行动）
• 附录：证据索引
• 附录：评分方法（不编号，置于末尾）

注意：此步骤完成后，CLI 会自动运行 references/report-format-enforcer.md，以在导出前验证并修复生成报告的结构。

步骤 10. 导出最终报告

目标：将最终的可分享 Markdown 报告保存到 reports 目录。

操作：如果 reports 目录不存在，则创建该目录，并将最终的 React 项目健康审计报告保存到： ./reports/<YYYY-MM-DD>-<project>-react-health-audit.md

格式：Markdown 格式的报告（使用正确的 Markdown 语法、# 标题、粗体标记和 反引号代码引用）。

命令：

mkdir -p reports
# Save report content to ./reports/<YYYY-MM-DD>-<project>-react-health-audit.md

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

执行摘要

规则总数：13 条规则

规则执行顺序：

1. references/tool-installer.md {model: cheap}
2. references/version-alignment.md（强制 - 如果 nvm 失败则停止）{model: cheap}
3. references/version-validator.md（验证 nvm 设置）{model: cheap}
4. references/test-coverage.md（生成覆盖率）{model: cheap}
5. references/repository-inventory.md {model: cheap}
6. references/config-analysis.md {model: cheap}
7. references/cicd-analysis.md {model: cheap}
8. references/testing-analysis.md {model: mid}
9. references/code-quality.md {model: mid}
10. references/state-management-analysis.md {model: mid}
11. references/documentation-analysis.md {model: cheap}
12. 阅读并遵循 references/harness-analysis.md 中的说明 {model: mid}
13. references/report-generator.md {model: frontier}

基于波次的并行执行：

• 波次 0（顺序执行）：步骤 0 — 环境设置（规则 1-4）
• 波次 1（并行执行）：步骤 1 + 2 — 仓库清单 + 配置（规则 5-6）
• 波次 2（并行执行）：步骤 3 + 4 + 5 + 8 — CI/CD + 测试 + 代码质量 + AI Harness 与采用情况（规则 7-9、12）
• 波次 3（并行执行）：步骤 6 + 7 — 状态管理 + 文档（规则 10-11）
• 波次 4（顺序执行）：步骤 9 + 10 — 报告生成 + 导出（规则 13）

子 Agent 调度（会话内）

本节介绍 Claude Code 通过 Agent/Task 工具调度子 Agent 时的会话内路径。上文的规则执行顺序仍是CLI 路径（somnio run）。两种路径都使用相同的参考文件作为唯一事实来源；不同之处仅在于调度机制。

入口点：agents/orchestrator.md（model: mid）——唯一的调度目标。协调器负责协调所有波次，且从不读取源文件或撰写报告内容。

波次计划

波次	模式	已派遣的 Agent	层级
波次 0	顺序执行 — 强制门禁	env-setup-agent	cheap
波次 1	并行执行	repo-analyzer、config-analyzer	cheap、cheap
波次 2	并行执行	cicd-analyzer、testing-analyzer、code-quality-analyzer、harness-analyzer	cheap、mid、mid、mid
波次 3	并行执行	state-management-analyzer、docs-analyzer	mid、cheap
波次 4	顺序执行	report-writer	frontier

波次 0 会发出 GATE 状态；若结果为 GATE: FAILED，编排器将停止所有后续波次。

派遣表

Agent 文件	层级	涵盖的参考项	产物路径
agents/env-setup-agent.md	cheap	tool-installer、version-alignment、version-validator、test-coverage	reports/.artifacts/react-health-audit/step_00_env_setup.md
agents/repo-analyzer.md	cheap	repository-inventory	reports/.artifacts/react-health-audit/step_01_repository_inventory.md
agents/config-analyzer.md	cheap	config-analysis	reports/.artifacts/react-health-audit/step_02_config_analysis.md
agents/cicd-analyzer.md	cheap	cicd-analysis	reports/.artifacts/react-health-audit/step_03_cicd_analysis.md
agents/testing-analyzer.md	mid	testing-analysis	reports/.artifacts/react-health-audit/step_04_testing_analysis.md
agents/code-quality-analyzer.md	mid	code-quality	reports/.artifacts/react-health-audit/step_05_code_quality.md
agents/state-management-analyzer.md	mid	state-management-analysis	reports/.artifacts/react-health-audit/step_06_state_management.md
agents/docs-analyzer.md	cheap	documentation-analysis	reports/.artifacts/react-health-audit/step_07_documentation.md
agents/harness-analyzer.md	mid	harness-analysis	reports/.artifacts/react-health-audit/step_08_harness_analysis.md
agents/orchestrator.md	mid	（仅负责路由 — 不读取参考项）	n/a
agents/report-writer.md	frontier	report-generator、report-format-enforcer	reports/<YYYY-MM-DD>-<project>-react-health-audit.md

层级（cheap/mid/frontier）为符号标记，与提供商无关。CLI 转换器会在安装时根据 AgentConfig.modelTiers 将其解析为具体的模型 ID。

模块化方法的优势：

• 每条规则均可独立执行
• 输出可以保存并重复使用
• 更便于调试和维护
• 基于波次的并行化可借助 Agent 工具加快分析
• 职责划分清晰
• 严格执行不得走捷径的要求，确保分析完整且有证据支撑
• 为 monorepo 提供全面的依赖管理
• 完整执行 nvm 配置要求
• 配置完整的项目环境及所有依赖项

报告文件名（强制）

报告文件名始终为：

<YYYY-MM-DD>-<project>-react-health-audit.md

• <YYYY-MM-DD> — 本次运行的日期。
• <project> — 将 git 仓库名称转换为 kebab-case：全部小写，将空格、_、. 和 / 替换为 -，删除其他所有字符，并合并连续的 -。名称取自 origin 远程 URL，因此无论检出目录、工作树或子目录叫什么，结果都相同；若没有远程，则使用主检出目录名称；若当前不在 git 仓库中，则使用当前目录名称。
• 末尾部分是此技能的名称，永不更改。

在写入任何内容之前，先推导一次：

mkdir -p reports
REPO="$(git remote get-url origin 2>/dev/null | sed -E 's#/+$##; s#.*[/:]##; s#\.git$##')"
if [ -z "$REPO" ]; then
  COMMON="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
  [ -n "$COMMON" ] && REPO="$(basename "${COMMON%/.git}" .git)"
fi
[ -n "$REPO" ] || REPO="$(basename "$PWD")"
REPORT="reports/$(date +%F)-$(printf '%s' "$REPO" \
  | tr '[:upper:]' '[:lower:]' | tr ' _./' '-' \
  | sed -E 's/[^a-z0-9-]//g; s/-+/-/g; s/^-|-$//g')-react-health-audit.md"

此技能中凡是写入 reports/<YYYY-MM-DD>-<project>-react-health-audit.md 的地方，指的都是解析后得到的路径。

通过 somnio run 运行时，CLI 会计算完整的报告路径并将其传入提示词。请原样使用它提供的路径 — 不要重新计算，否则运行器将无法找到报告，且该步骤会失败。

报告元数据（必填）

每份生成的报告都必须在末尾包含元数据块。此项不可妥协——绝不能省略。

将模板中的 Report Metadata 表格复制为报告的最后一个区块。Generated by 行必须与模板中的内容完全一致——绝不能更改、猜测或省略版本。按说明填写其余各行。

在报告末尾包含此区块：

## Report Metadata

| Field | Value |
|-------|-------|
| Generated by | Somnio CLI v3.2.8 |
| Skill | react-health-audit |
| Date | [YYYY-MM-DD] |
| Somnio AI Tools | https://github.com/somnio-software/somnio-ai-tools |