---
description: |
  在新增功能前评估项目健康度、架构与风险。
  使用时机：接手旧项目、在现有代码上新增功能、评估技术债。
  关键字：discovery, assessment, audit, legacy, health check, technical debt, 现况评估, 风险分析, 技术债, 项目盘点。
source: ../../../../skills/project-discovery/SKILL.md
source_version: 1.0.0
translation_version: 1.0.0
last_synced: 2026-02-10
status: current
---

# 项目现况评估指南

> **语言**: [English](../../../../skills/project-discovery/SKILL.md) | 简体中文

**版本**: 1.0.0
**最后更新**: 2026-02-10
**适用范围**: 所有 AI 编码助手

> **工具型技能**：此技能组合既有的 UDS 核心规范，构建结构化的现况评估流程。无需专属的核心规范。

---

## 目的

在现有代码上新增功能前，你需要清楚了解其目前的状态。Phase 0 -- 现况评估 -- 提供系统化的代码健康度、架构、文档、依赖和风险评估，让你能有信心地规划变更。

此技能引导你完成 6 个评估步骤，每个步骤均引用既有的 UDS 规范作为方法论和质量闸门。

## 快速参考

### Phase 0 现况评估工作流程

```
+-------------------------------------------------------------------+
|                  Phase 0：项目现况评估                              |
+-------------------------------------------------------------------+
|                                                                    |
|  0.1  代码健康度检查                                               |
|       -- 测试覆盖率、lint 问题、代码异味                           |
|                                                                    |
|  0.2  架构理解                                                     |
|       -- 入口点、模块地图、架构模式                                 |
|                                                                    |
|  0.3  文档盘点                                                     |
|       -- README、ADR、变更日志、内嵌文档                           |
|                                                                    |
|  0.4  代码审查快照                                                  |
|       -- 关键路径的抽样审计                                         |
|                                                                    |
|  0.5  依赖与安全检查                                                |
|       -- 过期套件、已知漏洞                                        |
|                                                                    |
|  0.6  影响范围分析                                                  |
|       -- 变更传播、风险矩阵                                        |
|                                                                    |
|  ------------------------------------------------------------------  |
|  输出：现况评估报告（通过 / 不通过 / 有条件通过）                   |
|  下一步：/reverse -> /sdd -> 实现                                   |
+-------------------------------------------------------------------+
```

### 步骤总览

| 步骤 | 重点 | 主要产出 | 引用的 UDS 规范 |
|------|------|----------|----------------|
| 0.1 | 代码健康度 | 测试覆盖率 %、lint 分数、代码异味数 | 测试标准、反向工程 |
| 0.2 | 架构 | 模块依赖图、架构模式识别 | AI 友善架构、反向工程 |
| 0.3 | 文档 | 文档覆盖矩阵、过期指标 | 文档结构、变更日志 |
| 0.4 | 代码审查 | 关键路径审计、质量快照 | 反幻觉、代码审查清单 |
| 0.5 | 依赖 | 漏洞报告、过期套件清单 | 安全标准、签入标准 |
| 0.6 | 影响范围 | 风险矩阵、变更传播地图 | 需求工程 |

## 工作流程步骤

### 步骤 0.1：代码健康度检查

**目标**：建立代码质量的基准量测。

**操作**：
1. 执行现有测试套件并记录通过率和覆盖率
2. 执行 linter 并统计警告/错误数
3. 识别代码异味（过长函数、深层嵌套、重复逻辑）
4. 检查死代码和未使用的导出

**输出格式**：
```markdown
## 代码健康度摘要

| 指标 | 值 | 状态 |
|------|-----|------|
| 测试通过率 | 85/100 (85%) | ⚠️ 低于目标 |
| 测试覆盖率 | 42% | ❌ 偏低 |
| Lint 错误 | 23 | ⚠️ 需要关注 |
| 代码异味 | 7 个主要 | ⚠️ 需要关注 |
```

**质量闸门**：若测试通过率 < 70%，标记为高风险后再继续。

**引用规范**：
- [测试标准](../../../../core/testing-standards.md)
- [反向工程标准](../../../../core/reverse-engineering-standards.md)

### 步骤 0.2：架构理解

**目标**：绘制系统结构并识别架构模式。

**操作**：
1. 识别入口点（主文件、API 路由、事件处理器）
2. 绘制模块/套件依赖关系
3. 识别架构模式（MVC、DDD、微服务、单体式等）
4. 标记反模式（循环依赖、上帝模块）
5. 评估 AI 友善度（清晰边界、可发现性结构）

**输出格式**：
```markdown
## 架构概览

**模式**: [Confirmed] MVC 含服务层
**入口点**: src/index.ts, src/api/routes.ts
**模块数**: 24 个模块横跨 6 个套件

### 依赖地图（简化版）
routes -> controllers -> services -> repositories -> database

### 问题
- [Confirmed] UserService <-> AuthService 之间存在循环依赖
- [Inferred] 支付模块存在紧耦合
```

**质量闸门**：若无清晰模块边界，建议在功能开发前进行架构重构。

**引用规范**：
- [AI 友善架构](../../../../core/ai-friendly-architecture.md)
- [反向工程标准](../../../../core/reverse-engineering-standards.md)

### 步骤 0.3：文档盘点

**目标**：评估文档完整性和新鲜度。

**操作**：
1. 检查 README、CONTRIBUTING、CHANGELOG
2. 扫描架构决策记录（ADR）
3. 评估内嵌文档（JSDoc、docstring、注释）
4. 检查文档是否与当前代码状态一致

**输出格式**：
```markdown
## 文档盘点

| 文档 | 存在 | 最后更新 | 状态 |
|------|------|----------|------|
| README.md | ✅ | 2025-06-15 | ⚠️ 过期 |
| CHANGELOG.md | ❌ | — | — |
| API 文档 | ✅ | 2025-09-01 | ✅ 最新 |
| ADR | ❌ | — | — |
| 内嵌文档 | ⚠️ 部分 | — | — |
```

**质量闸门**：若 README 遗失或严重过期，建议先更新文档。

**引用规范**：
- [文档结构](../../../../core/documentation-structure.md)
- [变更日志标准](../../../../core/changelog-standards.md)

### 步骤 0.4：代码审查快照

**目标**：对关键代码路径进行抽样质量审计。

**操作**：
1. 识别 3-5 条最关键的代码路径（认证、支付、数据访问等）
2. 使用代码审查清单逐一检视
3. 套用反幻觉标签 -- 只报告你实际读过的内容
4. 标记任何安全疑虑或错误处理缺口

**输出格式**：
```markdown
## 代码审查快照

### 关键路径：认证
[Confirmed] 已审查 src/auth/login.ts、src/auth/middleware.ts

| 面向 | 评分 | 备注 |
|------|------|------|
| 错误处理 | ⚠️ | 缺少 token 更新失败的 catch |
| 安全性 | ✅ | bcrypt 杂凑、参数化查询 |
| 可读性 | ✅ | 命名清晰、函数长度合理 |

[Unknown] Token 轮换策略 -- 需要利害关系人确认
```

**质量闸门**：任何 ❌ 安全性发现必须在功能开发前立即处理。

**引用规范**：
- [反幻觉指南](../../../../core/anti-hallucination.md)
- [代码审查清单](../../../../core/code-review-checklist.md)

### 步骤 0.5：依赖与安全检查

**目标**：识别有漏洞、过期或不必要的依赖。

**操作**：
1. 执行 `npm audit` / `pip audit` / 等效指令
2. 列出过期套件及严重程度
3. 检查依赖中的已知 CVE
4. 识别未使用的依赖

**输出格式**：
```markdown
## 依赖报告

| 类别 | 数量 | 严重程度 |
|------|------|----------|
| 严重漏洞 | 1 | ❌ 高 |
| 高风险漏洞 | 3 | ⚠️ 中 |
| 过期（主要版本） | 5 | ⚠️ |
| 过期（次要/修补） | 12 | ℹ️ |
| 未使用依赖 | 2 | ℹ️ |
```

**质量闸门**：任何严重漏洞必须在新增功能前修补。

**引用规范**：
- [安全标准](../../../../core/security-standards.md)
- [签入标准](../../../../core/checkin-standards.md)

### 步骤 0.6：影响范围分析

**目标**：绘制提议变更在系统中的传播方式并评估风险。

**操作**：
1. 识别要修改的功能区域
2. 追踪直接和间接依赖
3. 评估爆炸半径（影响多少模块）
4. 构建风险矩阵（可能性 vs. 影响）

**输出格式**：
```markdown
## 影响分析

### 变更目标：用户个人资料模块

**爆炸半径**: 6 个模块直接受影响，3 个间接受影响

### 风险矩阵

| 风险 | 可能性 | 影响 | 缓解措施 |
|------|--------|------|----------|
| 认证流程中断 | 中 | 高 | 新增集成测试 |
| 支付回归 | 低 | 严重 | 部署前手动 QA |
| API 契约变更 | 高 | 中 | 为 API 端点加版本号 |
```

**质量闸门**：若爆炸半径超过模块总数的 30%，建议采用渐进式方法。

**引用规范**：
- [需求工程](../../../../core/requirement-engineering.md)

## 现况评估报告模板

完成全部 6 个步骤后，将发现汇整为现况评估报告：

```markdown
# 现况评估报告：[项目名称]

**日期**: YYYY-MM-DD
**评估者**: [AI / 人类]

## 执行摘要
[1-2 句：整体项目健康度与准备程度]

## 判定：[通过 / 不通过 / 有条件通过]

## 关键发现
1. ...
2. ...
3. ...

## 阻塞项目（如有）
- ...

## 建议
1. ...
2. ...

## 后续步骤
- [ ] /reverse（若旧代码需要 SDD 规格）
- [ ] /sdd（为新功能编写规格）
- [ ] 处理上述阻塞项目
```

## 与其他技能的集成

### 搭配 /reverse（反向工程）

在以下情况下于现况评估后使用 `/reverse`：
- 架构缺乏文档记录
- 需要为既有模块建立正式的 SDD 规格
- 旧有代码需要结构化分析才能进行变更

### 搭配 /sdd（规格驱动开发）

在现况评估后使用 `/sdd`：
- 根据现况评估发现编写新功能规格
- 在风险评估区段引用现况评估报告

### 搭配 /review（代码审查）

步骤 0.4 的快照是 `/review` 的轻量版。在以下情况使用完整的 `/review`：
- 现况评估发现重大质量疑虑
- 规划变更前需要更深入的审计

## 应避免的反模式

### 不应该做的事

1. **跳过现况评估**
   - 错误：直接在不熟悉的代码上开始编码
   - 正确：先执行 `/discover` 了解你正在处理的内容

2. **捏造指标**
   - 错误：「测试覆盖率大概在 60% 左右」
   - 正确：「[Unknown] 测试覆盖率 -- 需要执行测试套件才能量测」

3. **不完整的评估**
   - 错误：只检查代码健康度，跳过依赖
   - 正确：完成全部 6 个步骤以获得可靠的全貌

4. **忽视质量闸门**
   - 错误：无视严重漏洞继续进行
   - 正确：在增加复杂度前先处理阻塞项目

## 最佳实践

- 在做出声明前先阅读所有相关代码（反幻觉）
- 使用确定性标签：`[Confirmed]`、`[Inferred]`、`[Unknown]`
- 包含来源引用及 file:line 参考
- 清楚区分事实与建议
- 根据项目规模调整深度（小型项目 = 轻量评估）

---

## 相关规范

- [反向工程标准](../../../../core/reverse-engineering-standards.md) -- 深度代码分析方法论
- [测试标准](../../../../core/testing-standards.md) -- 测试覆盖率基准
- [安全标准](../../../../core/security-standards.md) -- 漏洞评估
- [AI 友善架构](../../../../core/ai-friendly-architecture.md) -- 架构评估标准
- [文档结构](../../../../core/documentation-structure.md) -- 文档完整性
- [变更日志标准](../../../../core/changelog-standards.md) -- 变更追踪
- [反幻觉指南](../../../../core/anti-hallucination.md) -- 证据导向分析
- [代码审查清单](../../../../core/code-review-checklist.md) -- 审查方法论
- [签入标准](../../../../core/checkin-standards.md) -- 质量闸门
- [需求工程](../../../../core/requirement-engineering.md) -- 影响分析

---

## 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0.0 | 2026-02-10 | 初始发布 |

---

## 授权

此技能采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权。

**来源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)
